doctrina-cli 0.13.0 → 0.15.0

package/src/lib/gates.js

@@ -0,0 +1,123 @@
+// @ts-check
+import { getSection } from "./doc-model.js";
+import path from "node:path";
+import { appendFileSync, writeFileSync } from "node:fs";
+import { exists, isFile, mkdirp, read } from "./fs-ops.js";
+import { today } from "./dates.js";
+import { collectAnalysis } from "../commands/analyze.js";
+
+// The gate-to-transition map (audit item C6).
+//
+// Each command used to decide its own preconditions. `change archive` and
+// `close` checked theirs; `change apply` checked nothing. So `analyze`
+// could exit 1 on a change and `change apply` would mutate it anyway and
+// exit 0 — and the README flowchart tells agents to follow exactly that
+// analyze → apply path. An agent could reach, through one path, a state
+// another path forbids.
+//
+// The fix is not "add a check to apply" but "declare once which gates
+// guard which transition, and have every driver consult the declaration".
+// Which specific gate guards which transition matters less than the
+// guarantee that the answer does not depend on how you got there.
+
+// A gate is a named precondition returning human-readable blockers.
+export const GATES = {
+  // Structural validity: the change's own files parse and point at real
+  // targets. The same checks `doctrina analyze` reports.
+  structure: {
+    label: "structure",
+    rerun: (id) => `doctrina analyze ${id}`,
+    blockers(projectRoot, changeDir) {
+      return collectAnalysis(projectRoot, changeDir)
+        .filter((r) => r.kind === "fail")
+        .map((r) => stripAnsi(r.line).replace(/^✗\s*/, "").trim());
+    },
+  },
+
+  // Verification: the work is claimed complete. Every checkbox in
+  // tasks.md (closing steps included) and in the proposal's
+  // "## Verification" section.
+  verification: {
+    label: "verification",
+    rerun: (id) => `doctrina change tick ${id}`,
+    blockers(projectRoot, changeDir) {
+      const out = [];
+      const countUnchecked = (s) => (s.match(/^\s*-\s*\[ \]/gm) ?? []).length;
+
+      const tasksPath = path.join(changeDir, "tasks.md");
+      if (isFile(tasksPath)) {
+        const n = countUnchecked(read(tasksPath));
+        if (n > 0) out.push(`${n} unchecked task${n === 1 ? "" : "s"} in tasks.md (closing steps count)`);
+      }
+      const proposalPath = path.join(changeDir, "proposal.md");
+      if (isFile(proposalPath)) {
+        const n = countUnchecked(getSection(read(proposalPath), "Verification"));
+        if (n > 0) out.push(`${n} unmet verification item${n === 1 ? "" : "s"} in proposal.md (## Verification)`);
+      }
+      return out;
+    },
+  },
+};
+
+// Which gates guard each lifecycle transition. The single declaration.
+//
+// `apply` requires structure: mutating specs from a change whose deltas do
+// not parse is how a malformed delta reaches a spec file. This is the gate
+// `analyze` reports and that `apply` used to ignore entirely (C6).
+//
+// `archive` requires verification, and deliberately NOT structure. The
+// structure gate is a PRE-APPLY question — "is this safe to apply?" — and
+// one of its checks is that an ADDED delta's target does not already hold
+// real content. After a successful apply that target holds exactly the
+// content the delta just wrote, so re-asking at archive time reports a
+// conflict that is the proof the apply worked. A gate must be asked at the
+// point its question is meaningful.
+export const TRANSITIONS = {
+  apply: { label: "change apply", gates: ["structure"] },
+  archive: { label: "change archive", gates: ["verification"] },
+};
+
+// Evaluate a transition's gates. Returns { ok, blockers, gates } where
+// blockers is a flat list of human-readable reasons.
+export function checkTransition(projectRoot, changeDir, transition) {
+  const t = TRANSITIONS[transition];
+  if (!t) throw new Error(`unknown transition "${transition}"`);
+  const blockers = [];
+  for (const name of t.gates) {
+    for (const b of GATES[name].blockers(projectRoot, changeDir)) {
+      blockers.push({ gate: name, message: b });
+    }
+  }
+  return { ok: blockers.length === 0, blockers, gates: t.gates };
+}
+
+// Record a forced transition in the archive ledger, so a gap that was
+// waved through is part of the visible history rather than nothing at all
+// — the same posture `change archive --force` and `change abandon` take.
+export function recordForcedGap(projectRoot, id, transition, blockers) {
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
+  const ledgerPath = path.join(archiveDir, "LEDGER.md");
+  // Create the ledger if this is the first entry. A forced transition can
+  // happen before any change has ever been archived, and a gap that goes
+  // unrecorded because the file did not exist yet is exactly the silence
+  // this is meant to break.
+  if (!exists(ledgerPath)) {
+    mkdirp(archiveDir);
+    writeFileSync(ledgerPath,
+      "# Change ledger\n\n" +
+      "One line per archived change, newest last. Appended by\n" +
+      "`doctrina change archive`; edit freely, the CLI only appends.\n\n");
+  }
+  const summary = blockers.map((b) => `${b.gate}: ${b.message}`).join("; ");
+  appendFileSync(
+    ledgerPath,
+    `  - ${today()} — ${id} — forced ${transition} past ${blockers.length} ` +
+    `blocker${blockers.length === 1 ? "" : "s"} (${summary})\n`,
+  );
+  return true;
+}
+
+function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s).replace(/\[[0-9;]*m/g, "");
+}

