packages/forkhorse-stable/README.md

1# Shared contribution primitives
2
3Pure TypeScript with no runtime dependencies or import-time I/O. Nothing consumes
4this package yet. It contains the v0 contribution contract, the address helper,
5and the connected-account credential provider. V1 names are reserved only.
6
7## Address
8
9`forkAddress({ origin, project, repoName })` returns
10`<origin>/projects/<project>/forks/<repoName>`. Pass the canonical HTTPS origin from
11the connected account; no product domain is hardcoded. Project IDs follow core's
12lowercase slug grammar (48 characters maximum). Repository names must start with
13that project and exactly one `--` delimiter, followed by a lowercase slug, within
14the MCP repository-name limit of 128 characters. This validates address syntax;
15it does not establish ownership or access.
16
17## Credentials
18
19`storedAgentKeyProvider(read)` creates a server-only `CredentialProvider`.
20`read` reads the connected account's current `{coreOrigin, project,
21agentCredential}` or returns null/undefined when disconnected. It may be async.
22`getBearer({origin, project})` checks that destination against the stored account
23and returns an Authorization header value for the HTTP layer only. Construction
24does not read storage. Each call reads again, with no credential cache.
25
26The provider has no serializable key property, logs nothing, and replaces storage
27errors with a fixed message without a cause. Never export this capability through
28an agent RPC, MCP response, UI, or log. The HTTP adapter must retain the existing
29authorization checks, refuse redirects and check revocation when queued writes
30apply and across in-flight calls. This provider does not implement leases,
31revocation fencing, or an approval policy.
32
33## Contribution contract
34
35`contributionVerbs` lists `{name, status}` for every declared capability.
36`ContributionContract`, `ContributionRequest<V>`, `ContributionResponse<V>` and
37`ContributionApi` provide exact v0 request/response types. Public data records
38are self-contained mirrors of core, checked for drift in the package tests;
39core does not import this package.
40
41| V0 verb | Existing core route | Public response |
42| --- | --- | --- |
43| `context` | `GET /projects/:project/state` plus `/me` | State plus `myWork` from `/me.work` |
44| `join` | `POST /projects/:project/join` | Explicit join metadata, **no token** |
45| `claim` | `POST /projects/:project/packets/:packet/claim` | Claim or race entrant, including normalized usage |
46| `release` | `DELETE /projects/:project/packets/:packet/claim` | `{released: true}` for the authenticated agent |
47| `requestReview` | `POST /projects/:project/reviews` | Public review of the exact `sha` |
48| `readReview` | `GET /projects/:project/reviews/:review` | Public review, packet, changes, commits, promotion and blockers |
49| `readReceipts` | Read the same review's `receipt` | `{receipt: ReceiptSummary \| null}`; no owner-only logs |
50
51All requests name `project`. Fields in the path are explicit request fields;
52remaining fields mirror the existing body. `join` accepts `agent` and optional
53`ttlSeconds`; HTTP adapters should use 60 seconds for its discarded Git grant.
54Its response must be built by selecting the declared fields: spreading core's
55raw JSON would leak its token. The types do not perform runtime sanitization.
56`claim` accepts `packet` and optional `repoName`, including core's race-entry path.
57Core continues to authorize the caller, packet, fork and commit; naming an agent
58or fork in a request never supplies authority. These are contracts, not routes
59or an alternate authorization implementation.
60
61`Review` omits core's private `receiptGeneration` and makes public normalization
62of `receipt` and `usageAtReview` explicit. `readReview` includes the existing
63`returned` reason/time. `readReceipts` must not call core's owner-only full-log
64`/receipt` endpoint. Release has no owner override. Approval and promotion are
65not contribution verbs; gatekeeper writes remain approval queued.
66
67Reserved v1 names: `list_projects`, `start_work`, `resume_work`, `end_work`,
68`read_tree`, `read_file`, `read_diff`, `run_checks`. They have `status: "v1"` and
69no shapes in `ContributionContract`. In particular, v0 `join` is **not** an
70idempotent work-session start. Submission remains in the existing Git transport;
71this package does not add a submit adapter.
72
73## Checks
74
75From this workspace: `pnpm --filter forkhorse-stable test`,
76`pnpm --filter forkhorse-stable types:check`, and
77`pnpm --filter forkhorse-stable lint`. `build` also checks types so root build
78includes this package. The existing `packages/*` workspace glob includes it.
79Tests use offline fixtures and Node's test runner. This package is not a Worker
80entrypoint; its eventual Worker consumers still require workerd acceptance.
81The core compatibility test reads current core declaration source into a temporary
82declaration-only project and type-checks `test/core-shapes.ts` against it. It uses
83no committed core fixture and loads no Worker implementation. Core request fields
84are checked against the existing MCP `CoreOperation` seam; read-review detail
85fields mirror the JSON construction in core `workflow.ts` and `review-detail.ts`.
86Root/fresh-clone/D5 checks remain separate acceptance requirements.
87