@nodii/dev 0.5.0 → 0.6.2

package/dist/docs.js

@@ -0,0 +1,204 @@
+// Local checks for AD documents (M-05) before anything is sent to Dev. They
+// mirror Dev's structure checks (AD-era contract §1.3) rule for rule, so a
+// document that passes here fails in Dev only on checks that need Dev's data:
+// `pre:` and DEC resolution, versions, retired clause ids. Dev stays the
+// authority; this exists so an upload fails fast, offline, with every problem
+// in one report, using Dev's error codes. Warnings name text Dev reads
+// differently from what its author probably meant.
+
+export const CHANGE_CLASSES = ["ruling", "conformance", "editorial"];
+
+// Contract §1.4.
+export const RULEBOOK_SECTIONS = ["Summary", "Scope", "Rules", "Rationale", "Edge cases and examples", "Enforcement", "Relations", "Sources", "Open questions for ratification", "Change history"];
+export const FEATURE_SECTIONS = ["Summary", "Scope and non-goals", "Actors and permissions", "Rules", "Behaviour", "Data and contracts", "Edge cases and failure modes", "Rationale", "Enforcement and tests", "Relations", "Sources", "Known gaps", "Open questions for ratification", "Change history"];
+export const OVERVIEW_SECTIONS = ["Summary", "Purpose and users", "Capability map", "Component map", "Peer services", "Deployment and environments", "State of the service", "Known gaps", "Open questions for ratification", "Change history"];
+
+// Contract §1.2: front matter `kind` as written → Dev's kind.
+const KINDS = {
+  principles: "principles", methodology: "methodology", standard: "standard", standards: "standard",
+  doctrine: "doctrine", doctrines: "doctrine", "ux-guideline": "ux-guideline", "ux guideline": "ux-guideline",
+  "ux-guidelines": "ux-guideline", "ux guidelines": "ux-guideline", ux: "ux-guideline", "know-how": "know-how",
+  feature: "feature-doc", "feature-doc": "feature-doc",
+  "feature-overview": "service-overview", "feature-doc-overview": "service-overview", "service-overview": "service-overview", overview: "service-overview",
+  "capability-plan": "capability-plan", "feature-plan": "capability-plan", "feature-doc-plan": "capability-plan",
+};
+const ANATOMY = { "feature-doc": FEATURE_SECTIONS, "service-overview": OVERVIEW_SECTIONS, "capability-plan": ["Change history"] };
+const FRONT_MATTER = ["id", "code", "title", "kind", "era", "status", "version", "owner", "incorporates"];
+const CODE_PATTERN = /^[A-Z][A-Z0-9]*(-[A-Z0-9]+)*$/;
+const GROUNDED_AT = /^[a-z0-9][a-z0-9._-]*@[0-9a-f]{7,40}$/;
+const VERSION = /^(\d{1,4})(?:\.(\d{1,4}))?$/;
+
+export const devKind = (label) => KINDS[String(label ?? "").trim().toLowerCase()] ?? null;
+
+const unquote = (raw) => (raw.length >= 2 && ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) ? raw.slice(1, -1) : raw);
+function flowList(raw) {
+  const items = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of raw.slice(1, -1)) {
+    if (ch === "(" || ch === "[") depth++;
+    if (ch === ")" || ch === "]") depth--;
+    if (ch === "," && depth === 0) { items.push(current); current = ""; continue; }
+    current += ch;
+  }
+  items.push(current);
+  return items.map((x) => unquote(x.trim())).filter(Boolean);
+}
+
+/** Flat `key: value` front matter with `[a, b]` flow lists, as Dev reads it. */
+export function parseFrontMatter(content) {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return null;
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+  if (end === -1) return null;
+  const fields = {};
+  const blockLists = [];
+  for (const [i, line] of lines.slice(1, end).entries()) {
+    const m = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line);
+    if (!m) {
+      if (/^\s+-\s/.test(line) && i > 0) blockLists.push(i + 2);
+      continue;
+    }
+    const value = m[2].trim();
+    fields[m[1]] = value.startsWith("[") && value.endsWith("]") ? flowList(value) : unquote(value);
+  }
+  return { fields, bodyStartLine: end + 2, blockLists };
+}
+
+const sectionTitle = (heading) => heading.replace(/^\d+(\.\d+)*\.?\s+/, "").trim();
+// Dev's definitions (src/lib/ad/markdown.ts), exactly.
+// A clause id: `<code>-<n>`, a Scope clause `<code>-S<n>`, sub-clauses `.m`.
+const CLAUSE_ID = "[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-S?\\d+(?:\\.\\d+)*";
+const CLAUSE_DEF = new RegExp(`^\\s*[-*+]\\s+\\*\\*(${CLAUSE_ID})\\*\\*(?=\\s|$)(.*)$`);
+// A parked item (M05-11.1): Undecided: … · **Undecided:** … · **Undecided** …
+// · **Undecided (PAYC-26):** … · **Undecided: … (MW1-12.4).** · - **TELE-32** Undecided: …
+const PARKED = new RegExp(`^\\s*(?:[-*+]\\s+|\\d+\\.\\s+)?(?:\\*\\*(${CLAUSE_ID})\\*\\*\\s+)?(\\*\\*)?Undecided(?:\\s*\\(([^)]*)\\))?(?:\\*\\*\\s*:|:\\s*\\*\\*|:|\\*\\*(?=\\s))\\s*(.*)$`);
+// A bare `D` id needs two or more digits (a lone `D1` is Cloudflare's
+// database); namespaced ids (`billing-D7`) are always decisions.
+const DECISION_ID = /\b(?:[a-z][a-z0-9_]*(?:-[a-z0-9_]+)*-D\d+|D\d{2,})\b/g;
+
+/** One line as a parked item, as Dev stores it; null when it is not one. */
+export function parkedItem(line) {
+  const m = PARKED.exec(line);
+  if (!m) return null;
+  return `${m[3] ? `(${m[3]}) ` : ""}${(m[4] ?? "").trim()}`.replace(/\*\*\s*$/, "").trim();
+}
+
+/** Which lines are fenced code (the fence lines included). */
+function fencedLines(lines) {
+  let open = false;
+  return lines.map((line) => {
+    if (/^\s*(```|~~~)/.test(line)) { open = !open; return true; }
+    return open;
+  });
+}
+
+/** Sections, clause definitions and parked items, skipping fenced code, with 1-based lines of the whole file. */
+export function parseBody(content, bodyStartLine = 1) {
+  const lines = content.split("\n");
+  const sections = [];
+  const clauses = [];
+  const parked = [];
+  const fenced = fencedLines(lines);
+  let section = "";
+  for (let i = bodyStartLine - 1; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (fenced[i]) continue;
+    const h2 = /^##\s+(.+?)\s*#*\s*$/.exec(line);
+    if (h2 && !line.startsWith("###")) {
+      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; }
+    const clause = CLAUSE_DEF.exec(line);
+    if (clause) clauses.push({ id: clause[1], section, line: i + 1 });
+  }
+  return { sections, clauses, parked };
+}
+
+/**
+ * Bare pre-dev decision ids (M05-5): a `D12`+ or `billing-D7` in prose, not
+ * right after `pre:`. Fenced code and inline code spans are skipped, as Dev does.
+ */
+export function bareCitations(content) {
+  const out = [];
+  const lines = content.split("\n");
+  const fenced = fencedLines(lines);
+  lines.forEach((line, i) => {
+    if (fenced[i]) return;
+    const prose = line.replace(/`[^`]*`/g, (span) => " ".repeat(span.length));
+    for (const m of prose.matchAll(DECISION_ID))
+      if (prose.slice(Math.max(0, m.index - 4), m.index) !== "pre:") out.push({ citation: m[0], line: i + 1 });
+  });
+  return out;
+}
+
+// "The capability map" is the "Capability map" section.
+const startsWithTitle = (actual, expected) => actual.replace(/^the\s+/i, "").toLowerCase().startsWith(expected.toLowerCase());
+
+function sectionErrors(sections, kind) {
+  const titles = sections.map((s) => s.title);
+  if (kind === "feature-doc" && titles.some((t) => startsWithTitle(t, "Capability map")) && titles.some((t) => startsWithTitle(t, "Purpose and users")))
+    return [{ code: "LOOKS_LIKE_OVERVIEW", message: "this document has the service-overview sections; set `kind: service-overview`", line: 1 }];
+  const errors = [];
+  const required = ANATOMY[kind] ?? RULEBOOK_SECTIONS;
+  let cursor = 0;
+  for (const expected of required) {
+    const at = sections.findIndex((s) => startsWithTitle(s.title, expected));
+    if (at === -1) { errors.push({ code: "SECTION_MISSING", message: `section \`## ${expected}\` is required for kind \`${kind}\`` }); continue; }
+    if (at < cursor) { errors.push({ code: "SECTION_ORDER", message: `section \`## ${expected}\` is out of order (expected: ${required.join(" · ")})`, line: sections[at].line }); continue; }
+    cursor = at;
+  }
+  return errors;
+}
+
+const scalar = (v) => (v === undefined ? "" : Array.isArray(v) ? v.join(", ") : v);
+
+/**
+ * Validate one AD document. Returns { meta, errors, warnings, parked, clauses };
+ * each error is { code, message, line? } with Dev's codes (contract §1.3).
+ */
+export function validateDocument(content) {
+  const text = content.replace(/\r\n/g, "\n");
+  const errors = [];
+  const warnings = [];
+  const parsed = parseFrontMatter(text);
+  if (!parsed) {
+    errors.push({ code: "FRONT_MATTER_MISSING", message: "the document must open with a `---` front matter block (M05-15)", line: 1 });
+    return { meta: {}, errors, warnings, parked: [], clauses: [] };
+  }
+  const { fields, bodyStartLine, blockLists } = parsed;
+  for (const key of FRONT_MATTER)
+    if (fields[key] === undefined || (scalar(fields[key]).length === 0 && !(key === "incorporates" && Array.isArray(fields[key]))))
+      errors.push({ code: "FRONT_MATTER_FIELD_MISSING", message: `front matter field \`${key}\` is required (M05-15)`, line: 1 });
+  if (blockLists.length)
+    warnings.push({ message: "front matter uses a YAML block list (`  - item`); Dev reads only `key: value` and `[a, b]` lists, so write it as `[a, b]`", line: blockLists[0] });
+  const kind = scalar(fields.kind) ? devKind(scalar(fields.kind)) : null;
+  if (scalar(fields.kind) && !kind) errors.push({ code: "KIND_UNKNOWN", message: `kind \`${scalar(fields.kind)}\` is not a rulebook kind or a feature-doc kind`, line: 1 });
+  const code = scalar(fields.code);
+  if (code && !CODE_PATTERN.test(code)) errors.push({ code: "CODE_INVALID", message: `code \`${code}\` must be upper-case letters, digits and hyphens (e.g. PII, M05, AUTH-SES)`, line: 1 });
+  const version = scalar(fields.version);
+  if (version && !VERSION.test(version.trim())) errors.push({ code: "VERSION_INVALID", message: `version \`${version}\` must be \`major.minor\` (e.g. 0.2, 1.0)`, line: 1 });
+  const groundedAt = fields.grounded_at === undefined ? null : scalar(fields.grounded_at);
+  if ((kind === "feature-doc" || kind === "service-overview") && !groundedAt)
+    errors.push({ code: "FRONT_MATTER_FIELD_MISSING", message: "front matter field `grounded_at` (`<repo>@<sha>`) is required on feature docs (M05-15)", line: 1 });
+  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);
+  if (kind) errors.push(...sectionErrors(body.sections, kind));
+  if (code) {
+    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; }
+      if (seen.has(c.id)) errors.push({ code: "CLAUSE_ID_DUPLICATE", message: `clause \`${c.id}\` is defined twice (first at line ${seen.get(c.id)}) (M05-6)`, line: c.line });
+      else seen.set(c.id, c.line);
+    }
+  }
+  for (const b of bareCitations(text))
+    errors.push({ code: "BARE_DECISION_ID", message: `\`${b.citation}\` is a bare pre-dev decision id; cite it as \`pre:${b.citation}\` (M05-5)`, line: b.line });
+  return { meta: { ...fields, devKind: kind }, errors, warnings, parked: body.parked, clauses: body.clauses };
+}

