@vibe-commit/capture 0.1.0

package/dist/exit.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The exit-code contract — CR-022.
+ *
+ * The contract is SPLIT, and the split is load-bearing (D61 round 3 §D8). As
+ * originally written the exit-0/stdout-empty rule governed the whole binary,
+ * which would have made `why` on a read-lane 5xx exit 0 and print nothing —
+ * a read verb failing silently.
+ *
+ * - HOOK invocations: always exit 0, always silent on stdout. Capture must never
+ *   block or slow a developer's turn (D56 plan §D8, a founder override). A hook
+ *   that exits non-zero or writes to stdout is a defect regardless of what went
+ *   wrong underneath.
+ * - INTERACTIVE verbs (`connect`, `status`, `off`, `why`, `report`): normal CLI
+ *   semantics. Non-zero on failure, diagnostics on stderr, output on stdout.
+ */
+export declare const EXIT: {
+    readonly ok: 0;
+    /** Interactive-only. A hook must never return this. */
+    readonly failure: 1;
+    /**
+     * Interactive-only. Usage error — unknown verb, bad flag, **or consent
+     * requested on a non-TTY** (DESIGN.md §13.7, D65 plan §DR7). A consent prompt
+     * that proceeds when nobody can answer it is not a consent prompt.
+     */
+    readonly usage: 2;
+    /**
+     * Interactive-only. Not connected — distinct from `failure` so a wrapper can
+     * branch on it without parsing copy (DESIGN.md §13.7).
+     */
+    readonly notConnected: 3;
+    /**
+     * Interactive-only. Connected, nothing to report — the empty window.
+     * **Not an error** (DESIGN.md §13.7, and it is load-bearing): collapsing an
+     * empty `report` window or a pre-install `why` into `1` teaches a wrapper that
+     * absence of a record means the tool broke — one `||` away from the
+     * permanently BLOCKED claim that absence of an edge means no agent was
+     * involved.
+     */
+    readonly empty: 4;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+export type InvocationMode = "hook" | "interactive";
+/**
+ * Resolve the exit code for a completed invocation.
+ * Hooks collapse every outcome to 0 by contract; interactive verbs pass through.
+ */
+export declare function resolveExitCode(mode: InvocationMode, outcome: number): number;
+/**
+ * The hook-side half of the contract, stated as data so the contract test can
+ * enumerate it rather than restate it (DESIGN.md §13.7).
+ *
+ * `stdout` is "empty on the happy path, otherwise exactly one well-formed JSON
+ * object carrying `systemMessage`. If JSON construction fails for ANY reason →
+ * empty stdout. The fallback is always silence."
+ */
+export declare const HOOK_CONTRACT: {
+    readonly exit: 0;
+    readonly stderrBytes: 0;
+};

package/dist/exit.js

@@ -0,0 +1,60 @@
+/**
+ * The exit-code contract — CR-022.
+ *
+ * The contract is SPLIT, and the split is load-bearing (D61 round 3 §D8). As
+ * originally written the exit-0/stdout-empty rule governed the whole binary,
+ * which would have made `why` on a read-lane 5xx exit 0 and print nothing —
+ * a read verb failing silently.
+ *
+ * - HOOK invocations: always exit 0, always silent on stdout. Capture must never
+ *   block or slow a developer's turn (D56 plan §D8, a founder override). A hook
+ *   that exits non-zero or writes to stdout is a defect regardless of what went
+ *   wrong underneath.
+ * - INTERACTIVE verbs (`connect`, `status`, `off`, `why`, `report`): normal CLI
+ *   semantics. Non-zero on failure, diagnostics on stderr, output on stdout.
+ */
+export const EXIT = {
+    ok: 0,
+    /** Interactive-only. A hook must never return this. */
+    failure: 1,
+    /**
+     * Interactive-only. Usage error — unknown verb, bad flag, **or consent
+     * requested on a non-TTY** (DESIGN.md §13.7, D65 plan §DR7). A consent prompt
+     * that proceeds when nobody can answer it is not a consent prompt.
+     */
+    usage: 2,
+    /**
+     * Interactive-only. Not connected — distinct from `failure` so a wrapper can
+     * branch on it without parsing copy (DESIGN.md §13.7).
+     */
+    notConnected: 3,
+    /**
+     * Interactive-only. Connected, nothing to report — the empty window.
+     * **Not an error** (DESIGN.md §13.7, and it is load-bearing): collapsing an
+     * empty `report` window or a pre-install `why` into `1` teaches a wrapper that
+     * absence of a record means the tool broke — one `||` away from the
+     * permanently BLOCKED claim that absence of an edge means no agent was
+     * involved.
+     */
+    empty: 4,
+};
+/**
+ * Resolve the exit code for a completed invocation.
+ * Hooks collapse every outcome to 0 by contract; interactive verbs pass through.
+ */
+export function resolveExitCode(mode, outcome) {
+    return mode === "hook" ? EXIT.ok : outcome;
+}
+/**
+ * The hook-side half of the contract, stated as data so the contract test can
+ * enumerate it rather than restate it (DESIGN.md §13.7).
+ *
+ * `stdout` is "empty on the happy path, otherwise exactly one well-formed JSON
+ * object carrying `systemMessage`. If JSON construction fails for ANY reason →
+ * empty stdout. The fallback is always silence."
+ */
+export const HOOK_CONTRACT = {
+    exit: EXIT.ok,
+    stderrBytes: 0,
+};
+//# sourceMappingURL=exit.js.map

package/dist/exit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit.js","sourceRoot":"","sources":["../src/exit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,EAAE,EAAE,CAAC;IACL,uDAAuD;IACvD,OAAO,EAAE,CAAC;IACV;;;;OAIG;IACH,KAAK,EAAE,CAAC;IACR;;;OAGG;IACH,YAAY,EAAE,CAAC;IACf;;;;;;;OAOG;IACH,KAAK,EAAE,CAAC;CACA,CAAC;AAMX;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAoB,EAAE,OAAe;IACnE,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,IAAI,EAAE,IAAI,CAAC,EAAE;IACb,WAAW,EAAE,CAAC;CACN,CAAC"}

package/dist/git.d.ts

@@ -0,0 +1,299 @@
+/**
+ * What "this repository" means ON THE WIRE — `CR-019d`, the client half of
+ * `CR-019`.
+ *
+ * ⚠ **This is not `project.ts`'s question and the two answers are not
+ * interchangeable.** `resolveProjectKey()` answers "which work tree is this?"
+ * with a local filesystem path, and that path is (since `CR-017d`) half the
+ * local state key — it never leaves the machine. `resolveRepoSlug()` answers
+ * "which repository is this, in terms the SERVER can resolve?" and its value
+ * goes on the wire as `X-Repo-Slug`. Conflating them would put an absolute path
+ * from a developer's laptop into a tenant-scoped lookup, so they stay separate
+ * functions with separate return shapes.
+ *
+ * ⛔ **THIS PARAGRAPH USED TO CALL THAT PATH "THE CONSENT KEY" TOO, AND `D184`
+ * MADE THAT FALSE.** The consent gate now keys on the canonicalised git COMMON
+ * DIR — `resolveProjectKeys(dir).consent` — and `resolveProjectKey`'s own
+ * docblock says so in terms (`project.ts:197`). Corrected here rather than left
+ * standing, because this is the paragraph a reader meets first and it was
+ * teaching the retired model.
+ *
+ * ## The contract this must satisfy, read from the merged server, not inferred
+ *
+ * `CR-019b` shipped and `X-Repo-Slug` is REQUIRED. `parseIngestHeaders`
+ * (`vibecommit-mcp/src/conversation/ingest_session.ts`) rejects an absent header
+ * — and a present one that is empty after `.trim()` — with a 400 whose reason is
+ * `missing X-Repo-Slug`, and rejects anything over 256 characters. So there is
+ * no lenient path to fall back to: this module always returns a non-empty slug
+ * for a directory that has a git toplevel at all.
+ *
+ * D57 §OV1 is why the server is strict: *"A NULL `repository_id` is
+ * fail-closed-invisible per `org_access_model.sql`, so without this every hook
+ * capture would be hidden from its own author."* `readable_repository_ids` is a
+ * POSITIVE list, so a capture with no repository renders to nobody — including
+ * the person who just made it. A 400 is strictly better than that silence.
+ *
+ * ## The two keys have different GRAIN, and that is correct in both directions
+ *
+ * This is where the local and wire identities line up, so it is where the
+ * mismatch between them belongs on the record. A linked `git worktree` has its
+ * own toplevel — verified, `rev-parse --show-toplevel` returns the worktree
+ * directory, not the main clone — so two worktrees of one repository are two
+ * `repoKey`s and therefore two local offset ledgers, while sharing one `origin`
+ * makes them one `repoSlug` and one server `repository_id`.
+ *
+ * Both halves of that are the behaviour you want. Locally, separate ledgers are
+ * the safe direction: the state key exists to keep two work trees from applying
+ * each other's byte offsets (`CR-017d`, D58), and over-separating costs a resync
+ * at worst. On the wire, one identity is simply true — two worktrees of one
+ * repository ARE one repository, and minting two would fragment the audit record
+ * of a single repo.
+ *
+ * ⛔ **THE SPLIT IS NOW THE STATE BUCKET'S ALONE, AND IT USED TO BE EVERYTHING'S
+ * (`D184`).** Read the paragraph above as being about the OFFSET LEDGER, because
+ * that is all it still governs. Consent no longer follows the toplevel: it keys
+ * on the git common dir, which a main clone and every worktree linked to it
+ * SHARE. So the two statements a reader is likely to run together are now
+ * opposites — two worktrees are **two** state buckets and **one** consent
+ * grant — and the `CR-017d`/D58 reasoning above is kept verbatim because it is
+ * still exactly right about the half it was written for.
+ *
+ * ⚠ **The reason they moved apart is the same fact seen from two sides.** A
+ * per-worktree consent key made an agent session inside a `git worktree` capture
+ * NOTHING, silently, while `D19` makes worktree-per-builder the house convention
+ * — so sharing was the fix. A per-worktree state key is what stops two work
+ * trees applying each other's byte offsets — so separating is the fix. One
+ * value could not do both, and `project.ts` is where the two are produced
+ * together precisely so taking the wrong one has to be deliberate.
+ *
+ * The one reachable oddity: two worktrees driven by ONE Claude Code session (so,
+ * one `session_id`) would keep two independent client ledgers against a single
+ * server stream key. The server is idempotent on `(session, offset)` and treats
+ * a disagreement as a resync, so the cost is re-sent bytes, never a cross-repo
+ * bleed. Not designed around; recorded so the next person meets it as a known
+ * property rather than a surprise.
+ *
+ * ## Case, and why this does not lowercase
+ *
+ * `resolve_repository` canonicalises with `lower(trim(coalesce(slug, '')))` and
+ * the App-installation oracle compares `lower(r.repo_full_name) = v_slug`, so
+ * both sides are lowercased and case cannot affect resolution. What case DOES
+ * affect is the row the server writes: `display_name` is
+ * `trim(p_source_repo_full_name)` — the raw value sent here. Preserving the
+ * remote's own case therefore gives a correctly-cased display name for free,
+ * and lowercasing would throw that away for no gain.
+ *
+ * @provenance vibecommit-mcp src/conversation/ingest_session.ts — parseIngestHeaders, read
+ * @provenance vibecommit-schema org_access_model.sql — readable_repository_ids, read
+ */
+/**
+ * `owner/repo` for a work tree whose `origin` is GitHub, `host/owner/repo` for
+ * any other host, else `local:<sha256(abspath)[0:12]>`.
+ *
+ * **Takes the TOPLEVEL, not a `cwd`.** Every caller already has it: the consent
+ * gate resolves `resolveProjectKey(input.cwd)` before anything else runs and
+ * refuses when it is null, so re-deriving it here would be a second
+ * `git rev-parse` spent against the hook's wall-clock budget (DESIGN.md §13.7)
+ * to recompute a value the caller is holding — and a second call could disagree
+ * with the first, which is the same reason `CR-017d` reuses it for the state key
+ * rather than recomputing.
+ *
+ * **Never returns empty.** A work tree always has an identity: with a remote it
+ * is the remote's, without one it is the path's. That is what lets the server
+ * require the header (D58 §ER25).
+ *
+ * ## ⚠ Why `local:` had to stop being the answer for a real remote (D157)
+ *
+ * `localSlug` hashes the developer's OWN ABSOLUTE PATH. That is correct for a
+ * work tree with no remote — there is nothing else to key on, and two such trees
+ * genuinely are two repositories. It is WRONG for a tree that has a remote:
+ * every colleague, and every second clone on one machine, mints a DIFFERENT
+ * repository for what is provably one repo. Captures never join, the graph
+ * cannot span them, and **nothing errors** — the failure is silent by
+ * construction, which is what made it survive this long.
+ *
+ * So `local:` now survives only where it is true: **no remote at all**, or a
+ * remote whose path is not `owner/repo` and therefore cannot be named without
+ * guessing (`parseRemoteSlug` refuses rather than guesses — `CR-019d`).
+ */
+export declare function resolveRepoSlug(toplevel: string): string;
+/**
+ * `origin`'s URL, or null when there is no `origin` (or git cannot say).
+ *
+ * `execFileSync` with an argument array, never a shell string — a repository
+ * path containing a space or a `;` is ordinary on a developer's machine and
+ * would be a command-injection sink through `execSync`. Same discipline as
+ * `project.ts`'s `gitToplevel`, for the same reason.
+ */
+export declare function gitRemoteUrl(dir: string): string | null;
+/**
+ * Run one git command, or return null — the shared probe.
+ *
+ * ⚠ **AN ARGUMENT ARRAY, NEVER A SHELL STRING.** A repository path containing a
+ * space or a `;` is ordinary on a developer's machine and a shell string is a
+ * command-injection sink. Identical shape to `gitRemoteUrl` above and
+ * `project.ts`'s `gitToplevel`: `-C <dir>`, utf8, stderr discarded, a
+ * five-second bound, and a failure that resolves to a VALUE rather than
+ * throwing.
+ *
+ * ⚠ **MOVED HERE FROM `src/commands/why.ts` BY `CR-108`**, because `report`
+ * needs the same probe and a second copy is how the two drift. `why`'s screens
+ * are byte-identical afterwards — `test/why.test.ts` is the oracle for that,
+ * and the move changes no behaviour: this is the same function.
+ */
+export declare function gitProbe(dir: string, args: readonly string[]): string | null;
+/**
+ * Is this a shallow clone?
+ *
+ * ⚠ **LOAD-BEARING RATHER THAN DEFENSIVE** (D67's posture), and it is the same
+ * hazard for two different verbs. `git blame` on a shallow clone attributes
+ * every line older than the graft boundary to the boundary commit; a
+ * REACHABILITY question on a shallow clone is wrong the same way, because the
+ * commits that would answer it may simply not be in the clone. Both return a
+ * PLAUSIBLE WRONG ANSWER — D98's hazard class — and shallow clones live in CI
+ * containers, which is where nobody is reading the output.
+ *
+ * ⚠ **FAILS CLOSED.** If git cannot answer, we do not know the clone is
+ * complete, and an answer we cannot stand behind is worse than a refusal.
+ */
+export declare function isShallowClone(dir: string): boolean;
+/**
+ * Is `sha` an ancestor of `ref` — i.e. still reachable from it?
+ *
+ * ⚠ **THE ONE THING THE SERVER CANNOT ANSWER.** `commit_coverage` returns the
+ * shas we hold an edge for and deliberately no rate, because reachability is a
+ * property of the user's clone and that process has no repository (D67). This
+ * is the client half of that split.
+ *
+ * ⚠ **FAILS CLOSED, and the direction matters.** `merge-base --is-ancestor`
+ * exits 0 for yes and 1 for no, so `gitProbe` returns `""` for reachable and
+ * `null` for BOTH "not reachable" and "git could not answer". Those are
+ * different facts, and collapsing them would silently count an unanswerable
+ * probe as unreachable — deflating the rate rather than refusing it. So the
+ * caller is handed `null` for "unknown" and must decide, and `report` refuses.
+ */
+export declare function isReachable(dir: string, sha: string, ref: string): boolean | null;
+/**
+ * The `git patch-id` of one commit — the CLIENT-ASSERTED half of a successor
+ * pair (`CR-133d`, D111 §1).
+ *
+ * ⚠ **THE CLIENT IS THE ONLY SIDE THAT CAN COMPUTE THIS.** The server provably
+ * cannot: no git dependency, no clone, and its only `child_process` is a
+ * best-effort `git show` on no live path (D108). A patch id is a fact about a
+ * DIFF, so it survives the rewrite that changes the sha — which is what lets a
+ * successor pair resolve through a rebase or GitHub's squash-merge button.
+ *
+ * ⚠ **IT IS EVIDENCE THE CLIENT ASSERTS, NOT SOMETHING WE WITNESSED** (D111 §1
+ * condition 3, the same posture as `cli_read` in D73). Whatever consumes this
+ * must record it as client-asserted; nothing here establishes that the caller's
+ * repository is the one the server thinks it is.
+ *
+ * ⚠ **NULL RATHER THAN A GUESS, AND THE REASON IS PERMANENCE.** `match_kind` is
+ * in the primary key and `reject_history_mutation` raises on every UPDATE
+ * including `service_role` (D105, D108), so **a wrong row can never be
+ * retracted**. That makes guessing not a degraded-but-acceptable mode. Every
+ * unanswerable case below therefore returns `null`, exactly like `isReachable`
+ * beside it, and the caller must be able to express "no patch id" as a state
+ * rather than as a value.
+ *
+ * MEASURED cases that return `null` — none of them is an error:
+ *   - a MERGE commit — `diff-tree` emits no patch for one, and a merge has no
+ *     single diff to identify;
+ *   - an EMPTY commit — nothing to hash;
+ *   - a sha absent from this clone, which is the ordinary SHALLOW-clone case
+ *     (`isShallowClone` above exists for the same reason);
+ *   - git missing, a timeout, or output that is not a hex id.
+ *
+ * ⚠ `--root` is deliberate: without it the INITIAL commit of a repository has
+ * no patch id at all, which would silently exclude the one commit every
+ * repository has.
+ *
+ * ⚠ `--no-ext-diff` is load-bearing, not tidiness: a developer's configured
+ * external differ would otherwise rewrite the bytes being hashed, and the
+ * resulting id would be stable only on that machine.
+ *
+ * ⚠ **NO SHELL, so no pipe.** `git patch-id` normally reads a pipe; feeding it
+ * through `input` keeps the argument-array rule `gitProbe` documents above — a
+ * repository path containing a space or a `;` is ordinary.
+ */
+export declare function gitPatchId(dir: string, ref: string): string | null;
+/** Where `HEAD` points right now — the ref-move observation (`CR-170`, D154). */
+export interface HeadRef {
+    /** Validated 40- or 64-hex. Never abbreviated: the server's join is width-sensitive. */
+    readonly sha: string;
+    /** Null on a detached HEAD, which is a state and not a failure. */
+    readonly branch: string | null;
+}
+/**
+ * `HEAD`'s sha and branch — **the ONE new spawn `CR-170` adds to the Claude Code
+ * hook path**, and it is for REF MOVES, not for commits.
+ *
+ * Commits are observed by `post-commit` (D154), which cannot see a `pull`, a
+ * `checkout` or a `reset --hard` — those move a ref **without creating a
+ * commit**, so no commit hook fires and only a direct look at `HEAD` records it.
+ *
+ * ⛔ **ONE SPAWN, BUT NOT COMBINED WITH `--show-toplevel`.** MEASURED
+ * 2026-08-17: `git rev-parse --show-toplevel nosuchref` prints the toplevel and
+ * THEN exits **128**, so `execFileSync` throws and the toplevel is lost with it —
+ * and on a repository with no commits `rev-parse HEAD` is exactly that case
+ * (measured: exit 128, `HEAD` on stdout, a usage line on stderr). Folding the two
+ * together would make an empty repo lose its project key, which is the `C3`
+ * regression. The toplevel keeps its own spawn; this is the second.
+ *
+ * ⛔ **THE OUTPUT IS VALIDATED, NEVER TRUSTED.** MEASURED, same day: when the rev
+ * argument is itself 40 hex, `rev-parse` exits **0 and ECHOES IT BACK** as though
+ * it had resolved something. Nothing distinguishes that from a real answer except
+ * checking the shape — the same reason `gitPatchId` tests its own return before
+ * believing it. ⚠ Marked as an inference: the echo-back is not reachable from
+ * THIS caller, which passes the literal `HEAD`, so the test below is defence
+ * against a future caller and against a git we do not understand, not a live path.
+ */
+export declare function headRef(dir: string): HeadRef | null;
+/** The branch `HEAD` is on, or null on a detached HEAD or a failure. */
+export declare function currentBranch(dir: string): string | null;
+/**
+ * `owner/repo` from a github.com remote, `host/owner/repo` from any other host,
+ * or null when the URL cannot be named without guessing.
+ *
+ * ⚠ **RENAMED FROM `parseGitHubSlug` BY `CR-167`**, because it stopped being
+ * about GitHub. A function that answers `gitlab.com/owner/repo` while calling
+ * itself `parseGitHubSlug` is the kind of name the next reader trusts and should
+ * not. Nothing outside this module and its test imported the old name.
+ *
+ * ## ⚠ SEGMENT COUNT IS THE DISCRIMINATOR, AND THE SERVER ALREADY PARSES IT
+ *
+ * `cr033a` §4 branches on the slash count: exactly one slash means the host is
+ * IMPLIED to be github.com and segment 1 is the owner; otherwise segment 1 is
+ * the host and segment 2 is the owner. This function emits into that grammar
+ * rather than inventing one.
+ *
+ * ⛔ **github.com therefore stays UNQUALIFIED at two segments.**
+ * `resolve_repository` matches the App-installation oracle on
+ * `github_installation_repos.repo_full_name`, which is `owner/repo`. Qualifying
+ * github.com would silently break every oracle join — the exact failure class
+ * this change exists to fix, re-introduced from the other side.
+ *
+ * ## Null is still the safe answer, and that asymmetry is still the design
+ *
+ * A wrong slug is worse than no slug. `local:` is designed to be safe: it can
+ * never collide with a real repository (neither a two- nor a three-segment slug
+ * can contain a `:`), and `resolve_repository` resolves it ungated because a
+ * local-only work tree has no external owner to check against. A
+ * confidently-wrong slug, by contrast, attributes a capture to a repository the
+ * user may not own. So every branch below still fails to null rather than
+ * guessing, and callers turn null into `local:`.
+ *
+ * ⚠ **HOST-QUALIFYING DOES NOT WEAKEN THE SUFFIX-ATTACK GUARD, IT RELOCATES IT.**
+ * `github.com.evil.example` no longer returns null — it returns
+ * `github.com.evil.example/owner/repo`. The security property was never "returns
+ * null"; it is **"is never mistaken for a github.com slug"**, and a three-segment
+ * slug provably cannot collide with the two-segment github.com namespace. The
+ * server agrees independently: `cr033a` §4 reads segment 1 as the HOST, so that
+ * slug is scoped to a namespace claim on `github.com.evil.example`, never to
+ * `owner`'s GitHub account.
+ *
+ * Exported for its own tests: the parsing is where the confidence lives, and it
+ * is pure apart from one `ssh -G`, so it is tested directly rather than through
+ * a spawned `git`.
+ */
+export declare function parseRemoteSlug(remoteUrl: string): string | null;