package/src/lib/git.js

@@ -0,0 +1,97 @@
+// @ts-check
+import { spawnSync } from "node:child_process";
+
+// One place that knows how to ask git a question and how to interpret not
+// getting an answer (audit item C8).
+//
+// Nine call sites each ran `spawnSync("git", ...)` and decided for
+// themselves what a non-zero status meant. `metrics` decided it meant
+// failure, so on a brand-new project — the most common state in which
+// someone explores the CLI — it printed:
+//
+//   error: git log failed: fatal: your current branch 'master' does not
+//   have any commits yet
+//
+// A repository with no commits is a valid state, not an error. So is a
+// directory that is not a repository at all. What is genuinely an error
+// is git being absent when a command cannot work without it — and that is
+// an ENVIRONMENT condition (exit 4), not a gate failure.
+
+export const GIT_STATE = Object.freeze({
+  /** git ran and answered. */
+  OK: "ok",
+  /** A repository with no commits yet — a valid first-run state. */
+  EMPTY: "empty",
+  /** Not a git repository. */
+  NOT_A_REPO: "not-a-repo",
+  /** git is not installed or not on PATH. */
+  ABSENT: "absent",
+  /** git ran and refused, for a reason this module does not classify. */
+  FAILED: "failed",
+});
+
+// Run a git command. Never throws. Returns
+// { state, stdout, lines, stderr, code }.
+export function git(cwd, args) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8" });
+  if (r.error) {
+    // ENOENT here means the binary is missing, not that the command failed.
+    return { state: GIT_STATE.ABSENT, stdout: "", lines: [], stderr: String(r.error.message ?? ""), code: null };
+  }
+  const stderr = String(r.stderr ?? "");
+  if (r.status === 0) {
+    const stdout = String(r.stdout ?? "");
+    return { state: GIT_STATE.OK, stdout, lines: splitLines(stdout), stderr, code: 0 };
+  }
+  // git's own wording for the benign cases. Matched on the message because
+  // git reports them all with a generic non-zero status. "Needed a single
+  // revision" is what `rev-parse --verify HEAD` says on a repo with no
+  // commits, which is how the empty-history probe first fooled itself.
+  if (/does not have any commits yet|unknown revision or path not in the working tree|bad default revision|Needed a single revision|ambiguous argument 'HEAD'/i.test(stderr)) {
+    return { state: GIT_STATE.EMPTY, stdout: "", lines: [], stderr, code: r.status };
+  }
+  if (/not a git repository/i.test(stderr)) {
+    return { state: GIT_STATE.NOT_A_REPO, stdout: "", lines: [], stderr, code: r.status };
+  }
+  // Anything else that exited non-zero is a failure, NOT a success with an
+  // empty answer. Reporting it as OK is how a caller reads "no results"
+  // from a command that actually refused.
+  return { state: GIT_STATE.FAILED, stdout: "", lines: [], stderr, code: r.status };
+}
+
+// Is this a git repository at all?
+export function isRepo(cwd) {
+  return git(cwd, ["rev-parse", "--is-inside-work-tree"]).state === GIT_STATE.OK;
+}
+
+// Does it have at least one commit? False for a fresh `git init`.
+export function hasCommits(cwd) {
+  return git(cwd, ["rev-parse", "--verify", "HEAD"]).state === GIT_STATE.OK;
+}
+
+// The state a command should report before trying to read history:
+// { usable, state, reason } where `reason` is a sentence fit to print.
+export function historyState(cwd) {
+  const probe = git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+  if (probe.state === GIT_STATE.ABSENT) {
+    return { usable: false, state: GIT_STATE.ABSENT, reason: "git is not installed or not on PATH" };
+  }
+  if (probe.state !== GIT_STATE.OK) {
+    return { usable: false, state: GIT_STATE.NOT_A_REPO, reason: "this is not a git repository" };
+  }
+  if (!hasCommits(cwd)) {
+    return { usable: false, state: GIT_STATE.EMPTY, reason: "this repository has no commits yet" };
+  }
+  return { usable: true, state: GIT_STATE.OK, reason: "" };
+}
+
+// Lines of output, trimmed and blank-filtered — what nearly every caller
+// actually wanted from stdout.
+export function gitLines(cwd, args) {
+  const r = git(cwd, args);
+  return r.state === GIT_STATE.OK ? r.lines : [];
+}
+
+function splitLines(s) {
+  return s.split(/\r?\n/).map((x) => x.trim()).filter(Boolean);
+}

