spec-ctx 0.0.0-stage → 0.1.1

package/dist/check/check.js

@@ -0,0 +1,126 @@
+// REQ-CHK-001 REQ-CHK-002 REQ-GOV-002 integrity rules over the index.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { canon, SPEC_KINDS } from "../index/canonical.js";
+import { changeKey } from "../index/scan.js";
+import { listEvidence } from "../tasks/evidence.js";
+import { cmpTuple } from "../util/pystr.js";
+import { evidenceFindings } from "./evidence.js";
+const RETIRED_RE = /\b(REQ-[A-Z]{2,6}-\d{3}|ADR-\d{3})\b/g;
+const REQ_CAP = /^REQ-([A-Z]{2,6})-/;
+export function retiredIds(root) {
+    const p = join(root, "decisions", "retired-ids.md");
+    if (!existsSync(p))
+        return new Set();
+    // REQ-GOV-002 the retired ID is the first ID of a line. A reason may name the replacement ID, which stays live.
+    const out = new Set();
+    for (const line of readFileSync(p, "utf8").split("\n")) {
+        const m = new RegExp(RETIRED_RE.source).exec(line);
+        if (m)
+            out.add(m[1]);
+    }
+    return out;
+}
+/**
+ * REQ-CHK-004 two change folders, active or archived, with one key are a hard finding.
+ * The first folder in path order keeps the key. Every later folder gets a finding.
+ */
+export function duplicateChangeKeys(root) {
+    const base = join(root, "openspec/changes");
+    const dirs = (abs) => {
+        if (!existsSync(abs))
+            return [];
+        return readdirSync(abs).filter((n) => statSync(join(abs, n)).isDirectory()).sort();
+    };
+    const folders = [];
+    for (const n of dirs(base))
+        if (n !== "archive")
+            folders.push([`openspec/changes/${n}`, n]);
+    // openspec archive prefixes the folder with a date: 2026-10-23-001-foundation
+    for (const n of dirs(join(base, "archive")))
+        folders.push([`openspec/changes/archive/${n}`, n.replace(/^\d{4}-\d{2}-\d{2}-/, "")]);
+    const seen = new Set();
+    const out = [];
+    for (const [rel, name] of folders.sort((a, b) => cmpTuple(a, b))) {
+        const key = changeKey(name);
+        if (seen.has(key))
+            out.push([rel, 1, "duplicate-change-key", key]);
+        seen.add(key);
+    }
+    return out;
+}
+/** Sorted, unique findings. The scan never reads .ctx/, so evidence adds no index entry. */
+export function check(root, cfg, data, strict) {
+    const entries = data.entries;
+    const findings = data.problems.map((p) => [...p]);
+    findings.push(...duplicateChangeKeys(root));
+    const seen = new Set();
+    for (const e of entries) {
+        if (!SPEC_KINDS.has(e.kind))
+            continue;
+        // archived folders keep a copy of main specs. A MODIFIED or REMOVED block is a pending edit of one.
+        if (e.status === "archived" || e.status === "modified" || e.status === "removed")
+            continue;
+        if (seen.has(e.id))
+            findings.push([e.file, e.line, "duplicate-id", e.id]);
+        seen.add(e.id);
+    }
+    const known = new Set(entries.filter((e) => ["req", "scn", "adr", "task"].includes(e.kind)).map((e) => e.id));
+    const ids = canon(entries);
+    const retired = retiredIds(root);
+    const caps = new Set(cfg.ids.caps);
+    for (const e of entries) {
+        if ((e.kind === "req" || e.kind === "adr") && retired.has(e.id) && e.status !== "archived") {
+            findings.push([e.file, e.line, "reused-id", e.id]);
+        }
+        for (const r of e.refs) {
+            if (!known.has(r)) {
+                if (e.kind === "task" && !strict)
+                    continue;
+                findings.push([e.file, e.line, e.kind === "task" ? "unknown-task-req" : "dangling-ref", r]);
+            }
+            else if (e.kind === "code" && (!ids.has(r) || ids.get(r).status === "archived")) {
+                // the tag points at a requirement that lives only in an archived change
+                findings.push([e.file, e.line, "code-tag-no-canonical", r]);
+            }
+        }
+        // an archived block is history. An archived REMOVED block has no scenario by design.
+        if (e.kind === "req" && e.status !== "removed" && e.status !== "archived" && !(e.scenarios ?? []).length) {
+            findings.push([e.file, e.line, "req-without-scn", e.id]);
+        }
+        if (caps.size && e.kind === "req" && e.status !== "archived") {
+            const m = REQ_CAP.exec(e.id);
+            if (m && !caps.has(m[1]))
+                findings.push([e.file, e.line, "unknown-cap", e.id]);
+        }
+    }
+    if (strict) {
+        const covered = new Set(entries.filter((e) => e.kind === "test").flatMap((e) => e.refs));
+        const named = new Set(data.scn_named ?? []);
+        // an ID that a REMOVED block of an active change names waits for archive, so it needs no test
+        const pending = new Set();
+        for (const e of entries) {
+            if (e.status !== "removed")
+                continue;
+            pending.add(e.id);
+            for (const s of e.scenarios ?? [])
+                pending.add(s);
+        }
+        const scnOf = new Map(entries.filter((e) => e.kind === "req").flatMap((e) => (e.scenarios ?? []).map((s) => [s, e.id])));
+        for (const e of entries) {
+            if (e.change !== "main" || e.status !== "active")
+                continue;
+            if (pending.has(e.id) || (e.kind === "scn" && pending.has(scnOf.get(e.id) ?? "")))
+                continue;
+            if (e.kind === "req" && !covered.has(e.id))
+                findings.push([e.file, e.line, "uncovered", e.id]);
+            if (e.kind === "scn" && !named.has(e.id))
+                findings.push([e.file, e.line, "scenario-untested", e.id]);
+        }
+        findings.push(...evidenceFindings(root, entries, listEvidence(root)));
+    }
+    const uniq = new Map();
+    for (const f of findings)
+        uniq.set(JSON.stringify(f), f);
+    return [...uniq.values()].sort((a, b) => cmpTuple(a, b)).map(([file, line, rule, id]) => ({ file, line, rule, id }));
+}

