@design-twin/dtwin 0.0.0-stage → 0.1.0

package/src/variables-merge.ts

@@ -0,0 +1,337 @@
+// variables-merge.ts — design/variables.json accumulates across single-screen pulls.
+//
+// A `--node`/`--selection` pull returns only the variables THAT node binds. Writing that slice
+// straight to design/variables.json would make every pull silently delete
+// the previous screen's tokens: pull screen A, pull screen B, and A's theme no longer resolves.
+// Nothing would warn, because the screen JSON carries raw hex beside every binding — so the build would still
+// render, just unthemed. That is the worst shape a data-loss bug can take.
+//
+// So: merge. A variable's identity is its Figma `key` (stable across files and across pulls); only
+// when a key is absent (never seen on a real export, but the field is optional in the IR) do we fall
+// back to collection+name, which is the weakest thing that is still not wrong. Collections merge the
+// same way, unioning their `modes` — two slices of one collection can legitimately report different
+// mode subsets.
+//
+// Merge direction: the NEW slice wins a value conflict (it is the fresher read of the same file) and
+// the disagreement is recorded in `_conflicts` + `hygiene` rather than silently resolved. On the live
+// runs that produced this module there were zero conflicts across five slices, which is the expected
+// case: the slices are views of one variable set.
+//
+// Provenance is kept, not inferred: `_slices` records one entry per contributing pull — including the
+// KEYS that pull carried — and the raw slice is also written verbatim beside its screen as
+// <Screen>.vars.json by write-out.ts. So "which screen did this variable come from" survives the
+// merge, and deleting design/export/variables.json resets everything.
+//
+// Two DIFFERENT variables (distinct keys) with the SAME collection and name are both kept — the key
+// is the identity — but they are a conflict for every consumer that looks a token up by name, which
+// is most of them (a theme generator, a slugged CSS variable, a designer reading a list). A real
+// pull had two `Spacing / Space 4` (24 and 16) and two `Spacing / Space 2` in the union and
+// an EMPTY `_conflicts`, because only same-key value changes were recorded. Each such pair is
+// a `_conflicts` entry of kind "same-name", naming every key, its values and the screens whose
+// slice carries it, and a CONFLICT line in `hygiene` — the two places the skills tell a reader to look.
+
+// The per-pull slices are not under a "variables/" directory (none exists): bridge/src/pages-layout.ts's
+// screenPaths() writes each slice BESIDE its screen, as pages/<Page>/<Screen>__<id>.vars.json (see
+// design/README.md's template), not into a top-level variables/ directory.
+import type {
+  VariableCollection, Variable, SliceEntry, ValueConflict, SameNameConflict, VariableConflict, VariablesDoc,
+} from "./doc-types.ts";
+import { ifDefined, isUnknownArray } from "./json-util.ts";
+
+/** The pull a slice came from: its screen stem, its screen file, and (optionally) when it was read. */
+export interface SliceInput {
+  screen: string;
+  file?: string;
+  at?: string;
+}
+
+/** The merged design/export/variables.json. `_note`/`exportedAt` are always set by mergeVariablesDoc
+ *  (they are optional only because VariablesDoc declares them so); `_conflicts` only when non-empty. */
+export interface MergedVariablesDoc extends VariablesDoc {
+  collections: VariableCollection[];
+  variables: Variable[];
+  hygiene: string[];
+  _slices: SliceEntry[];
+}
+
+/** What the CLI prints about one merge — this module never logs. */
+export interface MergeStats {
+  added: number;
+  updated: number;
+  kept: number;
+  conflicts: ValueConflict[];
+  nameConflicts?: SameNameConflict[];
+  collections: number;
+  first: boolean;
+}
+
+export interface MergeResult {
+  doc: MergedVariablesDoc;
+  stats: MergeStats;
+}
+
+/** What varId / collId read — any variable or collection (or a partial one, or nothing). */
+interface Keyed { key?: unknown; name?: unknown; collection?: unknown }
+
+export const MERGE_NOTE =
+  "Merged across single-screen pulls: this file is the UNION of every --node/--selection export " +
+  "written into this directory, keyed on each variable's Figma key. Per-pull slices are kept verbatim " +
+  "beside each screen, as pages/<Page>/<Screen>__<id>.vars.json. Delete this file to start over.";
+
+export function varId(v: Keyed | null | undefined): string {
+  if (v && typeof v.key === "string" && v.key) return "k:" + v.key;
+  return "n:" + String((v && v.collection) || "") + "\u0000" + String((v && v.name) || "");
+}
+
+export function collId(c: Keyed | null | undefined): string {
+  if (c && typeof c.key === "string" && c.key) return "k:" + c.key;
+  return "n:" + String((c && c.name) || "");
+}
+
+// Value equality is compared on the fields that DECIDE a token: what it resolves to per mode, and
+// what kind of thing it is. Metadata that legitimately differs between slices (scopes reported by a
+// partial read, hiddenFromPublishing) is not a conflict, so it does not generate noise.
+function sameValue(a: Variable | null | undefined, b: Variable | null | undefined): boolean {
+  return JSON.stringify(a && a.values) === JSON.stringify(b && b.values) && (a && a.type) === (b && b.type);
+}
+
+function mergeModes(prev: unknown, next: unknown): string[] {
+  // Mode lists from two exports on disk (untyped JSON): only their string entries are modes.
+  const out: string[] = isUnknownArray(prev) ? prev.filter((m): m is string => typeof m === "string") : [];
+  for (const m of isUnknownArray(next) ? next : []) if (typeof m === "string" && !out.includes(m)) out.push(m);
+  return out;
+}
+
+// prev/next are whole variables.json documents ({collections, variables, hygiene}). `slice` names the
+// pull that produced `next` so the provenance list can carry it. Returns the merged doc plus the
+// stats the CLI prints — callers decide how loud to be, this module never logs.
+//
+// `prev` is whatever variables.json is on disk (untyped JSON). It is only merged when it is an object
+// carrying a `variables` or `collections` array — i.e. a document this module wrote on an earlier
+// pull — and from there it is read as that shape; every array is still re-checked with
+// Array.isArray and every element null-guarded, exactly as the JS did.
+function asMergedDoc(prev: unknown): VariablesDoc | null {
+  if (!prev || typeof prev !== "object") return null;
+  const d = prev as VariablesDoc;
+  return !Array.isArray(d.variables) && !Array.isArray(d.collections) ? null : d;
+}
+
+export function mergeVariablesDoc(prevRaw: unknown, next: VariablesDoc | null | undefined, slice?: SliceInput): MergeResult {
+  const nextDoc: VariablesDoc = next || {};
+  const prev = asMergedDoc(prevRaw);
+  if (!prev) {
+    // First pull into this directory: nothing to merge, but stamp the provenance so the second pull
+    // has a list to append to rather than an unexplained new key.
+    const core = {
+      collections: Array.isArray(nextDoc.collections) ? nextDoc.collections.slice() : [],
+      variables: Array.isArray(nextDoc.variables) ? nextDoc.variables.slice() : [],
+      hygiene: Array.isArray(nextDoc.hygiene) ? nextDoc.hygiene.slice() : [],
+    };
+    // Object.assign onto `core` keeps the JS key order: collections, variables, hygiene, _slices, …
+    const doc: MergedVariablesDoc = Object.assign(core, { _slices: slice ? [sliceEntry(slice, core)] : [] });
+    const nameConflicts = sameNameConflicts(doc.variables, doc._slices);
+    applyNameConflicts(doc, nameConflicts, []);
+    doc._note = MERGE_NOTE;
+    doc.exportedAt = docExportedAt(doc._slices);
+    return {
+      doc,
+      stats: { added: doc.variables.length, updated: 0, kept: 0, conflicts: [], nameConflicts, collections: doc.collections.length, first: true },
+    };
+  }
+
+  const collections: VariableCollection[] = [];
+  const collIndex = new Map<string, number>();
+  for (const c of Array.isArray(prev.collections) ? prev.collections : []) {
+    const id = collId(c);
+    if (collIndex.has(id)) continue;
+    collIndex.set(id, collections.length);
+    collections.push(Object.assign({}, c));
+  }
+  for (const c of Array.isArray(nextDoc.collections) ? nextDoc.collections : []) {
+    const id = collId(c);
+    const at = collIndex.get(id);
+    // `was` is always set when `at` is: collIndex only ever holds indexes of pushed (object) entries.
+    const was = at === undefined ? undefined : collections[at];
+    if (at === undefined || was === undefined) {
+      collIndex.set(id, collections.length);
+      collections.push(Object.assign({}, c));
+      continue;
+    }
+    const merged: VariableCollection = Object.assign({}, was, c);
+    merged.modes = mergeModes(was.modes, c.modes);
+    collections[at] = merged;
+  }
+
+  const variables: Variable[] = [];
+  const varIndex = new Map<string, number>();
+  for (const v of Array.isArray(prev.variables) ? prev.variables : []) {
+    const id = varId(v);
+    if (varIndex.has(id)) continue;
+    varIndex.set(id, variables.length);
+    variables.push(v);
+  }
+  const stats: MergeStats = { added: 0, updated: 0, kept: 0, conflicts: [], collections: collections.length, first: false };
+  for (const v of Array.isArray(nextDoc.variables) ? nextDoc.variables : []) {
+    const id = varId(v);
+    const at = varIndex.get(id);
+    // `before` is always set when `at` is: varIndex only ever holds indexes of pushed entries.
+    const before = at === undefined ? undefined : variables[at];
+    if (at === undefined || before === undefined) {
+      varIndex.set(id, variables.length);
+      variables.push(v);
+      stats.added++;
+      continue;
+    }
+    if (sameValue(before, v)) {
+      // Same token, same resolution — keep the richer record rather than the newer one, so a slice
+      // that happened to read fewer scopes cannot strip fields an earlier slice captured.
+      variables[at] = Object.assign({}, v, before);
+      stats.kept++;
+      continue;
+    }
+    stats.conflicts.push({
+      name: v.name,
+      ...ifDefined("collection", v.collection),
+      ...ifDefined("key", v.key),
+      was: before.values,
+      now: v.values,
+      ...ifDefined("from", slice && slice.screen),
+    });
+    variables[at] = v;
+    stats.updated++;
+  }
+
+  const hygiene: string[] = [];
+  const seenHy = new Set<string>();
+  for (const h of (Array.isArray(prev.hygiene) ? prev.hygiene : []).concat(Array.isArray(nextDoc.hygiene) ? nextDoc.hygiene : [])) {
+    const s = String(h);
+    if (seenHy.has(s)) continue;
+    seenHy.add(s);
+    hygiene.push(h);
+  }
+  for (const c of stats.conflicts) {
+    const line =
+      `CONFLICT: '${c.name}' (${c.collection}) resolves differently in ${slice && slice.screen ? "'" + slice.screen + "'" : "the newest pull"} ` +
+      `than in an earlier pull — the newest value is kept. Check which screen is right before generating a theme.`;
+    if (!seenHy.has(line)) {
+      seenHy.add(line);
+      hygiene.push(line);
+    }
+  }
+
+  const slices: SliceEntry[] = Array.isArray(prev._slices) ? prev._slices.filter((s) => !slice || s.screen !== slice.screen) : [];
+  if (slice) slices.push(sliceEntry(slice, nextDoc));
+  const doc: MergedVariablesDoc = { collections, variables, hygiene, _slices: slices };
+  // Value conflicts are events (a pull changed a known variable), so earlier ones are carried forward
+  // rather than wiped by the next pull; same-name conflicts are a property of the union, so they are
+  // recomputed from it every time.
+  const seenValue = new Set<string>();
+  const valueConflicts: ValueConflict[] = [];
+  for (const c of (Array.isArray(prev._conflicts) ? prev._conflicts : []).concat(stats.conflicts)) {
+    if (!c || c.kind === "same-name") continue;
+    const id = JSON.stringify([c.key, c.name, c.collection, c.now, c.from]);
+    if (seenValue.has(id)) continue;
+    seenValue.add(id);
+    valueConflicts.push(Object.assign({ kind: "value" }, c));
+  }
+  stats.nameConflicts = sameNameConflicts(variables, slices);
+  applyNameConflicts(doc, stats.nameConflicts, valueConflicts);
+  doc._note = MERGE_NOTE;
+  doc.exportedAt = docExportedAt(doc._slices);
+  return { doc, stats };
+}
+
+const SAME_NAME_PREFIX = "CONFLICT (same name): ";
+const short = (k: unknown): string => (typeof k === "string" && k ? k.slice(0, 8) + "…" : "(no key)");
+
+// Every [collection, name] held by more than one distinct variable in the union.
+export function sameNameConflicts(variables: Variable[], slices: SliceEntry[] | null | undefined): SameNameConflict[] {
+  const groups = new Map<string, Map<string, Variable>>();
+  for (const v of variables) {
+    if (!v || !v.name) continue;
+    const id = String(v.collection || "") + "\u0000" + v.name;
+    let group = groups.get(id);
+    if (!group) { group = new Map(); groups.set(id, group); }
+    group.set(varId(v), v);
+  }
+  const out: SameNameConflict[] = [];
+  for (const members of groups.values()) {
+    if (members.size < 2) continue;
+    const list = [...members.values()];
+    const [first] = list;
+    if (first === undefined) continue; // cannot happen: members.size >= 2
+    out.push({
+      kind: "same-name",
+      name: first.name,
+      ...ifDefined("collection", first.collection),
+      sameValue: list.every((v) => resolvesAlike(v, first)),
+      variants: list.map((v) => ({
+        ...ifDefined("key", v.key),
+        values: v.values,
+        screens: (slices || []).filter((s) => Array.isArray(s.keys) && v.key !== undefined && s.keys.includes(v.key)).map((s) => s.screen),
+      })),
+    });
+  }
+  return out;
+}
+
+// Same resolution under different MODE NAMES: `Space 2` = 8 under Desktop/Tablet/Mobile and 8 under
+// Mode 1 is one value, and tokens.ts emits such a pair once. Shared modes must agree; with no shared
+// mode, both must be one constant, and the same one.
+function resolvesAlike(a: Variable, b: Variable): boolean {
+  if (sameValue(a, b)) return true;
+  if ((a && a.type) !== (b && b.type)) return false;
+  const va = (a && a.values) || {}, vb = (b && b.values) || {};
+  const shared = Object.keys(va).filter((m) => m in vb);
+  if (shared.length) return shared.every((m) => JSON.stringify(va[m]) === JSON.stringify(vb[m]));
+  const all = [...Object.values(va), ...Object.values(vb)].map((x) => JSON.stringify(x));
+  return all.length > 0 && all.every((x) => x === all[0]);
+}
+
+function applyNameConflicts(doc: MergedVariablesDoc, nameConflicts: SameNameConflict[], valueConflicts: ValueConflict[]): void {
+  // Stale same-name lines (an earlier union's screen lists) are replaced, not accumulated.
+  doc.hygiene = doc.hygiene.filter((h) => !String(h).startsWith(SAME_NAME_PREFIX));
+  for (const c of nameConflicts) {
+    const parts = c.variants.map((v) => `key ${short(v.key)} = ${JSON.stringify(v.values || {})}` + (v.screens.length ? ` (from ${v.screens.join(", ")})` : ""));
+    doc.hygiene.push(
+      SAME_NAME_PREFIX +
+        `${c.variants.length} different variables are all called '${c.name}'${c.collection ? ` in collection '${c.collection}'` : ""} — ` +
+        parts.join(c.sameValue ? " and " : " vs ") + ". " +
+        (c.sameValue
+          ? "They resolve identically, so a theme emits them once, but they are still two variables."
+          : "They resolve DIFFERENTLY. Both are kept here (keyed by Figma key), but anything that looks a token up by NAME gets one of them — " +
+            "generate a screen's theme from that screen's own .vars.json (or design-system/tokens.json), not from this union.")
+    );
+  }
+  const all: VariableConflict[] = [...valueConflicts, ...nameConflicts];
+  if (all.length) doc._conflicts = all;
+}
+
+function sliceEntry(slice: SliceInput, doc: { variables?: Variable[]; collections?: VariableCollection[] } | null | undefined): SliceEntry {
+  const vars = doc && Array.isArray(doc.variables) ? doc.variables : [];
+  return {
+    screen: slice.screen,
+    ...ifDefined("file", slice.file),
+    at: slice.at || new Date().toISOString(),
+    variables: vars.length,
+    collections: doc && Array.isArray(doc.collections) ? doc.collections.length : 0,
+    // Which variables THIS pull carried, by key — the provenance a same-name conflict needs to say
+    // which screen each of the two variables came from.
+    keys: [...new Set(vars.map((v) => v && v.key).filter((k): k is string => typeof k === "string" && !!k))].sort(),
+  };
+}
+
+// A top-level freshness stamp, derived from `_slices[].at` (never invented separately from it) so a
+// consumer that expects every export document to carry `exportedAt` (design-diff.ts's `previous()`,
+// `dtwin doctor`'s export-age check) has one to read (without it the
+// stale-baseline check that works for tokens.json could never fire for it). This is a MAX over the
+// slice times, i.e. "when did the most recent contributing pull happen" — not a plain re-stamped
+// "now", which must be avoided: `_slices[].at` legitimately re-appends on every
+// re-pull of any ONE screen, so `exportedAt` moves whenever slices do, same as they do,
+// and nothing here compares variable VALUES by exportedAt equality — that comparison stays keyed
+// (`varId`/`sameValue` above), so a moved `exportedAt` alone can never manufacture a fake "token
+// changed" the way a naive independent timestamp would.
+export function docExportedAt(slices: SliceEntry[] | null | undefined): string | null {
+  const times = (Array.isArray(slices) ? slices : []).map((s) => s && typeof s.at === "string" ? s.at : null).filter((t): t is string => Boolean(t));
+  return times.length ? times.reduce((mx, t) => (t > mx ? t : mx)) : null;
+}