package/dist/guidelines.js

@@ -0,0 +1,223 @@
+// `nodii-dev design guideline list|show|propose` and `design changeset
+// list|show`: design-system guideline edits (A-032, DEV-DS-GUIDELINES-EDIT-1).
+// A proposal is a guideline change set in Dev. Approving or rejecting one is a
+// person's action in Dev, and nobody decides their own, so there is no command
+// for it here.
+//
+// The Markdown form is what `guideline show` prints and `propose --file` reads:
+//
+//   # Button (`button`)
+//   ## dos
+//   <!-- sourced; refs: … -->
+//   - Use one primary button per view.
+//   ## anatomy (drafted)
+//   - …
+//
+// One `## <list>` heading per statement list, `(drafted)` when the text still
+// awaits a real source, one bullet per item (a line break inside an item reads
+// back as a space). Lines that are HTML comments are ignored; the `#` title
+// names the entry, and `propose` refuses a file titled for another one. Only
+// the lists that differ from Dev's current guideline are sent.
+import { readFile } from "node:fs/promises";
+import { CliError, devRequest, encode, query } from "./core.js";
+
+// Dev's editable statement lists (the request schema's `edits[].list` enum).
+// A parked guideline has only the first four.
+export const BASE_LISTS = ["whenToUse", "whenNotToUse", "dos", "donts"];
+export const GUIDELINE_LISTS = [...BASE_LISTS, "anatomy", "states.states", "states.loading", "states.empty", "states.error", "copy", "composition", "data.notes"];
+export const CHANGE_SET_STATES = ["in_review", "approved", "pr_open", "merged", "closed", "rejected", "conflict"];
+
+const getList = (guideline, path) => path.split(".").reduce((node, key) => node?.[key], guideline);
+/** The lists this guideline has that Dev lets a change set edit. */
+export const editableLists = (guideline) =>
+  (guideline?.status === "active" ? GUIDELINE_LISTS : BASE_LISTS).filter((path) => getList(guideline, path) !== undefined);
+
+/** A guideline as the Markdown `propose --file` reads back. */
+export function guidelineMarkdown(entry) {
+  const lines = [`# ${entry.title} (\`${entry.key}\`)`, "", `<!-- guideline: ${entry.guideline.status}. Edit the items, then: nodii-dev design guideline propose ${entry.key} --file FILE -->`];
+  for (const path of editableLists(entry.guideline)) {
+    const list = getList(entry.guideline, path);
+    lines.push("", `## ${path}${list.provenance === "drafted" ? " (drafted)" : ""}`, `<!-- ${list.provenance}${list.refs.length ? `; refs: ${list.refs.join(", ")}` : ""} -->`, ...list.items.map((item) => `- ${item}`));
+  }
+  return lines.join("\n");
+}
+
+const problem = (line, message) => `line ${line}: ${message}`;
+/** Parse the Markdown form into Dev's `edits` and the entry key its title names. Throws one error listing every problem. */
+export function parseGuidelineMarkdown(text) {
+  const edits = [];
+  let entryKey = null;
+  const problems = [];
+  // undefined before the first heading; null under a heading that is not a list (its items are skipped).
+  let current;
+  let comment = false;
+  let last = null;
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
+  lines.forEach((raw, i) => {
+    const n = i + 1;
+    let line = raw;
+    if (comment) {
+      const end = line.indexOf("-->");
+      if (end === -1) return;
+      comment = false;
+      line = line.slice(end + 3);
+    }
+    // A comment is a line of its own; `<!--` inside an item is the item's text.
+    while (/^\s*<!--/.test(line)) {
+      const end = line.indexOf("-->");
+      if (end === -1) { comment = true; return; }
+      line = line.slice(end + 3);
+    }
+    if (!line.trim()) { last = null; return; }
+    const title = /^#\s+(.*)$/.exec(line);
+    if (title && current === undefined && entryKey === null) {
+      entryKey = /\(`([^`]+)`\)\s*$/.exec(title[1])?.[1] ?? "";
+      last = null;
+      return;
+    }
+    const heading = /^##\s+(\S+)(\s+\(drafted\))?\s*$/.exec(line);
+    if (heading) {
+      last = null;
+      const [, list, drafted] = heading;
+      if (!GUIDELINE_LISTS.includes(list)) {
+        problems.push(problem(n, `\`${list}\` is not a guideline list (${GUIDELINE_LISTS.join(", ")})`));
+        current = null;
+        return;
+      }
+      if (edits.some((e) => e.list === list)) problems.push(problem(n, `${list} appears twice`));
+      current = { list, items: [], drafted: Boolean(drafted), line: n };
+      edits.push(current);
+      return;
+    }
+    if (/^#/.test(line)) { problems.push(problem(n, `expected \`## <list>\`, got: ${line.trim()}`)); return; }
+    const item = /^\s{0,3}(?:[-*+]|\d+\.)\s+(.*)$/.exec(line);
+    if (item) {
+      if (current === undefined) problems.push(problem(n, "a list item before any `## <list>` heading"));
+      if (!current) return;
+      last = { text: item[1].trim() };
+      current.items.push(last);
+      return;
+    }
+    // An indented line continues the item above it.
+    if (/^\s/.test(line) && last) { last.text = `${last.text} ${line.trim()}`; return; }
+    if (current !== null) problems.push(problem(n, `expected a \`- \` list item, got: ${line.trim()}`));
+  });
+  if (comment) problems.push("an HTML comment is not closed");
+  for (const edit of edits) {
+    edit.items = edit.items.map((x) => x.text);
+    // The checks Dev (and the design-system validator) apply to a list's items.
+    if (!edit.items.length) problems.push(problem(edit.line, `${edit.list} needs at least one item`));
+    if (edit.items.some((x) => x === "")) problems.push(problem(edit.line, `${edit.list} has an empty item`));
+    const seen = new Set();
+    for (const x of edit.items) if (seen.has(x)) problems.push(problem(edit.line, `${edit.list} repeats: ${x}`)); else seen.add(x);
+  }
+  if (!edits.length && !problems.length) problems.push("no `## <list>` sections");
+  if (problems.length) throw new CliError("GUIDELINE_FILE_INVALID", `The guideline file has problems:\n  ${problems.join("\n  ")}`, 2);
+  return { entryKey: entryKey || null, edits: edits.map(({ list, items, drafted }) => ({ list, items, drafted })) };
+}
+
+/** The edits that change Dev's current guideline; refuses lists it cannot edit. */
+export function changedEdits(entry, edits) {
+  if (!entry.guideline) throw new CliError("GUIDELINE_MISSING", `${entry.key} has no synced guideline to edit`, 1);
+  const allowed = editableLists(entry.guideline);
+  const refused = edits.filter((e) => !allowed.includes(e.list)).map((e) => e.list);
+  if (refused.length)
+    throw new CliError("GUIDELINE_LIST_NOT_EDITABLE", `${refused.join(", ")}: not a list of ${entry.key}'s ${entry.guideline.status} guideline (it has ${allowed.join(", ")})`, 2);
+  return edits.filter((e) => {
+    const now = getList(entry.guideline, e.list);
+    return JSON.stringify(now.items) !== JSON.stringify(e.items) || (now.provenance === "drafted") !== e.drafted;
+  });
+}
+
+const person = (p) => (p ? (p.displayName?.value ?? p.displayName?.hint ?? p.id) : "—");
+const changeSetLine = (x) => `${x.id}\t${x.state}\t${x.entryKey}\t${x.edits.map((e) => e.list).join(",")}\t${x.summary ?? ""}`;
+function changeSetText(x) {
+  const out = [
+    `${x.id} ${x.state} — ${x.entryTitle} (${x.entryKey})`,
+    ...(x.summary ? [x.summary] : []),
+    `proposed by ${person(x.createdBy)} at ${x.createdAt}`,
+    ...(x.decidedAt ? [`decided by ${person(x.decidedBy)} at ${x.decidedAt}${x.decisionComment ? `: ${x.decisionComment}` : ""}`] : []),
+    ...(x.pr ? [`PR #${x.pr.number} ${x.pr.url}${x.mergedAt ? ` (merged ${x.mergedAt})` : ""}`] : []),
+    ...(x.error ? [`error: ${x.error}`] : []),
+  ];
+  for (const edit of x.edits) {
+    const before = x.before?.[edit.list];
+    out.push("", `## ${edit.list}${edit.drafted ? " (drafted)" : ""}`);
+    // Removed items first, then the new list: `-` removed, `+` added, blank kept.
+    for (const item of before?.items ?? []) if (!edit.items.includes(item)) out.push(`- ${item}`);
+    for (const item of edit.items) out.push(`${before?.items.includes(item) ? " " : "+"} ${item}`);
+  }
+  return out.join("\n");
+}
+
+const usage = (text) => new CliError("USAGE", text, 2);
+const flagValue = (flags, name, example) => {
+  if (flags[name] === true) throw usage(`--${name} needs a value, e.g. --${name} ${example}`);
+  if (Array.isArray(flags[name])) throw usage(`--${name} is given more than once`);
+  return flags[name];
+};
+
+export async function guidelineCommand(action, args, flags, { request = devRequest, read = (path) => readFile(path, "utf8") } = {}) {
+  if (action === "list") {
+    const params = { kind: flagValue(flags, "kind", "component"), group: flagValue(flags, "group", "inputs"), q: flagValue(flags, "q", "button"), guidelineDrafted: flags.drafted ? "true" : undefined, limit: flagValue(flags, "limit", "100") ?? 100 };
+    let cursor = flagValue(flags, "cursor", "CURSOR");
+    const data = [];
+    let nextCursor;
+    do {
+      const page = await request("GET", `/api/v1/design/entries${query({ ...params, cursor })}`);
+      data.push(...page.data);
+      nextCursor = page.nextCursor ?? null;
+      cursor = nextCursor;
+    } while (flags.all && cursor);
+    return {
+      payload: { data, nextCursor },
+      // Dev lists root entries with their parts nested; a part is shown indented under its root.
+      human: (p) => [p.data.flatMap((x) => [x, ...(x.parts ?? []).map((part) => ({ ...part, key: `  ${part.key}` }))]).map((x) => `${x.key}\t${x.kind}\t${x.status}\tdrafted=${x.guidelineDraftedCount}\t${x.title}`).join("\n") || "No design entries.", ...(p.nextCursor ? [`more: --cursor ${p.nextCursor} (or --all)`] : [])].join("\n"),
+    };
+  }
+  const key = args[0];
+  if (action === "show") {
+    if (!key || args.length > 1) throw usage("design guideline show ENTRY");
+    const payload = await request("GET", `/api/v1/design/entries/${encode(key)}`);
+    if (!payload.data.guideline && !flags.json) throw new CliError("GUIDELINE_MISSING", `${key} has no synced guideline`, 1);
+    return { payload, human: (p) => guidelineMarkdown(p.data) };
+  }
+  if (action === "propose") {
+    if (!key || args.length > 1) throw usage("design guideline propose ENTRY --file FILE.md [--summary TEXT] [--dry-run]");
+    const file = flagValue(flags, "file", "ENTRY.md");
+    if (!file) throw usage("Missing --file FILE.md (start from `nodii-dev design guideline show ENTRY > FILE.md`)");
+    const summary = flagValue(flags, "summary", "'Clarify when to use'")?.trim();
+    if (summary !== undefined && (summary === "" || summary.length > 500)) throw usage("--summary must be 1 to 500 characters");
+    let text;
+    try { text = await read(file); } catch (error) { throw new CliError("NOT_FOUND", `Cannot read ${file}: ${error.message}`, 2); }
+    const { entryKey, edits } = parseGuidelineMarkdown(text);
+    if (entryKey && entryKey !== key) throw usage(`${file} is titled for ${entryKey}, not ${key}`);
+    const entry = (await request("GET", `/api/v1/design/entries/${encode(key)}`)).data;
+    const changed = changedEdits(entry, edits);
+    if (!changed.length) throw new CliError("NO_CHANGES", `${file} matches ${key}'s current guideline; nothing to propose`, 1);
+    const body = { ...(summary ? { summary } : {}), edits: changed };
+    if (flags["dry-run"])
+      return { payload: { dryRun: true, entryKey: key, body }, human: () => `Would propose ${changed.map((e) => e.list).join(", ")} for ${key} (dry run; nothing sent).` };
+    const payload = await request("POST", `/api/v1/design/entries/${encode(key)}/guideline-change-sets`, body);
+    return { payload, human: (p) => `Proposed ${p.data.id} (${p.data.state}) for ${p.data.entryKey}: ${p.data.edits.map((e) => e.list).join(", ")}. A person approves or rejects it in Dev.` };
+  }
+  throw usage("design guideline list|show ENTRY|propose ENTRY --file FILE.md");
+}
+
+export async function changeSetCommand(action, args, flags, { request = devRequest } = {}) {
+  if (action === "list") {
+    const states = flags.state === undefined ? undefined : [flags.state].flat();
+    for (const state of states ?? [])
+      if (!CHANGE_SET_STATES.includes(state)) throw usage(`--state is one of ${CHANGE_SET_STATES.join(", ")}`);
+    const payload = await request("GET", `/api/v1/design/guideline-change-sets${query({ entryKey: flagValue(flags, "entry", "button"), state: states, limit: flagValue(flags, "limit", "100") })}`);
+    return { payload, human: (p) => [p.data.map(changeSetLine).join("\n") || "No guideline change sets.", ...(p.total > p.data.length ? [`showing ${p.data.length} of ${p.total}; raise --limit (up to 200) or narrow with --entry/--state`] : [])].join("\n") };
+  }
+  if (action === "show") {
+    if (!args[0] || args.length > 1) throw usage("design changeset show ID");
+    const payload = await request("GET", `/api/v1/design/guideline-change-sets/${encode(args[0])}`);
+    return { payload, human: (p) => changeSetText(p.data) };
+  }
+  if (["approve", "reject"].includes(action))
+    throw usage(`Approving or rejecting a guideline change set is a person's action in Dev; nodii-dev has no ${action}.`);
+  throw usage("design changeset list [--entry KEY] [--state STATE] | show ID");
+}