doctrina-cli 0.20.0 → 0.22.0

package/src/lib/console-prefs.js

@@ -0,0 +1,67 @@
+// @ts-check
+import path from "node:path";
+import { isFile, mkdirp, read, write } from "./fs-ops.js";
+import { doctrinaHome } from "./workspace-locate.js";
+
+// WHAT A PERSON CHOSE IN THE CONSOLE (change 0258).
+//
+// Which agent answers and which model it runs are the person's choices, not
+// the project's: two people on one repository use different agents. So they
+// are kept beside the person's other Doctrina state, in
+// `$DOCTRINA_HOME/console.json`, per directory the console was opened in —
+// never in the repository, and never read by any command but the console.
+
+export const PREFS_FILE = "console.json";
+
+/** @typedef {{ agent: string | null, models: Record<string, string> }} ConsolePrefs */
+
+const prefsPath = (/** @type {NodeJS.ProcessEnv} */ env) => path.join(doctrinaHome(env), PREFS_FILE);
+
+function readAll(env) {
+  const file = prefsPath(env);
+  if (!isFile(file)) return {};
+  try {
+    const data = JSON.parse(read(file));
+    return data && typeof data.projects === "object" && data.projects !== null ? data.projects : {};
+  } catch {
+    // A file a person broke by hand is their choices lost, not a console that will not open.
+    return {};
+  }
+}
+
+/**
+ * The choices kept for a directory; the defaults when there are none.
+ * @param {string} cwd
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {ConsolePrefs}
+ */
+export function consolePrefs(cwd, env = process.env) {
+  const entry = readAll(env)[path.resolve(cwd)];
+  /** @type {Record<string, string>} */
+  const models = {};
+  if (entry && typeof entry.models === "object" && entry.models !== null) {
+    for (const [id, name] of Object.entries(entry.models)) {
+      if (typeof name === "string" && name.trim() !== "") models[id] = name;
+    }
+  }
+  return { agent: typeof entry?.agent === "string" ? entry.agent : null, models };
+}
+
+/**
+ * Keep a directory's choices. Returns false when the file cannot be written:
+ * the choice then lasts for the session, which is what it did before.
+ * @param {string} cwd
+ * @param {ConsolePrefs} prefs
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function saveConsolePrefs(cwd, prefs, env = process.env) {
+  try {
+    const projects = readAll(env);
+    projects[path.resolve(cwd)] = { agent: prefs.agent, models: prefs.models };
+    mkdirp(doctrinaHome(env));
+    write(prefsPath(env), JSON.stringify({ version: 1, projects }, null, 2) + "\n", { force: true, atomic: true });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/lib/console-room.js

@@ -0,0 +1,201 @@
+// @ts-check
+import path from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdirSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { isDir, isFile, read } from "./fs-ops.js";
+import { doctrinaHome, findWorkspace, projectAt, readWorkspace } from "./workspace-locate.js";
+
+// CONSOLES THAT TALK TO EACH OTHER (change 0259, ADR 0033).
+//
+// A person with three repositories has three terminals. A console in each
+// is three conversations that cannot hear one another — and the planner at
+// the workspace root (ADR 0030) has nobody to hand a card to.
+//
+// A ROOM is what consoles opened for the same work share: the workspace
+// when there is one, the directory otherwise. It is a folder under the
+// person's `$DOCTRINA_HOME`, readable and writable by them alone. Each
+// console keeps one small file there saying it is alive, and has an inbox;
+// a message is a file moved into an inbox. No socket, no port, no daemon:
+// the CLI still makes no network call, and a console that dies leaves a
+// file that stops being fresh.
+//
+// Nothing here reads a terminal or starts a process.
+
+/** @typedef {{ id: string, name: string, role: "planner" | "project" | "sender", cwd: string, pid: number, agent: string | null, model: string | null, busy: boolean, listening: boolean, seen: number }} Peer */
+/** @typedef {{ dir: string, root: string, id: string, name: string, role: Peer["role"] }} Room */
+/**
+ * @typedef {{ type: "request", id: string, from: { id: string, name: string }, text: string, at: number }
+ *   | { type: "result", re: string, from: { id: string, name: string }, ok: boolean, summary: string, detail: string, at: number }
+ *   | { type: "refused", re: string, from: { id: string, name: string }, reason: string, at: number }} Message
+ */
+
+/** A peer that has not said it is alive for this long is gone. */
+export const PEER_STALE_MS = 10_000;
+
+const key = (/** @type {string} */ root) => createHash("sha256").update(root).digest("hex").slice(0, 12);
+const token = () => randomBytes(3).toString("hex");
+
+/**
+ * Where the consoles of this directory meet, and what this one is called there.
+ * @param {string} cwd
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function roomFor(cwd, env = process.env) {
+  const here = path.resolve(cwd);
+  const found = findWorkspace(here, env);
+  let root = here;
+  let name = path.basename(here) || "console";
+  /** @type {Peer["role"]} */
+  let role = "project";
+  if (found) {
+    try {
+      const ws = readWorkspace(found.dir);
+      const member = projectAt(ws, here);
+      if (path.resolve(found.dir) === here) {
+        root = here;
+        name = ws.name || name;
+        role = "planner";
+      } else if (member) {
+        root = path.resolve(found.dir);
+        name = member.name;
+      }
+    } catch { /* an unreadable workspace is no room: the directory is */ }
+  }
+  return { dir: path.join(doctrinaHome(env), "rooms", key(root)), root, name, role };
+}
+
+function writeJson(file, data) {
+  const tmp = `${file}.${token()}.tmp`;
+  writeFileSync(tmp, JSON.stringify(data));
+  renameSync(tmp, file);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(read(file));
+  } catch {
+    return null;
+  }
+}
+
+/** Every peer file in the room that is still fresh. */
+function alive(dir, now) {
+  const peers = path.join(dir, "peers");
+  /** @type {Peer[]} */
+  const out = [];
+  if (!isDir(peers)) return out;
+  for (const f of readdirSync(peers).filter((n) => n.endsWith(".json")).sort()) {
+    const p = readJson(path.join(peers, f));
+    if (!p || typeof p.id !== "string" || typeof p.seen !== "number") continue;
+    if (now - p.seen > PEER_STALE_MS) {
+      // What a console that died left behind: its card and its unread mail.
+      rmSync(path.join(peers, f), { force: true });
+      rmSync(path.join(dir, "inbox", p.id), { recursive: true, force: true });
+      continue;
+    }
+    out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Enter the room: a card of this console's own, and an inbox.
+ * @param {string} cwd
+ * @param {{ env?: NodeJS.ProcessEnv, role?: Peer["role"], name?: string, now?: number }} [opts]
+ * @returns {Room}
+ */
+export function joinRoom(cwd, { env = process.env, role, name, now = Date.now() } = {}) {
+  const at = roomFor(cwd, env);
+  // The person's alone: a request found here was put here by them.
+  mkdirSync(path.join(at.dir, "peers"), { recursive: true, mode: 0o700 });
+  mkdirSync(path.join(at.dir, "inbox"), { recursive: true, mode: 0o700 });
+  if (!isFile(path.join(at.dir, "room.json"))) writeJson(path.join(at.dir, "room.json"), { root: at.root });
+  const id = token();
+  // Two consoles in one directory are told apart by a number.
+  const taken = new Set(alive(at.dir, now).filter((p) => p.role !== "sender").map((p) => p.name));
+  let unique = name ?? at.name;
+  // A `--send` speaks as the console whose agent ran it: it keeps that name.
+  for (let n = 2; role !== "sender" && taken.has(unique); n++) unique = `${name ?? at.name}-${n}`;
+  mkdirSync(path.join(at.dir, "inbox", id), { recursive: true, mode: 0o700 });
+  return { dir: at.dir, root: at.root, id, name: unique, role: role ?? at.role };
+}
+
+/**
+ * Say this console is alive, and what it is doing.
+ * @param {Room} room
+ * @param {{ cwd: string, agent: string | null, model: string | null, busy: boolean, listening: boolean }} info
+ * @param {number} [now]
+ */
+export function beat(room, info, now = Date.now()) {
+  /** @type {Peer} */
+  const card = { id: room.id, name: room.name, role: room.role, pid: process.pid, seen: now, ...info };
+  try {
+    writeJson(path.join(room.dir, "peers", `${room.id}.json`), card);
+  } catch { /* a home that cannot be written is a console alone, not a console that stops */ }
+}
+
+/** Leave: the card and the inbox go. */
+export function leaveRoom(room) {
+  rmSync(path.join(room.dir, "peers", `${room.id}.json`), { force: true });
+  rmSync(path.join(room.dir, "inbox", room.id), { recursive: true, force: true });
+}
+
+/**
+ * The other consoles in the room, by name. A `--send` in flight is not one.
+ * @param {Room} room
+ * @param {number} [now]
+ * @returns {Peer[]}
+ */
+export function listPeers(room, now = Date.now()) {
+  return alive(room.dir, now).filter((p) => p.id !== room.id && p.role !== "sender").sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * The consoles open for a directory, without entering the room.
+ * @param {string} cwd
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {number} [now]
+ * @returns {Peer[]}
+ */
+export function roomPeers(cwd, env = process.env, now = Date.now()) {
+  return alive(roomFor(cwd, env).dir, now).filter((p) => p.role !== "sender").sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Put a message in a console's inbox. False when that console is gone.
+ * @param {Room} room
+ * @param {string} toId
+ * @param {Message} message
+ */
+export function sendMessage(room, toId, message) {
+  const inbox = path.join(room.dir, "inbox", toId);
+  if (!/^[0-9a-f]+$/.test(toId) || !isDir(inbox)) return false;
+  try {
+    writeJson(path.join(inbox, `${String(message.at).padStart(15, "0")}-${token()}.json`), message);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Take what arrived, oldest first. Each message is read once.
+ * @param {Room} room
+ * @returns {Message[]}
+ */
+export function takeInbox(room) {
+  const inbox = path.join(room.dir, "inbox", room.id);
+  /** @type {Message[]} */
+  const out = [];
+  if (!isDir(inbox)) return out;
+  for (const f of readdirSync(inbox).filter((n) => n.endsWith(".json")).sort()) {
+    const file = path.join(inbox, f);
+    const m = readJson(file);
+    rmSync(file, { force: true });
+    if (m && typeof m.type === "string" && m.from && typeof m.from.id === "string" && typeof m.from.name === "string") out.push(m);
+  }
+  return out;
+}
+
+/** A new message id. */
+export const messageId = () => `${Date.now().toString(36)}${token()}`;

package/src/lib/console-state.js

@@ -0,0 +1,150 @@
+// @ts-check
+import path from "node:path";
+import { isDir } from "./fs-ops.js";
+import * as idx from "./index-json.js";
+import { collectSnapshot } from "./snapshot.js";
+import { invocation } from "./actions.js";
+import { cliVersion } from "./version.js";
+import { workspaceActions, workspaceRootAt, workspaceSnapshot } from "./workspace-view.js";
+
+// WHAT THE CONSOLE'S PANEL SHOWS (change 0257).
+//
+// The console is a face for a human; the panel beside the conversation is
+// the project's state — the gates, the open work, the next step — and it is
+// read from the tree after every command, never kept by the console. It is
+// the snapshot `prime`, `status` and `next` already render, reduced to what
+// fits a side panel, so the panel cannot disagree with them.
+//
+// Nothing here prints and nothing here writes. `doctrina ui --state` emits
+// it as JSON from a process of its own: the console is long-lived and the
+// CLI's collectors were written for one run.
+
+/** @typedef {"ok" | "warn" | "fail" | "off"} Light */
+/** @typedef {{ id: string, state: Light, text: string }} Gate */
+/** @typedef {{ id: string, title: string, status: string, done: number, total: number, stage: "plan" | "build" | "close", delivery: string | null }} OpenChange */
+/** @typedef {{ kind: string, id: string, label: string, path: string }} Mention */
+/**
+ * @typedef {{
+ *   kind: "project" | "workspace" | "none",
+ *   project: string | null,
+ *   cli: string,
+ *   gates: Gate[],
+ *   counts: { specs: number, decisions: number, skills: number, closed: number },
+ *   open: OpenChange[],
+ *   next: { text: string, command: string | null }[],
+ *   recent: { id: string, date: string }[],
+ *   projects: { name: string, mode: string, state: string, reason: string }[],
+ *   mentions: Mention[],
+ * }} ConsoleState
+ */
+
+const NEXT_SHOWN = 5;
+
+/** A change's stage, from its tasks: written yet, ticked yet. */
+function stageOf(ch) {
+  const placeholders = ch.unchecked.filter((/** @type {string} */ t) => t.startsWith("(unwritten task")).length;
+  if (ch.tasksTotal === 0 || placeholders > 0) return /** @type {const} */ ("plan");
+  return ch.tasksDone >= ch.tasksTotal ? /** @type {const} */ ("close") : /** @type {const} */ ("build");
+}
+
+/** @returns {ConsoleState} */
+function blank(kind) {
+  return {
+    kind, project: null, cli: cliVersion(), gates: [],
+    counts: { specs: 0, decisions: 0, skills: 0, closed: 0 },
+    open: [], next: [], recent: [], projects: [], mentions: [],
+  };
+}
+
+/**
+ * The panel's state for the directory the console runs in.
+ * @param {string} cwd
+ * @returns {ConsoleState}
+ */
+export function consoleState(cwd) {
+  const wsRoot = workspaceRootAt(cwd);
+  if (wsRoot) return workspaceState(wsRoot);
+  if (!isDir(path.join(cwd, ".doctrina"))) {
+    const out = blank("none");
+    out.next = [
+      { text: "this directory is not a Doctrina project yet", command: "doctrina init" },
+      { text: "the whole cycle once, guided", command: "doctrina onboard" },
+    ];
+    return out;
+  }
+  const s = collectSnapshot(cwd);
+  const out = blank("project");
+  out.project = s.project;
+  const cov = s.coverage;
+  out.gates = [
+    { id: "index", state: s.indexState === "in-sync" ? "ok" : "fail", text: s.indexState },
+    cov.pct === null || cov.pct === undefined
+      ? { id: "coverage", state: "off", text: "no criteria" }
+      : { id: "coverage", state: cov.pct === 100 ? "ok" : "warn", text: `${cov.pct}% (${cov.totalCovered}/${cov.totalCriteria})` },
+    s.trace.anchors === 0
+      ? { id: "trace", state: "off", text: "no anchors" }
+      : { id: "trace", state: s.trace.realized === s.trace.anchors ? "ok" : "warn", text: `${s.trace.realized}/${s.trace.anchors}` },
+    !s.verify.configured
+      ? { id: "verify", state: "off", text: "not set" }
+      : (s.verify.invalid
+        ? { id: "verify", state: "fail", text: "invalid" }
+        : { id: "verify", state: "ok", text: `${s.verify.checks} check${s.verify.checks === 1 ? "" : "s"}` }),
+  ];
+  out.counts = { specs: s.specs.total, decisions: s.decisions.total, skills: s.skills, closed: s.archive.length };
+  out.open = s.openChanges.map((ch) => ({
+    id: ch.id, title: ch.title ?? "", status: ch.status, done: ch.tasksDone, total: ch.tasksTotal,
+    stage: stageOf(ch), delivery: ch.delivery,
+  }));
+  out.next = s.actions.slice(0, NEXT_SHOWN).map((a) => ({ text: a.why, command: invocation(a) }));
+  out.recent = s.recentlyClosed.map((r) => ({ id: r.id, date: r.date }));
+  out.mentions = mentionsOf(cwd);
+  return out;
+}
+
+/** What `@` completes to: the artifacts the index names. */
+function mentionsOf(projectRoot) {
+  /** @type {Mention[]} */
+  const out = [];
+  let index;
+  try {
+    index = idx.load(projectRoot);
+  } catch {
+    return out;
+  }
+  const a = index?.artifacts ?? {};
+  for (const ch of a.changes ?? []) out.push({ kind: "change", id: ch.id, label: ch.title ?? "", path: `${ch.path}/proposal.md` });
+  for (const s of a.specs ?? []) out.push({ kind: "spec", id: s.id, label: `v${s.version} · ${s.implementation ?? s.status ?? ""}`, path: s.path });
+  for (const s of a.skills ?? []) out.push({ kind: "skill", id: s.id, label: s.description ?? "", path: s.path });
+  for (const d of a.decisions ?? []) out.push({ kind: "adr", id: d.id, label: d.title ?? "", path: d.path });
+  for (const ct of a.contracts ?? []) out.push({ kind: "contract", id: ct.id, label: "", path: ct.path });
+  return out;
+}
+
+/** @returns {ConsoleState} */
+function workspaceState(wsRoot) {
+  const snap = workspaceSnapshot(wsRoot);
+  const out = blank("workspace");
+  out.project = snap.ws.name ?? path.basename(wsRoot);
+  out.projects = snap.projects.map((p) => ({
+    name: p.project.name, mode: p.project.mode ?? "", state: p.state, reason: p.reason ?? "",
+  }));
+  const ready = out.projects.filter((p) => p.state === "ready").length;
+  out.gates = [
+    { id: "projects", state: ready === out.projects.length ? "ok" : "warn", text: `${ready}/${out.projects.length} ready` },
+    { id: "deliveries", state: snap.open.length === 0 ? "off" : "ok", text: `${snap.open.length} open` },
+  ];
+  out.counts.closed = snap.deliveries.length - snap.open.length;
+  out.open = snap.open.map(({ delivery: d, rows }) => {
+    const changes = rows.flatMap((r) => r.changes ?? []);
+    const closed = changes.filter((/** @type {any} */ ch) => ch.archived || ch.status === "archived").length;
+    return {
+      id: d.id, title: d.title, status: d.status, done: closed, total: Math.max(d.projects.length, changes.length),
+      stage: d.projects.length === 0 ? /** @type {const} */ ("plan") : /** @type {const} */ ("build"),
+      delivery: null,
+    };
+  });
+  out.next = workspaceActions(snap).slice(0, NEXT_SHOWN).map((a) => ({ text: a.text, command: a.command ?? null }));
+  for (const p of out.projects) out.mentions.push({ kind: "project", id: p.name, label: `${p.mode} · ${p.state}`, path: p.name });
+  for (const { delivery: d } of snap.open) out.mentions.push({ kind: "delivery", id: d.id, label: d.title, path: `deliveries/${d.id}/delivery.md` });
+  return out;
+}