@nodii/dev 0.5.0 → 0.6.1

package/dist/upload.js

@@ -0,0 +1,291 @@
+// `nodii-dev docs check|validate|upload|ratify|parked` and `rulebook list|show`:
+// AD documents (M-05; AD-era contract §1–3). Every document is checked
+// locally first, then sent to Dev, which runs the same checks plus the ones
+// that need its data, the version precondition and the parked-items gate.
+// Dev's refusals are shown unchanged.
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { CliError, devRequest, devTextRequest, encode, query } from "./core.js";
+import { CHANGE_CLASSES, validateDocument } from "./docs.js";
+
+/** Exit code when Dev is waiting on the operator to acknowledge parked items. */
+export const EXIT_PARKED = 4;
+
+/** Expand files and directories into the Markdown documents under them, sorted. */
+export async function collectDocuments(paths) {
+  if (!paths.length) throw new CliError("USAGE", "docs needs at least one file or directory", 2);
+  const out = new Set();
+  async function walk(path) {
+    const info = await stat(path).catch(() => null);
+    if (!info) throw new CliError("NOT_FOUND", `No such file or directory: ${path}`, 2);
+    if (info.isFile()) return void out.add(resolve(path));
+    for (const entry of await readdir(path, { withFileTypes: true })) {
+      // `_`-prefixed files and folders are working material, not documents.
+      if (entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
+      const child = join(path, entry.name);
+      if (entry.isDirectory()) await walk(child);
+      else if (entry.name.endsWith(".md")) out.add(resolve(child));
+    }
+  }
+  for (const path of paths) await walk(path);
+  return [...out].sort();
+}
+
+export async function checkDocuments(paths, cwd = process.cwd()) {
+  const files = await collectDocuments(paths);
+  const docs = await Promise.all(files.map(async (file) => {
+    const content = await readFile(file, "utf8");
+    return { path: relative(cwd, file) || file, content, ...validateDocument(content) };
+  }));
+  const byCode = new Map();
+  for (const d of docs) {
+    const code = d.meta.code;
+    if (!code) continue;
+    if (byCode.has(code)) d.errors.push({ code: "DUPLICATE_IN_UPLOAD", message: `code ${code} is also used by ${byCode.get(code)}` });
+    else byCode.set(code, d.path);
+  }
+  return docs;
+}
+
+const errorLines = (docs) =>
+  docs.flatMap((d) => (d.errors ?? []).map((e) => `${d.path}${e.line ? `:${e.line}` : ""}: ${e.code}: ${e.message}`));
+
+const parkedLines = (docs) =>
+  docs.filter((d) => d.items?.length).flatMap((d) => [
+    `${d.label} has ${d.items.length} parked item${d.items.length === 1 ? "" : "s"}:`,
+    ...d.items.map((p, i) => `  ${i + 1}. ${p.text}${p.line ? `  (line ${p.line})` : ""}`),
+  ]);
+const warningLines = (docs) =>
+  docs.flatMap((d) => (d.warnings ?? []).map((w) => `${d.path}${w.line ? `:${w.line}` : ""}: warning: ${w.message}`));
+
+const localParked = (docs) => docs.map((d) => ({ label: `${d.path} (${d.meta.code ?? "?"})`, items: d.parked }));
+
+const ACK_HINT =
+  "An operator must acknowledge each list in Dev (Parked items, or the document's entry page). nodii-dev is an OAuth app and cannot acknowledge for them. " +
+  "Re-run this command after they do, or add --wait to keep waiting.";
+
+function localGate(docs, json) {
+  const lines = errorLines(docs);
+  if (!lines.length) return;
+  throw new CliError("DOCUMENT_INVALID", `${lines.length} problem${lines.length === 1 ? "" : "s"} found locally; nothing sent to Dev.${json ? "" : `\n${lines.join("\n")}`}`, 1,
+    json ? { documents: docs.filter((d) => d.errors.length).map((d) => ({ path: d.path, code: d.meta.code ?? null, errors: d.errors })) } : undefined);
+}
+
+function changeClass(flags) {
+  const value = flags.class ?? flags["change-class"];
+  if (!CHANGE_CLASSES.includes(value)) throw new CliError("USAGE", `--class is required: ${CHANGE_CLASSES.join(" | ")} (M05-8)`, 2);
+  return value;
+}
+
+/** `--base CODE=VERSION` (repeatable) or `--base VERSION` for one document. */
+function baseFlags(flags, docs) {
+  const map = new Map();
+  for (const raw of [flags.base].flat().filter((x) => x !== undefined && x !== true)) {
+    const value = String(raw);
+    const at = value.indexOf("=");
+    if (at > 0) map.set(value.slice(0, at), value.slice(at + 1));
+    else if (docs.length === 1) map.set(docs[0].meta.code, value);
+    else throw new CliError("USAGE", "With several documents, pass --base CODE=VERSION for each existing one.", 2);
+  }
+  return map;
+}
+
+/**
+ * M05-11: each write names the version it was based on. A new document is
+ * based on nothing (null). For an existing one the author must say which
+ * version they started from; the CLI never fills in Dev's current version
+ * for them, because that would turn the precondition into a silent overwrite.
+ */
+async function baseVersions(docs, flags, request) {
+  const given = baseFlags(flags, docs);
+  const missing = [];
+  for (const d of docs) {
+    let current = null;
+    try { current = (await request("GET", `/api/v1/documents/${encode(d.meta.code)}`)).data?.currentVersion ?? null; }
+    catch (error) { if (error.code !== "DOCUMENT_NOT_FOUND" && error.code !== "HTTP_404") throw error; }
+    d.currentVersion = current;
+    if (given.has(d.meta.code)) d.baseVersion = given.get(d.meta.code);
+    else if (current === null) d.baseVersion = null;
+    else missing.push(`${d.meta.code} (Dev is at ${current})`);
+  }
+  if (missing.length)
+    throw new CliError("BASE_VERSION_REQUIRED", `These documents already exist in Dev. Say which version you started from with --base CODE=VERSION (M05-11): ${missing.join(", ")}`, 2);
+}
+
+async function readJsonFile(path, flag) {
+  if (!path || path === true) return undefined;
+  try { return JSON.parse(await readFile(path, "utf8")); }
+  catch { throw new CliError("USAGE", `--${flag} must name a JSON file`, 2); }
+}
+
+const serverParked = (details) => (details?.documents ?? []).map((d) => ({ label: `${d.code} (${d.title ?? ""})`.replace(" ()", ""), code: d.code, itemsSha256: d.itemsSha256, items: d.items ?? [] }));
+
+/**
+ * Poll Dev until every refused list is acknowledged. The acknowledgement
+ * records are matched on code and digest: the document being uploaded may
+ * not exist yet, or may differ from Dev's current version.
+ */
+async function waitForAcknowledgement(pending, { request, interval, timeout, log }) {
+  const deadline = Date.now() + timeout;
+  const open = new Map(pending.map((p) => [p.code, p.itemsSha256]));
+  while (open.size) {
+    const acknowledged = (await request("GET", "/api/v1/documents/parked?status=acknowledged")).data ?? [];
+    for (const [code, digest] of [...open])
+      if (acknowledged.some((r) => r.docCode === code && r.itemsSha256 === digest)) { open.delete(code); log(`${code}: parked items acknowledged.`); }
+    if (!open.size) return;
+    if (Date.now() >= deadline) throw new CliError("PARKED_ITEMS_UNACKNOWLEDGED", `Still waiting on the operator for: ${[...open.keys()].join(", ")}`, EXIT_PARKED);
+    await sleep(interval);
+  }
+}
+
+/** Dev's per-document refusals (`details.documents[].errors`), one line each, as the local check prints them. */
+function withDocumentErrors(error) {
+  const docs = error.details?.documents;
+  if (!(error instanceof CliError) || !Array.isArray(docs) || !docs.some((d) => d.errors?.length)) return error;
+  const lines = docs.flatMap((d) => (d.errors ?? []).map((e) => `${d.path ?? d.code}${e.line ? `:${e.line}` : ""}: ${e.code}: ${e.message}`));
+  return new CliError(error.code, `${error.message}\n${lines.join("\n")}`, error.exitCode, error.details);
+}
+
+/** Send a write; on the parked gate, show Dev's list and (with --wait) retry once acknowledged. */
+async function withParkedGate(send, flags, { request, log, waitInterval = 15000 }) {
+  for (;;) {
+    try { return await send(); }
+    catch (error) {
+      if (error.code !== "PARKED_ITEMS_UNACKNOWLEDGED") throw withDocumentErrors(error);
+      const pending = serverParked(error.details);
+      if (!flags.wait) throw new CliError(error.code, `${error.message}\n${parkedLines(pending).join("\n")}\n${ACK_HINT}`, EXIT_PARKED, error.details);
+      log(`${parkedLines(pending).join("\n")}\nWaiting for the operator to acknowledge in Dev…`);
+      await waitForAcknowledgement(pending, { request, interval: waitInterval, timeout: Number(flags["wait-minutes"] ?? 120) * 60000, log });
+    }
+  }
+}
+
+const uploadBody = (docs, cls, flags, decision) => ({
+  documents: docs.map((d) => ({
+    path: d.path, content: d.content, changeClass: cls, baseVersion: d.baseVersion,
+    ...(flags["conformance-ref"] && cls === "conformance" ? { conformanceRef: String(flags["conformance-ref"]) } : {}),
+    ...(flags["meaning-unchanged"] && cls === "editorial" ? { meaningUnchangedReason: String(flags["meaning-unchanged"]) } : {}),
+  })),
+  ...(decision ? { decision } : {}),
+});
+
+export async function docsCommand(action, args, flags, { request = devRequest, log = console.error, cwd = process.cwd(), waitInterval } = {}) {
+  const json = Boolean(flags.json);
+  if (action === "check") {
+    const docs = await checkDocuments(args, cwd);
+    const lines = errorLines(docs);
+    const parked = parkedLines(localParked(docs));
+    if (lines.length) process.exitCode = 1;
+    return {
+      payload: { data: { ok: !lines.length, documents: docs.map((d) => ({ path: d.path, code: d.meta.code ?? null, kind: d.meta.devKind ?? null, version: d.meta.version ?? null, clauseCount: d.clauses.length, parked: d.parked, errors: d.errors, warnings: d.warnings })) } },
+      human: [...lines, ...warningLines(docs), ...parked, `${docs.length} document${docs.length === 1 ? "" : "s"} checked: ${lines.length ? `${lines.length} problem${lines.length === 1 ? "" : "s"}` : "no problems"}.`].join("\n"),
+    };
+  }
+
+  if (action === "validate" || action === "upload") {
+    const cls = changeClass(flags);
+    const decision = await readJsonFile(flags.decision, "decision");
+    if (cls === "ruling" && !decision) throw new CliError("RULING_NEEDS_DECISION", "A ruling write needs its decision: --decision DECISION.json (title, context, options, ruling, consequences, provenance, amends).", 2);
+    if (cls !== "ruling" && decision) throw new CliError("DECISION_NEEDS_RULING", "--decision goes with --class ruling only.", 2);
+    if (decision && !decision.amends?.length) throw new CliError("AMENDS_EMPTY", "A decision whose amends list is empty is refused (M05-13).", 2);
+    if (cls === "editorial" && flags["meaning-unchanged"] === true) throw new CliError("USAGE", "--meaning-unchanged needs a reason.", 2);
+    if (flags["conformance-ref"] === true) throw new CliError("USAGE", "--conformance-ref needs a value: a PR or REPO@SHA.", 2);
+    const docs = await checkDocuments(args, cwd);
+    localGate(docs, json);
+    await baseVersions(docs, flags, request);
+    const notes = [...warningLines(docs), ...parkedLines(localParked(docs))];
+    if (notes.length) log(notes.join("\n"));
+    const body = uploadBody(docs, cls, flags, decision);
+
+    if (action === "validate") {
+      const result = (await request("POST", "/api/v1/documents/validate", body).catch((e) => { throw withDocumentErrors(e); })).data;
+      if (!result.ok) process.exitCode = 1;
+      return {
+        payload: { data: result },
+        human: [
+          ...result.documents.flatMap((d) => [
+            `${d.path ?? d.code}\t${d.code} ${d.version} ${d.changeClass} ${d.kind} ${d.domain}\tclauses=${d.clauseCount} parked=${d.parkedCount}${d.parkedCount ? (d.parkedAcknowledged ? " (acknowledged)" : " (NOT acknowledged)") : ""}`,
+            ...d.errors.map((e) => `  ${e.code}${e.line ? ` (line ${e.line})` : ""}: ${e.message}`),
+            ...(d.warnings ?? []).map((w) => `  warning ${w.code}${w.line ? ` (line ${w.line})` : ""}: ${w.message}`),
+          ]),
+          ...(result.decisionErrors ?? []).map((e) => `decision: ${e.code}: ${e.message}`),
+          result.ok ? "Dev accepts this upload." : "Dev would refuse this upload.",
+        ].join("\n"),
+      };
+    }
+
+    const result = (await withParkedGate(() => request("POST", "/api/v1/documents/upload", body), flags, { request, log, waitInterval })).data;
+    return {
+      payload: { data: result },
+      human: [
+        ...result.documents.map((d) => `${d.created ? "+" : "~"} ${d.code} ${d.version}\t${d.changeNote}`),
+        ...(result.decision ? [`Locked ${result.decision.id}: ${result.decision.title}`] : []),
+        `Uploaded ${result.documents.length} document${result.documents.length === 1 ? "" : "s"} (${cls}).`,
+      ].join("\n"),
+    };
+  }
+
+  if (action === "ratify") {
+    // Bulk ratification (M05-2): one decision locks v1.0 of every draft in
+    // the named domains, and those domains become AD. A domain that is
+    // already AD may be named again to ratify drafts added to it since.
+    const domains = [flags.domain].flat().filter((x) => x && x !== true).flatMap((x) => String(x).split(",")).filter(Boolean);
+    if (!domains.length) throw new CliError("USAGE", "docs ratify needs --domain KEY (repeatable), e.g. --domain rulebook/methodology", 2);
+    const decision = await readJsonFile(flags.decision, "decision");
+    const parts = ["title", "context", "options", "ruling", "consequences", "provenance"];
+    const absent = parts.filter((k) => typeof decision?.[k] !== "string" || !decision[k].trim());
+    if (absent.length) throw new CliError("USAGE", `--decision DECISION.json needs non-empty ${absent.join(", ")} (Dev generates the amends).`, 2);
+    const documents = [];
+    for (const key of domains) {
+      const domain = (await request("GET", `/api/v1/domains/${encode(key)}`)).data;
+      for (const d of domain.documents ?? []) if (d.status === "draft") documents.push({ code: d.code, baseVersion: d.currentVersion, parkedCount: d.parkedCount ?? 0 });
+    }
+    if (!documents.length) throw new CliError("DOMAIN_EMPTY", `No draft documents in ${domains.join(", ")}; upload them first with \`nodii-dev docs upload\`.`, 1);
+    // Dev's ratify gate decides on the current versions' parked lists; its refusal carries the real list.
+    log(`Ratifying ${documents.length} document${documents.length === 1 ? "" : "s"} in ${domains.join(", ")} as v1.0:\n${documents.map((d) => `  ${d.code} ${d.baseVersion}${d.parkedCount ? `  (${d.parkedCount} parked)` : ""}`).join("\n")}`);
+    const body = { domains, documents: documents.map(({ code, baseVersion }) => ({ code, baseVersion })), decision: Object.fromEntries(parts.map((k) => [k, decision[k]])) };
+    const result = (await withParkedGate(() => request("POST", "/api/v1/documents/ratify", body), flags, { request, log, waitInterval })).data;
+    return {
+      payload: { data: result },
+      human: [`Locked ${result.decision.id}: ${result.decision.title}`, ...result.documents.map((d) => `  ${d.code} ${d.version}`), `AD now: ${result.domains.map((d) => d.key).join(", ")}`].join("\n"),
+    };
+  }
+
+  if (action === "parked") {
+    if (args[0]) {
+      const p = (await request("GET", `/api/v1/documents/${encode(args[0])}/parked`)).data;
+      const ack = p.current?.acknowledgement;
+      const lines = p.current
+        ? [`${p.code}: ${p.current.count} parked item${p.current.count === 1 ? "" : "s"} in the current version${ack ? ` (${ack.status}${ack.acknowledgedByLabel ? ` by ${ack.acknowledgedByLabel}` : ""})` : ""}`, ...p.current.items.map((x, i) => `  ${i + 1}. ${x.text}`)]
+        : [`${p.code}: not in Dev yet`];
+      for (const x of p.pending ?? []) lines.push(`Awaiting acknowledgement (${x.count} item${x.count === 1 ? "" : "s"}, requested ${x.requestedAt}):`, ...x.items.map((it, i) => `  ${i + 1}. ${it.text}`));
+      return { payload: { data: p }, human: lines.join("\n") };
+    }
+    const payload = await request("GET", `/api/v1/documents/parked${query({ status: flags.status })}`);
+    return { payload, human: (p) => p.data.map((x) => `${x.docCode}\t${x.status}\t${x.count} item${x.count === 1 ? "" : "s"}\t${x.title}`).join("\n") || "No parked-item lists." };
+  }
+  throw new CliError("USAGE", "docs check|validate|upload|ratify|parked", 2);
+}
+
+export async function rulebookCommand(action, args, flags, { request = devRequest, text = devTextRequest } = {}) {
+  for (const name of ["version", "from", "to"])
+    if (flags[name] === true) throw new CliError("USAGE", `--${name} needs a version, e.g. --${name} 1.0`, 2);
+  if (action === "list") {
+    const payload = await request("GET", `/api/v1/documents${query({ section: flags.section ?? (flags.all ? undefined : "rulebook"), kind: flags.kind, serviceId: flags.service, domain: flags.domain, status: flags.status, q: flags.q, limit: flags.limit ?? 500, offset: flags.offset })}`);
+    return { payload, human: (p) => p.data.map((x) => `${x.code}\t${x.currentVersion}\t${x.status}\t${x.kind}\t${x.title}${x.parkedCount ? `\tparked=${x.parkedCount}` : ""}`).join("\n") || "No documents." };
+  }
+  if (action === "show") {
+    const code = args[0];
+    if (!code) throw new CliError("USAGE", "rulebook show CODE [--version V]", 2);
+    if (flags.json) return { payload: await request("GET", flags.version ? `/api/v1/documents/${encode(code)}/versions/${encode(flags.version)}` : `/api/v1/documents/${encode(code)}`) };
+    return { payload: null, human: (await text("GET", `/api/v1/documents/${encode(code)}/body${query({ version: flags.version })}`)).trimEnd() };
+  }
+  if (action === "diff") {
+    const code = args[0];
+    if (!code) throw new CliError("USAGE", "rulebook diff CODE [--from V] [--to V]", 2);
+    const payload = await request("GET", `/api/v1/documents/${encode(code)}/diff${query({ from: flags.from, to: flags.to })}`);
+    return { payload, human: (p) => `${p.data.code} ${p.data.from} → ${p.data.to}\nclauses added: ${p.data.clauses.added.join(", ") || "none"}; removed: ${p.data.clauses.removed.join(", ") || "none"}; changed: ${p.data.clauses.changed.join(", ") || "none"}\n${p.data.unified}` };
+  }
+  throw new CliError("USAGE", "rulebook list|show|diff", 2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {
@@ -20,7 +20,8 @@
     "format": "git diff --check",
     "test": "node --test test/*.test.js",
     "pack:smoke": "node scripts/pack-smoke.mjs",
-    "openapi:snapshot": "node scripts/openapi-snapshot.mjs"
+    "openapi:snapshot": "node scripts/openapi-snapshot.mjs",
+    "openapi:ad-era": "node scripts/ad-era-openapi-snapshot.mjs"
   },
   "license": "UNLICENSED",
   "publishConfig": {