@cairn-tool/cairn 3.3.1 → 3.5.0

package/dist/qa/agents/index.js

@@ -0,0 +1,83 @@
+import { UserError, which } from "../config.js";
+import { findExplicitAgent } from "../config.js";
+import { claudeCodeProfile } from "./claude-code.js";
+import { cursorProfile } from "./cursor.js";
+/**
+ * Every backend `qa run` can spawn.
+ *
+ * Registering another assistant is a new module plus a line here. Nothing
+ * outside this directory may branch on an agent's name: argv, event parsing,
+ * and the default model are read from the profile.
+ */
+export const AGENTS = [cursorProfile, claudeCodeProfile];
+for (const profile of AGENTS) {
+    if (profile.maxParallel !== undefined &&
+        (!Number.isInteger(profile.maxParallel) || profile.maxParallel < 1)) {
+        throw new Error(`qa agent profile ${profile.name} maxParallel must be >= 1`);
+    }
+}
+export const SUPPORTED_AGENTS = AGENTS.map((profile) => profile.name);
+const BY_NAME = new Map(AGENTS.map((profile) => [profile.name, profile]));
+const binaryCache = new Map();
+export function resolveAgent(name) {
+    const profile = BY_NAME.get(name);
+    if (!profile) {
+        throw new UserError(`Unknown agent: ${name} (known: ${SUPPORTED_AGENTS.join(", ")})`);
+    }
+    return profile;
+}
+export function defaultModels() {
+    return Object.fromEntries(AGENTS.map((profile) => [profile.name, profile.defaultModel]));
+}
+/**
+ * Resolve the executable for one profile. An explicit `--agent` path overrides
+ * every backend — that is the fake-agent test hook. PATH lookup is lazy and
+ * cached per profile so a cursor-only queue does not fail because `claude` is
+ * absent.
+ */
+export function resolveBinary(name, explicit) {
+    if (explicit)
+        return findExplicitAgent(explicit);
+    const hit = binaryCache.get(name);
+    if (hit)
+        return hit;
+    const profile = resolveAgent(name);
+    for (const candidate of profile.binaries) {
+        const found = which(candidate);
+        if (found) {
+            binaryCache.set(name, found);
+            return found;
+        }
+    }
+    throw new UserError(`${profile.binaries[0]} not on PATH; pass --agent /path/to/${profile.binaries[0]}`);
+}
+/**
+ * The executable to *display* for a profile, for --dry-run only.
+ *
+ * Falls back to the profile's first candidate name when nothing is on PATH: previewing a
+ * queue launches nothing, so requiring the backend to be installed would make `qa run
+ * --dry-run` fail on exactly the machine you would preview a queue on — and would make the
+ * e2e suite depend on cursor-agent and claude being present on the CI runner. An explicit
+ * --agent is still validated, because a bad path there is a real invocation error.
+ */
+export function displayBinary(name, explicit) {
+    if (explicit)
+        return findExplicitAgent(explicit);
+    try {
+        return resolveBinary(name, null);
+    }
+    catch {
+        return resolveAgent(name).binaries[0];
+    }
+}
+export function agentCaps(parallel) {
+    const caps = new Map();
+    for (const profile of AGENTS) {
+        // An absent cap means --parallel alone decides, so a queue of one backend can use
+        // every slot the user asked for.
+        caps.set(profile.name, Math.min(profile.maxParallel ?? parallel, parallel));
+    }
+    return caps;
+}
+export { asEventList } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/qa/agents/index.js.map

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

package/dist/qa/agents/types.d.ts

