doctrina-cli 0.15.1 → 0.17.0

package/src/lib/intake-model.js

@@ -0,0 +1,155 @@
+// @ts-check
+// Writing the intake and printing the bootstrap playbook.
+//
+// `init --intake` performs the same three operations `intake` does, and
+// reached into `commands/intake.js` for them (audit finding F7). They are
+// operations over the tree, not renderings of one command, so both
+// entry points read them from here.
+import path from "node:path";
+import { exists, isFile, read, relPath, write } from "./fs-ops.js";
+import { assessBrief } from "./clarity.js";
+import { c } from "./colors.js";
+import { printPlaybookTemplate } from "./playbook.js";
+import { getHeader, setHeader } from "./doc-model.js";
+import { stateWord } from "./spec-ops.js";
+// Clarification gate (review Topic A). A description too thin to spec from is
+// the moment to ask the user, not to let the agent invent requirements. Prints
+// the specific gaps before the bootstrap playbook; advisory, never blocking —
+// the intake is still captured verbatim (the playbook step 6 resolves it).
+/**
+ * Does this argument read as a FILE PATH, or as the description itself?
+ *
+ * `doctrina intake "<description>"` is the form the surface block's wording
+ * invites — "store the intent" — and it answered `description file not found:`
+ * followed by the author's whole sentence, echoed back as if it were a
+ * filename, with no mention of `--text` (change 0071). Prose and a path are
+ * distinguishable without guessing: a path has no sentence in it.
+ *
+ * Deliberately conservative — anything that could be a path IS treated as one,
+ * so a real file is never mistaken for prose and read as a description.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function looksLikePath(value) {
+  const v = String(value).trim();
+  if (v === "") return false;
+  if (/[/\\]/.test(v)) return true;            // a separator settles it
+  if (/^[.~]/.test(v)) return true;             // ./x, ../x, ~/x
+  if (!/\s/.test(v)) return true;              // one token: assume a filename
+  if (/\.(md|txt|markdown|rst|adoc|org)$/i.test(v)) return true; // "my notes.txt"
+  return false;
+}
+
+// What `init` tells a person to do next (change 0173). The first run used to
+// contradict itself three ways: `init` said "edit AGENTS.md and product.md",
+// `next` asked for the description again as an intake, and AGENTS.md said the
+// agent runs the commands while the human stays passive. One answer now,
+// the same one `next` and AGENTS.md give.
+//
+// `intakeFrom` is "tty" when the description was typed at init's question
+// (it is stored as the intake), or null when init got no intake at all.
+export function nextStepAfterInit(intakeFrom) {
+  if (intakeFrom === "tty") {
+    return [
+      "Next: open your AI agent in this repository and tell it:",
+      "    read AGENTS.md and run doctrina next",
+      "It turns your description into product.md and specs; you review and approve.",
+    ];
+  }
+  return [
+    "Next: give your AI agent the whole project description. It runs",
+    "    doctrina intake --text \"<description>\"",
+    "and turns it into product.md and specs (AGENTS.md, \"Working from intent\");",
+    "for an existing codebase, `doctrina work --from-diff` backfills them from the code.",
+  ];
+}
+
+export function warnIfThinIntake(body) {
+  const assessment = assessBrief(body, { kind: "intake" });
+  if (!assessment.thin) return;
+  console.log(c.yellow("⚠ thin intake — clarify with the user before converting to specs:"));
+  for (const reason of assessment.reasons) console.log(`    - ${reason}`);
+  console.log("");
+}
+
+// THE INTAKE'S STATUS IS A CONTROL VALUE, SO IT GETS AN ENUM AND AN OWNER.
+//
+// `next` branches on it: pending means the bootstrap is unfinished, and every
+// other artifact's status in this framework is both written by a command and
+// checked against an enum — `spec set` refuses "Status: nonsense", and
+// `validate` calls it an error. The intake was the one header the playbook
+// told an agent to edit BY HAND, and the one nothing read back.
+//
+// So any token that was not exactly "converted" meant pending, in silence:
+// "convertido" typed in a Portuguese project, "done", or an empty value left
+// by a botched edit. `validate` exited 0 on all of them and `next` went on
+// asking for a bootstrap that had already happened.
+export const INTAKE_STATUSES = ["pending", "converted"];
+
+/** The intake's status word, note stripped and folded. Defaults to pending. */
+export function intakeStatus(text) {
+  const raw = getHeader(String(text ?? ""), "Status");
+  if (raw === null) return "pending";
+  return stateWord(raw) || "";
+}
+
+/** null when the intake's status is a declared value; otherwise the error. */
+export function intakeStatusError(text) {
+  const word = intakeStatus(text);
+  if (INTAKE_STATUSES.includes(word)) return null;
+  const got = getHeader(String(text ?? ""), "Status");
+  return `Status must be one of ${INTAKE_STATUSES.join("|")} `
+    + `(got "${String(got ?? "").trim()}") — every other value reads as pending, in silence`;
+}
+
+/**
+ * Flip the stored intake to `converted`. Returns the path written, or null
+ * when there is no intake (or no Status header) to flip.
+ */
+export function markIntakeConverted(projectRoot) {
+  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
+  if (!exists(intakePath)) return null;
+  const next = setHeader(read(intakePath), "Status", "converted");
+  if (next === null) return null;
+  write(intakePath, next, { force: true });
+  return intakePath;
+}
+
+// Shared with `init --intake`. Writes the intake verbatim under a small
+// status header; `doctrina intake --converted` flips it at the end of the
+// playbook, which is how `next` knows the bootstrap is done.
+export function writeIntakeFile(projectRoot, { body, source, projectName, date, force = false }) {
+  const intakePath = path.join(projectRoot, ".doctrina", "intake.md");
+  const content = [
+    `# Intake — ${projectName}`,
+    "",
+    "- **Status:** pending",
+    `- **Date:** ${date}`,
+    `- **Source:** ${source}`,
+    "",
+    "<!-- Raw project intent, stored verbatim. The bootstrap playbook",
+    "     (doctrina intake) converts it into product.md and capability",
+    "     specs. Close it with `doctrina intake --converted`; after that the",
+    "     specs are the only source of truth; never edit this file to",
+    "     change requirements. -->",
+    "",
+    "---",
+    "",
+    body.replace(/\r\n/g, "\n").replace(/\n*$/, "\n"),
+  ].join("\n");
+  write(intakePath, content, { force });
+  return intakePath;
+}
+
+// The bootstrap playbook, like the work and chore playbooks, is a TEMPLATE
+// resolved project-over-bundled (audit finding F17). What stays here is the
+// one conditional: a tree that never got its specs/ directory.
+export function printBootstrapPlaybook(projectRoot) {
+  const hasSpecs = exists(path.join(projectRoot, ".doctrina", "specs"));
+  printPlaybookTemplate(projectRoot, "bootstrap", {
+    MISSING_SPECS_WARNING: hasSpecs
+      ? ""
+      : "\n" + c.yellow("warn:") + " .doctrina/specs/ is missing — re-run `doctrina init` first.",
+  });
+}

