litmus-cli 1.4.32 → 1.4.34

package/dist/lib/capture-selftest.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Post-init capture self-test (ENG-2477).
+ *
+ * WHY THIS EXISTS. A candidate ran Cursor for a full hour on the CLI lane,
+ * produced zero captured prompts, and the report told the judge the tool was
+ * not used. Every safeguard `init` had for that was a config validator or a
+ * sentence: the hook entry is present, the logger file exists, "restart your
+ * editor". None of them asks the only question that matters, which is whether
+ * a prompt typed into the tool would reach Litmus. Checked on a real
+ * engineer's machine on 2026-09-22, `~/.cursor/hooks.json` pointed at a
+ * leftover debugging probe: valid JSON, executable, exits 0, returns a
+ * well-formed verdict, sends nothing. Every shape-check passes on that file
+ * and it captures nothing. There will be a third cause with the same symptom.
+ *
+ * WHAT IT DOES. For each tool `init` configures, read the command string back
+ * out of the file the TOOL reads, run it the way the tool would (through the
+ * shell, the tool's own payload shape on stdin), and then ask the backend
+ * whether the resulting event landed in `candidate_activity_logs`. The payload
+ * carries a nonce; the read-back matches on it. Same reasoning as the
+ * Codespaces image's build-time hook self-test (`install-cursor-hook.sh` §4:
+ * a synthetic payload on stdin, asserted rather than assumed), one step
+ * further: that test asserts the hook exits 0 with parseable stdout, this one
+ * asserts an event ARRIVED, because exit 0 and a parseable verdict is exactly
+ * what the leftover probe produced.
+ *
+ * WHAT IT PROVES AND WHAT IT DOES NOT. Arrival proves the whole chain from the
+ * config file's command string to a row in the database: the entry is ours,
+ * the path resolves, node runs, the logger finds the assessment, reads the
+ * token, and the upload reaches the backend. It does NOT prove the tool will
+ * invoke that command. Cursor and Codex read their hook config once at launch,
+ * so a tool that was already open when `init` wrote the file fires nothing
+ * until it is restarted; and Codex, Gemini and Copilot skip untrusted hooks in
+ * silence. Those cannot be probed from outside the tool, which is why the pass
+ * message still carries the restart instruction, sharpened by a process scan
+ * to name the tool that is open right now. The probe also runs with THIS
+ * terminal's environment, not the editor's: a `node` that resolves here and
+ * not inside a Dock-launched Cursor is a gap this check cannot see.
+ *
+ * WARN, NOT GATE — and why. A failing self-test prints a red block as the last
+ * thing `init` outputs, records the verdict in `.litmus/` and uploads it as a
+ * `capture_selftest` event so the report and the admin monitor can see it,
+ * and then lets the candidate proceed. It does not refuse to finish. Three
+ * reasons, in order of weight:
+ *
+ *   1. The candidate may use none of these tools. A Cursor hook that cannot
+ *      reach Litmus is no reason to block someone about to work with a web
+ *      chat or no AI at all, and `init` cannot tell which candidate it has.
+ *   2. The check depends on things outside the candidate's control — the
+ *      backend, their network, a corporate proxy. A gate turns a transient
+ *      outage of ours into a candidate locked out minutes before a live
+ *      interview, which is a worse harm than the one being prevented.
+ *   3. What a missed capture now costs the candidate is bounded. ENG-2476
+ *      makes a zero-prompt Cursor session read as unmeasurable rather than as
+ *      "did not use AI", so proceeding with a known gap yields a report that
+ *      names the gap, not a wrong score. A gate would also need an escape
+ *      hatch, and a candidate on a clock reaches for escape hatches blindly.
+ *
+ * The failure is made impossible to miss by placement and by record rather
+ * than by refusal: last block printed, coloured, actionable (`litmus doctor`
+ * repairs the hook files and re-runs this same check), and stored on both
+ * sides so nobody has to have been watching the terminal.
+ *
+ * Pure decisions live in exported functions so tests can drive them against a
+ * fake backend and a deliberately broken hook without going through `init`.
+ */
+import { type HookCapturableTool, type InstalledHookCommands } from "./ai-tracking.js";
+/** The event the logger records for a probe. Not a prompt; no reader counts it. */
+export declare const PROBE_EVENT_TYPE = "capture_selftest_probe";
+/** The CLI's own verdict, uploaded so the report and the monitor can see it. */
+export declare const RESULT_EVENT_TYPE = "capture_selftest";
+/** Where the verdict is kept locally, under `.litmus/`. */
+export declare const SELFTEST_RECORD_FILE = "capture-selftest.json";
+/**
+ * Per-hook budget. The logger waits up to 5s for a complete payload on stdin
+ * (STDIN_TIMEOUT_MS) and up to 2s for the upload (UPLOAD_TIMEOUT_MS); the
+ * hook runners themselves allow 10-30s. Generous on purpose: a probe that is
+ * killed early would report "no event" for a hook that was about to deliver.
+ */
+export declare const HOOK_TIMEOUT_MS = 15000;
+export declare const TOOL_LABELS: Record<HookCapturableTool, string>;
+export type ToolStatus = 
+/** The probe landed in candidate_activity_logs. Capture works for this tool. */
+"arrived"
+/** No Litmus entry in the file the tool reads. Nothing would fire. */
+ | "not_installed"
+/** The command ran (or failed to run) and nothing reached Litmus. */
+ | "no_event"
+/** The hook ran but the read-back itself failed; nothing is known. */
+ | "unverified";
+export interface ToolResult {
+    tool: HookCapturableTool;
+    label: string;
+    status: ToolStatus;
+    /** The config file that was read. */
+    file: string;
+    /** One line a candidate or a reviewer can act on. */
+    detail: string;
+    exitCode?: number | null;
+    stderrTail?: string;
+}
+export type Verdict = "pass" | "fail" | "unverified";
+export interface CaptureSelfTestReport {
+    verdict: Verdict;
+    at: string;
+    durationMs: number;
+    tools: ToolResult[];
+}
+/** The prompt text a probe carries. Carries the nonce so a pre-ENG-2477 logger's
+ *  `ai_prompt` record of it is still recognisable on the read-back. */
+export declare function probePromptText(nonce: string): string;
+/**
+ * The payload each tool's prompt hook would deliver, in that tool's shape, so
+ * the logger's real per-tool branch runs. Field sets are the ones the logger's
+ * extractPrompt documents per tool. `litmus_selftest` is the marker.
+ */
+export declare function probePayload(tool: HookCapturableTool, nonce: string, assessmentDir: string): Record<string, unknown>;
+export interface HookRun {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    /** The shell itself could not be started. */
+    spawnError?: string;
+}
+/**
+ * Run one hook command the way its tool would: handed to the platform shell
+ * (`/bin/sh -c` on POSIX, `cmd.exe /c` on Windows, which is what the command's
+ * quoting was written for — see quoteForShell), payload on stdin, then stdin
+ * closed. The command string is not parsed or rebuilt here; whatever the
+ * candidate's file says is what runs.
+ *
+ * THE TIMEOUT IS AUTHORITATIVE. A hook is a candidate-controlled command, and
+ * it can start something that outlives it while holding the stdout/stderr
+ * pipes it inherited. Waiting for `close` would then wait for that grandchild,
+ * and neither `init` nor `doctor` has an outer deadline, so the candidate
+ * would sit at a spinner, blocked by the check meant to protect them, at the
+ * worst possible moment (Greptile on #2600). So on the deadline this settles
+ * with what it has, destroys its ends of the pipes, and kills the whole
+ * process group (the shell is spawned as a group leader for exactly that), or
+ * the tree on Windows. A hook that has not delivered inside HOOK_TIMEOUT_MS
+ * has not delivered; nothing it does afterwards changes the verdict.
+ */
+export declare function runHookCommand(command: string, payload: Record<string, unknown>, opts?: {
+    cwd: string;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<HookRun>;
+export interface SelfTestOptions {
+    assessmentDir: string;
+    backendUrl: string;
+    token: string;
+    /** Injected for tests; defaults to reading the real config files. */
+    hooks?: InstalledHookCommands[];
+    /** Injected for tests. */
+    confirm?: (nonces: string[]) => Promise<{
+        arrived: string[];
+    }>;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Fire one probe per tool through its installed command(s), in parallel, then
+ * ask the backend which arrived. Never throws; every failure becomes a status
+ * on the tool it belongs to, and a read-back failure becomes "unverified"
+ * rather than "broken", because those call for different fixes.
+ */
+export declare function runCaptureSelfTest(opts: SelfTestOptions): Promise<CaptureSelfTestReport>;
+export declare function writeSelfTestRecord(assessmentDir: string, report: CaptureSelfTestReport): void;
+/**
+ * The event `init` uploads with the verdict. Typed `capture_selftest`, which
+ * every reader treats as ours-not-theirs (cli-tracking.ts channel map); it
+ * exists so a failed check is visible on the report and the admin monitor,
+ * not only in a terminal nobody is watching. Paths are dropped: a home
+ * directory is a name.
+ */
+export declare function selfTestResultEvent(report: CaptureSelfTestReport, source: "init" | "doctor"): Record<string, unknown>;
+/**
+ * Tools that read hook config only at launch and are running at this moment,
+ * from a process listing (lowercased `ps aux` / `tasklist`). This is the one
+ * cause the probe cannot see, so the pass message names the tool by name
+ * instead of saying "any tool". Path-anchored patterns, like detection.ts:
+ * the word inside a config-directory path is not the tool running.
+ */
+export declare function detectRunningHookTools(ps?: string): HookCapturableTool[];
+/**
+ * Lines for the terminal. A failure is a coloured block meant to be the LAST
+ * thing `init` prints; a pass is one green line, plus a yellow one naming any
+ * tool that is open right now and needs a restart before it will fire.
+ */
+export declare function renderCaptureSelfTest(report: CaptureSelfTestReport, opts: {
+    runningTools: HookCapturableTool[];
+    folderName: string;
+}): string[];
+/**
+ * The restart notice for tools that are open right now, shared by init's
+ * verdict block and doctor's failure lines so the two never disagree on the
+ * grammar or the claim.
+ */
+export declare function renderRestartNotice(tools: HookCapturableTool[], opts?: {
+    then: string;
+}): string[];
+//# sourceMappingURL=capture-selftest.d.ts.map

package/dist/lib/capture-selftest.d.ts.map

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