@@ -0,0 +1,61 @@
+import type { Usage } from "../outcome.js";
+/**
+ * Normalized harness event. Slot.applyEvent consumes only this; vendor JSON never
+ * reaches the TUI, reports, or tracker.
+ */
+export type QaEvent = {
+    kind: "text";
+    text: string;
+    sessionId?: string;
+} | {
+    kind: "thinking";
+    phase: "delta" | "completed";
+    text?: string;
+    sessionId?: string;
+} | {
+    kind: "tool";
+    phase: "started" | "completed";
+    name: string;
+    summary: string;
+    failed?: boolean;
+    sessionId?: string;
+} | {
+    kind: "usage";
+    usage: Usage;
+    error?: string;
+    sessionId?: string;
+} | {
+    kind: "init";
+    model?: string;
+    sessionId?: string;
+};
+export type NormalizedEvents = QaEvent | QaEvent[] | null;
+/** Enough of a case for argv construction without importing Case. */
+export interface AgentArgvInput {
+    repo: string;
+    model: string;
+    prompt: string;
+}
+/**
+ * Per-backend profile. Registering another assistant is a new module plus a
+ * line in index.ts. Nothing outside src/qa/agents/ may branch on an agent's name.
+ */
+export interface QaAgentProfile {
+    readonly name: string;
+    /** PATH candidates, first match wins. */
+    readonly binaries: readonly string[];
+    readonly defaultModel: string;
+    /**
+     * A real concurrency limit for this backend, or absent when the vendor imposes none we
+     * know of. Combined with --parallel by min(), so an absent cap means --parallel alone
+     * decides. Never set this to the *default* of --parallel: that silently caps the flag.
+     * Must be >= 1 when present.
+     */
+    readonly maxParallel?: number;
+    buildArgv(input: AgentArgvInput, binary: string): string[];
+    normalize(raw: Record<string, unknown>): NormalizedEvents;
+}
+export declare function asEventList(events: NormalizedEvents): QaEvent[];
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function sessionIdOf(raw: Record<string, unknown>): string | undefined;
+export declare function num(value: unknown): number | undefined;

package/dist/qa/agents/types.js

