doctrina-cli 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# doctrina-cli
+
+> CLI for the Doctrina framework. The package is published as
+> `doctrina-cli`; the executable it installs is `doctrina`.
+
+**Status:** v0.1.0 — first working release. Zero runtime dependencies
+(Node.js standard library only).
+
+## Install
+
+```
+npm install -g doctrina-cli
+# or run on demand
+npx doctrina-cli init
+```
+
+Requires Node.js 20.12 or later.
+
+## Commands
+
+```
+doctrina init                              scaffold AGENTS.md + .doctrina/ in cwd
+doctrina spec new <capability>             create a capability spec
+doctrina change new <id> "<title>"         open a change proposal
+doctrina change apply <id>                 apply spec deltas (ADDED/REMOVED auto)
+doctrina change archive <id>               archive an applied change
+doctrina decision new "<title>"            create the next sequential ADR
+doctrina decision supersede <num> "<t>"    supersede an existing ADR
+doctrina analyze <change-id>               inspect a change folder before applying
+doctrina clarify <path>                    smell-test a Markdown file for ambiguity
+doctrina validate                          schema + artifact-existence checks
+doctrina templates list                    enumerate shipped templates
+doctrina templates check                   compare project against recommended template shape
+doctrina hooks install                     install pre-commit hook
+doctrina --help | -h                       print the command surface
+doctrina --version | -v                    print the package version
+```
+
+Per-command help is available with `doctrina <command> --help`.
+
+## `init` flags
+
+| Flag | Purpose |
+|------|---------|
+| `--project-name <name>` | Override the project name (defaults to cwd basename) |
+| `--project-description <text>` | One-sentence description (prompted if omitted) |
+| `--agent <name>` | Install adapter for `claude`, `codex`, `cursor`, or `all` |
+| `--date <YYYY-MM-DD>` | Override the system date in artifacts |
+| `--force` | Overwrite existing files |
+| `--non-interactive` | Fail instead of prompting for missing required values |
+
+## Adapter behaviour
+
+- `--agent claude` writes a `CLAUDE.md` at the project root that
+  `@`-imports `AGENTS.md`. Claude Code picks it up automatically.
+- `--agent codex` installs nothing. OpenAI Codex CLI reads `AGENTS.md`
+  natively.
+- `--agent cursor` writes `.cursor/rules/00-doctrina.mdc` with
+  `alwaysApply: true` pointing at `AGENTS.md`.
+- `--agent all` installs every adapter.
+
+All adapter files are kept under 30 lines to avoid per-turn token tax
+and to make drift from `AGENTS.md` mechanically impossible.
+
+## `change apply` semantics
+
+For each spec delta found under `.doctrina/changes/<id>/specs/`:
+
+- **ADDED:** writes the delta body to the target spec; refuses if the
+  target already exists.
+- **REMOVED:** deletes the target spec.
+- **MODIFIED:** prints a manual-merge pointer and does not write. The
+  user merges the delta into the target spec by hand. This is
+  deliberate; auto-merging is the kind of implicit decision Doctrina
+  avoids.
+
+## `validate` checks
+
+1. `AGENTS.md` exists at root and is ≤ 200 lines (warns at > 150).
+2. `.doctrina/product.md` exists.
+3. `.doctrina/index.json` parses and matches the v0.1 shape.
+4. Every artifact referenced in `index.json` exists.
+5. Every ADR has a parseable `Status:` header.
+6. Every adapter template under `.doctrina/templates/adapters/` is ≤ 30 lines.
+7. Every open change has a `proposal.md`.
+8. Capability specs are ≤ 400 lines (warns above).
+9. ADRs are ≤ 300 lines (warns above).
+10. Spec/ADR files on disk are present in `index.json` (orphan warn).
+11. Markdown links inside specs/ADRs resolve to real files (stale ref warn).
+
+Exit code: 0 if no errors (warnings allowed), 1 otherwise.
+
+## Tests
+
+```
+npm test
+```
+
+Runs the suite via the built-in Node test runner. The integration tests
+spawn the CLI as a subprocess and exercise the full surface against a
+temporary project directory.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "doctrina-cli",
+  "version": "0.1.0",
+  "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
+  "license": "MIT",
+  "keywords": [
+    "agents-md",
+    "spec-driven-development",
+    "sdd",
+    "ai-coding-agents",
+    "claude-code",
+    "codex",
+    "cursor",
+    "adr"
+  ],
+  "type": "module",
+  "bin": {
+    "doctrina": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gcarin1/doctrina.git",
+    "directory": "packages/doctrina-cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/analyze.js

@@ -0,0 +1,126 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isDir, isFile, read, walk } from "../lib/fs-ops.js";
+import { c } from "../lib/colors.js";
+
+export async function run(positional, _flags) {
+  const id = positional[0];
+  if (!id) {
+    console.error(c.red("error:") + " analyze requires <change-id>");
+    return 2;
+  }
+
+  const projectRoot = process.cwd();
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" not found at ${path.relative(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  console.log(`analyzing ${path.relative(projectRoot, changeDir)}/`);
+  console.log("");
+
+  const results = [];
+
+  // proposal.md
+  const proposalPath = path.join(changeDir, "proposal.md");
+  if (!isFile(proposalPath)) {
+    results.push(fail("proposal.md missing"));
+  } else {
+    results.push(pass("proposal.md present"));
+    const text = read(proposalPath);
+    if (/^##\s+Why\b/m.test(text)) results.push(pass(`proposal.md has a "## Why" section`));
+    else results.push(fail(`proposal.md missing "## Why" section`));
+  }
+
+  // tasks.md
+  const tasksPath = path.join(changeDir, "tasks.md");
+  if (!isFile(tasksPath)) {
+    results.push(fail("tasks.md missing"));
+  } else {
+    results.push(pass("tasks.md present"));
+    const text = read(tasksPath);
+    if (/^\s*-\s*\[\s\]/m.test(text)) results.push(pass("tasks.md has at least one unchecked task"));
+    else results.push(info("tasks.md has no unchecked tasks (already done?)"));
+  }
+
+  // design.md (optional)
+  const designPath = path.join(changeDir, "design.md");
+  if (isFile(designPath)) results.push(info("design.md present"));
+  else results.push(info("design.md absent (optional)"));
+
+  // Spec deltas
+  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
+  if (deltaFiles.length === 0) {
+    results.push(info("0 spec deltas (metadata-only change)"));
+  } else {
+    results.push(pass(`${deltaFiles.length} spec delta${deltaFiles.length === 1 ? "" : "s"}:`));
+    for (const deltaPath of deltaFiles) {
+      const rel = path.relative(projectRoot, deltaPath);
+      const text = read(deltaPath);
+      const opMatch = text.match(/^\*\*Operation:\*\*\s*([A-Z]+)/m);
+      const op = opMatch ? opMatch[1] : null;
+      const capMatch = text.match(/^#\s+Spec Delta\s*[—-]\s*capability:\s*([a-z][a-z0-9-]*)/m);
+      const cap = capMatch ? capMatch[1] : path.basename(path.dirname(deltaPath));
+
+      if (!op) {
+        results.push(fail(`  ${rel}: Operation header missing or malformed`, "  "));
+        continue;
+      }
+      if (!["ADDED", "MODIFIED", "REMOVED"].includes(op)) {
+        results.push(fail(`  ${rel}: Operation "${op}" is not one of ADDED|MODIFIED|REMOVED`, "  "));
+        continue;
+      }
+      const targetSpec = path.join(projectRoot, ".doctrina", "specs", cap, "spec.md");
+      const targetRel = path.relative(projectRoot, targetSpec);
+      if (op === "ADDED") {
+        if (exists(targetSpec)) {
+          results.push(fail(`  ${cap} (ADDED) but target ${targetRel} already exists`, "  "));
+        } else {
+          results.push(pass(`  ${cap} (ADDED) → ${targetRel} (new)`, "  "));
+        }
+      } else if (op === "MODIFIED") {
+        if (!exists(targetSpec)) {
+          results.push(fail(`  ${cap} (MODIFIED) but target ${targetRel} does not exist`, "  "));
+        } else {
+          results.push(pass(`  ${cap} (MODIFIED) → ${targetRel}`, "  "));
+        }
+      } else {
+        if (!exists(targetSpec)) {
+          results.push(fail(`  ${cap} (REMOVED) but target ${targetRel} does not exist`, "  "));
+        } else {
+          results.push(pass(`  ${cap} (REMOVED) → ${targetRel}`, "  "));
+        }
+      }
+    }
+  }
+
+  for (const r of results) console.log(r.line);
+  console.log("");
+
+  const failed = results.filter((r) => r.kind === "fail").length;
+  if (failed === 0) {
+    console.log(c.green("ok") + ` ready to apply`);
+  } else {
+    console.log(c.red("fail") + ` ${failed} issue${failed === 1 ? "" : "s"}`);
+  }
+  return failed === 0 ? 0 : 1;
+}
+
+function pass(msg) {
+  return { kind: "pass", line: c.green("✓ ") + msg };
+}
+function fail(msg) {
+  return { kind: "fail", line: c.red("✗ ") + msg };
+}
+function info(msg) {
+  return { kind: "info", line: c.gray("- ") + msg };
+}
+
+export const help = `
+Usage: doctrina analyze <change-id>
+
+Inspect a change folder before applying. Reports on proposal,
+tasks, design, and each spec delta. Exits 0 when no failures, 1
+otherwise. Does not modify any files.
+`;

package/src/commands/change.js

@@ -0,0 +1,292 @@
+import path from "node:path";
+import process from "node:process";
+import { exists, isDir, mkdirp, move, read, remove, walk, write } from "../lib/fs-ops.js";
+import { locateTemplatesDir, loadTemplateTree, materialiseEntry } from "../lib/templates.js";
+import * as idx from "../lib/index-json.js";
+import { today } from "../lib/dates.js";
+import { flagBool } from "../lib/args.js";
+import { c } from "../lib/colors.js";
+import { suggest } from "../lib/suggest.js";
+
+const SUBCOMMANDS = ["new", "apply", "archive"];
+
+export async function run(positional, flags) {
+  const sub = positional[0];
+  switch (sub) {
+    case "new":
+      return changeNew(positional.slice(1), flags);
+    case "apply":
+      return changeApply(positional.slice(1), flags);
+    case "archive":
+      return changeArchive(positional.slice(1), flags);
+    default:
+      console.error(c.red("error:") + ` unknown change subcommand "${sub ?? ""}"`);
+      const guess = suggest(sub, SUBCOMMANDS);
+      console.error(c.gray("hint: ") + (guess
+        ? `did you mean \`doctrina change ${guess}\`?`
+        : `available: ${SUBCOMMANDS.join(", ")}`));
+      return 2;
+  }
+}
+
+function changeNew(args, flags) {
+  const id = args[0];
+  const title = args.slice(1).join(" ").trim();
+  if (!id) {
+    console.error(c.red("error:") + " change new requires <id> and \"<title>\"");
+    return 2;
+  }
+  if (!title) {
+    console.error(c.red("error:") + " change new requires a title (quote it if it contains spaces)");
+    return 2;
+  }
+
+  const force = flagBool(flags, "force", false);
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (exists(changeDir) && !force) {
+    console.error(c.red("error:") + ` change "${id}" already exists at ${path.relative(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  const templatesDir = locateTemplatesDir();
+  const date = today();
+  const tokens = { CHANGE_ID: id, CHANGE_TITLE: title, DATE: date, CAPABILITY: "" };
+
+  const tree = loadTemplateTree(templatesDir, "change");
+  for (const entry of tree) {
+    if (entry.relativePath === "spec-delta.md.template") continue;
+    const written = materialiseEntry(entry, changeDir, tokens, { force });
+    console.log(c.green("created") + ` ${path.relative(projectRoot, written)}`);
+  }
+  mkdirp(path.join(changeDir, "specs"));
+
+  const index = idx.load(projectRoot);
+  idx.addChange(index, { id, title, path: `.doctrina/changes/${id}`, status: "proposed", opened: date });
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+
+  console.log("");
+  console.log(c.bold("Change opened.") + " Add spec deltas under " +
+    c.cyan(`.doctrina/changes/${id}/specs/<capability>/delta.md`));
+  return 0;
+}
+
+function changeApply(args, _flags) {
+  const id = args[0];
+  if (!id) {
+    console.error(c.red("error:") + " change apply requires <id>");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" not found at ${path.relative(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  const deltaFiles = walk(path.join(changeDir, "specs")).filter((p) => p.endsWith("delta.md"));
+  const date = today();
+  let errors = 0;
+  let writes = 0;
+  let manual = 0;
+
+  if (deltaFiles.length === 0) {
+    console.log(c.yellow("note:") + " no spec deltas in this change. Marking proposal as applied.");
+  }
+
+  for (const deltaPath of deltaFiles) {
+    const rel = path.relative(changeDir, deltaPath);
+    const text = read(deltaPath);
+    const op = parseOperation(text);
+    const capability = parseCapabilityFromDelta(text, deltaPath);
+    if (!op || !capability) {
+      console.error(c.red("error:") + ` cannot parse Operation or capability in ${rel}`);
+      errors += 1;
+      continue;
+    }
+    const targetPath = path.join(projectRoot, ".doctrina", "specs", capability, "spec.md");
+
+    if (op === "ADDED") {
+      if (exists(targetPath)) {
+        console.error(c.red("error:") + ` ADDED delta targets existing spec ${path.relative(projectRoot, targetPath)} — refusing to overwrite`);
+        errors += 1;
+        continue;
+      }
+      const body = extractDeltaBody(text);
+      write(targetPath, body, { force: false });
+      writes += 1;
+      console.log(c.green("applied[ADDED]") + ` ${path.relative(projectRoot, targetPath)}`);
+    } else if (op === "REMOVED") {
+      if (!exists(targetPath)) {
+        console.log(c.yellow("warn:") + ` REMOVED delta targets missing spec ${path.relative(projectRoot, targetPath)} — skipping`);
+        continue;
+      }
+      remove(targetPath);
+      writes += 1;
+      console.log(c.green("applied[REMOVED]") + ` ${path.relative(projectRoot, targetPath)}`);
+    } else if (op === "MODIFIED") {
+      console.log(c.yellow("manual[MODIFIED]") + ` merge ${path.relative(projectRoot, deltaPath)} into ${path.relative(projectRoot, targetPath)} by hand`);
+      manual += 1;
+    } else {
+      console.error(c.red("error:") + ` unknown Operation "${op}" in ${rel}`);
+      errors += 1;
+    }
+  }
+
+  // Flip proposal status from "proposed" to "applied" when fully successful.
+  // Zero-delta changes are trivially successful (no work to fail), so they
+  // also flip — otherwise metadata-only changes are stuck at "proposed".
+  if (errors === 0 && manual === 0) {
+    const proposalPath = path.join(changeDir, "proposal.md");
+    if (exists(proposalPath)) {
+      const txt = read(proposalPath);
+      const updated = txt.replace(
+        /^(-\s+\*\*Status:\*\*)\s+proposed\s*$/m,
+        `$1 applied\n- **Applied:** ${date}`,
+      );
+      if (updated !== txt) {
+        write(proposalPath, updated, { force: true });
+        console.log(c.green("status") + " proposal.md → applied");
+      }
+    }
+  }
+
+  // Update index for ADDED/REMOVED that affected specs
+  if (writes > 0) {
+    const index = idx.load(projectRoot);
+    for (const deltaPath of deltaFiles) {
+      const text = read(deltaPath);
+      const op = parseOperation(text);
+      const capability = parseCapabilityFromDelta(text, deltaPath);
+      if (!capability) continue;
+      if (op === "ADDED") {
+        idx.addSpec(index, {
+          id: capability,
+          path: `.doctrina/specs/${capability}/spec.md`,
+          status: "active",
+          version: "0.1.0",
+          last_updated: date,
+        });
+      } else if (op === "REMOVED") {
+        idx.removeSpec(index, capability);
+      }
+    }
+    idx.touch(index, date);
+    idx.save(projectRoot, index);
+  }
+
+  console.log("");
+  console.log(c.bold("Apply summary:") + ` ${writes} written, ${manual} manual, ${errors} errors.`);
+  if (manual > 0) {
+    console.log(`Resolve manual merges, then run ${c.cyan(`doctrina change archive ${id}`)}.`);
+  } else if (errors === 0) {
+    console.log(`Next: ${c.cyan(`doctrina change archive ${id}`)}.`);
+  }
+  return errors > 0 ? 1 : 0;
+}
+
+function changeArchive(args, _flags) {
+  const id = args[0];
+  if (!id) {
+    console.error(c.red("error:") + " change archive requires <id>");
+    return 2;
+  }
+  const projectRoot = process.cwd();
+  ensureDoctrinaProject(projectRoot);
+
+  const changeDir = path.join(projectRoot, ".doctrina", "changes", id);
+  if (!isDir(changeDir)) {
+    console.error(c.red("error:") + ` change "${id}" not found at ${path.relative(projectRoot, changeDir)}`);
+    return 1;
+  }
+
+  const date = today();
+  const archiveName = `${date}-${id}`;
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive", archiveName);
+  if (exists(archiveDir)) {
+    console.error(c.red("error:") + ` archive target already exists: ${path.relative(projectRoot, archiveDir)}`);
+    return 1;
+  }
+  move(changeDir, archiveDir);
+  console.log(c.green("archived") + ` ${path.relative(projectRoot, archiveDir)}`);
+
+  // Collect affected specs from delta files for the index entry
+  const deltaFiles = walk(path.join(archiveDir, "specs")).filter((p) => p.endsWith("delta.md"));
+  const specsAffected = [];
+  let title = id;
+  for (const deltaPath of deltaFiles) {
+    const text = read(deltaPath);
+    const op = parseOperation(text) ?? "MODIFIED";
+    const capability = parseCapabilityFromDelta(text, deltaPath);
+    if (capability) specsAffected.push({ capability, operation: op });
+  }
+  // Title from proposal
+  const proposal = path.join(archiveDir, "proposal.md");
+  if (exists(proposal)) {
+    const firstLine = read(proposal).split("\n", 1)[0] ?? "";
+    const m = firstLine.match(/^#\s+Change\s+[^—-]+[—-]\s*(.+)$/);
+    if (m) title = m[1].trim();
+  }
+
+  const index = idx.load(projectRoot);
+  idx.moveChangeToArchive(index, id, {
+    id,
+    title,
+    path: `.doctrina/changes/archive/${archiveName}`,
+    status: "applied",
+    applied: date,
+    specs_affected: specsAffected,
+  });
+  idx.touch(index, date);
+  idx.save(projectRoot, index);
+  console.log(c.green("indexed") + " change archived");
+  return 0;
+}
+
+function parseOperation(text) {
+  const m = text.match(/^\*\*Operation:\*\*\s*([A-Z]+)/m);
+  if (!m) return null;
+  const op = m[1];
+  if (op === "ADDED" || op === "MODIFIED" || op === "REMOVED") return op;
+  return null;
+}
+
+function parseCapabilityFromDelta(text, deltaPath) {
+  // Prefer the explicit header "# Spec Delta — capability: <name>"
+  const m = text.match(/^#\s+Spec Delta\s*[—-]\s*capability:\s*([a-z][a-z0-9-]*)/m);
+  if (m) return m[1];
+  // Fall back to the parent directory name of the delta file
+  const parent = path.basename(path.dirname(deltaPath));
+  if (/^[a-z][a-z0-9-]*$/.test(parent)) return parent;
+  return null;
+}
+
+function extractDeltaBody(text) {
+  // The delta separates headers from the spec body with a `---` line.
+  const idxSep = text.indexOf("\n---\n");
+  if (idxSep < 0) return text;
+  return text.slice(idxSep + 5).replace(/^\n+/, "");
+}
+
+function ensureDoctrinaProject(projectRoot) {
+  if (!exists(path.join(projectRoot, ".doctrina"))) {
+    throw new Error("not a Doctrina project (no .doctrina/ in cwd). Run `doctrina init` first.");
+  }
+}
+
+export const help = `
+Usage: doctrina change <subcommand> [args]
+
+Subcommands:
+  new <id> "<title>"     Open a new change proposal at .doctrina/changes/<id>/
+  apply <id>             Apply spec deltas (ADDED writes, REMOVED deletes, MODIFIED is manual)
+  archive <id>           Move the change to .doctrina/changes/archive/YYYY-MM-DD-<id>/
+
+Options:
+  --force                Overwrite existing files (where applicable)
+`;