doctrina-cli 0.18.0 → 0.21.0

package/src/index.js

@@ -11,68 +11,73 @@ import { EXIT, exitCodeHelp } from "./lib/exit-codes.js";
 import { recordUsage, operationOf } from "./lib/usage.js";
 import { wantsJson, emitJson, captureOutput, stripAnsi, setDeprecation, deferJson, flushJson } from "./lib/json-out.js";
 
-import * as init from "./commands/init.js";
-import * as spec from "./commands/spec.js";
-import * as change from "./commands/change.js";
-import * as decision from "./commands/decision.js";
-import * as validate from "./commands/validate.js";
-import * as hooks from "./commands/hooks.js";
-import * as analyze from "./commands/analyze.js";
-import * as clarify from "./commands/clarify.js";
-import * as templates from "./commands/templates.js";
-import * as skill from "./commands/skill.js";
-import * as indexCmd from "./commands/index-rebuild.js";
-import * as next from "./commands/next.js";
-import * as metrics from "./commands/metrics.js";
-import * as context from "./commands/context.js";
-import * as search from "./commands/search.js";
-import * as intake from "./commands/intake.js";
-import * as work from "./commands/work.js";
-import * as coverage from "./commands/coverage.js";
-import * as verify from "./commands/verify.js";
-import * as contract from "./commands/contract.js";
-import * as trace from "./commands/trace.js";
-import * as status from "./commands/status.js";
-import * as close from "./commands/close.js";
-import * as review from "./commands/review.js";
-import * as watch from "./commands/watch.js";
-import * as why from "./commands/why.js";
-import * as prime from "./commands/prime.js";
-import * as handoff from "./commands/handoff.js";
-import * as show from "./commands/show.js";
-import * as doctor from "./commands/doctor.js";
-import * as report from "./commands/report.js";
-import * as completion from "./commands/completion.js";
-import * as intent from "./commands/intent.js";
-import * as upgrade from "./commands/upgrade.js";
-import * as adapter from "./commands/adapter.js";
-import * as triage from "./commands/triage.js";
-import * as ci from "./commands/ci.js";
 
+// Each command is loaded when it is the one invoked (fifth audit, change
+// 0236): the 39 static imports cost ~150 ms before any command ran, and
+// `workspace guard` runs on EVERY MCP call an agent makes — a Playwright
+// session's hundred clicks paid it a hundred times.
+/** @type {Record<string, () => Promise<any>>} */
 const COMMANDS = {
-  init, spec, change, decision, validate, hooks, analyze, clarify,
-  templates, skill, index: indexCmd, next, metrics, context, search,
-  intake, work, coverage, verify, contract, trace,
-  status, close, review, watch, why,
-  prime, handoff, show, doctor, report, completion,
-  intent, upgrade, adapter, triage, ci,
+  init: () => import("./commands/init.js"),
+  spec: () => import("./commands/spec.js"),
+  change: () => import("./commands/change.js"),
+  decision: () => import("./commands/decision.js"),
+  validate: () => import("./commands/validate.js"),
+  hooks: () => import("./commands/hooks.js"),
+  analyze: () => import("./commands/analyze.js"),
+  clarify: () => import("./commands/clarify.js"),
+  templates: () => import("./commands/templates.js"),
+  skill: () => import("./commands/skill.js"),
+  index: () => import("./commands/index-rebuild.js"),
+  next: () => import("./commands/next.js"),
+  metrics: () => import("./commands/metrics.js"),
+  context: () => import("./commands/context.js"),
+  search: () => import("./commands/search.js"),
+  intake: () => import("./commands/intake.js"),
+  work: () => import("./commands/work.js"),
+  coverage: () => import("./commands/coverage.js"),
+  verify: () => import("./commands/verify.js"),
+  contract: () => import("./commands/contract.js"),
+  trace: () => import("./commands/trace.js"),
+  status: () => import("./commands/status.js"),
+  close: () => import("./commands/close.js"),
+  review: () => import("./commands/review.js"),
+  watch: () => import("./commands/watch.js"),
+  why: () => import("./commands/why.js"),
+  prime: () => import("./commands/prime.js"),
+  handoff: () => import("./commands/handoff.js"),
+  show: () => import("./commands/show.js"),
+  doctor: () => import("./commands/doctor.js"),
+  report: () => import("./commands/report.js"),
+  completion: () => import("./commands/completion.js"),
+  intent: () => import("./commands/intent.js"),
+  upgrade: () => import("./commands/upgrade.js"),
+  adapter: () => import("./commands/adapter.js"),
+  triage: () => import("./commands/triage.js"),
+  ci: () => import("./commands/ci.js"),
+  workspace: () => import("./commands/workspace.js"),
+  delivery: () => import("./commands/delivery.js"),
 };
 
