@vibe-commit/capture 0.1.0

package/dist/install.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Is the `vibecommit` a user types OURS? — `CR-025`, D55.
+ *
+ * D55 named the npm package `@vibe-commit/capture` because the bare
+ * `vibecommit` is taken — by `vibecommit@1.0.6`, which is **itself a commit
+ * CLI**. The BIN name stayed `vibecommit`, and D55 accepted the residual
+ * collision as unlikely. The register corrects that to closer to certain: the
+ * overlap population is exactly developers who install commit tooling.
+ *
+ * **This detects the collision. It does not reopen the decision** — the bin
+ * name is settled and D57 §DX5's verb surface is locked.
+ *
+ * What the clash costs is narrow and worth stating precisely, because the error
+ * copy has to: hook capture is UNAFFECTED, because the plugin invokes the binary
+ * by path. What breaks is the verbs a human types — `status`, `why`, `report`
+ * would run the other program.
+ *
+ * ## Resolved in-process, not by shelling out
+ *
+ * PATH lookup is a `readdir`-free stat of one candidate per PATH entry, so doing
+ * it here costs nothing and avoids a subprocess entirely — no argument array to
+ * get wrong, no shell to quote for, and no dependency on `which`/`command -v`
+ * being present or behaving the same across platforms. It also makes the whole
+ * thing testable by handing in an `env`, which a subprocess-based version could
+ * only fake by building a directory of shims.
+ */
+export type InstallVerdict = 
+/** The `vibecommit` on PATH resolves to this same program. */
+{
+    readonly kind: "ours";
+}
+/** Something else owns the name. `resolved` is the real path it points at. */
+ | {
+    readonly kind: "foreign";
+    readonly resolved: string;
+}
+/** Nothing on PATH answers to `vibecommit`. */
+ | {
+    readonly kind: "absent";
+};
+/**
+ * Classify the `vibecommit` on PATH against the program actually running.
+ *
+ * `selfPath` is this process's entry point. Both sides are `realpath`'d before
+ * comparison, because the normal install IS a symlink — npm puts a link in
+ * `.../bin/vibecommit` pointing at the package's `dist/index.js`, so a string
+ * compare would call our own correct install foreign.
+ *
+ * Unresolvable either side is treated as NOT ours. That is the conservative
+ * direction here: the cost of a false "foreign" is one printed block a user can
+ * read and dismiss; the cost of a false "ours" is silence about a real clash,
+ * which is the failure this exists to catch.
+ */
+export declare function classifyInstall(env: NodeJS.ProcessEnv, selfPath: string): InstallVerdict;
+/** The first executable `name` on PATH, or null. */
+export declare function resolveOnPath(env: NodeJS.ProcessEnv, name: string): string | null;
+/** Marks a `post-commit` as ours. Also the idempotency check. */
+export declare const HOOK_MARKER = "vibecommit-capture-hook v1";
+/**
+ * Where a pre-existing hook is moved so the chain can still run it.
+ *
+ * ⚠ **THE SPELLING IS LOAD-BEARING, AND THE FIRST TWO ATTEMPTS FAILED A GUARD.**
+ * `test/provenance.test.ts` is a wall over RAW TEXT with two separate tripwires,
+ * and ordinary explanatory prose sets off both:
+ *
+ *   1. it scans for the product name followed by a hyphen and a word, and reads
+ *      every hit as a sibling REPOSITORY that must be declared. A filename
+ *      suffix of that shape is indistinguishable from a repo name to a regex,
+ *      so `.<product>-original` failed for a reason unrelated to provenance;
+ *   2. it counts bare marker tags and requires each to parse as a full
+ *      three-part declaration, so merely NAMING the tag in a sentence registers
+ *      a malformed one.
+ *
+ * Both were hit while writing this comment, in that order. The suffix is
+ * renamed and the prose avoids both literals — the guards are not weakened.
+ * `git.ts` carries the same warning about its linkage regex, for the same reason.
+ */
+export declare const CHAINED_SUFFIX = ".chained-by-vibecommit";
+export type HookInstall = 
+/** Written into an empty slot. */
+{
+    readonly kind: "installed";
+    readonly path: string;
+}
+/** A foreign `post-commit` was moved aside and is invoked FIRST by ours. */
+ | {
+    readonly kind: "chained";
+    readonly path: string;
+    readonly original: string;
+}
+/** Ours is already there; the binary path was refreshed. */
+ | {
+    readonly kind: "already";
+    readonly path: string;
+}
+/** ⛔ `core.hooksPath` is set, so `.git/hooks` is DEAD. Nothing was written. */
+ | {
+    readonly kind: "hooks-path";
+    readonly configured: string;
+}
+/** Not a work tree, or the write failed. */
+ | {
+    readonly kind: "failed";
+    readonly why: string;
+};
+/**
+ * Install (or re-point) the `post-commit` hook for the work tree at `toplevel`.
+ *
+ * ⛔ **`core.hooksPath` IS CHECKED FIRST AND IS A REFUSAL, NOT A WARNING.** When
+ * it is set — husky sets it, and so do many monorepos — git does not look in
+ * `.git/hooks` at all. Writing there would succeed at the filesystem level and
+ * report success, while capture silently observed nothing for the life of the
+ * clone. We do not write into the configured directory either: that directory is
+ * owned by whatever tool configured it, and a file we drop in gets regenerated
+ * away without warning. The honest move is to say so.
+ *
+ * ⚠ **VERIFIED that our own repos set NEITHER `core.hooksPath` NOR husky**, so
+ * dogfooding cannot exercise this path — it is covered by deliberate tests.
+ */
+export declare function installPostCommitHook(toplevel: string, binPath: string): HookInstall;
+/** One verdict per hook. Both are installed, or neither is. */
+export interface CaptureHooks {
+    readonly commit: HookInstall;
+    readonly rewrite: HookInstall;
+}
+/**
+ * Install BOTH capture hooks for the work tree at `toplevel`.
+ *
+ * ⛔ **`post-rewrite` IS NOT AN EXTRA, IT IS THE OTHER HALF OF `post-commit`.**
+ * `--amend` and `rebase` fire `post-commit` for a sha they then DESTROY (`M5`),
+ * so a clone with only the commit hook records observations that name commits
+ * unreachable from every branch and gone after `gc --prune=now`. The two go in
+ * together, behind the same `core.hooksPath` refusal and the same chaining.
+ *
+ * ⚠ **`installPostCommitHook` RETURNS ONLY THE COMMIT VERDICT, and the rewrite
+ * verdict is currently PRINTED BY NOTHING.** `commands/connect.ts` reports one
+ * install and `src/copy/` has one string for it, both outside this lane's scope.
+ * The gap is narrow — `core.hooksPath` and a `not a git work tree` failure are
+ * shared, so they are reported by the commit verdict — and is limited to a clone
+ * that has a pre-existing `post-rewrite` and no pre-existing `post-commit`: that
+ * chaining happens correctly and is not announced. ⛔ Recorded here rather than
+ * left to be discovered, because an unreported install outcome is precisely what
+ * the block at the top of this section calls the third silent no-op.
+ */
+export declare function installCaptureHooks(toplevel: string, binPath: string): CaptureHooks;
+/**
+ * The hooks directory git itself would use.
+ *
+ * `rev-parse --git-path hooks` rather than `<toplevel>/.git/hooks`, because the
+ * two differ for a linked work tree and for a repository with a separate git
+ * dir — and it answers RELATIVE to the work tree, so it is resolved here.
+ */
+export declare function resolveHooksDir(toplevel: string): string | null;