package/dist/check/evidence.js

@@ -0,0 +1,70 @@
+// REQ-CHK-003 evidence rules of check --strict.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileSha256 } from "../util/hash.js";
+export function evidenceFindings(root, entries, evidence) {
+    const out = [];
+    const tasks = new Map();
+    for (const e of entries) {
+        if (e.kind !== "task")
+            continue;
+        const l = tasks.get(e.id) ?? [];
+        l.push(e);
+        tasks.set(e.id, l);
+    }
+    const have = new Set();
+    for (const rel of evidence) {
+        const parts = rel.split("/");
+        const id = `${parts[2]}/${parts[3].replace(/\.json$/, "")}`;
+        have.add(id);
+        const copies = tasks.get(id) ?? [];
+        const active = copies.find((t) => !t.file.includes("/archive/"));
+        const task = active ?? copies[0];
+        if (!task || task.status !== "done") {
+            out.push([rel, 1, "evidence-without-done", id]);
+            continue;
+        }
+        // archived changes are exempt from stale-evidence
+        if (!active)
+            continue;
+        let files = {};
+        try {
+            const ev = JSON.parse(readFileSync(join(root, rel), "utf8"));
+            files = ev.files ?? {};
+        }
+        catch {
+            out.push([rel, 1, "stale-evidence", `${id} ${rel}`]);
+            continue;
+        }
+        for (const [path, digest] of Object.entries(files)) {
+            if (fileSha256(join(root, path)) !== digest)
+                out.push([rel, 1, "stale-evidence", `${id} ${path}`]);
+        }
+    }
+    for (const e of entries) {
+        if (e.kind === "task" && e.status === "done" && !e.file.includes("/archive/") && !have.has(e.id)) {
+            out.push([e.file, e.line, "done-without-evidence", e.id]);
+        }
+    }
+    return out;
+}
+/** REQ-CHK-003 manual evidence for a task in an active change is a warning, not a finding. */
+export function manualWarnings(root, entries, evidence) {
+    const active = new Set(entries.filter((e) => e.kind === "task" && !e.file.includes("/archive/") && e.change !== "main").map((e) => e.id));
+    const out = [];
+    for (const rel of evidence) {
+        const parts = rel.split("/");
+        const id = `${parts[2]}/${parts[3].replace(/\.json$/, "")}`;
+        if (!active.has(id))
+            continue;
+        try {
+            const ev = JSON.parse(readFileSync(join(root, rel), "utf8"));
+            if (ev.kind === "manual")
+                out.push(`manual-evidence ${id}`);
+        }
+        catch {
+            // a damaged file is a stale-evidence finding already
+        }
+    }
+    return out.sort();
+}