package/src/lib/index-json.js

@@ -1,9 +1,22 @@
+// @ts-check
 import path from "node:path";
 import { read, write, exists } from "./fs-ops.js";
 import { cliVersion } from "./version.js";
 
 export const SCHEMA_VERSION = "0.1.0";
 
+// The artifact categories a well-formed index.json carries. ONE definition,
+// consumed by `blank()` (what `init` writes) and by `templates check` /
+// `templates update` (what a project is measured against).
+//
+// There used to be two: the shape `init` materialised from a template file
+// and the shape `templates check` required. Nothing compared them, so when
+// `contracts` was added to the expected shape and not to the template,
+// every project was born needing a scaffold update (audit item C5).
+export const ARTIFACT_CATEGORIES = Object.freeze([
+  "specs", "decisions", "changes", "changes_archive", "skills", "contracts",
+]);
+
 export function indexPath(projectRoot) {
   return path.join(projectRoot, ".doctrina", "index.json");
 }
@@ -46,12 +59,7 @@ export function blank(projectName, date) {
         version: "0.1.0",
         last_updated: date,
       },
-      specs: [],
-      decisions: [],
-      changes: [],
-      changes_archive: [],
-      skills: [],
-      contracts: [],
+      ...Object.fromEntries(ARTIFACT_CATEGORIES.map((cat) => [cat, []])),
     },
   };
 }

package/src/lib/json-out.js

@@ -0,0 +1,83 @@
+// @ts-check
+import process from "node:process";
+import { EXIT } from "./exit-codes.js";
+
+// `--json` on every command, with a versioned envelope (audit item M7).
+//
+// Five of thirty-five commands spoke JSON. Everything else emitted
+// ANSI-coloured prose, while the primary consumer is a machine. Paired with
+// the exit-code contract (ADR 0018), the two form the machine interface:
+// structured output plus a meaningful status. Without both, an autonomous
+// loop is parsing English.
+//
+// Two levels of support, and the difference is stated rather than hidden:
+//
+//   STRUCTURED — the command builds a payload describing its result. These
+//     are the read and report commands, where a result has real shape.
+//   ENVELOPE   — the command's human output is captured and returned inside
+//     a versioned envelope alongside `ok` and `exitCode`. Branch on those;
+//     the lines are there for completeness, not for parsing.
+//
+// A command with nothing better to say is still machine-consumable, which
+// is what makes "--json on every command" a claim rather than an intention.
+
+export const JSON_SCHEMA_VERSION = "1.0.0";
+
+export function wantsJson(flags) {
+  return flags?.get?.("json") === true;
+}
+
+// Print a structured payload. `command` is the invocation, `data` whatever
+// that command has to say.
+export function emitJson(command, data, { ok = true, exitCode = EXIT.OK } = {}) {
+  process.stdout.write(JSON.stringify({
+    $schema_version: JSON_SCHEMA_VERSION,
+    command,
+    ok,
+    exit_code: exitCode,
+    ...data,
+  }, null, 2) + "\n");
+}
+
+// Run `fn` with console output captured, so a command that has no
+// structured payload can still answer in JSON. Returns { code, stdout,
+// stderr } with the lines it would have printed.
+export async function captureOutput(fn) {
+  const stdout = [];
+  const stderr = [];
+  const origLog = console.log;
+  const origError = console.error;
+  const origWarn = console.warn;
+  // Some commands write to the stream directly rather than through console
+  // — `completion` emits a shell script meant for redirection. Capturing
+  // only console.* let that output escape the envelope and corrupt the
+  // JSON on stdout, so the raw stream is captured too.
+  const origWrite = process.stdout.write.bind(process.stdout);
+  const pushLines = (target, chunk) => {
+    for (const line of String(chunk).replace(/\n$/, "").split("\n")) target.push(line);
+  };
+  console.log = (...args) => stdout.push(args.map(String).join(" "));
+  console.error = (...args) => stderr.push(args.map(String).join(" "));
+  console.warn = (...args) => stderr.push(args.map(String).join(" "));
+  process.stdout.write = (chunk, ...rest) => {
+    pushLines(stdout, chunk);
+    const cb = rest.find((r) => typeof r === "function");
+    if (cb) cb();
+    return true;
+  };
+  try {
+    const code = await fn();
+    return { code: code ?? EXIT.OK, stdout, stderr };
+  } finally {
+    console.log = origLog;
+    console.error = origError;
+    console.warn = origWarn;
+    process.stdout.write = origWrite;
+  }
+}
+
+// Strip ANSI so captured lines are usable as data even when colour was on.
+export function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return String(s).replace(/\[[0-9;]*m/g, "");
+}

