@vibe-commit/capture 0.1.0

package/dist/hooks/entry.d.ts

@@ -0,0 +1,277 @@
+/**
+ * The hook client — and the enforcement of the hook half of the exit contract.
+ *
+ * DESIGN.md §13.7, restated because every line below exists to hold it:
+ *
+ *   exit        ALWAYS 0. Every path: success, 401, 403, network failure,
+ *               uncaught exception, unsupported Node, signal.
+ *   stderr      ALWAYS empty.
+ *   wall clock  ALWAYS under the hooks.json timeout for that event.
+ *   stdout      At most one well-formed JSON object carrying `systemMessage`;
+ *               otherwise empty. If JSON construction fails for ANY reason →
+ *               empty stdout. The fallback is always silence.
+ *
+ * ⚠ **That stdout line reads "EMPTY on the happy path" in DESIGN.md §13.7, and
+ * as of `CR-023d` it is no longer true.** Style guide §10.1's fourth state
+ * (`capture confirmed`) fires on a successful send, once per `(repo, day)` — so
+ * a populated stdout no longer implies something went wrong. §13.7 and §10.1
+ * disagreed on this before this task; the code now follows §10.1, which D65
+ * records as the executed ruling. DESIGN.md is orchestrator-owned (D66 §3), so
+ * the amendment there is reported, not made here.
+ *
+ * **A hook that exits non-zero feeds stderr back into the user's agent and
+ * derails the task they were actually doing.** That is the whole reason.
+ *
+ * ## Read this before trusting a green contract test
+ *
+ * `silenceStderr()` makes the stderr-empty assertion true STRUCTURALLY. That is
+ * the correct engineering choice — it is the only thing that holds when a
+ * dependency three levels down decides to warn — but it also means a green
+ * "stderr is empty" proves the hook never speaks, and proves **nothing** about
+ * whether the credential is handled carefully. The credential's own control is
+ * separate and lives in `credential.ts` (opaque wrapper + redaction), with its
+ * own red-proof in `test/credential.test.ts`. Do not read one as evidence for
+ * the other.
+ */
+import { type ProjectKeys } from "../project.js";
+/**
+ * Default wall-clock budget. `CR-028` sets the real per-event `timeout` in
+ * `claude-plugin/hooks/hooks.json`; this is the client-side backstop, which must
+ * be the SMALLER of the two or the backstop never fires.
+ *
+ * ⚠ **That relation was prose and was checked by nothing until `CR-183`.** It is
+ * now asserted for every event of every dialect in `test/agent-registry.test.ts`,
+ * which also pins this constant against the `claude-code` dialect's own entry.
+ */
+export declare const DEFAULT_HOOK_BUDGET_MS = 5000;
+/**
+ * What one send attempt may take, after the settle has taken its share.
+ *
+ * `consumedMs` is 0 on every event but `SessionEnd`, and at 0 this is exactly
+ * the expression that was inline here before `CR-020d`
+ * (`Math.floor(budgetMs * SEND_BUDGET_FRACTION)`) for any budget above ~84 ms —
+ * so `Stop` and `PreCompact` are unchanged in both timing and code path.
+ */
+export declare function sendTimeoutMs(budgetMs: number, consumedMs: number): number;
+/**
+ * The budget the SENDS may spend — the whole budget, less the stamp's share.
+ *
+ * A function, and exported, for the reason `sendTimeoutMs` is: the carve-out is
+ * the thing this task changes, and a wall-clock test cannot pin it. Every
+ * discriminator that distinguishes reserve from no-reserve through a real
+ * process turned out to slide with per-send overhead — a 149 ms window that
+ * moves by 25 ms for every 10 ms of connect-and-compress cost — so pinning it
+ * there would be tuning a constant to one machine. Here it is arithmetic.
+ *
+ * ⛔ `budgetMs` itself still governs the SETTLE and the WATCHDOG. Only the sends
+ * are carved.
+ */
+export declare function sendBudgetMs(budgetMs: number, eventName: string): number;
+export interface HookInput {
+    readonly sessionId: string;
+    readonly transcriptPath: string;
+    readonly cwd: string;
+    readonly eventName: string;
+    /**
+     * ⛔ **THE ANNOUNCED DELEGATED TRANSCRIPT — `CR-196`, D177 §9.**
+     *
+     * `agent_transcript_path`, which an `announce` dialect hands over on stdin
+     * instead of writing a directory to glob. Absent for `discover` dialects and
+     * absent on every event but the one that delegates, so `undefined` is the
+     * ordinary case rather than an error.
+     *
+     * ⛔ **INPUT, in the full `/cso` finding-1 sense.** It is a path that reaches
+     * a read whose result is uploaded, so it is confined exactly as the main
+     * transcript is — `admitsTranscript`, which is the registry-computed boundary
+     * plus the file gate. Being handed a path by the agent is not evidence about
+     * where the path points.
+     */
+    readonly agentTranscriptPath?: string;
+}
+/**
+ * Parse hook stdin. Claude Code supplies `{ session_id, transcript_path, cwd,
+ * hook_event_name }` on stdin — NOT in the environment.
+ *
+ * ⚠ **And an `announce` dialect adds `agent_transcript_path` (`CR-196`).** It is
+ * OPTIONAL in both directions: a `discover` install never sends it, and reading
+ * it here rather than in a Cursor-specific parser is deliberate — stdin has one
+ * shape and one parser, and a second one would be a second place for the
+ * confinement boundary to be forgotten.
+ *
+ * Returns null on anything malformed. A hook cannot report a parse error (stderr
+ * is empty by contract), so the only honest response is to do nothing. ⚠ A
+ * malformed `agent_transcript_path` is NOT malformed input: it is dropped and
+ * the main transcript still goes, because losing the whole capture over a
+ * delegated extra would be the larger loss.
+ */
+export declare function parseHookInput(raw: string): HookInput | null;
+/**
+ * Replace stderr with a sink for the rest of the process.
+ *
+ * Node writes uncaught exceptions, unhandled rejections and process warnings to
+ * `process.stderr`, so overriding `write` is what makes the contract hold on the
+ * paths we do not control. The handlers below stop the non-zero exit; this stops
+ * the bytes.
+ */
+export declare function silenceStderr(): void;
+export interface HookEnvironment {
+    readonly env: NodeJS.ProcessEnv;
+    readonly home: string;
+    readonly nodeVersion: string;
+    /**
+     * ⛔ **WHICH AGENT REGISTERED THE HOOK — `--agent=<id>`, resolved in
+     * `index.ts`. NOT which agent produced the transcript.**
+     *
+     * ## The split, and it is load-bearing (`CR-204`, D177 §7)
+     *
+     * `agentId` answered two different questions until `CR-204`, and one of the
+     * two answers was routinely wrong. What each is derived from now:
+     *
+     * | use | derived from |
+     * |---|---|
+     * | wire `X-Agent` | ⛔ the CONTAINING ROOT (`agentForTranscript`) |
+     * | delegated-transcript discovery | ⛔ the CONTAINING ROOT — sub-agent LAYOUT is a property of the transcript |
+     * | the redaction profile | ⛔ the CONTAINING ROOT (`rulesForTranscript`, `CR-185`) |
+     * | ⛔ **hook budgets and timeouts** | ⛔ **THIS FIELD** |
+     *
+     * The budget is the one thing the flag is genuinely the oracle for: the clock
+     * belongs to the PROCESS THAT REGISTERED THE HOOK and is waiting on our exit,
+     * and it is armed before stdin is read — before any transcript path exists to
+     * ask a root about. The other three are properties of the FILE, and no install
+     * passes the flag anyway (`DEFAULT_AGENT_ID` is `claude-code`), so deriving
+     * them from it meant answering `claude-code` for everyone.
+     *
+     * ⛔ **HERE, and not on `HookInput`.** `HookInput` is parsed from stdin, which
+     * is the attacker-influenced input the confinement boundary exists to
+     * constrain; a selector read from there would be the rejected
+     * `transcript_path`-as-selector design wearing a different field name. This
+     * field arrives through the same injected seam as `home` and `nodeVersion`.
+     *
+     * The LITERAL, unnarrowed: an id we do not recognise falls back to the default
+     * dialect for BEHAVIOUR and is never coerced as a value (plan §D7). ⚠ That is
+     * also why it is a `string` and `SelectedAgentId` is not — the flag is not
+     * assignable to the value the wire is built from.
+     */
+    readonly agentId: string;
+    readonly readStdin: () => Promise<string>;
+}
+/**
+ * Install every contract guard, then run the body.
+ *
+ * Guards go in FIRST, before any work, because the paths they cover include
+ * "the body threw on its first line".
+ */
+export declare function runHook(ctx: HookEnvironment): Promise<never>;
+/**
+ * The wall clock this invocation gets.
+ *
+ * ⛔ **THE TIGHTEST BUDGET THE DIALECT REGISTERS, and the reason is the ORDER
+ * things happen in `runHook`** — the watchdog is armed BEFORE stdin is read, so
+ * the event name is not known yet and a per-event budget cannot be applied here
+ * without re-arming the guard. Taking the minimum is the direction that is safe
+ * to be wrong in: it can only finish early, never overrun a registered timeout
+ * and let the agent kill the process instead.
+ *
+ * ⚠ **Claude Code is unchanged, arithmetically** — its three events all carry
+ * `DEFAULT_HOOK_BUDGET_MS`, so the minimum IS that constant. What this costs is
+ * an agent whose events differ: it runs every event at its tightest one, which
+ * under-uses the wide ones. Stated rather than smuggled; widening it means
+ * re-arming the watchdog after the parse, which is its own change.
+ *
+ * `VIBECOMMIT_HOOK_TIMEOUT_MS` still wins outright, as it always has.
+ */
+export declare function hookBudgetMs(env: NodeJS.ProcessEnv, agentId: string): number;
+/**
+ * ⛔ **The redaction confinement ROOT SET — `D184 §3`.**
+ *
+ * ```
+ * isInsideAny([worktree, mainToplevel], candidate)
+ * ```
+ *
+ * ## Why it is a set, and why the common dir is not in it
+ *
+ * `D184` moved the consent key to the git common dir so that a session inside a
+ * `git worktree` is admitted at all. ⛔ **The confinement root MUST NOT follow
+ * it there.** `isInside` realpaths both sides and fail-closes anything it cannot
+ * place to *outside* — which here means REDACT — so a root at `<main>/.git`
+ * would judge every file of an external worktree to be outside the main clone
+ * and replace its `content`, `oldString`, `newString` and `structuredPatch` with
+ * markers. **The capture still succeeds. The turn counts still look right. The
+ * content is gone**, and a test asserting *"worktree sessions capture now"*
+ * passes on an empty payload.
+ *
+ * Two roots, because both are genuinely the user's own tree: the worktree the
+ * session is running in, and the main clone it was cut from — a builder in a
+ * worktree reads the main clone's files constantly.
+ *
+ * ## ⛔ The `paths.ts:487-489` prohibition, answered — `D184 §5`
+ *
+ * > *"`roots` comes from the REGISTRY. It must never be derived from input."*
+ *
+ * **That prohibition is about PROVENANCE, and both members have the right one.**
+ * The named hazard is *anything on hook stdin* — attacker-supplied. Neither of
+ * these is: `keys` can only be produced by `resolveProjectKeys`, which is git's
+ * own answer about the directory the session runs in; `mainToplevel` is git's
+ * answer about the repository **the consent gate already approved**, and it is
+ * content-validated by `mainWorkTree` above. The worktree root has exactly the
+ * same provenance and has been used this way since `CR-024d`.
+ *
+ * ⚠ **Provenance is the whole argument, so this code preserves it:** nothing
+ * here is read from stdin, the derivation is validated by content, and a failure
+ * yields no second root rather than a fallback. An empty set would refuse
+ * everything (`paths.ts:491-492`), which is the correct direction — but this
+ * function cannot return one, because `keys.worktree` is always a member.
+ *
+ * ⚠ The dedup is cosmetic. `isInsideAny` over a repeated root is a union with
+ * itself; it is dropped so that a main-clone session reads as the single root it
+ * has always had, and so a cell asserting "no second root" is asserting
+ * something.
+ */
+export declare function confinementRoots(keys: ProjectKeys): readonly string[];
+/**
+ * Read `[from, to)` of the transcript, REDACT it, and compress it.
+ *
+ * The path is already confined to the Claude Code transcript root by the caller
+ * (`/cso` finding 1) — this function must never be handed one that is not.
+ * Returns null on any failure, because a hook cannot report a read error.
+ *
+ * ## The one chokepoint
+ *
+ * This is the single place transcript bytes become a request body, which is why
+ * `CR-024d`'s redaction goes HERE and nowhere else — the same discipline
+ * `post.ts` applies to `expose()`: one call site, greppable, reviewable. Any
+ * future path that reads transcript bytes for upload must come through here or
+ * it silently bypasses the confidentiality boundary.
+ *
+ * `redactSpan` is length-preserving BY CONTRACT (see `redact.ts`), which the
+ * server's offset accounting depends on — so the compressed body still covers
+ * exactly `[from, to)`.
+ *
+ * ## ⛔ The SCRUBBER is chosen HERE, from the path, and never from `ctx.agentId`
+ *
+ * `CR-185`, D164 §5. This function knows the file it is about to read, so it is
+ * the one place that can answer *which registry root contains it* — and a
+ * caller therefore cannot pick the wrong profile for a file it hands over. The
+ * flag is not consulted: both no-flag install paths resolve to `claude-code`,
+ * and running Claude's key set over a Codex record redacts NOTHING.
+ *
+ * ⚠ **`home` and `env` are here for that lookup and nothing else.** They are
+ * passed rather than read from the process for the reason `paths.ts` states: a
+ * module that reads the real HOME cannot be tested without touching the
+ * developer's own transcripts.
+ *
+ * ## ⛔ `projectRoots` is a SET, and the consent key is not in it
+ *
+ * `D184 §3`. It was one string — the consented toplevel — while the consent key
+ * and the confinement boundary were the same value. They are not any more:
+ * `confinementRoots` above builds `[worktree, mainToplevel]` and the git common
+ * dir the consent gate approved is deliberately absent from it. A single-element
+ * set is the ordinary main-clone case and behaves exactly as the old parameter
+ * did.
+ *
+ * EXPORTED for `connect`'s test capture (`CR-025`), which reads a transcript on
+ * a path the hook never takes. It reuses this rather than opening one itself,
+ * because a second reader would bypass both the confinement and the redaction —
+ * exactly what the chokepoint note above warns about.
+ */
+export declare function readSpan(path: string, from: number, to: number, projectRoots: readonly string[], home: string, env: NodeJS.ProcessEnv): Uint8Array | null;