package/dist/check/hints.js

@@ -0,0 +1,26 @@
+// REQ-CHK-004 the rules of check and one fix hint per rule. The check summary prints the hint of each rule it found.
+/** `hard` rules set exit 1. `advisory` rules print a warning and keep exit 0. */
+export const RULES = {
+    "missing-id": { level: "hard", hint: "Add an ID to the header. Run specctx adopt --dry-run to see the plan." },
+    "scenario-id-mismatch": { level: "hard", hint: "Give the scenario the number of its requirement." },
+    "bad-ref": { level: "hard", hint: "Write only IDs on the Refs line, separated by commas." },
+    "task-without-req": { level: "hard", hint: "Cite a requirement in brackets on the task line, for example [REQ-ABC-001]." },
+    "task-without-verify": { level: "hard", hint: "Add Verify: and a command in backticks to the task line." },
+    "duplicate-id": { level: "hard", hint: "Give one of the two entries a new ID from specctx id new." },
+    "duplicate-change-key": { level: "hard", hint: "Rename one change folder, so that each key names one change." },
+    "reused-id": { level: "hard", hint: "The ID is retired. Get a new ID from specctx id new." },
+    "dangling-ref": { level: "hard", hint: "Fix the ID or remove the link. No entry has this ID." },
+    "unknown-task-req": { level: "hard", hint: "The task cites an ID that the index does not hold. Fix the ID on the task line." },
+    "req-without-scn": { level: "hard", hint: "Add a scenario under the requirement." },
+    "code-tag-no-canonical": { level: "hard", hint: "The tag names an archived requirement. Tag the current requirement." },
+    "unknown-cap": { level: "hard", hint: "Add the code to caps under [ids] in spec-ctx.toml." },
+    uncovered: { level: "hard", hint: "Add a test with a Covers tag for the requirement." },
+    "scenario-untested": { level: "hard", hint: "Name the scenario ID in a test." },
+    "done-without-evidence": { level: "hard", hint: "Run specctx task done, or specctx task backfill for old tasks." },
+    "stale-evidence": { level: "hard", hint: "Run specctx task reopen and then specctx task done." },
+    "evidence-without-done": { level: "hard", hint: "Run specctx task done, or remove the evidence file." },
+    "manual-evidence": { level: "advisory", hint: "Give the task a Verify command and run specctx task done again." },
+};
+export function hintOf(rule) {
+    return RULES[rule]?.hint ?? "Read the check rules in the check spec.";
+}

package/dist/cli/args.js

