@vibe-commit/capture 0.1.0

package/dist/project.js

@@ -0,0 +1,192 @@
+/**
+ * What "this repository" means — ⛔ **TWO answers, and D184 splits them.**
+ *
+ * One value served four roles until `D184`. It still serves three of them; the
+ * fourth — **the consent key** — moves, and `resolveProjectKeys` is where the two
+ * surviving answers are produced together so a caller cannot take the wrong one
+ * by accident:
+ *
+ * ```
+ *  resolveProjectKeys(cwd) ──┬──> consent gate     = canonicalised git COMMON DIR   [MOVES]
+ *                            ├──> session bucket   = worktree TOPLEVEL   (D58/CR-017d)
+ *                            ├──> repoSlug input   = worktree TOPLEVEL
+ *                            └──> redaction root   = NOT FROM HERE. A SET, and the
+ *                                                    common dir is never in it (D184 §3).
+ * ```
+ *
+ * ⛔ **The redaction confinement root is NOT one of the values this module
+ * returns**, and that omission is the decision. `D184 §3`: if the confinement
+ * root follows the consent key to the common dir, every file of an external
+ * worktree is judged outside the main clone and `isInside` fail-closes each one
+ * into a redaction marker. Capture succeeds, turn counts look right, the content
+ * is gone. Widening it is `T2`'s work in `redact.ts`, against a root SET.
+ *
+ * ## ⛔ Why the consent key had to move at all
+ *
+ * Consent was keyed on `--show-toplevel`, which **differs per worktree**, with no
+ * wildcards and absence-means-no. So an agent session inside a `git worktree`
+ * captured **nothing** — no conversation, no commit, no notice — and `D19` makes
+ * worktree-per-builder the house convention. `M2`: `rev-parse --git-path hooks`
+ * in a linked worktree returns the MAIN clone's `.git/hooks`, so one install
+ * already covers every worktree. The common dir is the identity the install
+ * already had.
+ *
+ * ⚠ Deliberately NOT `src/git.ts`. `CR-019` owns that file (deriving the repo slug
+ * for `X-Repo-Slug`) and would collide. This module holds only what the consent
+ * gate needs; `CR-019` may fold it in when it lands.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { spawnTimeoutMs } from "./spawn_budget.js";
+/** This spawn's own ceiling, used when no hook budget is armed. */
+const TOPLEVEL_TIMEOUT_MS = 5_000;
+/**
+ * One `rev-parse` answer, or null.
+ *
+ * ⛔ **ONE ARGUMENT PER INVOCATION, and `resolveProjectKeys` therefore spawns
+ * TWICE rather than once.** Prior learning `git-rev-parse-combined-args-fail-together`,
+ * reproduced 10/10: *when the unresolvable arg is 40 hex, `rev-parse` exits 0 and
+ * echoes it back verbatim as if it were an answer.* Reproduced again here on
+ * 2026-08-21 — `rev-parse --show-toplevel <40×a>` prints the toplevel, then
+ * `aaaa…`, and exits 0. A combined invocation therefore cannot be validated by
+ * WHICH LINE the answer landed on, because a garbage answer occupies a line too.
+ *
+ * ⚠ **The cost is +1 spawn at hook entry, outside the 8-file loop**, and it is
+ * accepted on the record (`D184 §6`). `hooks/post_commit.ts` arms no spawn
+ * budget, deliberately, so this path is unaffected there.
+ *
+ * `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`.
+ */
+function revParse(dir, arg) {
+    const timeout = spawnTimeoutMs(TOPLEVEL_TIMEOUT_MS);
+    if (timeout === null)
+        return null;
+    try {
+        const out = execFileSync("git", ["-C", dir, "rev-parse", arg], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout,
+        });
+        const value = out.trim();
+        return value === "" ? null : value;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The git toplevel for `dir`, or null when it is not inside a work tree.
+ *
+ * ⚠ **The timeout DERIVES from the hook's remaining budget** (`TODOS[87]`).
+ * `execFileSync` blocks the event loop, so the watchdog cannot fire while this
+ * call is outstanding — a fixed 5s ceiling here is 5s the watchdog provably
+ * cannot cover, and it is one of four such ceilings that summed to 20s against a
+ * 5s budget. `null` means the budget is spent, and the answer is the one this
+ * function already gives when git cannot tell us: no toplevel, so no consent,
+ * so the hook does nothing. Silent by contract and correct by default.
+ *
+ * ⛔ **The answer is validated by CONTENT: `--show-toplevel` is absolute, always.**
+ * Without that gate a `git` on `PATH` that echoed a 40-hex string back would have
+ * it `resolve`d against `process.cwd()` and returned as a toplevel — accepted
+ * because it arrived where an answer was expected. Fail closed instead.
+ */
+export function gitToplevel(dir) {
+    const top = revParse(dir, "--show-toplevel");
+    if (top === null || !isAbsolute(top))
+        return null;
+    return resolve(top);
+}
+/**
+ * ⛔ **THE CONSENT KEY — the git common dir, canonicalised before it is ever a key.**
+ *
+ * ## `M3`: keying this naively is a SECURITY REGRESSION, not a formatting bug
+ *
+ * `--git-common-dir` is **`.git`, RELATIVE**, in a main clone, and an absolute
+ * path in a linked worktree. Measured 2026-08-21, four shapes:
+ *
+ * | shape | `--git-common-dir` |
+ * |---|---|
+ * | main clone, `-C` the toplevel | `.git` |
+ * | main clone, `-C` a subdirectory two deep | `../../.git` |
+ * | linked worktree | `<main>/.git`, absolute |
+ * | worktree of a BARE repo | `<repos>/project.git`, absolute |
+ *
+ * ⛔ Keyed on the raw string, **every main clone on the machine gets the key
+ * `.git`** — consent to one repo would grant capture on all of them.
+ *
+ * ⛔ **And the base for that resolution is `dir`, NOT the toplevel.** Row 2 is
+ * why, and it is the same hazard one layer over: `resolve(toplevel, "../../.git")`
+ * for a repo at `…/scratch/repo` is `…/.git` — a key SHARED by every sibling repo
+ * under that parent. Git's answer is relative to git's cwd, which `-C dir` makes
+ * `dir`. `D184 §2` says "resolve against the toplevel"; measured, that is wrong
+ * for the subdirectory case and this resolves against `dir`.
+ *
+ * ⚠ **`realpath` before it is a key**, so `/tmp/x` and `/private/tmp/x` are not
+ * two grants for one repo, and so an unresolvable answer fails closed.
+ *
+ * ## The content check, which is what makes this not "trust the line"
+ *
+ * A 40-hex string is legal syntax for a RELATIVE common dir, so absoluteness
+ * cannot reject it here the way it does for the toplevel. The answer must be a
+ * directory that actually holds a `HEAD` — present in all four measured shapes
+ * above, and absent from any directory that merely happens to exist under `dir`.
+ * ⚠ Existence alone would be a check the fixture can satisfy by accident
+ * (`project_redaction_fixture_must_exist_on_disk` is the same shape of trap).
+ */
+function gitConsentKey(dir) {
+    const raw = revParse(dir, "--git-common-dir");
+    if (raw === null)
+        return null;
+    let canonical;
+    try {
+        canonical = realpathSync(resolve(dir, raw));
+    }
+    catch {
+        return null;
+    }
+    return existsSync(join(canonical, "HEAD")) ? canonical : null;
+}
+/**
+ * Both keys for a directory, or **null** — ⛔ **fail closed, never a fallback.**
+ *
+ * If either spawn fails or either answer fails its content check, there is no
+ * partial answer: a guessed consent key grants capture on a repository the user
+ * never approved, and a guessed worktree key files a session under the wrong
+ * repository permanently.
+ *
+ * ⚠ **NO MIGRATION PATH FOR EXISTING `projects.json` ENTRIES, deliberately.**
+ * The allow list is keyed by string and the key changes shape, so a pre-existing
+ * grant at a toplevel stops matching. Pre-launch there are zero users and zero
+ * rows (`project_pre_launch_no_data`), so the migration is a no-op with nothing
+ * to migrate — writing one would be speculative code guarding a case that cannot
+ * occur. The observable cost if that assumption were ever wrong is one re-run of
+ * `vibecommit connect`, not a silent grant.
+ */
+export function resolveProjectKeys(dir) {
+    const worktree = gitToplevel(dir);
+    if (worktree === null)
+        return null;
+    const consent = gitConsentKey(dir);
+    if (consent === null)
+        return null;
+    return { worktree, consent };
+}
+/**
+ * The worktree toplevel for a directory: the session bucket and slug input.
+ *
+ * ⛔ **NO LONGER THE CONSENT KEY — `D184` moved that to
+ * `resolveProjectKeys(dir).consent`.** The name is kept because the three roles
+ * it still serves are unchanged and every caller of it wants the toplevel; a
+ * rename would be churn across files this change has no other reason to touch.
+ *
+ * Falls back to NOTHING. A directory outside a work tree has no project identity,
+ * and inventing one from `cwd` would file a session under a key the user cannot
+ * see in `vibecommit status`.
+ */
+export function resolveProjectKey(dir) {
+    return gitToplevel(dir);
+}
+//# sourceMappingURL=project.js.map

package/dist/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,mEAAmE;AACnE,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAElC;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,QAAQ,CAAC,GAAW,EAAE,GAAW;IACxC,MAAM,OAAO,GAAG,cAAc,CAAC,mBAAmB,CAAC,CAAC;IACpD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,CAAC,EAAE;YAC7D,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,OAAO;SACR,CAAC,CAAC;QACH,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACzB,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IAC7C,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAClD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,SAAS,aAAa,CAAC,GAAW;IAChC,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;IAC9C,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,SAAiB,CAAC;IACtB,IAAI,CAAC;QACH,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AAChE,CAAC;AAkBD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC"}

package/dist/redact.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Out-of-tree redaction — `CR-024d`, D57 §OV8d.
+ *
+ * A Claude Code transcript records structured file reads and writes VERBATIM:
+ * a `Read`, `Edit` or `Write` record carries a path and the file's content. When
+ * that path is outside the repository the user consented to, the content of a
+ * THIRD PARTY'S file is about to be uploaded under the user's credential and
+ * attached to a repo that has nothing to do with it. That is a confidentiality
+ * boundary, not a tidiness issue, and it is the whole reason this module exists.
+ *
+ * ## Why the client, permanently
+ *
+ * D57 §OV8d: *"Out-of-tree redaction is client-side. Server-side redaction would
+ * break `turn_hash == sha256(content)`, so it cannot live on the server at
+ * all."* A server that rewrote content after hashing would hold a hash chain
+ * over bytes it no longer has. There is no server-side variant to fall back on.
+ *
+ * ## The deviation this is allowed to make, and its limit
+ *
+ * D60 §D6 says the client holds no ANALYSIS, and OV8d is the ONE recorded
+ * deviation from it, because redacting requires parsing each line. The rule that
+ * survives is *"the client may render; it may not analyze, hash, or
+ * canonicalize."* So this module parses a line, finds a path, compares it to the
+ * project root, and replaces a span. It extracts no turns, computes no digest,
+ * canonicalises no record, and imports nothing from `vibecommit-mcp` — that last
+ * one is a LICENSING violation, not a style one (D60 §D1a, D64).
+ *
+ * ## ⚠ LENGTH PRESERVATION IS THE LOAD-BEARING PROPERTY
+ *
+ * The client sends a raw byte span with `X-Byte-Offset: from`, and the server
+ * advances its watermark by the DECOMPRESSED body's length
+ * (`vibecommit-mcp/src/conversation/ingest_session.ts`). The client's own
+ * `sentOffset` advances to `to`. If a redaction makes the body SHORTER, the two
+ * watermarks diverge and every subsequent delta arrives flagged `gap: true`,
+ * forever; longer, and every delta is `overlap: true`. A permanently
+ * gap-flagged stream is a capture-health surface reporting data loss that is
+ * not happening.
+ *
+ * So every replacement is padded to the exact byte length it replaced, and a
+ * span too short to hold even the shortest honest marker is LEFT ALONE. That
+ * trade — leak a sub-13-byte span rather than break the accounting — is the
+ * brief's, stated rather than smuggled, and `redactSpan` counts what it skipped
+ * so the number is reportable.
+ *
+ * ## Why re-serialising is safe here, measured rather than assumed
+ *
+ * `JSON.parse` → `JSON.stringify` was byte-identical on **39,910 of 39,910**
+ * real transcript lines across 25 sessions, because the transcript is written by
+ * `JSON.stringify` in the first place. That is what makes the padding
+ * arithmetic exact instead of approximate. It is not taken on faith: every line
+ * is round-tripped and compared BEFORE anything is changed, and a line that does
+ * not round-trip is returned untouched.
+ *
+ * @provenance vibecommit-mcp src/conversation/ingest_session.ts — offset accounting, read
+ */
+import { Buffer } from "node:buffer";
+import type { RedactionProfile } from "./agents/types.js";
+/**
+ * The DATA one profile supplies. **The algorithm above does not move.**
+ *
+ * `CR-185`, D164 §5. Everything below `walk` is the rule this module already
+ * had — *within one object, a path key naming a file outside the project root
+ * makes that object's content-bearing siblings third-party content, and the
+ * verdict inherits down the subtree* — and each agent supplies which keys play
+ * which part. A second agent is a second row in the table below, not a branch.
+ */
+export interface RedactionRules {
+    /** Keys whose STRING value is a filesystem path. The SELECTOR, never redacted. */
+    readonly pathKeys: ReadonlySet<string>;
+    /** Keys whose value is content, withheld when a path in scope is out of tree. */
+    readonly contentKeys: ReadonlySet<string>;
+    /**
+     * Keys whose STRING value is itself a JSON document to descend into.
+     *
+     * ⚠ **Empty for Claude Code, and that is not an oversight** — a Claude record
+     * carries its tool input as a real nested OBJECT, so `walk` already reaches
+     * it. Codex hands the whole argument list over as one escaped string.
+     */
+    readonly nestedJsonKeys: ReadonlySet<string>;
+    /** Keys holding `[{ lines: [...] }]` hunk arrays whose lines are content. */
+    readonly patchKeys: ReadonlySet<string>;
+}
+/**
+ * The rules a profile LABEL names.
+ *
+ * For a caller that already knows the dialect — `test/` does, and nothing in
+ * `src/` should, because ⛔ **the profile is selected by the containing root and
+ * not by anything the caller believes about the agent** (see
+ * `rulesForTranscript`).
+ */
+export declare function rulesFor(profile: RedactionProfile): RedactionRules;
+/**
+ * ⛔ **THE PROFILE IS SELECTED BY WHICH REGISTRY ROOT CONTAINS THE RESOLVED
+ * TRANSCRIPT PATH — NEVER BY THE `--agent=` FLAG (D164 §5).**
+ *
+ * The flag stays the BEHAVIOUR selector (roots to search, events, budgets,
+ * delegated discovery). The scrubber stops depending on anyone remembering to
+ * set it — which is the whole defect: both no-flag install paths (the
+ * `.claude-plugin` bundle whose command carries no `--agent=`, and a
+ * hand-written `.codex/` config) resolved to `claude-code`, and a Codex record
+ * went through Claude's key set and was redacted NOT AT ALL.
+ *
+ * ## ⛔ This does NOT reopen `CR-183`'s `transcript_path`-as-selector rejection
+ *
+ * That rejection is about the **confinement boundary**, which is computed from
+ * the registry and is never derived from input — and it still is. The
+ * difference is the direction of the failure:
+ *
+ *   - choosing a **stricter scrubber** because a path sits outside every known
+ *     root is **fail-closed**;
+ *   - choosing a **wider root** because a path *claims* to be there is not.
+ *
+ * A wrong answer here costs a suboptimal profile and can never make a file
+ * readable that was not readable before. `isInside` resolves both sides with
+ * `realpathSync`, so a symlink cannot claim a root it is not under.
+ *
+ * ⛔ **AMBIGUITY FAILS CLOSED TOO.** Two dialects can be pointed at one
+ * directory by environment (`CLAUDE_CONFIG_DIR` and `CODEX_HOME` are both
+ * operator-set, and both sides resolve through `realpath`), and a path inside
+ * two roots is a path whose producer is not known. Exactly one match selects a
+ * profile; zero or two select the strictest.
+ *
+ * ⚠ **Today no path reaching this function is unattributed**, because
+ * `isInsideAny(transcriptRoots(...))` refuses everything outside the union
+ * BEFORE `readSpan` opens it. So the fallback is a second, independent line
+ * rather than a live branch — stated plainly rather than left for a reader to
+ * assume it has a caller (`feedback_unexercisable_branch_not_verified`).
+ */
+export declare function rulesForTranscript(home: string, env: NodeJS.ProcessEnv, transcriptPath: string): RedactionRules;
+export interface RedactionCounts {
+    /** String values replaced with a marker. */
+    readonly redacted: number;
+    /** Out-of-tree values left alone because no honest marker fits. */
+    readonly skipped: number;
+}
+export interface RedactedLine extends RedactionCounts {
+    readonly line: string;
+}
+/**
+ * Redact one NDJSON line. **Pure, total, and length-preserving.**
+ *
+ * Returns the line UNCHANGED on anything it cannot handle — a blank line, a
+ * parse failure, a line that does not round-trip. A hook cannot report an error
+ * (DESIGN.md §13.7), and a redactor that dropped a line it could not parse would
+ * be silent data loss on a path where D56 §D8 makes loss permanent.
+ */
+export declare function redactLine(line: string, projectRoots: readonly string[], rules: RedactionRules, resolver?: Containment): RedactedLine;
+/**
+ * Redact every complete line in a raw transcript span.
+ *
+ * Operates on BYTES because a span is a byte range and its edges need not fall
+ * on a line — or even on a character. Segments are split on `\n` and a segment
+ * that does not decode to exactly its own bytes is passed through untouched,
+ * which is what keeps a span that bisects a multi-byte character from changing
+ * length when it is re-encoded.
+ */
+export declare function redactSpan(span: Buffer, projectRoots: readonly string[], rules: RedactionRules): {
+    bytes: Buffer;
+} & RedactionCounts;
+/**
+ * A marker whose JSON-ENCODED byte length is exactly the original's.
+ *
+ * Encoded, not raw: what has to match is the bytes on the wire, and
+ * `JSON.stringify` escapes newlines, quotes and control characters, so a
+ * 400-byte source file is rarely 400 bytes of JSON. The marker is pure ASCII
+ * with nothing `JSON.stringify` escapes, so its encoded length is simply its
+ * own length plus the two quotes — which is what makes the padding exact.
+ *
+ * Null when even `[out-of-tree]` does not fit. The caller counts that and leaves
+ * the value alone: a short span left intact is a small leak, and a mis-sized one
+ * is a permanently gap-flagged stream.
+ */
+export declare function markerFor(original: string): string | null;
+type Containment = (roots: readonly string[], candidate: string) => boolean;
+export {};