package/src/lib/pipeline.js

@@ -0,0 +1,161 @@
+// @ts-check
+import { getSection } from "./doc-model.js";
+
+// ORDERED requirements: what EARS cannot say.
+//
+// EARS event-driven requirements are individually true and mutually
+// unordered. "When the run finishes, the system shall append a summary" and
+// "When the analysis completes, the system shall publish the dashboard" both
+// pass every gate, and neither says the dashboard needs the analysis to have
+// run first. So "the dashboard includes this run's analysis" gets read as
+// "call the renderer at the end" without anyone checking whether the thing
+// it renders exists yet — and the failure is a published dashboard that is
+// silently one run stale, which no structural check can see.
+//
+// A Pipeline block states the order and the artifact each step hands on:
+//
+//   ### Pipeline
+//
+//   1. run-suite — produces `reports/results.json`
+//   2. analyse — requires `reports/results.json`, produces `reports/analysis.md`
+//   3. publish — requires `reports/analysis.md`
+//
+// The invariant is the one an ordered list cannot enforce on its own: a step
+// may only require what an EARLIER step produced. Requiring something a
+// later step produces is the inversion; requiring something no step produces
+// is the missing producer. Both are errors, and both are exactly the bug
+// that ships as "green, and a run behind".
+//
+// Artifacts that genuinely come from outside are marked `(external)`.
+
+/**
+ * @typedef {object} PipelineStep
+ * @property {number} number    The declared ordinal.
+ * @property {string} name
+ * @property {string[]} requires
+ * @property {string[]} produces
+ * @property {string[]} external  Requirements declared as coming from outside.
+ * @property {number} line        1-based line within the spec.
+ */
+
+/**
+ * Parse the `### Pipeline` block of a spec. Returns null when the spec
+ * declares none — the block is opt-in, so every spec written before it
+ * existed parses to null and is never checked.
+ *
+ * @returns {PipelineStep[] | null}
+ */
+export function parsePipeline(text) {
+  const section = getSection(text, "Pipeline", { level: 3 });
+  if (!section || !section.trim()) return null;
+
+  const all = String(text).split(/\r?\n/);
+  const offset = all.findIndex((l) => /^###\s+Pipeline\s*$/.test(l));
+
+  const steps = [];
+  const lines = section.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^\s*(\d+)\.\s+(.*\S)\s*$/);
+    if (!m) continue;
+    const number = Number.parseInt(m[1], 10);
+    const body = m[2];
+
+    // The step name is everything up to the first clause separator.
+    const name = body.split(/\s+[—-]\s+|\s*,\s*(?=requires|produces)/)[0].trim();
+
+    steps.push({
+      number,
+      name,
+      requires: clause(body, "requires").filter((a) => !a.external).map((a) => a.name),
+      external: clause(body, "requires").filter((a) => a.external).map((a) => a.name),
+      produces: clause(body, "produces").map((a) => a.name),
+      line: offset >= 0 ? offset + 1 + i + 1 : i + 1,
+    });
+  }
+  return steps;
+}
+
+// The artifacts named by one clause: `requires \`a\`, \`b\` (external)`.
+// Backticks are how a spec already marks a path, so they are the anchor.
+function clause(body, keyword) {
+  const re = new RegExp(`${keyword}\\s+([^;]*?)(?=(?:\\brequires\\b|\\bproduces\\b|$))`, "i");
+  const m = body.match(re);
+  if (!m) return [];
+  const out = [];
+  for (const artifact of m[1].matchAll(/`([^`]+)`(\s*\(external\))?/g)) {
+    out.push({ name: artifact[1].trim(), external: Boolean(artifact[2]) });
+  }
+  return out;
+}
+
+/**
+ * Check the ordering invariant.
+ * @param {PipelineStep[]} steps
+ * @returns {Array<{code: string, level: "error"|"warn", message: string, remedy: string, line: number}>}
+ */
+export function checkPipeline(steps) {
+  /** @type {Array<{code: string, level: "error"|"warn", message: string, remedy: string, line: number}>} */
+  const findings = [];
+  if (!steps || steps.length === 0) return findings;
+
+  // Numbering first: an out-of-order list is not a pipeline, and every
+  // check below reads the declared order as the real one.
+  for (let i = 0; i < steps.length; i++) {
+    if (steps[i].number !== i + 1) {
+      findings.push({
+        code: "PL01",
+        level: "error",
+        message: `pipeline step ${i + 1} is numbered ${steps[i].number} ("${steps[i].name}") — the order a pipeline declares must be the order it reads in`,
+        remedy: "renumber the Pipeline steps 1..n in execution order",
+        line: steps[i].line,
+      });
+    }
+  }
+
+  // Everything produced at or before each index, which is what "earlier"
+  // means. Built as we walk, so a step can never satisfy itself.
+  const producedBefore = new Set();
+  const producedBy = new Map();
+  for (const step of steps) {
+    for (const artifact of step.produces) {
+      if (!producedBy.has(artifact)) producedBy.set(artifact, step);
+    }
+  }
+
+  for (const step of steps) {
+    for (const artifact of step.requires) {
+      if (producedBefore.has(artifact)) continue;
+
+      const producer = producedBy.get(artifact);
+      if (producer && producer.number > step.number) {
+        // The inversion: the consumer runs first and reads last run's file.
+        findings.push({
+          code: "PL02",
+          level: "error",
+          message: `step ${step.number} ("${step.name}") requires \`${artifact}\`, which step ${producer.number} ("${producer.name}") produces LATER — this step can only ever read the previous run's copy`,
+          remedy: `move "${producer.name}" before "${step.name}", or make the dependency explicit and drop the requirement`,
+          line: step.line,
+        });
+      } else if (producer && producer.number === step.number) {
+        findings.push({
+          code: "PL02",
+          level: "error",
+          message: `step ${step.number} ("${step.name}") both requires and produces \`${artifact}\``,
+          remedy: `split the step, or mark the input \`${artifact}\` (external) if it comes from outside the pipeline`,
+          line: step.line,
+        });
+      } else {
+        findings.push({
+          code: "PL03",
+          level: "error",
+          message: `step ${step.number} ("${step.name}") requires \`${artifact}\`, which no step produces — the step runs against a file nothing in this pipeline creates`,
+          remedy: `add the producing step, or mark it \`${artifact}\` (external) to declare it comes from outside`,
+          line: step.line,
+        });
+      }
+    }
+    for (const artifact of step.produces) producedBefore.add(artifact);
+  }
+
+  return findings;
+}

package/src/lib/prompt.js

@@ -1,4 +1,15 @@
+// @ts-check
 import readline from "node:readline";
+import process from "node:process";
+
+// Is there a real person on the other end? Every prompt must ask this
+// first. `init` checked it before the ADAPTER prompt but not before the
+// project-description prompt, so a non-interactive caller that forgot
+// --non-interactive got a project with a blank description and no warning
+// (audit item C9).
+export function isInteractive() {
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
 
 export async function ask(question, { defaultValue = "" } = {}) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
@@ -11,7 +22,13 @@ export async function ask(question, { defaultValue = "" } = {}) {
   }
 }
 
-export async function confirm(question, { defaultYes = false } = {}) {
+// Ask for consent. Off a terminal there is nobody to ask, so the answer is
+// `whenNonInteractive` — which callers set to false for destructive
+// operations: silence is not consent.
+export async function confirm(question, { defaultYes = false, whenNonInteractive = null } = {}) {
+  if (!isInteractive()) {
+    return whenNonInteractive === null ? defaultYes : whenNonInteractive;
+  }
   const suffix = defaultYes ? "Y/n" : "y/N";
   const ans = await ask(`${question} (${suffix})`);
   if (!ans) return defaultYes;