package/src/lib/json-out.js

@@ -27,14 +27,99 @@ export function wantsJson(flags) {
   return flags?.get?.("json") === true;
 }
 
+// A deprecation notice belongs in the ENVELOPE, not only on the terminal
+// (change 0061). Change 0049 announced a superseded name on the real stderr,
+// before capture — right for a piped stdout, which stays exactly what it
+// was, but it meant the envelope's `stderr` array came back empty and the
+// machine reading only that never learned the name it invoked is on its way
+// out. Deprecation exists so consumers migrate, and this CLI's primary
+// consumer is an agent reading JSON.
+//
+// Set once by the entrypoint, before the command runs, so BOTH json paths
+// carry it: the captured envelope and a command that builds its own payload.
+/** @type {{ use: string, since: string, why: string } | null} */
+let deprecation = null;
+
+/** @param {{ use: string, since: string, why: string } | null} record */
+export function setDeprecation(record) {
+  deprecation = record;
+}
+
+// A command that builds its own payload calls `emitJson` BEFORE it returns —
+// in `coverage.js` the call sits one line above `return jsonClean ? 0 :
+// strict ? 1 : 0`. So the call site cannot know the exit code, and the
+// optimistic defaults answered for it: `coverage --strict` exited 1 while
+// its payload said `"ok": true, "exit_code": 0`, and `exit_code` was 0 in
+// every native payload the CLI has ever emitted (change 0086).
+//
+// The entrypoint is the one place that knows the code, which is why the
+// CAPTURED path (a command with no payload of its own) was always right: it
+// emits after the run, with the real code. The native path now works the
+// same way — `deferJson()` before the run holds the payload, `flushJson(code)`
+// after it writes the envelope with the verdict the process actually reports.
+/** @type {{ command: string, data: object, opts: object } | null} */
+let held = null;
+let deferring = false;
+
+/** Hold the next payload instead of writing it, until `flushJson`. */
+export function deferJson() {
+  deferring = true;
+  held = null;
+}
+
+/**
+ * Write the held payload with the exit code the command actually returned,
+ * and leave deferred mode. A no-op when the command emitted nothing.
+ */
+export function flushJson(code) {
+  deferring = false;
+  if (!held) return;
+  const { command, data } = held;
+  held = null;
+  writeEnvelope(command, data, { ok: code === EXIT.OK, exitCode: code });
+}
+
 // 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 } = {}) {