@@ -0,0 +1,90 @@
+// REQ-CLI-001 argument parser. It loads nothing else, so --version stays fast.
+export const GLOBAL_FLAGS = { root: "string", json: "bool", help: "bool", version: "bool" };
+/** Flags per command. A group command such as `task done` has a two word key. */
+export const COMMAND_FLAGS = {
+    build: {},
+    status: {},
+    query: { kind: "string", change: "string", all: "bool", limit: "int" },
+    related: { depth: "int", all: "bool" },
+    bundle: { budget: "int", depth: "int", all: "bool" },
+    check: { strict: "bool" },
+    stats: { change: "string", write: "bool" },
+    gate: { strict: "bool", markdown: "string" },
+    "id new": { for: "string", count: "int" },
+    "id retire": {},
+    "task next": { change: "string" },
+    "task start": {},
+    "task verify": {},
+    "task done": { manual: "string" },
+    "task reopen": {},
+    "task backfill": { manual: "string", change: "string" },
+    "handoff write": {},
+    "handoff ask": {},
+    "handoff resolve": {},
+    adopt: { "dry-run": "bool" },
+    "baseline write": {},
+    "baseline prune": {},
+    init: { schema: "bool", skills: "bool", all: "bool", force: "bool" },
+};
+export const GROUPS = ["id", "task", "handoff", "baseline"];
+export const COMMANDS = Object.keys(COMMAND_FLAGS);
+export class UsageError extends Error {
+}
+const SHORT = { "-h": "help", "-V": "version" };
+export function parseArgs(argv) {
+    const out = { command: null, positional: [], flags: {} };
+    const spec = () => ({ ...GLOBAL_FLAGS, ...(out.command ? COMMAND_FLAGS[out.command] ?? {} : {}) });
+    let onlyPositional = false;
+    const positional = (a) => {
+        if (out.command === null)
+            out.command = a;
+        else if (GROUPS.includes(out.command) && !out.positional.length && !COMMAND_FLAGS[out.command])
+            out.command = `${out.command} ${a}`;
+        else
+            out.positional.push(a);
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (onlyPositional || !a.startsWith("-") || a === "-") {
+            positional(a);
+            continue;
+        }
+        if (a === "--") {
+            onlyPositional = true;
+            continue;
+        }
+        let name;
+        let value;
+        if (SHORT[a])
+            name = SHORT[a];
+        else if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            name = eq < 0 ? a.slice(2) : a.slice(2, eq);
+            value = eq < 0 ? undefined : a.slice(eq + 1);
+        }
+        else
+            throw new UsageError(`unknown flag: ${a}`);
+        const kind = spec()[name];
+        if (!kind)
+            throw new UsageError(`unknown flag: --${name}`);
+        if (kind === "bool") {
+            if (value !== undefined)
+                throw new UsageError(`flag --${name} takes no value`);
+            out.flags[name] = true;
+            continue;
+        }
+        if (value === undefined) {
+            value = argv[++i];
+            if (value === undefined)
+                throw new UsageError(`flag --${name} needs a value`);
+        }
+        if (kind === "int") {
+            if (!/^-?\d+$/.test(value))
+                throw new UsageError(`flag --${name} needs an integer`);
+            out.flags[name] = Number(value);
+        }
+        else
+            out.flags[name] = value;
+    }
+    return out;
+}

package/dist/cli/color.js

@@ -0,0 +1,23 @@
+// REQ-CLI-008 color on a TTY. Without color the bytes equal the plain output.
+const CODES = { ok: "\x1b[32m", fail: "\x1b[31m", dim: "\x1b[2m" };
+const RESET = "\x1b[0m";
+/**
+ * Color is on when `FORCE_COLOR` is set, or when stdout is a TTY and `TERM` is not `dumb`.
+ * `NO_COLOR` wins over both. An empty value counts as unset. `FORCE_COLOR=0` counts as unset.
+ */
+export function colorOn(tty, env = process.env) {
+    if (env.NO_COLOR)
+        return false;
+    const force = env.FORCE_COLOR;
+    if (force && force !== "0" && force !== "false")
+        return true;
+    return tty && env.TERM !== "dumb";
+}
+/** Wrap one line of text in the code of its kind. A trailing newline stays outside the codes. */
+export function paint(kind, text, tty) {
+    if (!colorOn(tty === true))
+        return text;
+    const nl = text.endsWith("\n") ? "\n" : "";
+    const body = nl ? text.slice(0, -1) : text;
+    return `${CODES[kind]}${body}${RESET}${nl}`;
+}

package/dist/cli/commands.js

