@cairn-tool/cairn 3.4.0 → 3.6.0

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[];

package/dist/qa/cases.js

@@ -0,0 +1,144 @@
+import { existsSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
+import { displayBinary, resolveAgent, resolveBinary } from "./agents/index.js";
+import { loadCaseFiles } from "./casefile.js";
+export class Case {
+    name;
+    number;
+    /** Absolute path to `_plans/tc-N.yaml`. */
+    file;
+    outDir;
+    repo;
+    /** The YAML `name` — a human title, distinct from `name` above, which is the identity. */
+    title;
+    agentName;
+    model;
+    parallel;
+    tags;
+    /** The plan text itself, verbatim from the YAML block scalar. */
+    plan;
+    constructor(spec, outDir, repo, defaultModel) {
+        this.name = spec.name;
+        this.number = spec.number;
+        this.file = spec.file;
+        this.outDir = outDir;
+        this.repo = repo;
+        this.title = spec.title;
+        this.agentName = spec.agent;
+        this.model = spec.model ?? defaultModel;
+        this.parallel = spec.parallel;
+        this.tags = spec.tags;
+        this.plan = spec.plan;
+    }
+    /** Python: Path.relative_to(repo).as_posix(), falling back to the absolute path. */
+    rel(path) {
+        const rel = relative(this.repo, path);
+        if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
+            return path;
+        return rel;
+    }
+    get fileRel() {
+        return this.rel(this.file);
+    }
+    get outRel() {
+        return `${this.rel(this.outDir)}/`;
+    }
+    get tempDir() {
+        return join(dirname(this.outDir), `${basename(this.outDir)}-temp`);
+    }
+    get tempRel() {
+        return `${this.rel(this.tempDir)}/`;
+    }
+    /** How this case schedules, for the dry-run listing and the pane note. */
+    get constraint() {
+        if (this.parallel)
+            return "parallel";
+        if (this.tags.length === 0)
+            return "exclusive";
+        return `tags ${this.tags.join(", ")}`;
+    }
+    /**
+     * 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() {
+        return (`Perform the test-case plan below. Write every deliverable to ${this.tempRel}, ` +
+            `creating that folder yourself. Do not write to ${this.outRel} — the harness ` +
+            `renames the temp folder there only after this run succeeds.\n\n---\n\n${this.plan}`);
+    }
+}
+/** Python: int(re.search(r"(\d+)", name).group(1)) */
+export function caseNumber(name) {
+    const match = /(\d+)/.exec(name);
+    if (!match)
+        throw new Error(`no number in case name: ${name}`);
+    return Number.parseInt(match[1], 10);
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function fallbackModel(spec, defaults) {
+    if (typeof defaults === "string")
+        return spec.model ?? defaults;
+    return spec.model ?? defaults[spec.agent] ?? resolveAgent(spec.agent).defaultModel;
+}
+/** Every case under `_plans/`, whether or not it has been run, plus every load error. */
+export function catalog(runs, repo, defaultModel) {
+    const loaded = loadCaseFiles(join(runs, "_plans"));
+    const cases = loaded.cases.map((spec) => new Case(spec, join(runs, spec.name), repo, fallbackModel(spec, defaultModel)));
+    // loadCaseFiles already sorts numerically — tc-2 must precede tc-10.
+    return { cases, errors: loaded.errors };
+}
+/** Cases whose run folder does not exist, natural-sorted, then filtered. */
+export function discover(all, only = null, limit = null) {
+    let cases = all.filter((c) => !existsSync(c.outDir));
+    if (only !== null)
+        cases = cases.filter((c) => only.has(c.name));
+    if (limit !== null)
+        cases = cases.slice(0, limit);
+    return cases;
+}
+export function stillEligible(kase) {
+    return isFile(kase.file) && !existsSync(kase.outDir);
+}
+export function agentCommand(binary, kase) {
+    return resolveAgent(kase.agentName).buildArgv({ repo: kase.repo, model: kase.model, prompt: kase.prompt }, binary);
+}
+export function commandFor(kase, explicitAgent) {
+    return agentCommand(resolveBinary(kase.agentName, explicitAgent), kase);
+}
+/** Python: shlex._find_unsafe = re.compile(r'[^\w@%+=:,./-]', re.ASCII).search */
+const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+export function shellQuote(s) {
+    if (SHELL_SAFE.test(s))
+        return s;
+    return `'${s.replaceAll("'", `'"'"'`)}'`;
+}
+export function shellJoin(argv) {
+    return argv.map(shellQuote).join(" ");
+}
+/** The argv with the plan body elided, for a `--dry-run` listing that stays readable. */
+export function elidedCommand(binary, kase) {
+    const argv = agentCommand(binary, kase);
+    const head = kase.prompt.slice(0, kase.prompt.indexOf("\n\n---\n\n"));
+    const hidden = kase.plan.length;
+    argv[argv.length - 1] = `${head} …[+${hidden.toLocaleString("en-US")} chars of plan]…`;
+    return argv;
+}
+/** Argv for the --dry-run listing: never spawned, so an absent backend is not an error. */
+export function displayCommandFor(kase, explicitAgent) {
+    return agentCommand(displayBinary(kase.agentName, explicitAgent), kase);
+}
+export function elidedCommandFor(kase, explicitAgent) {
+    const argv = displayCommandFor(kase, explicitAgent);
+    const head = kase.prompt.slice(0, kase.prompt.indexOf("\n\n---\n\n"));
+    const hidden = kase.plan.length;
+    argv[argv.length - 1] = `${head} …[+${hidden.toLocaleString("en-US")} chars of plan]…`;
+    return argv;
+}
+//# sourceMappingURL=cases.js.map

package/dist/qa/cases.js.map

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

package/dist/qa/config.d.ts

@@ -0,0 +1,50 @@
+/** Every `raise SystemExit("msg")` in the Python becomes one of these. */
+export declare class UserError extends Error {
+}
+export declare const DEFAULT_PARALLEL = 8;
+export declare const DEFAULT_TIMEOUT_MIN = 60;
+export declare const REPORT = "_report.md";
+export declare const RESULTS = "_results.md";
+export declare const TRANSCRIPT_CAP = 400;
+export declare const RENDER_HZ = 4;
+/** Digits 1..9 zoom a pane; a tenth pane simply has no key. */
+export declare const MAX_ZOOM_KEYS = 9;
+/**
+ * A case's plan travels inside the prompt argv, so it is bounded by ARG_MAX (1 MiB here, shared
+ * with the environment). Well under it, with a message that names the file instead of E2BIG.
+ */
+export declare const MAX_PROMPT_BYTES: number;
+export declare const DONE_OK = "ok";
+export declare const DONE_FAIL: ReadonlySet<string>;
+export interface Options {
+    repo: string;
+    runsDir: string;
+    /** Maximum agents in flight; per-case `parallel`/`tags` may hold it below this. */
+    parallel: number;
+    /**
+     * Session-log label for `--model`. Per-case fallbacks live on the Case via
+     * `models` / the profile default — a mixed queue does not share one slug.
+     */
+    model: string;
+    only: ReadonlySet<string> | null;
+    limit: number | null;
+    dryRun: boolean;
+    showPrompts: boolean;
+    noTui: boolean;
+    timeoutMs: number;
+    /** Explicit binary for every backend, or null to resolve per profile on PATH. */
+    agent: string | null;
+    /** When true, main() does not print the human console summary (JSON owns stdout). */
+    json: boolean;
+}
+/** Python: resolve_dir(raw, base, what) */
+export declare function resolveDir(raw: string, base: string, what: string): string;
+/** Python: shutil.which — POSIX PATH walk, no PATHEXT handling. */
+export declare function which(name: string): string | null;
+/**
+ * An explicit `--agent` path. Kept expanduser'd as given — it is not absolutized,
+ * and the result goes verbatim into command.txt and --dry-run output.
+ */
+export declare function findExplicitAgent(explicit: string): string;
+/** Python: parse_only("27, tc-28,") -> {"tc-27", "tc-28"} */
+export declare function parseOnly(raw: string | null | undefined): ReadonlySet<string> | null;

package/dist/qa/config.js

@@ -0,0 +1,105 @@
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
+/** Every `raise SystemExit("msg")` in the Python becomes one of these. */
+export class UserError extends Error {
+}
+export const DEFAULT_PARALLEL = 8;
+export const DEFAULT_TIMEOUT_MIN = 60;
+export const REPORT = "_report.md";
+export const RESULTS = "_results.md";
+export const TRANSCRIPT_CAP = 400;
+export const RENDER_HZ = 4;
+/** Digits 1..9 zoom a pane; a tenth pane simply has no key. */
+export const MAX_ZOOM_KEYS = 9;
+/**
+ * A case's plan travels inside the prompt argv, so it is bounded by ARG_MAX (1 MiB here, shared
+ * with the environment). Well under it, with a message that names the file instead of E2BIG.
+ */
+export const MAX_PROMPT_BYTES = 256 * 1024;
+export const DONE_OK = "ok";
+export const DONE_FAIL = new Set([
+    "error",
+    "timeout",
+    "no-output",
+    "no-folder",
+]);
+function expandUser(raw) {
+    if (raw === "~")
+        return homedir();
+    if (raw.startsWith("~/"))
+        return join(homedir(), raw.slice(2));
+    return raw;
+}
+/** Python: resolve_dir(raw, base, what) */
+export function resolveDir(raw, base, what) {
+    const expanded = expandUser(raw);
+    const joined = isAbsolute(expanded) ? expanded : join(base, expanded);
+    // Python's Path.resolve() also resolves symlinks — on macOS /tmp is a link to /private/tmp,
+    // so path.resolve() alone would produce a different --workspace and different log paths.
+    let path;
+    try {
+        path = realpathSync(joined);
+    }
+    catch {
+        path = resolve(joined);
+    }
+    let dir = false;
+    try {
+        dir = statSync(path).isDirectory();
+    }
+    catch {
+        /* keep false */
+    }
+    if (!dir)
+        throw new UserError(`${what} is not a directory: ${path}`);
+    return path;
+}
+function isExecutableFile(path) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Python: shutil.which — POSIX PATH walk, no PATHEXT handling. */
+export function which(name) {
+    if (name.includes("/"))
+        return isExecutableFile(name) ? name : null;
+    const path = process.env["PATH"] ?? "";
+    for (const dir of path.split(":")) {
+        const candidate = join(dir === "" ? "." : dir, name);
+        if (isExecutableFile(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * An explicit `--agent` path. Kept expanduser'd as given — it is not absolutized,
+ * and the result goes verbatim into command.txt and --dry-run output.
+ */
+export function findExplicitAgent(explicit) {
+    const path = expandUser(explicit);
+    if (!isExecutableFile(path)) {
+        throw new UserError(`--agent is not an executable file: ${explicit}`);
+    }
+    return path;
+}
+/** Python: parse_only("27, tc-28,") -> {"tc-27", "tc-28"} */
+export function parseOnly(raw) {
+    if (raw === null || raw === undefined || raw === "")
+        return null;
+    const names = new Set();
+    for (const part of raw.split(",")) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        names.add(trimmed.startsWith("tc-") ? trimmed : `tc-${trimmed}`);
+    }
+    return names;
+}
+//# sourceMappingURL=config.js.map

package/dist/qa/config.js.map

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

package/dist/qa/demo.d.ts

@@ -0,0 +1,10 @@
+export interface DemoOptions {
+    rows?: number;
+    cols?: number;
+    table?: boolean;
+    once?: boolean;
+    /** How many panes to show, so the dynamic pane region can be eyeballed at any width. */
+    panes?: number;
+}
+/** A canned frame, so the TUI can be eyeballed at any size without launching an agent. */
+export declare function runDemo(opts: DemoOptions): Promise<number>;