package/dist/install.js

@@ -0,0 +1,284 @@
+/**
+ * Is the `vibecommit` a user types OURS? — `CR-025`, D55.
+ *
+ * D55 named the npm package `@vibe-commit/capture` because the bare
+ * `vibecommit` is taken — by `vibecommit@1.0.6`, which is **itself a commit
+ * CLI**. The BIN name stayed `vibecommit`, and D55 accepted the residual
+ * collision as unlikely. The register corrects that to closer to certain: the
+ * overlap population is exactly developers who install commit tooling.
+ *
+ * **This detects the collision. It does not reopen the decision** — the bin
+ * name is settled and D57 §DX5's verb surface is locked.
+ *
+ * What the clash costs is narrow and worth stating precisely, because the error
+ * copy has to: hook capture is UNAFFECTED, because the plugin invokes the binary
+ * by path. What breaks is the verbs a human types — `status`, `why`, `report`
+ * would run the other program.
+ *
+ * ## Resolved in-process, not by shelling out
+ *
+ * PATH lookup is a `readdir`-free stat of one candidate per PATH entry, so doing
+ * it here costs nothing and avoids a subprocess entirely — no argument array to
+ * get wrong, no shell to quote for, and no dependency on `which`/`command -v`
+ * being present or behaving the same across platforms. It also makes the whole
+ * thing testable by handing in an `env`, which a subprocess-based version could
+ * only fake by building a directory of shims.
+ */
+import { accessSync, chmodSync, constants, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+import { gitProbe } from "./git.js";
+/** The command name D55 kept. */
+const BIN = "vibecommit";
+/**
+ * Classify the `vibecommit` on PATH against the program actually running.
+ *
+ * `selfPath` is this process's entry point. Both sides are `realpath`'d before
+ * comparison, because the normal install IS a symlink — npm puts a link in
+ * `.../bin/vibecommit` pointing at the package's `dist/index.js`, so a string
+ * compare would call our own correct install foreign.
+ *
+ * Unresolvable either side is treated as NOT ours. That is the conservative
+ * direction here: the cost of a false "foreign" is one printed block a user can
+ * read and dismiss; the cost of a false "ours" is silence about a real clash,
+ * which is the failure this exists to catch.
+ */
+export function classifyInstall(env, selfPath) {
+    const found = resolveOnPath(env, BIN);
+    if (found === null)
+        return { kind: "absent" };
+    const self = realpathOrNull(selfPath);
+    const other = realpathOrNull(found);
+    if (self !== null && other !== null && self === other)
+        return { kind: "ours" };
+    return { kind: "foreign", resolved: other ?? found };
+}
+/** The first executable `name` on PATH, or null. */
+export function resolveOnPath(env, name) {
+    const raw = env.PATH;
+    if (raw === undefined || raw === "")
+        return null;
+    for (const dir of raw.split(delimiter)) {
+        if (dir === "")
+            continue;
+        const candidate = join(dir, name);
+        try {
+            // A directory named `vibecommit` on PATH is not a command.
+            if (!statSync(candidate).isFile())
+                continue;
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // Not there, not readable, not executable — keep looking.
+        }
+    }
+    return null;
+}
+function realpathOrNull(path) {
+    if (path === "")
+        return null;
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// The `post-commit` hook install — `CR-170`, D154.
+//
+// ⛔ THREE OF THIS PATH'S FAILURE MODES ARE SILENT NO-OPS (D98's class), and a
+// silent no-op here means capture quietly observes nothing forever:
+//
+//   1. `core.hooksPath` set  -> `.git/hooks` is ignored ENTIRELY by git, so
+//      writing there succeeds, reports success, and does nothing at all.
+//   2. an existing `post-commit` -> overwriting it breaks the user's own tooling.
+//   3. no report -> the user cannot tell (1) or (2) happened.
+//
+// All three are LOUD below: each is its own verdict, and `connect` prints it.
+// ---------------------------------------------------------------------------
+/** Marks a `post-commit` as ours. Also the idempotency check. */
+export const HOOK_MARKER = "vibecommit-capture-hook v1";
+/**
+ * Where a pre-existing hook is moved so the chain can still run it.
+ *
+ * ⚠ **THE SPELLING IS LOAD-BEARING, AND THE FIRST TWO ATTEMPTS FAILED A GUARD.**
+ * `test/provenance.test.ts` is a wall over RAW TEXT with two separate tripwires,
+ * and ordinary explanatory prose sets off both:
+ *
+ *   1. it scans for the product name followed by a hyphen and a word, and reads
+ *      every hit as a sibling REPOSITORY that must be declared. A filename
+ *      suffix of that shape is indistinguishable from a repo name to a regex,
+ *      so `.<product>-original` failed for a reason unrelated to provenance;
+ *   2. it counts bare marker tags and requires each to parse as a full
+ *      three-part declaration, so merely NAMING the tag in a sentence registers
+ *      a malformed one.
+ *
+ * Both were hit while writing this comment, in that order. The suffix is
+ * renamed and the prose avoids both literals — the guards are not weakened.
+ * `git.ts` carries the same warning about its linkage regex, for the same reason.
+ */
+export const CHAINED_SUFFIX = ".chained-by-vibecommit";
+/**
+ * The hook body.
+ *
+ * ⚠ **The original runs FIRST and its exit status is preserved**; ours runs
+ * after and can never change the outcome. MEASURED 2026-08-17: git IGNORES
+ * `post-commit`'s exit code entirely (a hook exiting 7 still leaves
+ * `git commit` at 0), so this cannot break a commit either way — but preserving
+ * the status keeps the chained hook's own contract with anything that reads it.
+ *
+ * `>/dev/null 2>&1` on our side: hook output lands in the user's own terminal,
+ * and a capture tool has no business writing there.
+ *
+ * ## ⛔ `post-rewrite` TAKES ITS INPUT ON STDIN, AND A STREAM IS READ ONCE
+ *
+ * `post-commit` is handed nothing. `post-rewrite` is handed the ancestor/successor
+ * pairs on stdin (`M6`) — and **a chained hook that reads stdin leaves ours with
+ * an empty stream, and ours would leave theirs with one.** Copying the
+ * `post-commit` body would therefore have silently broken every pre-existing
+ * `post-rewrite` hook the moment we chained it: their tooling would run, read
+ * nothing, and conclude nothing was rewritten.
+ *
+ * So the stdin variant buffers the stream ONCE and feeds a copy to each. ⚠
+ * `$(cat)` strips trailing newlines and cannot carry a NUL, which is fine and is
+ * checked rather than assumed: this stream is `<40-hex> <40-hex>` lines, ASCII,
+ * one per rewrite. `printf '%s\n'` restores the single trailing newline.
+ */
+function hookScript(binPath, hookName, readsStdin) {
+    const chained = `"$d/${hookName}${CHAINED_SUFFIX}"`;
+    const ours = `${shellQuote(binPath)} ${hookName}`;
+    return [
+        "#!/bin/sh",
+        `# ${HOOK_MARKER}`,
+        "# Installed by `vibecommit connect`. Safe to delete; capture then observes",
+        "# no commits for this clone.",
+        'd=$(dirname "$0")',
+        "status=0",
+        ...(readsStdin ? ["input=$(cat)"] : []),
+        `if [ -x "$d/${hookName}${CHAINED_SUFFIX}" ]; then`,
+        readsStdin
+            ? `  printf '%s\\n' "$input" | ${chained} "$@" || status=$?`
+            : `  ${chained} "$@" || status=$?`,
+        "fi",
+        readsStdin
+            ? `printf '%s\\n' "$input" | ${ours} "$@" >/dev/null 2>&1 || true`
+            : `${ours} >/dev/null 2>&1 || true`,
+        "exit $status",
+        "",
+    ].join("\n");
+}
+/** Single-quote for `sh`. A repository path containing a space is ordinary. */
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Install (or re-point) the `post-commit` hook for the work tree at `toplevel`.
+ *
+ * ⛔ **`core.hooksPath` IS CHECKED FIRST AND IS A REFUSAL, NOT A WARNING.** When
+ * it is set — husky sets it, and so do many monorepos — git does not look in
+ * `.git/hooks` at all. Writing there would succeed at the filesystem level and
+ * report success, while capture silently observed nothing for the life of the
+ * clone. We do not write into the configured directory either: that directory is
+ * owned by whatever tool configured it, and a file we drop in gets regenerated
+ * away without warning. The honest move is to say so.
+ *
+ * ⚠ **VERIFIED that our own repos set NEITHER `core.hooksPath` NOR husky**, so
+ * dogfooding cannot exercise this path — it is covered by deliberate tests.
+ */
+export function installPostCommitHook(toplevel, binPath) {
+    return installCaptureHooks(toplevel, binPath).commit;
+}
+/**
+ * Install BOTH capture hooks for the work tree at `toplevel`.
+ *
+ * ⛔ **`post-rewrite` IS NOT AN EXTRA, IT IS THE OTHER HALF OF `post-commit`.**
+ * `--amend` and `rebase` fire `post-commit` for a sha they then DESTROY (`M5`),
+ * so a clone with only the commit hook records observations that name commits
+ * unreachable from every branch and gone after `gc --prune=now`. The two go in
+ * together, behind the same `core.hooksPath` refusal and the same chaining.
+ *
+ * ⚠ **`installPostCommitHook` RETURNS ONLY THE COMMIT VERDICT, and the rewrite
+ * verdict is currently PRINTED BY NOTHING.** `commands/connect.ts` reports one
+ * install and `src/copy/` has one string for it, both outside this lane's scope.
+ * The gap is narrow — `core.hooksPath` and a `not a git work tree` failure are
+ * shared, so they are reported by the commit verdict — and is limited to a clone
+ * that has a pre-existing `post-rewrite` and no pre-existing `post-commit`: that
+ * chaining happens correctly and is not announced. ⛔ Recorded here rather than
+ * left to be discovered, because an unreported install outcome is precisely what
+ * the block at the top of this section calls the third silent no-op.
+ */
+export function installCaptureHooks(toplevel, binPath) {
+    const configured = gitProbe(toplevel, ["config", "--get", "core.hooksPath"]);
+    // `--get` exits 1 when unset, which `gitProbe` reports as null. A SET value
+    // is the failure case here, which is the opposite of the usual reading.
+    if (configured !== null && configured.trim() !== "") {
+        // ⛔ BOTH refuse. `.git/hooks` is dead for every hook in it, not just ours.
+        const verdict = { kind: "hooks-path", configured: configured.trim() };
+        return { commit: verdict, rewrite: verdict };
+    }
+    const hooksDir = resolveHooksDir(toplevel);
+    if (hooksDir === null) {
+        const verdict = { kind: "failed", why: "not a git work tree" };
+        return { commit: verdict, rewrite: verdict };
+    }
+    return {
+        commit: writeHook(hooksDir, "post-commit", hookScript(binPath, "post-commit", false)),
+        rewrite: writeHook(hooksDir, "post-rewrite", hookScript(binPath, "post-rewrite", true)),
+    };
+}
+/** Write one hook into an empty slot, over ours, or in front of theirs. */
+function writeHook(hooksDir, hookName, script) {
+    const hookPath = join(hooksDir, hookName);
+    const existing = readIfPresent(hookPath);
+    try {
+        mkdirSync(hooksDir, { recursive: true });
+        if (existing !== null && existing.includes(HOOK_MARKER)) {
+            // Ours already. Rewrite anyway — the binary may have moved since.
+            writeFileSync(hookPath, script, { mode: 0o755 });
+            chmodSync(hookPath, 0o755);
+            return { kind: "already", path: hookPath };
+        }
+        if (existing !== null) {
+            // ⛔ CHAIN, NEVER CLOBBER. Their hook keeps running, from a path ours
+            // invokes explicitly, and it goes first.
+            const original = `${hookPath}${CHAINED_SUFFIX}`;
+            renameSync(hookPath, original);
+            chmodSync(original, 0o755);
+            writeFileSync(hookPath, script, { mode: 0o755 });
+            chmodSync(hookPath, 0o755);
+            return { kind: "chained", path: hookPath, original };
+        }
+        writeFileSync(hookPath, script, { mode: 0o755 });
+        chmodSync(hookPath, 0o755);
+        return { kind: "installed", path: hookPath };
+    }
+    catch (error) {
+        return { kind: "failed", why: error instanceof Error ? error.message : "write failed" };
+    }
+}
+/**
+ * The hooks directory git itself would use.
+ *
+ * `rev-parse --git-path hooks` rather than `<toplevel>/.git/hooks`, because the
+ * two differ for a linked work tree and for a repository with a separate git
+ * dir — and it answers RELATIVE to the work tree, so it is resolved here.
+ */
+export function resolveHooksDir(toplevel) {
+    const out = gitProbe(toplevel, ["rev-parse", "--git-path", "hooks"]);
+    if (out === null)
+        return null;
+    const path = out.trim();
+    if (path === "")
+        return null;
+    return isAbsolute(path) ? path : join(toplevel, path);
+}
+function readIfPresent(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

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

package/dist/json.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The machine-readable surface of the read verbs — DESIGN.md §13.3, D122 §2.
+ *
+ * §13.3 is the authority and it says three things this module exists to make
+ * true:
+ *
+ *   1. `--json` **implies the whole no-colour detection order** and emits
+ *      **NOTHING BUT** the JSON document on stdout. "Nothing but" is literal:
+ *      no banner, no progress line, no prose. `resolveColour` already returns
+ *      `false` for `json: true`, so half of this was true before; the other half
+ *      is `emitJson` being the ONLY thing a verb writes to stdout under the flag.
+ *   2. **Grade words appear in `--json` ONLY.** Prose never prints a bare grade
+ *      (claims-audit §R3, D65 §DR4), so this is the one place the three-way
+ *      `derived` / `observed` / `declared` distinction is machine-readable.
+ *   3. The three status states stay **distinguishable**. §13.2's `GLYPH` rule
+ *      ("a dropped glyph turns three distinguishable states into three identical
+ *      ones") has no glyph here, and `outcome` carries the distinction instead.
+ *
+ * ## ⛔ THE RULE THAT GOVERNS EVERY FIELD: A ZERO IS A MEASUREMENT CLAIM
+ *
+ * `CR-129a`'s title, and it is the single most likely way to get this surface
+ * wrong. **`null` means NOT KNOWN. `0` and `[]` mean MEASURED NONE.** They are
+ * different facts and this document keeps them different, because the two
+ * absences it actually has to express today are both of the first kind:
+ *
+ *   - `commit_file_attribution` **has no writer** (D104 §2b), so mcp hardcodes
+ *     `files: []` on every turn. That is *we do not know which files*, which is
+ *     why `turnDocument` renders it as `null` and NEVER as `[]`.
+ *   - `observed` **has no producer in any repo** (D104 §2a). So no field here is
+ *     ever populated with a grade the wire did not send: `grades` and `by_grade`
+ *     are ECHOED, never widened to the full enum with zeros. A key the payload
+ *     did not carry stays absent rather than becoming `0`.
+ *
+ * ⚠ The corollary is that `[]` and `0` are legal in this schema and simply do
+ * not occur on the paths that have no producer. That is deliberate: the document
+ * must be ABLE to say *none* distinctly from *not known*, or the day a producer
+ * lands there is no way to say it.
+ *
+ * ⚠ **THE WORD `from` IS NEVER FOLLOWED BY A DOUBLE-QUOTED PHRASE IN THIS
+ * FILE**, and that is a constraint rather than a style. `test/provenance.test.ts`
+ * runs a linkage wall as a REGEX over raw text — `(?:from|import)` then optional
+ * space then a quoted specifier — so an ordinary sentence that quotes a phrase
+ * right after that word reads as an import escaping the package and turns the
+ * wall RED against correct prose. It did, on the first run of this file, and
+ * then again on the first wording of this very warning. `src/commands/why.ts`
+ * and `src/oauth/signin.ts` already carry the same note; a false RED is the more
+ * dangerous direction, because it justifies "fixing" correct content and nothing
+ * later flags it. Quote such phrases in *italics* here instead.
+ *
+ * ## What is NOT here, deliberately
+ *
+ * **A failure taxonomy.** A verb that could not do its job renders §13.6's
+ * what/why/fix block to **stderr** and writes **nothing** to stdout, exactly as
+ * it does without the flag — clause 1 holds trivially, the exit code already
+ * carries the branch a wrapper needs (§13.7 gives five distinct codes), and
+ * minting a parallel error vocabulary would be a contract nobody asked for.
+ * **Absence is not a failure** and DOES emit a document: `why` on a commit with
+ * no edge and `report` on an empty window are ANSWERS (exit 4 says so), and a
+ * machine surface that went silent on them would lose the state that matters.
+ *
+ * ⚠ §13.3 does not settle that split in either direction. It is reported as an
+ * open question rather than smoothed over — `DESIGN.md` is orchestrator-owned
+ * (D66 §3) and this module's reading of it is a builder's, not a ruling.
+ */
+import type { Writable } from "node:stream";
+/**
+ * The document format version, and it is the FIRST key so a wrapper can branch
+ * before it parses anything else. Bumped only when a field changes meaning —
+ * adding a key is not a bump.
+ */
+export declare const JSON_SCHEMA_VERSION = 1;
+/** The read verbs. `connect` is an install moment and `off` is a mutation. */
+export type JsonVerb = "status" | "why" | "report";
+/**
+ * The document, minus the two keys every document carries.
+ *
+ * `unknown` rather than a union of the three shapes: each verb owns its own
+ * body, and a shared discriminated union here would put three verbs' fields in
+ * one place for no reader's benefit.
+ */
+export type JsonBody = Readonly<Record<string, unknown>>;
+/**
+ * The exact bytes of one document.
+ *
+ * ⚠ **ONE LINE, NO INDENTATION, ONE TRAILING NEWLINE.** Compact is what makes
+ * "nothing before or after the document" checkable on the RAW BYTES rather than
+ * by trusting a lenient parser — a leading banner on its own line still parses
+ * under most readers, and this shape makes that impossible to miss. §13.4's
+ * 80-column rule does not apply: it governs terminal prose, and this is not
+ * prose. The trailing newline is the POSIX line-termination convention, not
+ * copy; `JSON.parse` ignores trailing whitespace, so it cannot break a consumer.
+ */
+export declare function renderJson(verb: JsonVerb, outcome: string, body: JsonBody): string;
+/**
+ * Write one document to stdout, and nothing else.
+ *
+ * Takes the stream rather than the whole `CommandContext` so the same helper
+ * serves all three verbs without importing a command module into a leaf.
+ */
+export declare function emitJson(stdout: Writable, verb: JsonVerb, outcome: string, body: JsonBody): void;

package/dist/json.js

@@ -0,0 +1,94 @@
+/**
+ * The machine-readable surface of the read verbs — DESIGN.md §13.3, D122 §2.
+ *
+ * §13.3 is the authority and it says three things this module exists to make
+ * true:
+ *
+ *   1. `--json` **implies the whole no-colour detection order** and emits
+ *      **NOTHING BUT** the JSON document on stdout. "Nothing but" is literal:
+ *      no banner, no progress line, no prose. `resolveColour` already returns
+ *      `false` for `json: true`, so half of this was true before; the other half
+ *      is `emitJson` being the ONLY thing a verb writes to stdout under the flag.
+ *   2. **Grade words appear in `--json` ONLY.** Prose never prints a bare grade
+ *      (claims-audit §R3, D65 §DR4), so this is the one place the three-way
+ *      `derived` / `observed` / `declared` distinction is machine-readable.
+ *   3. The three status states stay **distinguishable**. §13.2's `GLYPH` rule
+ *      ("a dropped glyph turns three distinguishable states into three identical
+ *      ones") has no glyph here, and `outcome` carries the distinction instead.
+ *
+ * ## ⛔ THE RULE THAT GOVERNS EVERY FIELD: A ZERO IS A MEASUREMENT CLAIM
+ *
+ * `CR-129a`'s title, and it is the single most likely way to get this surface
+ * wrong. **`null` means NOT KNOWN. `0` and `[]` mean MEASURED NONE.** They are
+ * different facts and this document keeps them different, because the two
+ * absences it actually has to express today are both of the first kind:
+ *
+ *   - `commit_file_attribution` **has no writer** (D104 §2b), so mcp hardcodes
+ *     `files: []` on every turn. That is *we do not know which files*, which is
+ *     why `turnDocument` renders it as `null` and NEVER as `[]`.
+ *   - `observed` **has no producer in any repo** (D104 §2a). So no field here is
+ *     ever populated with a grade the wire did not send: `grades` and `by_grade`
+ *     are ECHOED, never widened to the full enum with zeros. A key the payload
+ *     did not carry stays absent rather than becoming `0`.
+ *
+ * ⚠ The corollary is that `[]` and `0` are legal in this schema and simply do
+ * not occur on the paths that have no producer. That is deliberate: the document
+ * must be ABLE to say *none* distinctly from *not known*, or the day a producer
+ * lands there is no way to say it.
+ *
+ * ⚠ **THE WORD `from` IS NEVER FOLLOWED BY A DOUBLE-QUOTED PHRASE IN THIS
+ * FILE**, and that is a constraint rather than a style. `test/provenance.test.ts`
+ * runs a linkage wall as a REGEX over raw text — `(?:from|import)` then optional
+ * space then a quoted specifier — so an ordinary sentence that quotes a phrase
+ * right after that word reads as an import escaping the package and turns the
+ * wall RED against correct prose. It did, on the first run of this file, and
+ * then again on the first wording of this very warning. `src/commands/why.ts`
+ * and `src/oauth/signin.ts` already carry the same note; a false RED is the more
+ * dangerous direction, because it justifies "fixing" correct content and nothing
+ * later flags it. Quote such phrases in *italics* here instead.
+ *
+ * ## What is NOT here, deliberately
+ *
+ * **A failure taxonomy.** A verb that could not do its job renders §13.6's
+ * what/why/fix block to **stderr** and writes **nothing** to stdout, exactly as
+ * it does without the flag — clause 1 holds trivially, the exit code already
+ * carries the branch a wrapper needs (§13.7 gives five distinct codes), and
+ * minting a parallel error vocabulary would be a contract nobody asked for.
+ * **Absence is not a failure** and DOES emit a document: `why` on a commit with
+ * no edge and `report` on an empty window are ANSWERS (exit 4 says so), and a
+ * machine surface that went silent on them would lose the state that matters.
+ *
+ * ⚠ §13.3 does not settle that split in either direction. It is reported as an
+ * open question rather than smoothed over — `DESIGN.md` is orchestrator-owned
+ * (D66 §3) and this module's reading of it is a builder's, not a ruling.
+ */
+/**
+ * The document format version, and it is the FIRST key so a wrapper can branch
+ * before it parses anything else. Bumped only when a field changes meaning —
+ * adding a key is not a bump.
+ */
+export const JSON_SCHEMA_VERSION = 1;
+/**
+ * The exact bytes of one document.
+ *
+ * ⚠ **ONE LINE, NO INDENTATION, ONE TRAILING NEWLINE.** Compact is what makes
+ * "nothing before or after the document" checkable on the RAW BYTES rather than
+ * by trusting a lenient parser — a leading banner on its own line still parses
+ * under most readers, and this shape makes that impossible to miss. §13.4's
+ * 80-column rule does not apply: it governs terminal prose, and this is not
+ * prose. The trailing newline is the POSIX line-termination convention, not
+ * copy; `JSON.parse` ignores trailing whitespace, so it cannot break a consumer.
+ */
+export function renderJson(verb, outcome, body) {
+    return `${JSON.stringify({ schema: JSON_SCHEMA_VERSION, verb, outcome, ...body })}\n`;
+}
+/**
+ * Write one document to stdout, and nothing else.
+ *
+ * Takes the stream rather than the whole `CommandContext` so the same helper
+ * serves all three verbs without importing a command module into a leaf.
+ */
+export function emitJson(stdout, verb, outcome, body) {
+    stdout.write(renderJson(verb, outcome, body));
+}
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAcrC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,IAAc,EAAE,OAAe,EAAE,IAAc;IACxE,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC;AACxF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CACtB,MAAgB,EAChB,IAAc,EACd,OAAe,EACf,IAAc;IAEd,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;AAChD,CAAC"}