+/**
+ * @param {string} command The OPERATION, never the operation plus arguments.
+ * @param {Record<string, unknown>} data
+ * @param {{ ok?: boolean, exitCode?: number, args?: string[] }} [opts]
+ */
+export function emitJson(command, data, opts = {}) {
+  if (deferring) {
+    held = { command, data, opts };
+    return;
+  }
+  writeEnvelope(command, data, opts);
+}
+
+/**
+ * `EXIT` is frozen, so its members infer as literal types — without this the
+ * default `exitCode = EXIT.OK` narrows the parameter to `0`.
+ *
+ * @param {string} command
+ * @param {Record<string, unknown>} data
+ * @param {{ ok?: boolean, exitCode?: number, args?: string[] }} [opts]
+ */
+function writeEnvelope(command, data, { ok = true, exitCode = EXIT.OK, args } = {}) {
   process.stdout.write(JSON.stringify({
     $schema_version: JSON_SCHEMA_VERSION,
+    // The OPERATION, never the operation plus its arguments. `command` used
+    // to carry `"why carteira"`, so the field a consumer branches on took a
+    // different value for every capability — while `next --json` documents
+    // `command`/`args` as the contract (third audit, finding 6). A
+    // sub-operation like `spec list` IS the operation and stays whole; the
+    // catalog is what tells the two apart.
     command,
     ok,
     exit_code: exitCode,
+    // Present when the invocation carried arguments, so it stays
+    // reconstructible without parsing the name.
+    ...(args && args.length > 0 ? { args } : {}),
+    // Present only when the invoked name is superseded, so a consumer can
+    // branch on its presence rather than on a string.
+    ...(deprecation ? { deprecated: deprecation } : {}),
     ...data,
   }, null, 2) + "\n");
 }
