AGENTS.md

main 11.7 KB · 160 lines · markdown

1	# AGENTS.md — OpenVibe.Git
2
3	## Project Overview
4
5	OpenVibe.Git hosts code with an OpenVibe account at `git.openvibe.codes`: bare git repositories on disk served by
6	git's own `git http-backend`, our pages/API/insights, GitHub mirrors, gzip tarballs for pins, commit statuses and
7	Forge CI, an npm registry, changes/reviews/issues/blame/code search, and the Link relay for clone-to-my-computer.
8
9	- Domain: `git.openvibe.codes` · Port: 5270 in production (dev 5250) · Service id: `git` ·
10	Env prefix: `GIT`
11	- Runtime: Node 22, Express 4, PostgreSQL 18 through `openvibe-sdk/db` (PGlite in dev/tests), bare git repos
12	under `GIT_DATA_DIR` (`DATA_DIR/repos/<owner>/<name>.git`), git itself on PATH.
13	- Read first: [README.md](README.md), [docs/g2-review.md](docs/g2-review.md), [docs/ci.md](docs/ci.md),
14	[docs/npm-registry.md](docs/npm-registry.md), [.env.example](.env.example).
15
16	Network context: sign-in is OpenVibe only (`git` OAuth client via `openvibe-sdk/sso`). A first-party service
17	(Codes, Run, Link) holds a typed Network token for `openvibe.git` and acts for the person it names in
18	`X-OV-Subject`; it never holds a person's password. GitHub is an external mirror/source (REST + git protocol), and
19	Community owns discussion threads on changes/issues (referenced by opaque id through the comments API). Events are
20	OpenVibe.Events; account export/deletion follows ADR-033.
21
22	## Commands
23
24	```bash
25	npm ci # install (contracts/sdk/shared pinned by tag)
26	npm run dev # http://localhost:5250, PGlite under data/
27	npm start # node server/index.js
28	npm test # every test/*.test.js on temp PGlite and a temp data dir
29	npm run test:pg # GIT_TEST_STORE=pg node test/run.js
30	npm test -- review # only test files whose name contains the word
31	node --check <file.js> # syntax check (no linter configured)
32	```
33
34	No build step: server-rendered pages; assets [public/css/git.css](public/css/git.css),
35	[public/js/git.js](public/js/git.js). Git itself must be installed in production.
36
37	## Architecture at a Glance
38
39	- Entry: [server/index.js](server/index.js) — listener, migrations, the official-mirror and mirror-poll jobs,
40	telemetry, graceful stop. `GIT_DRILL` keeps boot-time work off.
41	- App factory: [server/app.js](server/app.js) — helmet/CSP, `/auth`, Git over HTTPS mounted before pages,
42	the GitHub webhook, `/shared`, `/api/v1`, pages, 404/error handler. Tests build it with a temp DB/data dir.
43	- Config: [server/config.js](server/config.js) — `load(env)` is pure; production `/etc/openvibe/git.env`
44	(data limits, audience `openvibe.git`, official owners, GitHub API, CI).
45	- Git on disk: [server/git/](server/git/) — `store.js`, `refs.js`, `cat-file.js`, `http-backend.js`,
46	`review.js`, `run.js`; paths in [server/paths.js](server/paths.js). Wire auth
47	[server/auth/git-auth.js](server/auth/git-auth.js).
48	- Repositories/mirrors: [server/repos.js](server/repos.js), [server/mirror.js](server/mirror.js),
49	[server/official.js](server/official.js), [server/contracts.js](server/contracts.js),
50	[server/github.js](server/github.js), [server/archive.js](server/archive.js) (tarballs),
51	[server/starters.js](server/starters.js), [server/insights.js](server/insights.js).
52	- Changes/reviews/issues: [server/git/review.js](server/git/review.js), [server/reviews.js](server/reviews.js),
53	[server/review-services.js](server/review-services.js), [server/http/review.js](server/http/review.js),
54	[server/http/api.js](server/http/api.js), views [server/views/index.js](server/views/index.js).
55	- Checks/CI/npm: [server/checks.js](server/checks.js), [server/checks-intake.js](server/checks-intake.js),
56	[server/ci.js](server/ci.js), [server/ci-auth.js](server/ci-auth.js), [server/npm-registry.js](server/npm-registry.js);
57	runner in [runner/](runner/) + install/unit in [deploy/ci/](deploy/ci/) and
58	[deploy/systemd-user/openvibe-git-ci.service](deploy/systemd-user/openvibe-git-ci.service).
59	- Link relay: [server/http/link.js](server/http/link.js), [server/link-relay.js](server/link-relay.js).
60	- HTTP/render: [server/http/pages.js](server/http/pages.js), [server/http/identity.js](server/http/identity.js),
61	[server/render/](server/render/) (`layout.js`, `html.js`, `markdown.js`, `highlight.js`).
62	- Database: [server/db.js](server/db.js) and [migrations/](migrations/): `git_repos`, `git_tokens`, `git_views`,
63	`git_clones`, `git_stars`, `git_watches`, `git_events`, `git_changes`, `git_change_reviews`,
64	`git_change_comments`, `git_change_summaries`, `git_issues`, `git_releases`, `git_commit_statuses`,
65	`git_checks_sync`, `git_ci_repos`, `git_ci_runs`, `git_npm_versions`, `git_npm_tags`, `git_clone_requests`,
66	`git_machines`, `git_review_outbox`, `git_official_state`, `git_audit`.
67	- Deploy: [deploy/systemd/openvibe-git.service](deploy/systemd/openvibe-git.service) (PORT 5270,
68	`/etc/openvibe/git.env`) and [deploy/nginx/git.openvibe.codes.conf](deploy/nginx/git.openvibe.codes.conf).
69	`sudo ovhost deploy git` (ovhost service name `git`); the repositories live outside the code checkout.
70
71	## Ownership and Boundaries
72
73	Git owns repositories on disk, refs/trees/blobs/commits, tokens, mirrors and their metadata, official-mirror state,
74	tarball bytes, views/clones/stars/watches, changes/reviews/issues/releases, commit statuses and checks intake, CI
75	runs/repos, npm versions/tags, clone requests/machines and the Link relay state. It does not own identity,
76	accounts or roles (Network), discussion threads/comments (Community), event delivery (Events), GitHub itself (mirror
77	source), or the host/database (Host). A private repository answers 404 to anyone who may not see it — never 403
78	with a title; check visibility on every read path (page, API, raw, archive, clone).
79
80	## Auth and Capabilities
81
82	- Sign-in is Network SSO (`git` client). Git over HTTPS uses a short-lived Git token made on the repository page
83	(`git.repo.read` / `git.repo.write`) or a typed Network token for audience `openvibe.git`. There is no second
84	account system and no password storage.
85	- Service tokens: a first-party service acting for a person sends `X-OV-Subject` and may use `POST /api/v1/repos`
86	(with `owner_username`), `GET /api/v1/profile/:username`, `POST /api/v1/tokens`; the Git token it mints is the
87	person's own for clone/push.
88	- Capabilities used: `git.repo.read`, `git.repo.write`, `git.checks.write` (statuses), plus the
89	Community/Network service calls in [docs/g2-review.md](docs/g2-review.md). Check merges/labels/model settings
90	against repository ownership (G1 has no collaborator ACL).
91	- Session mutations require the exact Origin. A merge/summary request budget is five a minute per address.
92	- Errors are RFC 9457 problem+json with stable codes (`auth.required`, `token.scope`, `repo.not_found`, …); never
93	echo a private repository's existence or a token.
94
95	## Routes
96
97	Git wire: `/<owner>/<name>.git/…` (http-backend) and the same under `/api/v1/repos/<owner>/<name>/`.
98	Pages: `/`, explore, new repository, profiles, repository tree/blob/log/commit, changes/reviews/issues/blame/search,
99	`/<owner>/<name>/ci/<run>`, `/machines`, `/settings`, `/auth/*`, discovery.
100	API: repo CRUD and metadata, raw/blob/tree/commit/diff, tarball `/<owner>/<name>/archive/<ref>.tar.gz`,
101	`POST /api/v1/repos/:owner/:name/commits/:sha/statuses` (+ GET latest per context), required checks, npm registry,
102	changes/reviews/issues/releases, clone requests and clone-to-machine, machines, `/api/v1/link/...`, CI claim/result,
103	GitHub webhook, `/api/health`, `/api/ready`, `/release.json`, `/metrics`.
104
105	## Conventions
106
107	- CommonJS, 4-space indent, single quotes, semicolons; no linter/formatter.
108	- Never shell out with user input. Repository/ref/owner/name/path are validated and passed as argv to git, never
109	through a shell. `test/no-shell.test.js` guards it; path traversal, `..`, leading `-` and absolute paths are
110	refused. Keep `--` before paths.
111	- Limits are policy: `GIT_MAX_PUSH_BYTES` (512 MiB), `GIT_MAX_REPO_BYTES` (3 GiB), `GIT_MAX_FILE_BYTES` (2 MiB),
112	`GIT_MAX_ARCHIVE_BYTES` (256 MiB). Stream, never buffer a whole repository.
113	- Tarballs: `git archive` of the resolved commit, top folder `<name>-<commit>/`, commit as ETag; a tag/full id caches
114	immutably, a branch one minute. A package pin must point at a tag, not a branch.
115	- Mirrors: never delete anything on the forge; official seed falls back to the contracts' repository list when
116	GitHub's listing is refused (403/429/5xx/network), uses `ls-refs` (no REST quota) to check public/existing, skips
117	forks/archived, and reports each skip's reason.
118	- Checks: a change is mergeable only when its required contexts are green (per-repository, empty by default). For a
119	mirror, intake copies GitHub check-runs at most every two minutes and only when a head moved.
120	- Forge CI: only branch pushes to official OpenVibers repos by members; one live run per repo, a newer push
121	supersedes; install phase network only through the allowlisted proxy (`registry.npmjs.org`, `codeload.github.com`),
122	test phase `--network=none`; the verdict is `forge/test` and the GitHub copy is best effort. Never turn a GitHub
123	workflow off from here.
124	- CSP: add origins to `helmet` in [server/app.js](server/app.js); highlighted code is escaped, never raw source HTML.
125	- Phone first: pages fit 390 px; no Font Awesome (shared glyphs); a diff/table may scroll in its own box, never the
126	page.
127	- "Calm reduces, only Off removes": hiding a fork/notification reduces; only an explicit delete/ref deletion removes.
128
129	## Key Pitfalls
130
131	- Git over HTTPS is mounted before every page: `/owner/name.git/...` must never fall through to a page, and a page
132	must never shadow a repository path.
133	- A private repo is 404, including its raw file, archive and clone URL; do not leak a title, a branch or a count.
134	A repository that becomes private also hides its Community thread's content (the opaque thread reference has no
135	title); undelivered outbox rows should be inspected after an outage.
136	- Token lifetime: Git tokens are short-lived, scoped and revocable; never log or persist one. A token's audience
137	is `openvibe.git`; a typed `typ`/`purpose` token is refused.
138	- CI sandbox: the install proxy allows exactly npm and codeload; test phase has no network. A dependency that
139	downloads with Node's own fetch must be baked into the image, not fetched at run time.
140	- Npm registry and tarballs are public/private aware; a private package must not resolve without a token.
141	- Mirror webhooks are verified; a forged webhook writes nothing. A mirror poll fetches only when refs changed.
142	- Starter repositories are seeded only on first creation; never overwrite a person's existing repo.
143	- Account export/deletion is idempotent and never leaks another person's repository list.
144	- Drill mode (`GIT_DRILL`) keeps the official seed, mirror poll, checks intake and CI timers off.
145
146	## Testing
147
148	`npm test` runs each file in its own process on a temp PGlite database and data directory: refs/trees/blobs, http and
149	archive, API/pages, mirrors and quota, official seed, checks and intake, CI and runner, reviews/issues, Link relay and
150	clone-to-machine, npm registry, service delegation, insights, starters, security and no-shell. `npm run test:pg` uses
151	PostgreSQL. Run the narrowest file first, then the suite; always `node --check` changed files.
152
153	## Documentation
154
155	- [README.md](README.md) — run, official mirrors, tarballs/pins/checks, layout, Link clone/machines.
156	- [docs/g2-review.md](docs/g2-review.md) — changes/reviews/issues/blame/search, capabilities, Community integration.
157	- [docs/ci.md](docs/ci.md) — Forge CI, membership, sandbox, images, adding a repository.
158	- [docs/npm-registry.md](docs/npm-registry.md) — the npm registry surface.
159	- [SECURITY.md](SECURITY.md), [.env.example](.env.example).
160