plumbbob 0.9.3 → 0.10.0

package/node_modules/checkride/dist/gate.d.ts

@@ -0,0 +1,180 @@
+/**
+ * `checkride gate` — the stop-gate verdict, harness-neutral.
+ *
+ * Every agent harness offers some "the turn is ending" hook, and checkride's
+ * gate hangs off it: run the repo's `check` script, and while it is red, refuse
+ * to let the turn finish. What differs between harnesses is only the *wire
+ * format* of that refusal — Claude Code reads stderr and blocks on exit 2,
+ * Cursor reads a `followup_message` on stdout and submits it as the next turn.
+ * The decision itself (is it dirty, is it green, which artifact should the agent
+ * read) is identical, so it lives here once and the generated hook scripts
+ * become two-line adapters that name their harness.
+ *
+ * That split is the point. Before this command, the whole body was duplicated
+ * shell inside `.claude/hooks/checkride-gate.sh`, untestable outside an e2e run
+ * and impossible to share with a second harness.
+ *
+ * The gate answers three verdicts, not two. Green and red are the pipeline's;
+ * the third is **could not run**, for a package manager that refused to start
+ * the check script at all — an `engines.node` pin the hook's Node does not
+ * satisfy is the common cause, and it exits non-zero exactly like a failing
+ * test. Reading that as red produced a permanent red no code change could clear,
+ * pointing at a `.check/summary.json` no run had written. So it names the cause
+ * instead of naming an artifact. See `./pm/launch.ts` for the classification and
+ * `./node-pin.ts` for the alignment that avoids it.
+ *
+ * Whether that third verdict *blocks* turns on one question: can the turn clear
+ * it? A missing `check` script can be fixed by the agent holding the edit tools,
+ * so the gate blocks and the agent fixes it. A Node the harness never put on
+ * `PATH` cannot, so the gate says so and stands down (see
+ * {@link reportStandDown}). Blocking on the second only re-asks an agent that
+ * has no lever to pull, which is not gating — it is a loop, and the way out of
+ * a loop is turning the gate off.
+ *
+ * Not to be confused with `../triage/gate.ts`, which also runs the `check`
+ * script: that one runs it *verbatim* as a reader's preflight and classifies the
+ * result for a report. This one appends `--strict --digest` because it IS the
+ * gate, and its output is a verdict for the harness, not prose for a human.
+ */
+import type { CheckrideConfig, GateProfile } from './config.js';
+import type { PinEnv } from './node-pin.js';
+import type { Out } from './orchestrator.js';
+import { type PackageManager } from './pm/index.js';
+/**
+ * The edit marker: touched by the harness's "a file changed" hook, checked here
+ * under `--if-dirty`, and cleared by a green gate. Dot-named so it can never
+ * collide with a slot's `<slot>.json`/`<slot>.stdout.txt` artifacts, which the
+ * orchestrator deletes per slot before a re-run — the marker must survive every
+ * run.
+ *
+ * It lives here, not in `agent-setup`, because the gate is what reads and clears
+ * it; the hook writers import it from this module to build the touch command.
+ */
+export declare const DIRTY_MARKER = ".check/.dirty";
+/**
+ * Whether a follow-up has already been auto-submitted this conversation: `1` if
+ * so, `0` if not. The generated stop-hook script reads the harness's stop payload
+ * and exports it; the hook writers import the name from here to spell the export.
+ *
+ * It exists for exactly one decision. Under Cursor the only channel that reaches
+ * a *user* is `followup_message`, and that field **submits a new turn** — so a
+ * stand-down spending it on every turn is the unbounded loop a stand-down exists
+ * to avoid. `0` means the budget of one has not been spent yet. checkride cannot
+ * work this out alone: the stop payload goes to the hook script, never to this
+ * process. See {@link reportStandDown}.
+ *
+ * **Absence is not `0`.** A script generated before this variable existed exports
+ * neither value, and reading absence as "go ahead" would loop under precisely the
+ * pairing checkride cannot detect — a new binary, an old script, and the
+ * `loop_limit: null` the gate's own hook entry asks for. So absence keeps the
+ * older and quieter behavior, and only an explicit `0` unlocks the message.
+ */
+export declare const GATE_RETRY_ENV = "CHECKRIDE_GATE_RETRY";
+/**
+ * Cursor's own hook config. It lives here rather than in `agent-setup/cursor.ts`
+ * for the same reason {@link DIRTY_MARKER} does: the gate *reads* it (see
+ * {@link deferredToCursor}), and the writer importing from the gate is the
+ * direction that has no cycle. `agent-setup/cursor.ts` re-exports it.
+ */
+export declare const CURSOR_HOOKS_FILE = ".cursor/hooks.json";
+/** Every harness whose stop-hook protocol the gate can speak. */
+export declare const HARNESS_NAMES: readonly ["claude", "cursor"];
+export type HarnessName = (typeof HARNESS_NAMES)[number];
+/**
+ * Spawn the check script and forward its output. Injectable so the command's
+ * branches are testable without a real toolchain.
+ *
+ * Both child streams are forwarded to **stderr**, never stdout: under
+ * `--harness cursor` this process's stdout must contain the hook's JSON and
+ * nothing else, and in a hook context the check's output is human-facing
+ * progress either way. Returns the exit code; a signal death is `null` and the
+ * caller reads it as red, because "not cleanly green" is the only distinction a
+ * gate needs.
+ */
+export type GateSpawn = (command: string, args: readonly string[], opts: {
+    cwd: string;
+    stderr: Out;
+    env: Record<string, string | undefined>;
+}) => Promise<number | null>;
+export type GateOptions = {
+    cwd?: string;
+    /** Skip the run entirely when the edit marker is absent (`--if-dirty`). */
+    ifDirty?: boolean;
+    /** Which harness's stop-hook protocol to answer in. Defaults to `claude`. */
+    harness?: HarnessName;
+    pm?: PackageManager;
+    stdout?: Out;
+    stderr?: Out;
+    spawn?: GateSpawn;
+    /** Process environment; injectable so {@link deferredToCursor} is testable. */
+    env?: Record<string, string | undefined>;
+    /** The Node-pin surface; injectable so alignment is testable without a version manager. */
+    pinEnv?: PinEnv;
+    /**
+     * The gate profile. Read from `checkride.config.json` when absent; pass `null`
+     * to run the full check whatever the config says.
+     */
+    profile?: GateProfile | null;
+    /** Wall-clock source for the elapsed time the gate reports; injectable for tests. */
+    now?: () => number;
+};
+export type GateResult = {
+    exitCode: number;
+    /** False when `--if-dirty` or the Cursor deferral short-circuited the run. */
+    ran: boolean;
+    green: boolean;
+    /**
+     * Why the package manager never started the check script, or `null` when it
+     * did. A refusal is not a red: it blocks the turn all the same, but nothing
+     * was checked and nothing was written, so no artifact describes this run.
+     */
+    refusal: string | null;
+};
+/**
+ * The gate's `check`-script invocation for `pm` (the alias `agent-setup`
+ * ensures exists). The hook IS a gate, so it runs `--strict` (zero checks
+ * running is exit 2, not a pass — docs/contract.md) and `--digest` (the
+ * token-bounded failure excerpt is a far better landing spot for an agent than
+ * raw summary.json). npm alone needs `--` to reach the script with flags;
+ * pnpm/yarn/bun forward them directly.
+ */
+export declare function checkArgs(pm: PackageManager, profile?: GateProfile | null): string[];
+/**
+ * The repo's gate profile, or `null` when it configures none and the gate should
+ * run the whole check.
+ *
+ * A profile with nothing in it is `null` too: `"gate": {}` narrows nothing, and
+ * carrying it forward would put "not the full check" on a verdict that *was* the
+ * full check.
+ */
+export declare function gateProfile(cwd: string, config?: CheckrideConfig | null): GateProfile | null;
+/**
+ * The repo's gate preflight, or `null` when it declares none.
+ *
+ * Read at *write* time rather than at run time, by the hook writers in
+ * `./agent-setup/`, and baked into the generated script as a literal path. Two
+ * reasons, and both are the point of the seam:
+ *
+ * 1. A preflight that only ran once checkride had started could not answer for
+ *    the case it exists to cover — a repo whose dependencies were never
+ *    installed, where `checkride gate` is the thing that cannot run.
+ * 2. Every `hooks add`/`agent-setup` re-reads this file, so the wiring is
+ *    restored on every refresh instead of being clobbered by it. That is exactly
+ *    the failure a `--preflight` flag would have kept: a teammate running the
+ *    bare command would silently drop the guard.
+ *
+ * Kept separate from {@link gateProfile} because a preflight narrows nothing —
+ * it must never put a "NOT the full check" clause on a verdict.
+ */
+export declare function gatePreflight(cwd: string, config?: CheckrideConfig | null): string | null;
+/**
+ * Run the gate and answer in `harness`'s protocol.
+ *
+ * The exit code is unchanged and stays as `docs/contract.md` promises it: 2 while
+ * blocked under `--harness claude`, always 0 under `--harness cursor`. What each
+ * harness *displays* is carried by the JSON body on stdout — see
+ * {@link reportGreen} and {@link reportRed} — because that is the only channel
+ * either harness renders for a human.
+ */
+export declare function runGate(options?: GateOptions): Promise<GateResult>;
+//# sourceMappingURL=gate.d.ts.map

package/node_modules/checkride/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGhE,OAAO,KAAK,EAAiB,MAAM,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,KAAK,EAAE,GAAG,EAAgB,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAIL,KAAK,cAAc,EAGpB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAE5C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,yBAAyB,CAAC;AAKrD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAStD,iEAAiE;AACjE,eAAO,MAAM,aAAa,+BAAgC,CAAC;AAC3D,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAKzD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,KACxE,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AA8C5B,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,EAAE,CAAC,EAAE,cAAc,CAAC;IACpB,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AA+BF;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,cAAc,EAAE,OAAO,GAAE,WAAW,GAAG,IAAW,GAAG,MAAM,EAAE,CAS1F;AAkBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,eAAe,GAAG,IAAsB,GAAG,WAAW,GAAG,IAAI,CAI7G;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,eAAe,GAAG,IAAsB,GAAG,MAAM,GAAG,IAAI,CAG1G;AAsZD;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiD5E"}