package/src/verbs.ts

@@ -0,0 +1,140 @@
+// verbs.ts — `dtwin <verb>` front door. A PURE argv → argv translation onto the flags figma-pull.ts
+// already parses, so there is one parser and one set of guards, and every existing `--flag`
+// invocation keeps working unchanged (clig.dev: subcommands to tame a large surface; never break the
+// old spelling silently).
+//
+//   dtwin pull [outDir] [flags]      = dtwin [outDir] [flags]
+//   dtwin list [pages|libraries|clients]   = --list | --list-pages | --list-libraries | --list-clients
+//   dtwin list children <id|url>     = --children <id|url>
+//   dtwin whoami                     = --whoami
+//   dtwin screenshot <id|url>        = --screenshot <id|url>
+//   dtwin serve | stop | status      = --serve | --stop | --daemon-status
+//   dtwin token [status|show|rotate|forget]  = --token-status | --show-token | --rotate-token | --forget-token
+//   dtwin help | version             = --help | --version
+//   dtwin doctor | init | mcp | seed → their own entry points (routed in figma-pull.ts)
+//
+// A verb is only recognised as the FIRST argument. `dtwin design` still means "pull into ./design":
+// an outDir that happens to be spelled like a verb is written `dtwin pull list` or `dtwin ./list`.
+
+import { COMMAND_ROWS, VERB_DEFS } from "./cli-commands.ts";
+import type { CommandRow } from "./cli-commands.ts";
+
+export class VerbError extends Error {}
+
+// Every spelling, help page and summary line is a row in cli-commands.ts (the command registry): the
+// sub-nouns of `list` and `token` are the spellings on its COMMANDS rows, the verbs and their pages are
+// its VERB_ROWS. Derived here, so a command added there is a verb here without a line of this file changing.
+export { SEED_HELP } from "./cli-commands.ts";
+export const VERBS: string[] = VERB_DEFS.map((v) => v.word);
+
+// Words people (and agents) reach for first that are NOT verbs. Left alone they were a positional
+// outDir: `dtwin export` created ./export and then waited for a plugin, looking exactly like a pull
+// that was working. Same opt-outs as a near-miss: a path, an existing folder, or `dtwin pull export`.
+const ALIASES: Record<string, string> = { export: "pull", get: "pull", fetch: "pull", download: "pull", sync: "pull", ls: "list", frames: "list", pages: "list pages", libraries: "list libraries", clients: "list clients",
+  check: "doctor", diagnose: "doctor", setup: "init", install: "init", connect: "doctor", start: "serve", daemon: "serve", kill: "stop", tokens: "token" };
+// (`version` was listed here as an alias for `--version`, which made the real `dtwin version` a
+// did-you-mean error that pointed at itself. It is a verb row of its own now.)
+
+const isFlag = (a: unknown): boolean => typeof a === "string" && a.startsWith("-");
+
+// Per-verb help. `dtwin screenshot --help` must not hit translate's "needs a node id" refusal, which
+// the verb's own argument check would give if it ran before the global --help handler — a help probe
+// is the one thing that must never be answered with an error. Every verb has its own page (a row's
+// `help`) or answers through its own entry point (OWN_HELP_ROUTED); only `help` prints the full `dtwin --help`.
+export const HELP: Record<string, string> = Object.fromEntries(VERB_DEFS.flatMap((v) => (v.help === undefined ? [] : [[v.word, v.help]])));
+
+// The verbs that answer `--help` through their own entry point (routed in figma-pull.ts before verbHelp
+// runs) and have no page here. `help` is the one other verb without a page: its page IS the full usage.
+// test/cli-help.test.ts walks the verb rows and requires every one to have a page or be in this list.
+export const OWN_HELP_ROUTED: readonly string[] = VERB_DEFS.filter((v) => v.to === "routed" && v.help === undefined).map((v) => v.word);
+
+// The only port override is FIGMA_BRIDGE_PORT; DTWIN_PORT is not read, so setting it would be silently ignored.
+// One sentence for the CLI and doctor, or null when DTWIN_PORT is not set.
+export function dtwinPortWarning(env: Record<string, string | undefined>): string | null {
+  return env.DTWIN_PORT === undefined ? null : "DTWIN_PORT is not read — use FIGMA_BRIDGE_PORT (8787/8788/8789)";
+}
+
+/** A `dtwin <verb> [sub]` spelling of a command, with the command it means. */
+interface Spelling { row: CommandRow; flag: string; words: readonly string[] }
+const SPELLINGS: Spelling[] = COMMAND_ROWS.flatMap((row) => (row.flag === null ? [] : (row.verbs ?? []).map((words) => ({ row, flag: row.flag as string, words }))));
+
+export function translate(argv: string[], exists: (p: string) => boolean = () => false): string[] {
+  const [verb, ...rest] = argv;
+  if (!verb || isFlag(verb)) return argv;
+  const def = VERB_DEFS.find((v) => v.word === verb);
+  if (def) {
+    if (def.to === "pull") return rest;
+    if (def.to === "routed") return argv; // doctor | init | mcp | seed: routed by figma-pull.ts, not translated here
+    if (def.to !== "commands") return [def.to, ...rest]; // help | version
+    const mine = SPELLINGS.filter((s) => s.words[0] === verb);
+    if (def.badSub) {
+      // A verb with sub-nouns (`list pages`, `token rotate`): the first word after it, unless it is a flag.
+      const sub = rest[0] && !isFlag(rest[0]) ? rest[0] : "";
+      const hit = mine.find((s) => (s.words[1] ?? "") === sub);
+      if (!hit) throw new VerbError(def.badSub(sub));
+      return takeValue(hit, rest.slice(sub ? 1 : 0));
+    }
+    const hit = mine.find((s) => s.words.length === 1);
+    if (hit) return takeValue(hit, rest);
+  }
+  // Not a verb: a positional outDir — unless it is a near-miss of one. `dtwin whomai` would otherwise
+  // start a full pull into ./whomai; a bare word one or two edits from a verb is far likelier
+  // a typo than a folder. A path (`./serv`), an existing folder (`exists`), or `dtwin pull serv` opts out.
+  const alias = ALIASES[verb.toLowerCase()];
+  if (alias && !/[\\/.]/.test(verb) && !exists(verb))
+    throw new VerbError(`unknown command \`${verb}\` — did you mean \`dtwin ${alias}\`? (to export into a folder named "${verb}": dtwin pull ${verb})`);
+  const near = nearestVerb(verb);
+  if (near && !/[\\/.]/.test(verb) && !exists(verb))
+    throw new VerbError(`unknown command \`${verb}\` — did you mean \`dtwin ${near}\`? (to export into a folder named "${verb}": dtwin pull ${verb})`);
+  return argv;
+}
+
+// A spelling's flag in front of what follows it. A value-taking command (`dtwin screenshot <id>`,
+// `dtwin list children <id>`) needs its value next: it becomes the flag's value, the rest passes through.
+function takeValue({ row, flag }: Spelling, rest: string[]): string[] {
+  if (!row.value) return [flag, ...rest];
+  if (!rest[0] || isFlag(rest[0])) throw new VerbError(row.value.verbMissing ?? row.value.missing);
+  return [flag, rest[0], ...rest.slice(1)];
+}
+
+// The verb whose help a given argv is asking for, or null. Exported so figma-pull can answer BEFORE
+// translate runs its per-verb argument checks.
+export function verbHelp(argv: unknown): string | null {
+  if (!Array.isArray(argv) || !argv.some((a) => a === "--help" || a === "-h")) return null;
+  const verb: unknown = argv[0];
+  return (typeof verb === "string" && verb && HELP[verb]) || null;
+}
+
+export function distance(a: string, b: string): number {
+  // Levenshtein, one row at a time. `row` is the previous row (row[j] = distance(a[0..i-1), b[0..j)));
+  // `diag`/`left` carry row[j-1] and the new row's [j-1] so no cell is read by index.
+  let row = Array.from({ length: b.length + 1 }, (_, j) => j);
+  let last = b.length; // the bottom-right cell: row[b.length]
+  for (let i = 1; i <= a.length; i++) {
+    const next = [i];
+    let diag = i - 1; // row[0] of the previous row
+    let left = i;     // next[0]
+    for (const [k, up] of row.slice(1).entries()) { // k = j - 1, up = row[j]
+      const cur = Math.min(up + 1, left + 1, diag + (a[i - 1] === b[k] ? 0 : 1));
+      next.push(cur);
+      diag = up;
+      left = cur;
+    }
+    row = next;
+    last = left;
+  }
+  return last;
+}
+
+// Two edits for the longer verbs. A short verb ("pull", "list", "stop", "mcp" …) is one edit from real
+// folder names ("dist" ↔ "list"), so there only a dropped or extra LAST letter counts ("lis", "lists").
+function nearestVerb(word: string): string | null {
+  const w = String(word).toLowerCase();
+  let best: { v: string; d: number } | null = null;
+  for (const v of VERBS) {
+    const d = distance(w, v);
+    const ok = v.length >= 5 ? d <= (v.length >= 6 ? 2 : 1) : d === 1 && (w.startsWith(v) || v.startsWith(w));
+    if (ok && (!best || d < best.d)) best = { v, d };
+  }
+  return best && best.v;
+}