@@ -0,0 +1,18 @@
+export function asEventList(events) {
+    if (events === null)
+        return [];
+    if (Array.isArray(events))
+        return [...events];
+    return [events];
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function sessionIdOf(raw) {
+    const value = raw["session_id"];
+    return value ? String(value) : undefined;
+}
+export function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+//# sourceMappingURL=types.js.map

package/dist/qa/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/qa/agents/types.ts"],"names":[],"mappings":"AAmEA,MAAM,UAAU,WAAW,CAAC,MAAwB;IAClD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC;IAC9C,OAAO,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAA4B;IACtD,MAAM,KAAK,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,KAAc;IAChC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACjF,CAAC"}

package/dist/qa/async.d.ts

@@ -0,0 +1,27 @@
+/** A latch workers await while dispatch is paused. Opening it wakes everyone at once. */
+export declare class Gate {
+    private opened;
+    private waiters;
+    constructor(opened?: boolean);
+    get isOpen(): boolean;
+    set(opened: boolean): void;
+    wait(): Promise<void>;
+}
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+export declare function signalNumber(sig: NodeJS.Signals): number;
+/**
+ * Actions that must run exactly once, on every exit path. LIFO, idempotent, synchronous only —
+ * a `process.on('exit')` handler cannot await. The terminal restore and the lock release both
+ * register here rather than installing competing handlers that fight over process.exit.
+ *
+ * Signals are deliberately NOT handled here: the harness maps them to requestStop() so a run
+ * unwinds gracefully, and the resulting normal exit fires this via 'exit'.
+ */
+export declare class Cleanup {
+    private actions;
+    private ran;
+    private installed;
+    add(action: () => void): void;
+    run(): void;
+    install(onFatal: (err: unknown) => void): void;
+}

package/dist/qa/async.js

@@ -0,0 +1,91 @@
+import { constants as osConstants } from "node:os";
+/** A latch workers await while dispatch is paused. Opening it wakes everyone at once. */
+export class Gate {
+    opened;
+    waiters = [];
+    constructor(opened = true) {
+        this.opened = opened;
+    }
+    get isOpen() {
+        return this.opened;
+    }
+    set(opened) {
+        this.opened = opened;
+        if (!opened)
+            return;
+        const pending = this.waiters;
+        this.waiters = [];
+        for (const wake of pending)
+            wake();
+    }
+    wait() {
+        if (this.opened)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export function signalNumber(sig) {
+    return osConstants.signals[sig] ?? 0;
+}
+/**
+ * Actions that must run exactly once, on every exit path. LIFO, idempotent, synchronous only —
+ * a `process.on('exit')` handler cannot await. The terminal restore and the lock release both
+ * register here rather than installing competing handlers that fight over process.exit.
+ *
+ * Signals are deliberately NOT handled here: the harness maps them to requestStop() so a run
+ * unwinds gracefully, and the resulting normal exit fires this via 'exit'.
+ */
+export class Cleanup {
+    actions = [];
+    ran = false;
+    installed = false;
+    add(action) {
+        this.actions.push(action);
+    }
+    run() {
+        if (this.ran)
+            return;
+        this.ran = true;
+        for (const action of [...this.actions].reverse()) {
+            try {
+                action();
+            }
+            catch {
+                /* a failing cleanup must not block the others */
+            }
+        }
+    }
+    install(onFatal) {
+        if (this.installed)
+            return;
+        this.installed = true;
+        process.on("exit", () => this.run());
+        const fatal = (err) => {
+            this.run();
+            onFatal(err);
+            process.exit(1);
+        };
+        process.on("uncaughtException", fatal);
+        process.on("unhandledRejection", fatal);
+    }
+}
+//# sourceMappingURL=async.js.map

package/dist/qa/async.js.map

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

package/dist/qa/casefile.d.ts

@@ -0,0 +1,35 @@
+/** One `_plans/tc-<N>.yaml`, validated. Everything the harness needs about a case. */
+export interface CaseFile {
+    /** `tc-24` — the identity, derived from the filename and cross-checked against `id`. */
+    name: string;
+    number: number;
+    /** Absolute path to the YAML itself. */
+    file: string;
+    /** YAML `id`, as written (`TC-24`). */
+    id: string;
+    /** YAML `name` — the human title. */
+    title: string;
+    agent: string;
+    /** YAML `model`, or null when the case defers to `--model`. */
+    model: string | null;
+    parallel: boolean;
+    tags: string[];
+    /** The plan body, verbatim. */
+    plan: string;
+}
+/** `tc-24.yaml` -> `tc-24`, or null when the name is not a case file at all. */
+export declare function caseNameOf(entry: string): string | null;
+/**
+ * Validate one parsed YAML document against the schema. Every problem is reported, not just the
+ * first, so a single run tells the author everything wrong with the file.
+ */
+export declare function validateCaseFile(doc: unknown, name: string, file: string, fail: (message: string) => void): CaseFile | null;
+export interface LoadResult {
+    cases: CaseFile[];
+    errors: string[];
+}
+/**
+ * Every `tc-<N>.yaml` under `_plans/`, parsed and validated. Errors accumulate across files so one
+ * invocation reports every broken case rather than stopping at the first.
+ */
+export declare function loadCaseFiles(plansDir: string): LoadResult;

package/dist/qa/casefile.js

@@ -0,0 +1,181 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { MAX_PROMPT_BYTES } from "./config.js";
+import { SUPPORTED_AGENTS } from "./agents/index.js";
+const KEYS = new Set(["id", "name", "agent", "model", "parallel", "tags", "plan"]);
+const YAML_EXT = [".yaml", ".yml"];
+const isFile = (path) => {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** `tc-24.yaml` -> `tc-24`, or null when the name is not a case file at all. */
+export function caseNameOf(entry) {
+    for (const ext of YAML_EXT) {
+        if (!entry.endsWith(ext))
+            continue;
+        const name = entry.slice(0, -ext.length);
+        return /^tc-\d+$/.test(name) ? name : null;
+    }
+    return null;
+}
+/** A parse error carrying the position `yaml` gave us, so the message can point at a line. */
+function parseErrorText(err) {
+    const pos = err.linePos;
+    const where = pos && pos[0] ? `${pos[0].line}:${pos[0].col}: ` : "";
+    const message = err instanceof Error ? err.message : String(err);
+    // yaml already prefixes its message with the position; keep ours and drop the duplicate block.
+    return `${where}${message.split("\n")[0]}`;
+}
+function str(value, key, chk) {
+    if (typeof value !== "string") {
+        chk.fail(`\`${key}\` must be a string`);
+        return null;
+    }
+    if (value.trim() === "") {
+        chk.fail(`\`${key}\` must not be empty`);
+        return null;
+    }
+    return value;
+}
+/**
+ * Validate one parsed YAML document against the schema. Every problem is reported, not just the
+ * first, so a single run tells the author everything wrong with the file.
+ */
+export function validateCaseFile(doc, name, file, fail) {
+    if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
+        fail("expected a YAML mapping at the top level");
+        return null;
+    }
+    const raw = doc;
+    const chk = { fail };
+    const unknown = Object.keys(raw).filter((k) => !KEYS.has(k));
+    if (unknown.length > 0) {
+        fail(`unknown key(s): ${unknown.join(", ")} (expected ${[...KEYS].join(", ")})`);
+    }
+    const number = Number.parseInt(name.slice("tc-".length), 10);
+    const id = str(raw["id"], "id", chk);
+    if (id !== null) {
+        const match = /^tc-(\d+)$/i.exec(id.trim());
+        if (!match)
+            fail(`\`id\` must look like TC-24, not ${JSON.stringify(id)}`);
+        else if (Number.parseInt(match[1], 10) !== number) {
+            fail(`\`id\` is ${id.trim()} but the file is named ${name}`);
+        }
+    }
+    const title = str(raw["name"], "name", chk);
+    const plan = str(raw["plan"], "plan", chk);
+    let agent = SUPPORTED_AGENTS[0];
+    if (raw["agent"] !== undefined) {
+        const value = str(raw["agent"], "agent", chk);
+        if (value !== null) {
+            if (!SUPPORTED_AGENTS.includes(value)) {
+                fail(`\`agent\` must be one of ${SUPPORTED_AGENTS.join(", ")}, not ${JSON.stringify(value)}`);
+            }
+            else
+                agent = value;
+        }
+    }
+    let model = null;
+    if (raw["model"] !== undefined)
+        model = str(raw["model"], "model", chk);
+    let parallel = true;
+    if (raw["parallel"] !== undefined) {
+        if (typeof raw["parallel"] !== "boolean")
+            fail("`parallel` must be true or false");
+        else
+            parallel = raw["parallel"];
+    }
+    const tags = [];
+    if (raw["tags"] !== undefined) {
+        if (!Array.isArray(raw["tags"])) {
+            fail("`tags` must be a list of strings");
+        }
+        else {
+            for (const [i, tag] of raw["tags"].entries()) {
+                const value = str(tag, `tags[${i}]`, chk);
+                if (value !== null)
+                    tags.push(value.trim());
+            }
+            if (tags.length > 0 && parallel) {
+                fail("`tags` only constrains a case with `parallel: false`; remove one or the other");
+            }
+        }
+    }
+    if (plan !== null) {
+        // The plan travels in the prompt argv, so an unbounded one would die at spawn with E2BIG.
+        const bytes = Buffer.byteLength(plan, "utf8");
+        if (bytes > MAX_PROMPT_BYTES) {
+            fail(`\`plan\` is ${bytes} bytes; the limit is ${MAX_PROMPT_BYTES}`);
+        }
+    }
+    if (id === null || title === null || plan === null)
+        return null;
+    return { name, number, file, id: id.trim(), title, agent, model, parallel, tags, plan };
+}
+/**
+ * Every `tc-<N>.yaml` under `_plans/`, parsed and validated. Errors accumulate across files so one
+ * invocation reports every broken case rather than stopping at the first.
+ */
+export function loadCaseFiles(plansDir) {
+    let entries;
+    try {
+        entries = readdirSync(plansDir);
+    }
+    catch {
+        return { cases: [], errors: [] };
+    }
+    const errors = [];
+    const byName = new Map();
+    const collided = new Set();
+    const found = [];
+    for (const entry of entries.sort()) {
+        const name = caseNameOf(entry);
+        if (name === null)
+            continue;
+        const file = join(plansDir, entry);
+        if (!isFile(file))
+            continue;
+        const seen = byName.get(name);
+        if (seen !== undefined) {
+            // Refuse both rather than guessing which one the author meant.
+            errors.push(`${name}: both ${seen} and ${entry} exist; keep one`);
+            collided.add(name);
+            continue;
+        }
+        byName.set(name, entry);
+        found.push([name, file]);
+    }
+    const cases = [];
+    for (const [name, file] of found) {
+        if (collided.has(name))
+            continue;
+        const problems = [];
+        const fail = (message) => {
+            problems.push(message);
+        };
+        let doc;
+        try {
+            doc = parse(readFileSync(file, "utf8"));
+        }
+        catch (err) {
+            errors.push(`${name}.yaml: ${parseErrorText(err)}`);
+            continue;
+        }
+        const kase = validateCaseFile(doc, name, file, fail);
+        if (problems.length > 0) {
+            for (const problem of problems)
+                errors.push(`${name}: ${problem}`);
+            continue;
+        }
+        if (kase !== null)
+            cases.push(kase);
+    }
+    cases.sort((a, b) => a.number - b.number);
+    return { cases, errors };
+}
+//# sourceMappingURL=casefile.js.map

package/dist/qa/casefile.js.map

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

package/dist/qa/cases.d.ts

@@ -0,0 +1,51 @@
+import type { CaseFile } from "./casefile.js";
+export declare class Case {
+    readonly name: string;
+    readonly number: number;
+    /** Absolute path to `_plans/tc-N.yaml`. */
+    readonly file: string;
+    readonly outDir: string;
+    readonly repo: string;
+    /** The YAML `name` — a human title, distinct from `name` above, which is the identity. */
+    readonly title: string;
+    readonly agentName: string;
+    readonly model: string;
+    readonly parallel: boolean;
+    readonly tags: readonly string[];
+    /** The plan text itself, verbatim from the YAML block scalar. */
+    readonly plan: string;
+    constructor(spec: CaseFile, outDir: string, repo: string, defaultModel: string);
+    /** Python: Path.relative_to(repo).as_posix(), falling back to the absolute path. */
+    rel(path: string): string;
+    get fileRel(): string;
+    get outRel(): string;
+    get tempDir(): string;
+    get tempRel(): string;
+    /** How this case schedules, for the dry-run listing and the pane note. */
+    get constraint(): string;
+    /**
+     * Load-bearing: handed verbatim to cursor-agent. The dash is an em dash (U+2014). The plan is
+     * inlined rather than @-referenced, so the write constraint is stated before it, not after.
+     */
+    get prompt(): string;
+}
+/** Python: int(re.search(r"(\d+)", name).group(1)) */
+export declare function caseNumber(name: string): number;
+export interface Catalog {
+    cases: Case[];
+    errors: string[];
+}
+/** Every case under `_plans/`, whether or not it has been run, plus every load error. */
+export declare function catalog(runs: string, repo: string, defaultModel: string | Readonly<Record<string, string>>): Catalog;
+/** Cases whose run folder does not exist, natural-sorted, then filtered. */
+export declare function discover(all: readonly Case[], only?: ReadonlySet<string> | null, limit?: number | null): Case[];
+export declare function stillEligible(kase: Case): boolean;
+export declare function agentCommand(binary: string, kase: Case): string[];
+export declare function commandFor(kase: Case, explicitAgent: string | null): string[];
+export declare function shellQuote(s: string): string;
+export declare function shellJoin(argv: readonly string[]): string;
+/** The argv with the plan body elided, for a `--dry-run` listing that stays readable. */
+export declare function elidedCommand(binary: string, kase: Case): string[];
+/** Argv for the --dry-run listing: never spawned, so an absent backend is not an error. */
+export declare function displayCommandFor(kase: Case, explicitAgent: string | null): string[];
+export declare function elidedCommandFor(kase: Case, explicitAgent: string | null): string[];