@nodii/dev 0.6.8 → 0.6.10

package/dist/docs.js

@@ -93,12 +93,34 @@ function fencedLines(lines) {
   });
 }
 
+/**
+ * The document's own clause id at the start of a line in a definition
+ * position (Dev issue 80), as Dev reads it: a bullet, text inside the bold,
+ * a bold paragraph, a heading, a bold table row or a numbered item. Ranges and
+ * lists (`**A-1 to A-4:**`, `**A-1, A-2:**`) are references. Null otherwise.
+ */
+export function sourceIdAt(line, code) {
+  const m = /^\s*(?:([-*+])\s+|(\d+)\.\s+|(#{1,6})\s+|(\|)\s*)?(\*\*)?(.*)$/.exec(line);
+  if (!m) return null;
+  const [, bullet, numbered, heading, pipe, bold, rest = ""] = m;
+  if (!bold && !heading) return null;
+  const id = new RegExp(`^(${CLAUSE_ID})(?![\\d.]*\\d)`).exec(rest)?.[1];
+  // The document's own id: `TELE-3`, not the sibling code's `TELE-POR-3`.
+  if (!id || !new RegExp(`^${code.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-S?\\d`).test(id)) return null;
+  const after = rest.slice(id.length);
+  // A list or range (`, X-2`, ` to X-4`, `–4`) is a reference, in or just after the bold; a dash before prose is not.
+  if (new RegExp(`^(?:\\*\\*)?\\s*(?:,|to\\s|and\\s|or\\s|[\u2013\u2014-])\\s*(?:\\*\\*)?(?:${CLAUSE_ID}|\\d)`).test(after)) return null;
+  const form = bullet && bold ? (/^\*\*(?=\s|$)/.test(after) ? "bullet" : "bullet-malformed") : heading ? "heading" : pipe ? "table-row" : numbered ? "numbered" : "bold-paragraph";
+  return { id, form };
+}
+
 /** Sections, clause definitions and parked items, skipping fenced code, with 1-based lines of the whole file. */
-export function parseBody(content, bodyStartLine = 1) {
+export function parseBody(content, bodyStartLine = 1, code = "") {
   const lines = content.split("\n");
   const sections = [];
   const clauses = [];
   const parked = [];
+  const sourceIds = [];
   const fenced = fencedLines(lines);
   let section = "";
   for (let i = bodyStartLine - 1; i < lines.length; i++) {
@@ -106,17 +128,43 @@ export function parseBody(content, bodyStartLine = 1) {
     if (fenced[i]) continue;
     const h2 = /^##\s+(.+?)\s*#*\s*$/.exec(line);
     if (h2 && !line.startsWith("###")) {
+      const heading = code ? sourceIdAt(line, code) : null;
+      if (heading) sourceIds.push({ ...heading, line: i + 1 });
       section = sectionTitle(h2[1]);
       sections.push({ title: section, line: i + 1 });
       continue;
     }
     // `- **TELE-32** Undecided: …` parks that clause; it is not a second definition of it.
     const p = parkedItem(line);
-    if (p !== null) { parked.push({ text: p, line: i + 1 }); continue; }
+    if (p !== null) { parked.push({ text: p, line: i + 1, clauseId: PARKED.exec(line)?.[1] ?? null }); continue; }
+    const source = code ? sourceIdAt(line, code) : null;
+    if (source) sourceIds.push({ ...source, line: i + 1 });
     const clause = CLAUSE_DEF.exec(line);
     if (clause) clauses.push({ id: clause[1], section, line: i + 1 });
   }
-  return { sections, clauses, parked };
+  return { sections, clauses, parked, sourceIds };
+}
+
+/** Dev issue 80: refuse every non-bullet clause form, then state the count invariant. */
+export function clauseFormErrors(body) {
+  const defined = new Set(body.clauses.map((c) => c.id));
+  // A parked line names its clause; a `### X-12` group heading is defined by its sub-clauses.
+  // Only a heading groups sub-clauses: `**X-12** … MUST …` over `- **X-12.1**` is a clause of its own.
+  const known = (id, form) => defined.has(id) || body.parked.some((p) => p.clauseId === id) || (form === "heading" && body.clauses.some((c) => c.id.startsWith(`${id}.`)));
+  const missing = new Map();
+  const errors = [];
+  for (const s of body.sourceIds) {
+    if (known(s.id, s.form) || missing.has(s.id)) continue;
+    missing.set(s.id, s.line);
+    errors.push(s.form === "bullet-malformed"
+      ? { code: "CLAUSE_MALFORMED", message: `clause \`${s.id}\` has text inside its bold; write \`- **${s.id}** …\` with any tag such as \`[INTENDED]\` after the bold (Dev issue 80)`, line: s.line }
+      : { code: "CLAUSE_NOT_A_BULLET", message: `clause \`${s.id}\` is written as a ${s.form.replace("-", " ")}; Dev reads a clause only as a bullet, \`- **${s.id}** …\` (Dev issue 80)`, line: s.line });
+  }
+  if (missing.size) {
+    const source = defined.size + missing.size;
+    errors.push({ code: "CLAUSE_COUNT_MISMATCH", message: `Dev would store ${defined.size} clauses but the source defines ${source}; missing: ${[...missing.keys()].join(", ")} (Dev issue 80)` });
+  }
+  return errors;
 }
 
 /**
@@ -188,9 +236,10 @@ export function validateDocument(content) {
   else if (groundedAt && !GROUNDED_AT.test(groundedAt))
     errors.push({ code: "FRONT_MATTER_FIELD_MISSING", message: `grounded_at \`${groundedAt}\` must be \`<repo>@<sha>\``, line: 1 });
 
-  const body = parseBody(text, bodyStartLine);
+  const body = parseBody(text, bodyStartLine, code);
   if (kind) errors.push(...sectionErrors(body.sections, kind));
   if (code) {
+    errors.push(...clauseFormErrors(body));
     const seen = new Map();
     for (const c of body.clauses) {
       if (!c.id.startsWith(`${code}-`)) { errors.push({ code: "CLAUSE_CODE_MISMATCH", message: `clause \`${c.id}\` does not start with the document code \`${code}-\` (M05-6)`, line: c.line }); continue; }

package/dist/figma.js

@@ -1,4 +1,5 @@
-import { CliError } from "./core.js";
+import { readFile } from "node:fs/promises";
+import { CliError, devRequest, encode } from "./core.js";
 
 /** A Figma file key, or the key inside a figma.com file link (a branch link's branch key). */
 export function figmaFileKey(value) {
@@ -13,3 +14,93 @@ export function figmaFileKey(value) {
 /** What to run when Dev has no row for a Figma file (DESIGN_FILE_NOT_FOUND). */
 export const notRegisteredHint = (key) =>
   `${key} is NOT registered in Dev: run nodii-dev figma file add ${key} --name NAME --kind design-system|surfaces|prototype [--module M]`;
+
+// Dev's refusals of resubmitDesignChangeSet, said in terms of what to do next.
+const RESUBMIT_REFUSALS = {
+  CHANGE_SET_NOT_FOUND: (id) => `No change set ${id} in Dev.`,
+  CHANGE_SET_HOLDER_REQUIRED: (id) => `You don't hold ${id}; only its holder re-submits it.`,
+  INVALID_CHANGE_SET_STATE: (id) =>
+    `${id} is not applying; re-submit once every item is decided and some were rejected (see nodii-dev figma changeset show ${id}).`,
+  CHANGE_SET_HAS_NO_REJECTIONS: (id) => `Nothing in ${id} is rejected; run nodii-dev figma apply ${id} --figma-version VERSION instead.`,
+  REJECTED_ITEMS_MISSING: (id, details, message) =>
+    Array.isArray(details?.missing)
+      ? [`Re-submit every rejected item in ${id}; missing:`, ...details.missing.map((i) => `  ${i.figmaNodeId} (${i.id}): ${i.comment ?? "no comment"}`)].join("\n")
+      : message,
+  CHANGE_ITEM_NOT_REJECTED: (id, details, message) =>
+    Array.isArray(details?.rejected)
+      ? [`${message}`, `Rejected items in ${id}:`, ...details.rejected.map((i) => `  ${i.figmaNodeId} (${i.id})`)].join("\n")
+      : message,
+  CHANGE_SET_CHANGED: (id) => `${id} changed while re-submitting; read it with nodii-dev figma changeset show ${id} and try again.`,
+};
+
+/** A round-2 payload: { figmaVersion, items: [{ itemId | figmaNodeId, variants: [{ nodeId, beforePngBase64?, afterPngBase64? }] }] }. */
+export function resubmitPayload(text, file) {
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch (error) {
+    throw new CliError("USAGE", `${file} is not JSON: ${error.message}`, 2);
+  }
+  const bad = (why) => new CliError("USAGE", `${file}: ${why}`, 2);
+  if (!body || typeof body !== "object" || Array.isArray(body)) throw bad("expected a JSON object");
+  if (typeof body.figmaVersion !== "string" || !body.figmaVersion) throw bad("figmaVersion is required");
+  if (!Array.isArray(body.items) || body.items.length === 0) throw bad("items must list the rejected items");
+  body.items.forEach((item, n) => {
+    if (!item?.itemId && !item?.figmaNodeId) throw bad(`items[${n}] needs itemId or figmaNodeId`);
+    if (!Array.isArray(item.variants) || item.variants.length === 0) throw bad(`items[${n}] needs at least one variant`);
+    item.variants.forEach((v, m) => {
+      if (!v?.nodeId) throw bad(`items[${n}].variants[${m}] needs nodeId`);
+    });
+  });
+  return body;
+}
+
+export async function figmaResubmit(id, file, { request = devRequest, read = (f) => readFile(f, "utf8") } = {}) {
+  if (!id || !file) throw new CliError("USAGE", "figma resubmit CHANGE_SET PAYLOAD.json", 2);
+  let text;
+  try {
+    text = await read(file);
+  } catch (error) {
+    throw new CliError("USAGE", `cannot read ${file}: ${error.message}`, 2);
+  }
+  const body = resubmitPayload(text, file);
+  try {
+    return await request("POST", `/api/v1/design/change-sets/${encode(id)}/resubmit`, body);
+  } catch (error) {
+    const say = RESUBMIT_REFUSALS[error?.code];
+    if (!say) throw error;
+    throw new CliError(error.code, say(id, error.details, error.message), error.exitCode ?? 1, error.details);
+  }
+}
+
+export async function figmaChangeSetShow(id, { request = devRequest } = {}) {
+  if (!id) throw new CliError("USAGE", "figma changeset show CHANGE_SET", 2);
+  try {
+    return await request("GET", `/api/v1/design/change-sets/${encode(id)}`);
+  } catch (error) {
+    if (error?.code !== "CHANGE_SET_NOT_FOUND") throw error;
+    throw new CliError(error.code, `No Figma change set ${id} in Dev (guideline change sets: nodii-dev design changeset show).`, error.exitCode ?? 1, error.details);
+  }
+}
+
+const variantLine = (v) =>
+  `${v.figmaNodeId} (${[v.beforeImageId && "before", v.afterImageId && "after"].filter(Boolean).join(", ") || "no images"})`;
+
+/** One change set as lines: its items' round, decision, comment, the previous round's decision and comment, and variants. */
+export function figmaChangeSetText(cs) {
+  const c = cs.itemCounts ?? {};
+  const lines = [
+    `${cs.id}  ${cs.state}  ${cs.title}`,
+    `file ${cs.file?.name ?? cs.fileKey} (${cs.fileKey}); holder ${cs.holder?.agent?.displayName ?? cs.holder?.agent?.id ?? "none"}`,
+    `${c.total ?? cs.items.length} items: ${c.approved ?? 0} approved, ${c.rejected ?? 0} rejected, ${c.pending ?? 0} pending`,
+  ];
+  for (const item of cs.items ?? []) {
+    lines.push(`- ${item.decision}  round ${item.round}  ${item.figmaNodeId}  ${item.entryKey ?? "(new)"}  ${item.change}  item ${item.id}`);
+    if (item.comment) lines.push(`    comment: ${item.comment}`);
+    if (item.previousItemId)
+      lines.push(`    round ${item.round - 1}: ${item.previousDecision ?? "?"}${item.previousComment ? `: ${item.previousComment}` : ""}`);
+    if (item.variants?.length) lines.push(`    variants: ${item.variants.map(variantLine).join("; ")}`);
+  }
+  if (cs.previousRounds?.length) lines.push(`${cs.previousRounds.length} earlier-round item(s) replaced by a re-submit; --json lists them.`);
+  return lines.join("\n");
+}

package/dist/hooks.js

@@ -102,7 +102,9 @@ export async function preHook(payload, request = devRequest) {
   if (!response.data?.allowed)
     throw new CliError(
       "FIGMA_LOCK_DENIED",
-      response.data?.reason ?? "Blocked Figma write: lock not held.",
+      response.data?.reason === "change-set-not-editable"
+        ? `${response.data.changeSetId} is in review; writes wait for the reviewer's decisions (or nodii-dev figma withdraw ${response.data.changeSetId}).`
+        : (response.data?.reason ?? "Blocked Figma write: lock not held."),
       2,
       response.data,
     );

package/dist/lanes.js

@@ -167,12 +167,50 @@ export async function laneCommand(action, args, flags, { request = devRequest, c
   throw new CliError("USAGE", `Unknown lane action: ${action}`, 2);
 }
 
-export async function nextCommand(ref, flags, { request = devRequest } = {}) {
+/**
+ * The files a lane touches, for path-tagged rules (M05-32): its branch and
+ * working-tree changes against origin/main, plus untracked files, read from
+ * its recorded worktree. Null when that worktree cannot be read here; Dev then
+ * serves every path-tagged clause rather than miss one.
+ */
+export async function laneChangedPaths(lane) {
+  try {
+    const run = async (...args) => (await execFileAsync("git", ["-C", lane.worktree, ...args], { encoding: "utf8", maxBuffer: 16 * 1024 * 1024 })).stdout;
+    const base = (await run("merge-base", "origin/main", "HEAD")).trim();
+    const changed = (await run("diff", "--name-only", base)).split("\n");
+    const untracked = (await run("ls-files", "--others", "--exclude-standard")).split("\n");
+    return [...new Set([...changed, ...untracked].map((x) => x.trim()).filter(Boolean))].slice(0, 5000);
+  } catch {
+    return null;
+  }
+}
+
+const rulesLines = (rules, key) => {
+  if (rules.error) return [`Rules: not served (${rules.error}). Until Dev serves them, read the clauses your brief cites; review delivers the rest (M05-35).`];
+  if (!rules.clauseCount) return [`Rules for this step: none served (no clause tagged for it yet, M05-37). Core: nodii-dev rules core`];
+  return [
+    `Rules for this step: ${rules.clauseCount} clause${rules.clauseCount === 1 ? "" : "s"}, ~${rules.tokens} tokens (DEC-0020). Full text: nodii-dev next ${key} --json`,
+    ...rules.clauses.map((c) => `  ${c.id}  ${c.gist}${c.toolGap ? `  [TOOL GAP ${c.toolGap}]` : ""}\n    -> ${c.pointer}`),
+  ];
+};
+
+export async function nextCommand(ref, flags, { request = devRequest, changedPaths = laneChangedPaths } = {}) {
   const lane = (await request("GET", `/api/v1/lanes/${encode(ref)}`)).data;
   const pending = lane.steps.filter((x) => ["waiting", "current", "blocked"].includes(x.state)).sort((a, b) => a.position - b.position);
   const steps = ["backend", "frontend"].map((side) => pending.find((x) => x.side === side)).filter(Boolean);
   const data = steps.map((step) => ({ side: step.side, step: step.stepKey, label: step.label, state: step.state, command: `nodii-dev lane step ${lane.key} --side ${step.side} --${step.state === "current" ? "done" : "start"} ${step.stepKey}` }));
-  return { payload: { data }, human: data.length ? data.map((x) => `${x.side}: ${x.label}\n  ${x.command}`).join("\n") : `All workflow steps are complete. Run: nodii-dev lane land ${lane.key}` };
+  // M05-32: the clauses Dev serves for this step. A failure here never hides the next step.
+  let rules = null;
+  if (data.length) {
+    const paths = flags.paths ? list(flags.paths) : await changedPaths(lane);
+    const body = { ...(paths ? { paths } : {}), ...(flags.components ? { components: list(flags.components) } : {}), ...(flags.role ? { role: String(flags.role) } : {}) };
+    try { rules = (await request("POST", `/api/v1/lanes/${encode(lane.key)}/rules`, body)).data; }
+    catch (error) { rules = { error: error.code ?? error.message }; }
+  }
+  const human = data.length
+    ? [...data.map((x) => `${x.side}: ${x.label}\n  ${x.command}`), ...rulesLines(rules, lane.key)].join("\n")
+    : `All workflow steps are complete. Run: nodii-dev lane land ${lane.key}`;
+  return { payload: { data, ...(rules ? { rules } : {}) }, human };
 }
 
 export async function builtCommand(action, args, flags, { request = devRequest } = {}) {

package/dist/upload.js

@@ -273,7 +273,8 @@ export async function rulebookCommand(action, args, flags, { request = devReques
     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." };
+    // Dev issue 80: the clause count, so a document Dev reads as 0/44 shows at a glance.
+    return { payload, human: (p) => p.data.map((x) => `${x.code}\t${x.currentVersion}\t${x.status}\t${x.kind}\t${x.clauseCount ?? "?"} clause${x.clauseCount === 1 ? "" : "s"}\t${x.title}${x.parkedCount ? `\tparked=${x.parkedCount}` : ""}`).join("\n") || "No documents." };
   }
   if (action === "show") {
     const code = args[0];
@@ -289,3 +290,43 @@ export async function rulebookCommand(action, args, flags, { request = devReques
   }
   throw new CliError("USAGE", "rulebook list|show|diff", 2);
 }
+
+const pad = (v, n) => String(v).padStart(n);
+
+/**
+ * `nodii-dev rules core|report|cap` (DEC-0020; M05-33, M05-36): the generated
+ * core, the delivery report, and the operator's core token cap.
+ */
+export async function rulesCommand(action, args, flags, { request = devRequest } = {}) {
+  if (action === "core") {
+    // Dev refuses a core over the cap with CORE_OVER_CAP; that error is the output.
+    const payload = await request("GET", "/api/v1/rules/core");
+    return { payload, human: (p) => `${p.data.markdown.trimEnd()}\n\n${p.data.clauseCount} core clause${p.data.clauseCount === 1 ? "" : "s"}, ~${p.data.tokens} of ${p.data.cap} tokens.` };
+  }
+  if (action === "report") {
+    const payload = await request("GET", `/api/v1/rules/report${query({ section: flags.section, lane: flags.lane })}`);
+    return {
+      payload,
+      human: (p) => {
+        const d = p.data;
+        const row = (code, t) => `${code.padEnd(10)}${pad(t.clauses, 6)}${pad(t.must, 6)}${pad(t.enforced, 9)}${pad(t.served, 7)}${pad(t.core, 5)}${pad(t.untagged, 9)}${pad(t.untaggedMust, 14)}${pad(t.toolGap, 9)}`;
+        const lines = [
+          `${"document".padEnd(10)}${pad("all", 6)}${pad("MUST", 6)}${pad("enforced", 9)}${pad("served", 7)}${pad("core", 5)}${pad("untagged", 9)}${pad("untagged MUST", 14)}${pad("tool gap", 9)}`,
+          ...(flags.lane ? [] : d.documents.map((x) => row(x.code, x))),
+          row("TOTAL", d.totals),
+          `Core: ${d.core.clauseCount} clauses, ~${d.core.tokens} of ${d.core.cap} tokens${d.core.overCap ? " (OVER THE CAP)" : ""}.`,
+          ...(d.lanes.length ? ["Served per lane:"] : ["No lane has been served rules yet."]),
+          ...d.lanes.flatMap((l) => [`  ${l.key} (${l.status}): ${l.clauseCount} clauses, ~${l.tokens} tokens`, ...l.steps.map((s) => `    ${s.side}/${s.step}: ${s.clauseCount} clauses, ~${s.tokens} tokens, served ${s.servedCount}x`)]),
+        ];
+        return lines.join("\n");
+      },
+    };
+  }
+  if (action === "cap") {
+    const cap = Number(args[0]);
+    if (!Number.isInteger(cap) || cap < 100 || cap > 100000) throw new CliError("USAGE", "rules cap needs a whole number of tokens, 100 to 100000 (M05-33)", 2);
+    const payload = await request("PUT", "/api/v1/rules/core/cap", { cap });
+    return { payload, human: (p) => `Core cap: ${p.data.previous} -> ${p.data.cap} tokens.` };
+  }
+  throw new CliError("USAGE", "rules core | rules report [--section rulebook|services|all] [--lane KEY] | rules cap TOKENS", 2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodii/dev",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "Agent CLI for Nodii Dev, reached through the platform edge",
   "type": "module",
   "bin": {