@@ -53,8 +138,14 @@ export async function captureOutput(fn) {
   // 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);
+  // The raw stderr stream is captured too (change 0114): `verify` tees a
+  // child's stderr straight to process.stderr, so a failing check's
+  // diagnostics landed on the real stderr while the envelope said
+  // `"stderr": []`. Carriage returns are stripped — a child on Windows
+  // writes CRLF, and `"ok\r"` is not a line.
+  const origErrWrite = process.stderr.write.bind(process.stderr);
   const pushLines = (target, chunk) => {
-    for (const line of String(chunk).replace(/\n$/, "").split("\n")) target.push(line);
+    for (const line of String(chunk).replace(/\r?\n$/, "").split(/\r?\n/)) target.push(line.replace(/\r$/, ""));
   };
   console.log = (...args) => stdout.push(args.map(String).join(" "));
   console.error = (...args) => stderr.push(args.map(String).join(" "));
@@ -65,6 +156,12 @@ export async function captureOutput(fn) {
     if (cb) cb();
     return true;
   };
+  process.stderr.write = (chunk, ...rest) => {
+    pushLines(stderr, 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 };
@@ -73,6 +170,7 @@ export async function captureOutput(fn) {
     console.error = origError;
     console.warn = origWarn;
     process.stdout.write = origWrite;
+    process.stderr.write = origErrWrite;
   }
 }
 

package/src/lib/ledger.js

@@ -0,0 +1,192 @@
+// @ts-check
+// The archive ledger, read as well as written.
+//
+// `.doctrina/changes/archive/LEDGER.md` is a structured log — date, change
+// id, title, and the capabilities the change touched with the operation it
+// performed on each — and for two releases exactly two things read it: an
+// id set in `decision scope`, and a cross-check in `validate`. Everything
+// else that wanted to know "what has been happening here" derived it from
+// git, which knows about files and nothing about capabilities (audit
+// findings F13, F14).
+//
+// The parse is DELIBERATELY tolerant. The file's own header invites humans
+// to edit it and promises the CLI only appends, so a line that does not
+// match the grammar is not a corrupt ledger — it is a person writing a note.
+// Such lines are counted, never thrown, and never rewritten.
+import path from "node:path";
+import { appendFileSync } from "node:fs";
+import { exists, isFile, mkdirp, read, write } from "./fs-ops.js";
+import { today } from "./dates.js";
+
+export const LEDGER_REL = ".doctrina/changes/archive/LEDGER.md";
+
+const HEADER =
+  "# 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";
+
+export function ledgerPath(projectRoot) {
+  return path.join(projectRoot, ...LEDGER_REL.split("/"));
+}
+
+// One entry per recognised line. `kind` separates the three things the CLI
+// records, because they mean different things to a reader: a change that
+// LANDED, one that was discarded, and a gate that was waved through.
+/**
+ * @typedef {{
+ *   date: string, id: string, kind: "archived"|"abandoned"|"gap",
+ *   title: string, specs: {capability: string, operation: string}[],
+ *   line: number, raw: string
+ * }} LedgerEntry
+ */
+
+// `- YYYY-MM-DD — <id> — <rest>`, with either an em dash or a hyphen as the
+// separator and any indentation (a gap line is indented). The date's month
+// and day are range-checked: a bullet a person typed by hand is far more
+// likely to be prose that happens to start with digits than an entry, and
+// admitting it would put a fictional date into a churn window.
+const LINE_RE = /^\s*-\s+(\d{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01]))\s+[—-]\s+(\S+)\s+[—-]\s+(.*)$/;
+const SPECS_RE = /\(specs:\s*([^)]*)\)\s*$/;
+
+/**
+ * Parse ledger text into entries.
+ *
+ * @param {string} text
+ * @returns {{entries: LedgerEntry[], unparsed: number}}
+ */
+export function parseLedger(text) {
+  const entries = [];
+  let unparsed = 0;
+  const lines = String(text ?? "").split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (raw.trim() === "") continue;
+    const m = raw.match(LINE_RE);
+    if (!m) {
+      // Prose, the file's own header, a hand-written note: not an entry, and
+      // not an error either.
+      if (/^\s*-\s/.test(raw)) unparsed += 1;
+      continue;
+    }
+    const [, date, id, rest] = m;
+    const trimmed = rest.trim();
+    let kind = /** @type {"archived"|"abandoned"|"gap"} */ ("archived");
+    if (/^abandoned\b/i.test(trimmed)) kind = "abandoned";
+    else if (/^(?:forced|docs gap)\b/i.test(trimmed)) kind = "gap";
+
+    const specsMatch = trimmed.match(SPECS_RE);
+    const specs = specsMatch ? parseSpecs(specsMatch[1]) : [];
+    const title = specsMatch ? trimmed.slice(0, specsMatch.index).trim() : trimmed;
+    entries.push({ date, id, kind, title, specs, line: i + 1, raw });
+  }
+  return { entries, unparsed };
+}
+
+// "cli MODIFIED, gates MODIFIED" → [{capability, operation}]. An entry whose
+// operation is missing keeps the capability: the capability is the fact the
+// consumers need, and dropping the pair over a missing verb would lose it.
+function parseSpecs(list) {
+  const out = [];
+  for (const part of list.split(",")) {
+    const t = part.trim();
+    if (!t) continue;
+    const m = t.match(/^([a-z][a-z0-9-]*)(?:\s+([A-Z]+))?$/);
+    if (!m) continue;
+    out.push({ capability: m[1], operation: m[2] ?? "" });
+  }
+  return out;
+}
+
+/**
+ * Read and parse the project's ledger.
+ *
+ * @param {string} projectRoot
+ * @returns {{path: string, exists: boolean, entries: LedgerEntry[], unparsed: number}}
+ */
+export function readLedger(projectRoot) {
+  const p = ledgerPath(projectRoot);
+  if (!isFile(p)) return { path: p, exists: false, entries: [], unparsed: 0 };
+  const { entries, unparsed } = parseLedger(read(p));
+  return { path: p, exists: true, entries, unparsed };
+}
+
+/**
+ * How often each capability was touched, newest first by count.
+ *
+ * The number is reported, never judged: a spec that changes often may be
+ * badly drawn or may simply be where the work is, and the CLI has no way to
+ * tell those apart (ADR 0005). Only landed changes count — an abandoned
+ * change touched nothing, and a forced-gap line records a waived gate rather
+ * than a spec edit.
+ *
+ * @param {LedgerEntry[]} entries
+ * @param {{since?: string|null}} [options] since — ISO date, inclusive
+ * @returns {{capability: string, changes: number, last: string}[]}
+ */
+export function churnByCapability(entries, { since = null } = {}) {
+  const seen = new Map();
+  for (const e of entries) {
+    if (e.kind !== "archived") continue;
+    if (since && e.date < since) continue;
+    for (const s of e.specs) {
+      const row = seen.get(s.capability) ?? { capability: s.capability, changes: 0, last: "" };
+      row.changes += 1;
+      if (e.date > row.last) row.last = e.date;
+      seen.set(s.capability, row);
+    }
+  }
+  return [...seen.values()].sort((a, b) => b.changes - a.changes || a.capability.localeCompare(b.capability));
+}
+
+/**
+ * Append one line, creating the ledger when this is its first entry.
+ *
+ * The three things that write the ledger — archive, abandon, and a forced
+ * transition — used to carry their own copy of this header and their own
+ * append, so the format the parser above reads had three authors. 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 the ledger exists to break.
+ *
+ * @param {string} projectRoot
+ * @param {string} line  the entry, without the trailing newline
+ */
+export function appendLedgerLine(projectRoot, line) {
+  const p = ledgerPath(projectRoot);
+  if (!exists(p)) {
+    mkdirp(path.dirname(p));
+    write(p, HEADER);
+  }
+  appendFileSync(p, `${line}\n`);
+  return p;
+}
+
+/** The canonical line for an archived change. */
+export function archivedLine(id, title, specsAffected = [], date = today()) {
+  const specs = specsAffected.length > 0
+    ? ` (specs: ${specsAffected.map((s) => `${s.capability} ${s.operation}`).join(", ")})`
+    : "";
+  return `- ${date} — ${id} — ${title}${specs}`;
+}
+
+/** The canonical line for an abandoned change. */
+export function abandonedLine(id, reason = "", date = today()) {
+  return `- ${date} — ${id} — abandoned${reason ? ` — ${reason}` : ""}`;
+}
+
+/** The canonical line for a lifecycle gate that was waved through. */
+export function forcedLine(id, transition, blockers, date = today()) {
+  const summary = blockers.map((b) => `${b.gate}: ${b.message}`).join("; ");
+  return `  - ${date} — ${id} — forced ${transition} past ${blockers.length} ` +
+    `blocker${blockers.length === 1 ? "" : "s"} (${summary})`;
+}
+
+/**
+ * The canonical line for a docs gap closed with --force.
+ *
+ * It follows the entry grammar rather than being free prose, because a
+ * waived gate that no reader can find is the same as an unrecorded one.
+ */
+export function docsGapLine(id, signals, date = today()) {
+  return `  - ${date} — ${id} — docs gap: closed with --force; ${signals.join("; ")} documented nowhere`;
+}