-const TOP_HELP = `
-Usage: doctrina <command> [options]      (\`doctrina <command> --help\` for its flags)
+const TOP_HELP = `Usage: doctrina <command> [options]      (\`doctrina <command> --help\` for its flags)
 
 ${surfaceHelp()}
 
-Global flags:
-  --help, -h           Show this message (or per-command help if after a command)
-  --version, -v        Print the version
-  --debug              On an unexpected error, also print the stack trace
-
+Global flags: --help/-h (this, or a command's own) · --version/-v · --debug (stack traces)
 Exit codes (a contract — an agent reads these to decide what to do next):
 ${exitCodeHelp()}
 `;
 
 async function main(argv) {
+  // The MCP guard's own door (fifth audit, change 0236): it answers before
+  // every tool call an agent makes, so it loads the guard and its registry
+  // reader only. `--help` and `--json` take the ordinary path.
+  if (argv[0] === "workspace" && argv[1] === "guard" && !argv.some((a) => /^(--help|-h|--json|--debug)$/.test(a))) {
+    const at = argv.indexOf("--hook");
+    const hook = at >= 0 ? argv[at + 1] : argv.find((a) => a.startsWith("--hook="))?.slice("--hook=".length);
+    const { runGuard } = await import("./lib/workspace-guard.js");
+    return runGuard(hook);
+  }
   // `--version` is only "print the CLI version" when NO command is given.
   // With a command it is that command's flag to consume — the old global
   // intercept made `doctrina spec set x --version 0.10.0` print the CLI
@@ -91,7 +96,8 @@ async function main(argv) {
   // Declarations now live with the command, so a new command cannot
   // reintroduce the gap by forgetting to edit this file.
   const bootstrap = parseArgs(argv, { boolean: [...GLOBAL_FLAGS.boolean] });
-  const commandModule = COMMANDS[bootstrap.positional[0]];
+  const loader = Object.hasOwn(COMMANDS, bootstrap.positional[0] ?? "") ? COMMANDS[bootstrap.positional[0]] : null;
+  const commandModule = loader ? await loader() : null;
   const spec = commandModule?.flags;
   const { positional, flags } = parseArgs(argv, {
     boolean: [...GLOBAL_FLAGS.boolean, ...(spec?.boolean ?? [])],
@@ -109,7 +115,8 @@ async function main(argv) {
   }
 
   const commandName = positional[0];
-  const command = COMMANDS[commandName];
+  const command = commandName === bootstrap.positional[0] ? commandModule
+    : (Object.hasOwn(COMMANDS, commandName) ? await COMMANDS[commandName]() : null);
   const removed = removalFor(positional);
   if (removed) {
     const name = removed === removalFor([commandName]) ? commandName : positional.slice(0, 2).join(" ");
@@ -209,12 +216,13 @@ async function main(argv) {
       ? command.jsonNative(positional.slice(1))
       : command.jsonNative === true;
     if (wantsJson(flags) && !jsonNative) {
-      const { code, stdout, stderr } = await captureOutput(
+      const { code, stdout, stderr, error } = await captureOutput(
         () => command.run(positional.slice(1), flags),
       );
       emitJson(operationName(positional), {
         stdout: stdout.map(stripAnsi),
         stderr: stderr.map(stripAnsi),
+        ...(error ? { error: String(error.message ?? error) } : {}),
       }, { ok: code === EXIT.OK, exitCode: code, args: operationArgs(positional) });
       return code;
     }
@@ -224,27 +232,53 @@ async function main(argv) {
     if (wantsJson(flags)) {
       deferJson();
       let code = EXIT.OK;
+      let thrown = null;
       try {
         code = (await command.run(positional.slice(1), flags)) ?? EXIT.OK;
-      } finally {
-        flushJson(code);
+      } catch (err) {
+        thrown = err;
+        code = err.exitCode ?? EXIT.GATE;
+      }
+      // A native command that failed before building its payload still
+      // answers in JSON (third audit, change 0234): "not a Doctrina project"
+      // or an unknown delivery printed English only, and a loop parsing the
+      // payload read nothing at all.
+      if (!flushJson(code)) {
+        emitJson(operationName(positional), {
+          error: thrown ? String(thrown.message) : "the command stopped before it built its payload — stderr says why",
+          ...(thrown?.remedy ? { remedy: thrown.remedy } : {}),
+        }, { ok: code === EXIT.OK, exitCode: code, args: operationArgs(positional) });
       }
+      if (thrown) await reportError(thrown, flags);
       return code;
     }
     return await command.run(positional.slice(1), flags);
   } catch (err) {
-    console.error(c.red("error:") + ` ${err.message}`);
-    if (err.remedy) {
-      console.error(c.gray("hint: ") + `run ${c.cyan(err.remedy)} first, then retry`);
-    }
-    if (flags.get("debug") && err.stack) {
-      console.error(c.gray(err.stack));
-    }
-    // A typed error carries its own class (precondition vs environment).
-    // An untyped throw is an unexpected failure of the work itself, which
-    // is the GATE class: something is wrong here, fix it and retry (C7).
-    return err.exitCode ?? EXIT.GATE;
+    return await reportError(err, flags);
+  }
+}
+
+/** The human report of a thrown error, and the exit class it carries. */
+async function reportError(err, flags) {
+  console.error(c.red("error:") + ` ${err.message}`);
+  // A clone of a shadowed repository is not a project to init (change 0234).
+  // Loaded only on this error path, like the commands (change 0236).
+  const view = /^not a Doctrina project/.test(String(err.message)) ? await import("./lib/workspace-view.js") : null;
+  const clone = view ? view.shadowedCloneAt(process.cwd()) : null;
+  if (clone) {
+    console.error(c.gray("hint: ") + (clone.same
+      ? `this repository is the workspace's shadowed "${clone.name}" and its links are missing; never \`doctrina init\` here — link them again: ${c.cyan(view?.attachCommand(clone, process.cwd()))}`
+      : `this repository is the workspace's shadowed "${clone.name}" (registered at ${clone.path}); never \`doctrina init\` here — to work from this clone, link its context from the workspace: ${c.cyan(view?.attachCommand(clone, process.cwd()))}`));
+  } else if (err.remedy) {
+    console.error(c.gray("hint: ") + `run ${c.cyan(err.remedy)} first, then retry`);
+  }
+  if (flags.get("debug") && err.stack) {
+    console.error(c.gray(err.stack));
   }
+  // A typed error carries its own class (precondition vs environment).
+  // An untyped throw is an unexpected failure of the work itself, which
+  // is the GATE class: something is wrong here, fix it and retry (C7).
+  return err.exitCode ?? EXIT.GATE;
 }
 
 // The OPERATION an invocation names, and the arguments it carries — the two

package/src/lib/actions.js

@@ -4,10 +4,13 @@ import { readdirSync } from "node:fs";
 import { isDir, isFile, read, relPath, walk } from "./fs-ops.js";
 import * as idx from "./index-json.js";
 import { deriveIndex, indexesMatch, listHeader, specHeader } from "./scan.js";
+import { checklistProgress } from "./doc-model.js";
 import { collectRuntimeFindings } from "./runtime.js";
 import { FIX_SHAPED } from "./lexicon.js";
 import { summarize as coverageSummary } from "./coverage-model.js";
 import { summarize as traceSummary } from "./trace-model.js";
+import { projectWorkspaceLine } from "./workspace-view.js";
+import { cdThen, qarg } from "./shell.js";
 
 // What comes next, as DATA (change 0032).
 //
@@ -151,7 +154,7 @@ export function computeActions(projectRoot, gates = {}) {
       severity: "blocking",
       why: "no capability is specced yet, so nothing states what this project must do",
       text: 'doctrina intake --text "<what this project is>" — no capability is specced yet; ' +
-        "for an existing codebase, `doctrina work --from-diff` backfills from the code instead",
+        "for an existing codebase, `doctrina intake --from-code` takes its inventory as the intake (`doctrina work --from-diff` backfills one change from code already written)",
     }));
   }
 
@@ -214,9 +217,19 @@ export function computeActions(projectRoot, gates = {}) {
         continue;
       }
       const tasksPath = path.join(changesDir, id, "tasks.md");
-      const unchecked = isFile(tasksPath)
-        ? (read(tasksPath).match(/^-\s+\[ \]/gm) ?? []).length
-        : 0;
+      const progress = isFile(tasksPath) ? checklistProgress(read(tasksPath)) : { total: 0, done: 0, open: [], placeholders: 0 };
+      const unchecked = progress.total - progress.done;
+      if (progress.placeholders > 0) {
+        // Scaffold boxes are not open work (third audit, change 0234): "complete 3
+        // open tasks" sent an agent to do work no one had written down.
+        actions.push(action({
+          id: "change-tasks-unwritten",
+          command: "work",
+          args: ["--resume", id],
+          why: `write the ${unchecked} open task${unchecked === 1 ? "" : "s"} in .doctrina/changes/${id}/tasks.md first — ${progress.placeholders === unchecked ? (unchecked === 1 ? "it is" : "all are") : `${progress.placeholders} are`} still the scaffold's placeholder${progress.placeholders === 1 ? "" : "s"}, and the delta with them`,
+        }));
+        continue;
+      }
       if (unchecked > 0) {
         // Deliberately NOT runnable, and deliberately without a command:
         // the only thing that clears this is doing the work. `change tick`
@@ -253,6 +266,33 @@ export function computeActions(projectRoot, gates = {}) {
     }
   }
 
+  // A delivery open on this repository (second audit, change 0233). `prime`
+  // named it, `next` did not: after the close of this repository's part,
+  // "Next: doctrina next" answered with this project's own chores, and the
+  // planner lost the delivery that was still going on at the workspace.
+  let inWorkspace = null;
+  try {
+    inWorkspace = projectWorkspaceLine(projectRoot);
+  } catch {
+    inWorkspace = null;
+  }
+  for (const d of inWorkspace?.deliveries ?? []) {
+    if (d.changes.length === 0) {
+      actions.push(action({
+        id: "delivery-change-missing",
+        why: `delivery ${d.id} is routed to this repository and has no change here yet`,
+        text: `doctrina work ${qarg(d.title)} --delivery ${d.id} — delivery ${d.id} is routed to this repository and has no change here yet`,
+      }));
+    } else if (d.open === 0) {
+      actions.push(action({
+        id: "delivery-continues-at-workspace",
+        severity: "advisory",
+        why: `this repository's part of delivery ${d.id} is closed; the delivery goes on at the workspace`,
+        text: `${cdThen(inWorkspace?.dir ?? "", "doctrina next")} — this repository's part of delivery ${d.id} is closed; the delivery goes on at the workspace`,
+      }));
+    }
+  }
+
   // ADRs stuck in proposed need a human decision; accepted-but-bare ADRs are
   // the rot the review flagged — a decision with nothing behind it (no Evidence,
   // no Landed) is drift waiting to be superseded. Surface the proposed ones

package/src/lib/adapters.js

@@ -1,7 +1,7 @@
 // @ts-check
 import path from "node:path";
 import { readdirSync } from "node:fs";
-import { exists, isDir, isFile, read, relPath, walk } from "./fs-ops.js";
+import { exists, isDir, isFile, mkdirp, pruneEmptyDirs, read, relPath, remove, walk, write } from "./fs-ops.js";
 import { locateTemplatesDir, substitute } from "./templates.js";
 
 // Agent adapters: the thin per-agent files that point at AGENTS.md.
@@ -127,3 +127,145 @@ export function renderAdapterFile(file, tokens) {
 }
 
 export { exists };
+
+// Files an adapter USED to write, and the file that replaced each (change
+// 0238). Cursor's documentation no longer describes `.cursor/commands/`;
+// Cursor 2.4 converts slash commands to skills (`/migrate-to-skills`), with
+// `disable-model-invocation: true` to keep them explicit — which is what
+// the cursor adapter writes now, under `.cursor/skills/`.
+export const RETIRED_ADAPTER_FILES = Object.freeze({
+  cursor: ["context", "next", "status", "why", "work"].map((x) => ({
+    retired: `.cursor/commands/doctrina-${x}.md`,
+    replacedBy: `.cursor/skills/doctrina-${x}/SKILL.md`,
+  })),
+});
+
+/**
+ * Moving an installed adapter off its retired files: the replacement is
+ * written where it is missing; a retired file still exactly as the CLI
+ * wrote it is removed; one edited since is kept and named, never deleted.
+ * @param {string} projectRoot
+ * @param {Record<string, string>} tokens  as `adapter add` renders with
+ * @param {string} [root]  where the files live: the shadow folder of a shadowed repository
+ */
+export function planAdapterMigration(projectRoot, tokens, root = projectRoot) {
+  /** @type {{ writes: Array<{ relativePath: string, content: string }>, removes: string[], kept: string[] }} */
+  const plan = { writes: [], removes: [], kept: [] };
+  const norm = (/** @type {string} */ s) => s.replace(/\r\n/g, "\n").trim();
+  for (const [name, list] of Object.entries(RETIRED_ADAPTER_FILES)) {
+    const spec = adapterFiles(projectRoot, name);
+    if (!spec) continue;
+    for (const { retired, replacedBy } of list) {
+      if (!isFile(path.join(root, retired))) continue;
+      const file = spec.files.find((f) => f.relativePath === replacedBy);
+      if (!file) continue;
+      const rendered = renderAdapterFile(file, tokens);
+      if (!isFile(path.join(root, replacedBy))) plan.writes.push({ relativePath: replacedBy, content: rendered });
+      const body = rendered.replace(/^---\n[\s\S]*?\n---\n+/, "");
+      (norm(read(path.join(root, retired))) === norm(body) ? plan.removes : plan.kept).push(retired);
+    }
+  }
+  return plan;
+}
+
+/**
+ * Apply a migration plan under `root` — the project, or the shadow folder
+ * a shadowed repository's files live in. Returns the removed files with
+ * what they held, for the caller that re-links a shadow.
+ * @returns {Array<{ rel: string, content: string }>}
+ */
+export function applyAdapterMigration(root, plan) {
+  for (const w of plan.writes) {
+    mkdirp(path.dirname(path.join(root, w.relativePath)));
+    write(path.join(root, w.relativePath), w.content, { force: true });
+  }
+  const gone = [];
+  for (const rel of plan.removes) {
+    const at = path.join(root, rel);
+    if (!isFile(at)) continue;
+    gone.push({ rel, content: read(at) });
+    remove(at);
+    pruneEmptyDirs(path.dirname(at), root);
+  }
+  return gone;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration files an adapter SHARES with the user (change 0211).
+//
+// A hook lives in the agent's own settings — `.claude/settings.json`,
+// `.cursor/hooks.json` — which the project may already own: permissions,
+// other hooks, a model choice. Writing the file whole would be the data loss
+// `adapter add` exists to avoid, and skipping it because it exists would
+// leave the hooks out exactly where an agent is configured. So a `.json`
+// adapter file is MERGED: objects recurse, arrays gain the entries they do
+// not already hold, and a scalar the user set stays theirs. Removal takes
+// back only what the template put in.
+
+/** Whether an adapter file is merged into a shared configuration file. */
+export function isMergedConfig(file) {
+  return file.relativePath.endsWith(".json");
+}
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** `ours` merged into `theirs`; neither argument is modified. */
+export function mergeJson(theirs, ours) {
+  if (Array.isArray(theirs) && Array.isArray(ours)) {
+    return [...theirs, ...ours.filter((o) => !theirs.some((t) => same(t, o)))];
+  }
+  if (isPlainObject(theirs) && isPlainObject(ours)) {
+    const out = { ...theirs };
+    for (const [k, v] of Object.entries(ours)) {
+      out[k] = k in theirs ? mergeJson(theirs[k], v) : v;
+    }
+    return out;
+  }
+  return theirs;
+}
+
+/**
+ * `theirs` with everything `ours` contributed taken out, and the containers
+ * that leaves empty pruned. A scalar is removed only when it equals ours AND
+ * nothing of the user's remains beside it. Returns null when nothing is left.
+ */
+export function unmergeJson(theirs, ours) {
+  if (Array.isArray(theirs) && Array.isArray(ours)) {
+    const left = theirs.filter((t) => !ours.some((o) => same(t, o)));
+    return left.length > 0 ? left : null;
+  }
+  if (isPlainObject(theirs) && isPlainObject(ours)) {
+    const out = {};
+    for (const [k, v] of Object.entries(theirs)) {
+      if (!(k in ours) || isScalar(ours[k])) { out[k] = v; continue; }
+      const kept = unmergeJson(v, ours[k]);
+      if (kept !== null) out[k] = kept;
+    }
+    // Our scalars (a `"version": 1`) go only when they are all that is left.
+    const userKeys = Object.keys(out).filter((k) => !(k in ours && isScalar(ours[k]) && same(out[k], ours[k])));
+    return userKeys.length > 0 ? out : null;
+  }
+  return same(theirs, ours) ? null : theirs;
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function isScalar(v) {
+  return v === null || typeof v !== "object";
+}
+
+/** Whether `theirs` holds at least one array entry `ours` contributes. */
+export function holdsAnyOf(theirs, ours) {
+  if (Array.isArray(theirs) && Array.isArray(ours)) return ours.some((o) => theirs.some((t) => same(t, o)));
+  if (isPlainObject(theirs) && isPlainObject(ours)) {
+    return Object.keys(ours).some((k) => k in theirs && holdsAnyOf(theirs[k], ours[k]));
+  }
+  return false;
+}
+
+/** Whether every entry `ours` contributes is present in `theirs`. */
+export function containsJson(theirs, ours) {
+  return same(mergeJson(theirs, ours), theirs);
+}

package/src/lib/args.js

@@ -8,12 +8,25 @@
 //   -x=value or -x value            -> string value
 //   --                              -> stop flag parsing; rest is positional
 //
-// Anything else becomes positional. Repeated flags overwrite the previous value.
+// Anything else becomes positional. Repeated flags overwrite the previous value
+// in `flags`; every value is still kept, in order, for `flagAll` — a command
+// that takes a flag more than once (`change delta --op a --op b`) reads them
+// all there instead of losing every one but the last (change 0228).
+
+/** @type {WeakMap<Map<string, string|boolean>, Map<string, string[]>>} */
+const EVERY_VALUE = new WeakMap();
 
 export function parseArgs(argv, opts = {}) {
   const booleanFlags = new Set(opts.boolean ?? []);
   const positional = [];
+  /** @type {Map<string, string|boolean>} */
   const flags = new Map();
+  /** @type {Map<string, string[]>} */
+  const every = new Map();
+  EVERY_VALUE.set(flags, every);
+  const keep = (/** @type {string} */ name, /** @type {string|boolean} */ value) => {
+    if (typeof value === "string") every.set(name, [...(every.get(name) ?? []), value]);
+  };
   let i = 0;
   let stopped = false;
 
@@ -37,12 +50,14 @@ export function parseArgs(argv, opts = {}) {
       const eq = body.indexOf("=");
       if (eq >= 0) {
         flags.set(body.slice(0, eq), body.slice(eq + 1));
+        keep(body.slice(0, eq), body.slice(eq + 1));
         i += 1;
       } else if (booleanFlags.has(body) || isNextTokenFlag(argv[i + 1])) {
         flags.set(body, true);
         i += 1;
       } else {
         flags.set(body, argv[i + 1] ?? true);
+        keep(body, argv[i + 1] ?? true);
         i += 2;
       }
       continue;
@@ -53,12 +68,14 @@ export function parseArgs(argv, opts = {}) {
       const eq = body.indexOf("=");
       if (eq >= 0) {
         flags.set(body.slice(0, eq), body.slice(eq + 1));
+        keep(body.slice(0, eq), body.slice(eq + 1));
         i += 1;
       } else if (booleanFlags.has(body) || isNextTokenFlag(argv[i + 1])) {
         flags.set(body, true);
         i += 1;
       } else {
         flags.set(body, argv[i + 1] ?? true);
+        keep(body, argv[i + 1] ?? true);
         i += 2;
       }
       continue;
@@ -91,6 +108,21 @@ export function parsePositiveInt(raw) {
   return Number.isSafeInteger(n) && n > 0 ? n : null;
 }
 
+/**
+ * Every value a string flag was given, in the order given — `[]` when absent.
+ * A Map built by hand (tests, callers that never parsed argv) answers with
+ * its one value.
+ * @param {Map<string, string|boolean>} flags
+ * @param {string} name
+ * @returns {string[]}
+ */
+export function flagAll(flags, name) {
+  const every = EVERY_VALUE.get(flags)?.get(name);
+  if (every) return every;
+  const one = flags.get(name);
+  return typeof one === "string" ? [one] : [];
+}
+
 export function flagString(flags, name, fallback = undefined) {
   const v = flags.get(name);
   if (v === undefined || v === true) return fallback;