@@ -0,0 +1,278 @@
+// REQ-CLI-001 REQ-CLI-002 command actions.
+import { resolve } from "node:path";
+import { UsageExit } from "./errors.js";
+import { findRoot, requireOpenSpec } from "./root.js";
+import { hintOf } from "../check/hints.js";
+import { paint } from "./color.js";
+/** check with warnings and the baseline filter. Strict mode adds the strict rules and the warnings. */
+async function runCheck(root, cfg, data, strict) {
+    const { check } = await import("../check/check.js");
+    const { applyBaseline } = await import("../baseline/baseline.js");
+    const findings = check(root, cfg, data, strict);
+    let warnings = [];
+    if (strict) {
+        const { manualWarnings } = await import("../check/evidence.js");
+        const { listEvidence } = await import("../tasks/evidence.js");
+        warnings = manualWarnings(root, data.entries, listEvidence(root));
+    }
+    return applyBaseline(root, findings, warnings);
+}
+/**
+ * REQ-CHK-004 the findings, then a blank line, the summary line, and one line per rule with its hint.
+ * A warning counts as advisory. The `baselined` line stays last (REQ-CHK-002).
+ */
+export function checkText(r, tty) {
+    // REQ-CLI-008 every finding of check is hard, so every finding line is red. stale-evidence is one of them.
+    const body = r.findings.map((x) => paint("fail", `${x.file}:${x.line}  ${x.rule}  ${x.id}\n`, tty)).join("")
+        + r.warnings.map((w) => `warning: ${w}\n`).join("");
+    const base = r.baselined ? `baselined: ${r.baselined}\n` : "";
+    const n = r.findings.length + r.warnings.length;
+    if (!n)
+        return paint("dim", "0 findings\n", tty) + base;
+    const files = new Set(r.findings.map((x) => x.file));
+    const count = new Map();
+    for (const x of r.findings)
+        count.set(x.rule, (count.get(x.rule) ?? 0) + 1);
+    for (const w of r.warnings) {
+        const [rule, task] = w.split(" ");
+        count.set(rule, (count.get(rule) ?? 0) + 1);
+        // a manual-evidence warning names a task. Its file is the evidence file of the task.
+        if (task?.includes("/"))
+            files.add(`.ctx/evidence/${task}.json`);
+    }
+    const rules = [...count.keys()].sort();
+    return body
+        + "\n" + paint("dim", `${n} finding${n === 1 ? "" : "s"} in ${files.size} file${files.size === 1 ? "" : "s"} (${r.findings.length} hard, ${r.warnings.length} advisory)\n`, tty)
+        + rules.map((rule) => `${rule}  ${count.get(rule)}  ${hintOf(rule)}\n`).join("")
+        + base;
+}
+export async function run(p, io) {
+    const f = p.flags;
+    const json = !!f.json;
+    const cmd = p.command;
+    if (cmd === "init")
+        return init(p, io);
+    const root = findRoot(io.cwd, f.root);
+    requireOpenSpec(root);
+    const { loadConfig, ConfigError } = await import("../config.js");
+    let cfg;
+    try {
+        cfg = loadConfig(root);
+    }
+    catch (e) {
+        if (e instanceof ConfigError)
+            throw new UsageExit(e.message);
+        throw e;
+    }
+    const { dumps } = await import("../util/json.js");
+    const print = (v) => io.out(dumps(v) + "\n");
+    if (cmd === "build") {
+        if (p.positional.length)
+            throw new UsageExit("build takes no arguments");
+        const { buildIndex, INDEX_PATH } = await import("../index/build.js");
+        const data = buildIndex(root, cfg);
+        if (json)
+            print({ entries: data.entries.length, index: INDEX_PATH, problems: data.problems.length });
+        else
+            io.out(`indexed ${data.entries.length} entries, ${data.problems.length} problem(s) -> ${INDEX_PATH}\n`);
+        return 0;
+    }
+    if (cmd === "adopt") {
+        if (p.positional.length)
+            throw new UsageExit("adopt takes no arguments");
+        const { planAdopt, planLines } = await import("../adopt/plan.js");
+        const plan = planAdopt(root, cfg);
+        if (!f["dry-run"]) {
+            const { applyAdopt } = await import("../adopt/write.js");
+            return applyAdopt(root, cfg, plan, io, json);
+        }
+        if (json)
+            print(plan);
+        else if (!plan.edits.length)
+            io.out(plan.unmatched.length ? planLines(plan).join("\n") + "\nnothing to adopt\n" : "nothing to adopt\n");
+        // REQ-CLI-007 the dry run ends with the next step. The exit code stays 1.
+        else
+            io.out(planLines(plan).join("\n") + `\n${plan.edits.length} headers need an ID. Next: specctx adopt\n`);
+        return plan.edits.length ? 1 : 0;
+    }
+    if (cmd === "baseline write" || cmd === "baseline prune") {
+        if (p.positional.length)
+            throw new UsageExit(`${cmd} takes no arguments`);
+        const { buildIndex } = await import("../index/build.js");
+        const { check } = await import("../check/check.js");
+        const { manualWarnings } = await import("../check/evidence.js");
+        const { listEvidence } = await import("../tasks/evidence.js");
+        const { writeBaseline, pruneBaseline, BASELINE_PATH } = await import("../baseline/baseline.js");
+        const data = buildIndex(root, cfg);
+        const findings = check(root, cfg, data, true);
+        const warnings = manualWarnings(root, data.entries, listEvidence(root));
+        if (cmd === "baseline write") {
+            const list = writeBaseline(root, findings, warnings);
+            if (json)
+                print({ baseline: BASELINE_PATH, entries: list.length });
+            else
+                io.out(`wrote ${BASELINE_PATH} with ${list.length} entr${list.length === 1 ? "y" : "ies"}\n`);
+        }
+        else {
+            const n = pruneBaseline(root, findings, warnings);
+            if (json)
+                print({ pruned: n });
+            else
+                io.out(`pruned ${n}\n`);
+        }
+        return 0;
+    }
+    if (cmd === "gate") {
+        if (p.positional.length)
+            throw new UsageExit("gate takes no arguments");
+        const { runGate, DEFAULT_MARKDOWN } = await import("./gate.js");
+        const strict = !!f.strict;
+        return runGate(root, {
+            strict,
+            markdown: f.markdown ?? DEFAULT_MARKDOWN,
+            check: async () => {
+                const { buildIndex } = await import("../index/build.js");
+                const { check } = await import("../check/check.js");
+                void check;
+                const data = buildIndex(root, cfg);
+                const r = await runCheck(root, cfg, data, strict);
+                return { code: r.findings.length ? 1 : 0, out: checkText(r, io.tty) };
+            },
+        }, io);
+    }
+    const { loadIndex } = await import("../index/build.js");
+    const need = (n, what) => {
+        if (p.positional.length < n)
+            throw new UsageExit(`${cmd} needs ${what}`);
+    };
+    if (cmd === "query")
+        need(1, "at least one term");
+    if (cmd === "related") {
+        need(1, "one ID");
+        if (p.positional.length > 1)
+            throw new UsageExit("related takes one ID");
+    }
+    if (cmd === "bundle")
+        need(1, "at least one ID");
+    if ((cmd === "status" || cmd === "check") && p.positional.length)
+        throw new UsageExit(`${cmd} takes no arguments`);
+    const { data, rebuilt } = loadIndex(root, cfg);
+    if (rebuilt)
+        io.err("index rebuilt\n");
+    const entries = data.entries;
+    if (cmd.includes(" ")) {
+        const { runWorkflow } = await import("./workflow.js");
+        return runWorkflow({ root, cfg, data, p, io, json });
+    }
+    const all = !!f.all;
+    switch (cmd) {
+        case "status": {
+            const { statusReport, statusLines } = await import("./status.js");
+            const r = statusReport(root, entries);
+            if (json)
+                print(r);
+            // REQ-CLI-008 the next: line is dim
+            else
+                io.out(statusLines(r).map((l) => (l.startsWith("next: ") ? paint("dim", l, io.tty) : l) + "\n").join(""));
+            return 0;
+        }
+        case "query": {
+            const { query, queryLine } = await import("../graph/query.js");
+            const hits = query(entries, p.positional, {
+                kind: f.kind, change: f.change, all, limit: f.limit ?? 20,
+            });
+            if (json)
+                print(hits);
+            else
+                io.out(hits.map((e) => queryLine(e) + "\n").join(""));
+            return 0;
+        }
+        case "related": {
+            const { canon } = await import("../index/canonical.js");
+            const { related } = await import("../graph/related.js");
+            const id = p.positional[0];
+            const ids = canon(entries);
+            if (!ids.has(id) && !(all && entries.some((e) => e.id === id))) {
+                io.err(`unknown id ${id}\n`);
+                return 2;
+            }
+            const rows = [];
+            for (const [i, reason] of related(entries, id, f.depth ?? 1, all)) {
+                const copies = all ? entries.filter((e) => e.id === i) : ids.has(i) ? [ids.get(i)] : [];
+                // canonical copy first, the rest in index order
+                copies.sort((a, b) => Number(!a.canonical) - Number(!b.canonical));
+                for (const e of copies)
+                    rows.push([e, reason]);
+            }
+            if (json)
+                print(rows.map(([e, reason]) => ({ ...e, reason })));
+            else
+                io.out(rows.map(([e, r]) => `${e.kind}  ${e.id}  ${e.status}  ${e.file}:${e.line}  ${r}\n`).join(""));
+            return 0;
+        }
+        case "bundle": {
+            const { canon } = await import("../index/canonical.js");
+            const { bundle } = await import("../graph/bundle.js");
+            const ids = canon(entries);
+            const unknown = p.positional.filter((i) => !ids.has(i));
+            if (unknown.length) {
+                io.err(`unknown id(s): ${unknown.join(", ")}\n`);
+                return 2;
+            }
+            const b = bundle(root, entries, p.positional, f.budget ?? cfg.bundle.budget, f.depth ?? cfg.bundle.depth, all);
+            if (json)
+                print(b);
+            else
+                io.out(b.text);
+            return 0;
+        }
+        case "stats": {
+            if (p.positional.length)
+                throw new UsageExit("stats takes no arguments");
+            const { check } = await import("../check/check.js");
+            const { manualWarnings } = await import("../check/evidence.js");
+            const { listEvidence } = await import("../tasks/evidence.js");
+            const { computeStats, statsTable } = await import("../stats/stats.js");
+            const s = computeStats(root, entries, check(root, cfg, data, true), manualWarnings(root, entries, listEvidence(root)), f.change);
+            if (f.write) {
+                const { writeStats } = await import("../stats/write.js");
+                const rel = writeStats(root, s);
+                if (!json)
+                    io.out(`wrote ${rel}\n`);
+            }
+            if (json)
+                print(s);
+            else
+                io.out(statsTable(s).map((l) => l + "\n").join(""));
+            return 0;
+        }
+        case "check": {
+            const r = await runCheck(root, cfg, data, !!f.strict);
+            if (json)
+                print({ baselined: r.baselined, count: r.findings.length, findings: r.findings, warnings: r.warnings });
+            else
+                io.out(checkText(r, io.tty));
+            return r.findings.length ? 1 : 0;
+        }
+    }
+    throw new UsageExit(`unknown command: ${cmd}`);
+}
+async function init(p, io) {
+    const { runInit } = await import("../init/init.js");
+    if (p.positional.length)
+        throw new UsageExit("init takes no arguments");
+    const root = resolve(io.cwd, p.flags.root ?? ".");
+    const all = !!p.flags.all;
+    const r = runInit(root, { schema: all || !!p.flags.schema, skills: all || !!p.flags.skills, force: !!p.flags.force });
+    if (p.flags.json)
+        io.out(JSON.stringify(r, null, 2) + "\n");
+    else if (r.nothing)
+        io.out("nothing to do\n" + paint("dim", "next: specctx status\n", io.tty));
+    else {
+        io.out(r.written.map((w) => `wrote ${w}\n`).join(""));
+        io.out(r.kept.map((k) => `kept ${k}\n`).join(""));
+        // REQ-CLI-007 init ends with the next step
+        io.out(paint("dim", "next: specctx status\n", io.tty));
+    }
+    return 0;
+}

package/dist/cli/errors.js

@@ -0,0 +1,3 @@
+// REQ-CLI-002 a usage or missing input error exits 2.
+export class UsageExit extends Error {
+}