@vibe-commit/capture 0.7.0 → 0.9.0

package/dist/project.js

@@ -38,6 +38,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
+import { gitProbe } from "./git.js";
 import { spawnTimeoutMs } from "./spawn_budget.js";
 /** This spawn's own ceiling, used when no hook budget is armed. */
 const TOPLEVEL_TIMEOUT_MS = 5_000;
@@ -189,4 +190,126 @@ export function resolveProjectKeys(dir) {
 export function resolveProjectKey(dir) {
     return gitToplevel(dir);
 }
+// ---------------------------------------------------------------------------
+// Redaction roots (moved from `hooks/entry.ts` so `session_targets.ts` can use them without an import cycle).
+// ---------------------------------------------------------------------------
+/** The porcelain record's opening line — `worktree <absolute path>`. */
+const WORKTREE_LINE = "worktree ";
+/**
+ * The MAIN work tree of the repository whose common dir this is, or **null**.
+ *
+ * ## ⛔ `rev-parse --show-toplevel` CANNOT ANSWER THIS, measured
+ *
+ * `D184 §4` mandates `git -C <common-dir> rev-parse --show-toplevel`. Measured
+ * on git 2.39.5 against real repositories, that command exits **128** —
+ * *"fatal: this operation must be run in a work tree"* — for **every shape a
+ * consent key takes**, because a consent key is always a git DIRECTORY and
+ * `--is-inside-work-tree` is `false` inside one:
+ *
+ * | `-C` | `--show-toplevel` |
+ * |---|---|
+ * | `<main>/.git` (main clone, and every worktree linked to it) | ⛔ ec 128 |
+ * | `<repos>/project.git` (bare) | ⛔ ec 128 |
+ *
+ * Implemented literally, "a failure means no second root" would fire 100% of
+ * the time: the set would be the singleton it is today, forever, and a
+ * main-clone file read from a worktree session would come back a marker. The
+ * whole change would pass its own tests while doing nothing.
+ *
+ * ## What answers instead, and why it is not a guess
+ *
+ * `git worktree list --porcelain` DOES run from a git dir and from a bare
+ * directory, and its FIRST record is the main work tree. Bare repositories say
+ * so in the record itself — `bare`, with no work tree of their own.
+ *
+ * ⛔ **The answer is then validated by CONTENT, never trusted by position:**
+ * `realpath(<candidate>/.git)` must BE the consented common dir. That check is
+ * independently fatal to every wrong answer this could produce — a bare repo
+ * (`<repos>/.git` does not exist), a linked worktree returned first by some
+ * future git (its `.git` is a FILE, so the realpath is the file, not the common
+ * dir), a submodule work tree (same). `D184 §4`'s hazard is what it is for: in a
+ * worktree of a bare repo the common dir is `…/repos/project.git`, whose parent
+ * is **the folder holding every other repository on the machine**, and a root
+ * derived by stripping a suffix would transmit every sibling repo's file
+ * contents verbatim.
+ *
+ * Every failure yields NO SECOND ROOT. Never a fallback, never a parent, never a
+ * suffix strip.
+ */
+export function mainWorkTree(commonDir) {
+    const out = gitProbe(commonDir, ["worktree", "list", "--porcelain"]);
+    if (out === null)
+        return null;
+    const record = [];
+    for (const line of out.split("\n")) {
+        if (line === "")
+            break;
+        record.push(line);
+    }
+    // A BARE repository HAS no work tree, and git says so in the record itself.
+    if (record.includes("bare"))
+        return null;
+    const first = record[0];
+    if (first === undefined || !first.startsWith(WORKTREE_LINE))
+        return null;
+    const candidate = first.slice(WORKTREE_LINE.length);
+    if (!isAbsolute(candidate))
+        return null;
+    try {
+        return realpathSync(join(candidate, ".git")) === commonDir ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ⛔ **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 function confinementRoots(keys) {
+    const main = mainWorkTree(keys.consent);
+    return main === null || main === keys.worktree ? [keys.worktree] : [keys.worktree, main];
+}
 //# sourceMappingURL=project.js.map

package/dist/project.js.map

@@ -1 +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"}
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"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"}

package/dist/redact.d.ts

@@ -64,6 +64,14 @@ import type { RedactionProfile } from "./agents/types.js";
  * 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.
  */
+/** `values`: every content string withheld. `strict`: the same, and a record holding a data-shaped KEY (a skill name, a path) is withheld as a whole line (C26's form). */
+export type AlwaysWithheld = "values" | "strict";
+export type AggregateVerdict = {
+    readonly kind: "withhold";
+} | {
+    readonly kind: "keepKeys";
+    readonly paths: ReadonlySet<string>;
+};
 export interface RedactionRules {
     /** Keys whose STRING value is a filesystem path. The SELECTOR, never redacted. */
     readonly pathKeys: ReadonlySet<string>;
@@ -79,6 +87,33 @@ export interface RedactionRules {
     readonly nestedJsonKeys: ReadonlySet<string>;
     /** Keys holding `[{ lines: [...] }]` hunk arrays whose lines are content. */
     readonly patchKeys: ReadonlySet<string>;
+    /**
+     * C37: extra path and content keys that apply ONLY inside a record's `attachment` subtree. An attachment names its file as `path` or
+     * `filename` (not `filePath`) and carries it as `content`, `rawContent` or `snippet`: `nested_memory {path, content: {path, content,
+     * rawContent}}`, `edited_text_file {filename, snippet}`, `instructions {files: [{path, content}]}`. `path` cannot be a path key
+     * everywhere (a tool input's `path` names a SEARCH root, not the subject of its siblings), so the scope is the subtree.
+     */
+    readonly attachment?: {
+        readonly pathKeys: ReadonlySet<string>;
+        readonly contentKeys: ReadonlySet<string>;
+    };
+    /**
+     * C39 (iv): a record this dialect's own schema says is a SUMMARY OF THE WHOLE CONVERSATION (Claude's `isCompactSummary` user record: a
+     * model-written digest of everything before it, file text included). Its content is withheld in EVERY copy, single-repo copies and the
+     * golden's shape included, with the same length-preserving marks as an isolated record. Decided by the record, never by a path.
+     */
+    readonly alwaysWithheld?: (record: Record<string, unknown>) => AlwaysWithheld | null;
+    /**
+     * C27 (R17 for records with no folder of their own): what a MULTI-REPOSITORY copy of a session does with a record whose origin cannot be
+     * told from the record. `null`: kept as written (the path rule still applies). `withhold`: every content string is withheld, as in an isolated
+     * record. `keepKeys`: strings under the listed key paths stay, every other string is withheld (a KEEP type is bound to its measured keys).
+     */
+    readonly aggregate?: (record: Record<string, unknown>) => AggregateVerdict | null;
+    /**
+     * C40 (2): keys whose WHOLE subtree is instruction text this dialect injects (Codex's `developer_instructions`, `base_instructions`):
+     * every string under such a key is withheld wherever the key appears, in every copy, whatever path sits beside it.
+     */
+    readonly withheldKeys?: (key: string) => boolean;
 }
 /**
  * The rules a profile LABEL names.
@@ -136,6 +171,44 @@ export interface RedactionCounts {
 export interface RedactedLine extends RedactionCounts {
     readonly line: string;
 }
+/**
+ * ⛔ **THE TWO ADDITIONS ANY-FOLDER CAPTURE MAKES TO THIS CHOKEPOINT** (R6 · R17). Both are decided by the CALLER, which knows
+ * the target; this module only applies them, length-preservingly, with the same markers as every other redaction.
+ *
+ *  - `hole` (R6, a FOLDER target's EXCLUSION ROOTS): a path inside `projectRoots` is still OUT OF TREE when `hole` says so. A
+ *    folder like `~/Documents/VibeCommit` contains repos; the folder stream keeps what is inside the folder and outside every git
+ *    work tree, and withholds anything inside a nested work tree (a backstop for a repo the evidence missed). "Inside A but not
+ *    inside B" is not expressible as a root set, which is why this is a predicate.
+ *  - `foreignRecord` (R17, RECORD ISOLATION): a record whose `cwd` resolves inside a work tree OTHER than the target's is a
+ *    command, its output, or prose from another repo's session. Every content-bearing string in it is withheld; the structural
+ *    keys (`STRUCTURAL_KEYS`) stay, so the stream still parses and a turn is still a turn. Records run from the launch folder
+ *    are untouched: that residual (prompts and prose from the parent folder) is stated in the README and the claims register.
+ */
+export interface RedactionScope {
+    readonly hole?: (candidate: string) => boolean;
+    readonly foreignRecord?: (record: Record<string, unknown>) => boolean;
+    /**
+     * C48 (11), Codex: the FILES a record's call names (an `apply_patch`'s headers in any form, `view_image`'s path; the same for the call's output), and for a
+     * call itself the places only its input is judged by. Each is judged like a Claude path: a file outside this copy's roots, or inside a hole, withholds the
+     * whole record (length-preserving), in every copy.
+     */
+    readonly namedFiles?: (record: Record<string, unknown>) => readonly string[];
+    /**
+     * C27: this copy belongs to a session that named a work tree other than the target's (or whose status is unknown, which counts the same).
+     * Records the dialect cannot attribute (`RedactionRules.aggregate`) are withheld from it.
+     */
+    readonly multi?: boolean;
+    /**
+     * C40 (1): the open-calls checkpoint of THIS stream, read at the record `at` was last given. `paths`: the call named these files (judged per copy
+     * with the copy's roots and holes); `none`: the call named no file (a stated residual: its result is kept); `unknown`: the call is not known
+     * (an overflow, a position the checkpoint no longer covers): its result is withheld, failing closed.
+     */
+    readonly calls?: (id: string) => readonly string[] | "none" | "unknown";
+    /** Called by `redactSpan` with the absolute offset of each segment it is about to redact, so `calls` can judge by position. */
+    readonly at?: (absoluteOffset: number) => void;
+    /** C42: told each parsed record of a span before it is judged (past the scan cursor, the hook learns calls and a second work tree from it). */
+    readonly observe?: (record: Record<string, unknown>) => void;
+}
 /**
  * Redact one NDJSON line. **Pure, total, and length-preserving.**
  *
@@ -144,7 +217,7 @@ export interface RedactedLine extends RedactionCounts {
  * (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;
+export declare function redactLine(line: string, projectRoots: readonly string[], rules: RedactionRules, resolver?: Containment, scope?: RedactionScope): RedactedLine;
 /**
  * Redact every complete line in a raw transcript span.
  *
@@ -154,7 +227,9 @@ export declare function redactLine(line: string, projectRoots: readonly string[]
  * 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): {
+export declare function redactSpan(span: Buffer, projectRoots: readonly string[], rules: RedactionRules, scope?: RedactionScope, 
+/** The absolute offset of `span[0]` in its file (`scope.at` is told each segment's). */
+spanStart?: number): {
     bytes: Buffer;
 } & RedactionCounts;
 /**