@design-twin/dtwin 0.0.0-stage → 0.1.0

package/src/route.ts

@@ -0,0 +1,243 @@
+// route.ts — the one way a front-end reaches the Figma plugin, whoever holds the bridge.
+//
+// There are two ways to reach a plugin, and so two adapters behind one interface (Upstream):
+//   - own:    this process holds the bridge (server-core's createBridge) — the CLI with no daemon running, or
+//             the MCP server that bound the port first;
+//   - daemon: another process holds it and serves it on the daemon socket (daemon.ts) — any dtwin command
+//             while `dtwin serve` runs, or a second MCP server.
+// The adapters only translate shapes. The RULES sit above them, in the Route, so the CLI and the MCP server
+// cannot drift apart again (they had: a named-client wait done two ways, a stall check only one of them ran,
+// the listClients/connectionInfo fallbacks copied). A route owns:
+//   - the connect window: how long a request waits for a plugin (and for a named file, `namedWaitMs`, which is
+//     the same window unless the policy says otherwise) before it is resolved against whatever is connected.
+//     A one-shot route over its own bridge spends it once, up front (connect()); every other route spends it
+//     per request (the daemon waits inside each one);
+//   - the never-connected guard: a one-shot route whose window ran out with no plugin EVER connected says so
+//     in its own words, rather than resolveClient's "not connected" (which is right for one that left);
+//   - the stall check (server-core request `stallMs`): one-shot, own bridge, export-class commands
+//     only — the case where a freshly opened bridge can sit on a plugin too busy to answer at all. A daemon's
+//     or a long-lived server's connection is warm, so they never pay for it;
+//   - progress: only an export-class command hears ticks (a ping or a page list has none worth hearing);
+//   - listClients and connectionInfo, from whichever side holds the bridge.
+// MCP's sharing layer (figma-mcp.ts holder) decides per call WHICH upstream to use; a route takes that
+// decision as a function, so it re-resolves exactly when the sharing layer does.
+//
+// Side-effect free, like daemon.ts; only types come from server-core.
+import { TIMEOUTS, daemonGuardMs } from "./timeouts.ts";
+import { ifDefined } from "./json-util.ts";
+import { isExportCmd } from "./commands.ts";
+import type { Cmd, Commands } from "./commands.ts";
+import type { Bridge, ClientRow, ConnectionInfo, ProgressTick } from "./server-core.ts";
+import type { DaemonBridge, DaemonConnection, DaemonStatusView } from "./daemon.ts";
+
+/** A connection id as the registry mints it ("c" + a per-bridge sequence number). A target of this form
+ *  names one socket, so it never depends on identification: waits for a client never hold it for a name. */
+export function isConnId(target: string): boolean {
+  return /^c\d+$/.test(target);
+}
+
+/**
+ * `info` re-described for the connection `connId` — the `clients[]` row with that connId supplies
+ * `connId`, `connectedAt` and `connectionUptimeMs` (its `uptimeMs`); every other field (`connected`,
+ * `clientsConnected`, `clients`, `connectionsThisRun`, `takeovers`, `lastTakeoverAt`) is kept. A null/absent
+ * connId, or one not among `clients`, returns `info` unchanged. Pure — works on a daemon's relayed
+ * `status().connection` as well as on the own bridge's connectionInfo().
+ */
+export function connectionFor(info: ConnectionInfo, connId: string | null | undefined): ConnectionInfo {
+  if (!connId) return info;
+  const row = (info.clients || []).find((c) => c && c.connId === connId);
+  if (!row) return info;
+  return { ...info, connId: row.connId, connectedAt: row.connectedAt, connectionUptimeMs: row.uptimeMs };
+}
+
+/** What a request resolved with, and WHICH connected file answered (null only from a daemon too old to say). */
+export interface Sent<C extends Cmd> { reply: Commands[C]["reply"]; client: ClientRow | null }
+
+/** One request as an adapter takes it: no rules applied, every field passed through. */
+export interface UpstreamRequest {
+  /** the per-command budget (TIMEOUTS.command when absent) */
+  timeoutMs?: number | undefined;
+  /** connId / fileKey / file-name substring; absent = the only connected file */
+  target?: string | null | undefined;
+  /** > 0: wait that long for the target first (server-core awaitClient) */
+  waitMs?: number | undefined;
+  /** > 0: server-core's stall check (own bridge only; a daemon never runs it) */
+  stallMs?: number | undefined;
+  onProgress?: ((tick: ProgressTick) => void) | undefined;
+  signal?: AbortSignal | undefined;
+}
+
+/** Who holds the bridge a route reached: this process, or a daemon (its pid; port and pluginConnected kept
+ *  for a daemon too old to relay its whole connection). */
+export type Owner = { kind: "own" } | { kind: "daemon"; pid: number | null; port: number | null; pluginConnected: boolean | null };
+
+/** connectionInfo's answer: the socket half of whoami (null from a daemon too old to relay it), and its holder. */
+export interface RouteConnection { connection: ConnectionInfo | null; owner: Owner }
+
+/** The seam. Two adapters: ownUpstream (a bridge this process holds) and daemonUpstream (a daemon's socket). */
+export interface Upstream {
+  kind: "own" | "daemon";
+  /** Where it is reached: own, the bridge's ws:// URL; daemon, its socket path. For the log line that says so. */
+  address: string;
+  request<C extends Cmd>(cmd: C, args: Commands[C]["args"], o: UpstreamRequest): Promise<Sent<C>>;
+  /** Wait up to `waitMs` for a plugin (and `target`), then say whether any has connected in this bridge's
+   *  life. A daemon answers null at once: it waits inside each request instead (the frame's waitForConnection). */
+  awaitClient(target: string | null | undefined, waitMs: number): Promise<{ everConnected: boolean } | null>;
+  listClients(): Promise<ClientRow[]>;
+  connectionInfo(connId?: string | null): Promise<RouteConnection>;
+}
+
+/** What the own adapter and servedBridge use of a bridge this process holds (server-core's createBridge result) —
+ *  the narrow face the bridge holder hands them, and what a suite's fake bridge implements. */
+export type HeldBridge = Pick<Bridge, "port" | "isConnected" | "request" | "awaitClient" | "connectionInfo" | "listClients" | "close">;
+
+/** The own adapter: the bridge takes the request shape as it is. */
+export function ownUpstream(bridge: HeldBridge): Upstream {
+  return {
+    kind: "own",
+    address: "ws://localhost:" + bridge.port,
+    request: (cmd, args, o) => bridge.request(cmd, args, o),
+    async awaitClient(target, waitMs) {
+      await bridge.awaitClient(target, waitMs);
+      return { everConnected: bridge.connectionInfo().connectionsThisRun > 0 };
+    },
+    listClients: async () => bridge.listClients(),
+    connectionInfo: async (connId) => ({ connection: bridge.connectionInfo(connId ?? undefined), owner: { kind: "own" } }),
+  };
+}
+
+/** The daemon adapter: a request becomes a socket frame (the connect window rides on it as waitForConnection,
+ *  and the outer guard is sized for it — daemonGuardMs); listings come from the daemon's __status. */
+export function daemonUpstream(conn: DaemonConnection, status: () => Promise<DaemonStatusView | null>): Upstream {
+  return {
+    kind: "daemon",
+    address: conn.sock,
+    request(cmd, args, o) {
+      const timeoutMs = o.timeoutMs ?? TIMEOUTS.command;
+      const waitMs = o.waitMs && o.waitMs > 0 ? o.waitMs : 0;
+      return conn.request({ cmd, args, timeoutMs, ...ifDefined("client", o.target ?? undefined), ...(waitMs > 0 ? { waitForConnection: waitMs } : {}) },
+        { guardMs: daemonGuardMs(timeoutMs, waitMs), onProgress: o.onProgress, signal: o.signal });
+    },
+    awaitClient: async () => null,
+    listClients: async () => (await status())?.clients || [],
+    async connectionInfo(connId) {
+      // An older daemon may omit fields (daemon.ts DaemonStatusView) — reported as null, never guessed.
+      const st = await status();
+      const owner: Owner = { kind: "daemon", pid: st?.pid ?? null, port: st?.port ?? null, pluginConnected: st?.pluginConnected ?? null };
+      return { connection: st?.connection ? connectionFor(st.connection, connId) : null, owner };
+    },
+  };
+}
+
+/** What daemon.serve() drives, made from a bridge this process holds: requests go through the own adapter.
+ *  `close` replaces the bridge's own (the bridge holder's, which also forgets the bridge). */
+export function servedBridge(bridge: HeldBridge, close: () => void = () => bridge.close()): DaemonBridge {
+  return {
+    port: bridge.port,
+    isConnected: () => bridge.isConnected(),
+    request: ownUpstream(bridge).request, // a frame's args as they arrived (absent forwarded as absent)
+    close,
+    listClients: () => bridge.listClients(),
+    connectionInfo: () => bridge.connectionInfo(),
+  };
+}
+
+export interface RoutePolicy {
+  /** How long a request waits for a plugin to connect before it is resolved against whatever is there. */
+  connectWaitMs: number;
+  /** The CLI with no daemon: a bridge opened for one command. Spends the window once, up front, and is the
+   *  one case the stall check and the never-connected guard are for. */
+  oneShot: boolean;
+  /** The stall window (one-shot, own bridge, export-class only); FIGMA_BRIDGE_STALL_MS, else 20 s. */
+  stallMs?: number;
+  /** The connect window for a NAMED target (a file name or fileKey, not a connId); `connectWaitMs` when absent.
+   *  The CLI passes none: its `--timeout` is the window for every target, named or not (and server-core's
+   *  awaitClient already caps a name at NAMED_CLIENT_WAIT_MS once a plugin is connected). The MCP server, whose
+   *  connectWaitMs is 0, passes NAMED_CLIENT_WAIT_MS: every open window redials on its own clock, so the file
+   *  asked for may land a moment after another. */
+  namedWaitMs?: number;
+}
+
+export interface RouteRequest {
+  timeoutMs?: number | undefined;
+  target?: string | null | undefined;
+  /** Heard only by an export-class command. */
+  onProgress?: ((tick: ProgressTick) => void) | undefined;
+  signal?: AbortSignal | undefined;
+}
+
+export interface Route {
+  /** Spend the connect window (a one-shot route over its own bridge; otherwise nothing to wait for here) —
+   *  once: later calls answer the first one's result. Requests and listClients call it themselves; a caller
+   *  calls it first only to time the wait. `target` is what that first wait waits for. */
+  connect(target?: string | null): Promise<{ waitedMs: number }>;
+  request<C extends Cmd>(cmd: C, args: Commands[C]["args"], o?: RouteRequest): Promise<Sent<C>>;
+  listClients(): Promise<ClientRow[]>;
+  /** The socket half of whoami for `connId` (the connection a request was answered by), and who holds it. */
+  connectionInfo(connId?: string | null): Promise<RouteConnection>;
+}
+
+/** The window's text for the never-connected guard. */
+const neverConnected = (windowMs: number): Error => new Error(
+  `no Figma plugin connected within ${Math.round(windowMs / 1000)}s. In Figma DESKTOP open the file and run Plugins → Development → Design Twin, then run this again (--timeout <seconds> waits longer; \`dtwin doctor\` says what is wrong if it still won't connect).`,
+);
+
+const stallFromEnv = (): number => Number(process.env.FIGMA_BRIDGE_STALL_MS) || 20000;
+
+/** A route over whatever `upstream` answers (called per use: MCP's sharing layer re-resolves the holder). */
+export function createRoute(upstream: () => Promise<Upstream>, policy: RoutePolicy): Route {
+  const namedWaitMs = policy.namedWaitMs ?? policy.connectWaitMs;
+  const stallMs = policy.stallMs ?? stallFromEnv();
+  let connected: Promise<{ waitedMs: number; everConnected: boolean | null }> | null = null;
+
+  // The connect window a request carries: namedWaitMs for a named file, the policy's own for anything else.
+  const windowFor = (target: string | null | undefined): number => {
+    const named = !!target && !isConnId(target);
+    return named ? namedWaitMs : policy.connectWaitMs;
+  };
+
+  function spend(up: Upstream, target: string | null | undefined) {
+    return (connected ??= (async () => {
+      if (!policy.oneShot || up.kind !== "own") return { waitedMs: 0, everConnected: null };
+      const t0 = Date.now();
+      const r = await up.awaitClient(target, policy.connectWaitMs);
+      return { waitedMs: Date.now() - t0, everConnected: r ? r.everConnected : null };
+    })());
+  }
+
+  return {
+    async connect(target) {
+      const { waitedMs } = await spend(await upstream(), target);
+      return { waitedMs };
+    },
+    async request(cmd, args, o = {}) {
+      const up = await upstream();
+      // The `export` run trait (commands.ts): the commands that walk a tree and can run for minutes.
+      const exportClass = isExportCmd(cmd);
+      // A one-shot route over its own bridge has spent its window up front: a plugin that connected and has
+      // gone since is resolveClient's to report, at once — not another window.
+      const spentUpFront = policy.oneShot && up.kind === "own";
+      if (spentUpFront) {
+        const c = await spend(up, o.target);
+        if (c.everConnected === false) throw neverConnected(policy.connectWaitMs);
+      }
+      return up.request(cmd, args, {
+        timeoutMs: o.timeoutMs,
+        target: o.target,
+        waitMs: spentUpFront ? 0 : windowFor(o.target),
+        stallMs: spentUpFront && exportClass ? stallMs : undefined,
+        onProgress: exportClass ? o.onProgress : undefined,
+        signal: o.signal,
+      });
+    },
+    async listClients() {
+      const up = await upstream();
+      // No plugin within the window is this listing's legitimate "none", not the never-connected error.
+      if (policy.oneShot) await spend(up, null);
+      return up.listClients();
+    },
+    async connectionInfo(connId) {
+      return (await upstream()).connectionInfo(connId);
+    },
+  };
+}

package/src/seed-components.ts

@@ -0,0 +1,229 @@
+#!/usr/bin/env -S bun --no-install --no-env-file
+// seed-components — pre-populate design/components.json from Code Connect files in the codebase.
+//
+// Code Connect files ARE the Figma-component -> code-component mapping you'd otherwise hand-author,
+// and they're plain source files, so reading them is FREE (no MCP, no REST, no paid plan). This turns
+// components.json from fully hand-authored into mostly-generated; you only fill prop maps by hand.
+//
+// It recognizes all three shapes Code Connect uses:
+//   1) Template files (.figma.js/.ts) — `// url=` + `// component=` + `// source=` header comments
+//      (the format the current Figma CLI/MCP emit; gives component + source DIRECTLY, most reliable).
+//   2) Legacy React    — `figma.connect(Component, "https://…node-id=1-2", {…})`.
+//   3) SwiftUI/Compose — `FigmaConnect` with `let component = Button.self` / `component = Button::class`.
+//
+// Usage:
+//   dtwin seed [codeRoot=.] [outDir=design] [--dry-run]              (routed by figma-pull.ts)
+//   bun bridge/src/seed-components.ts [codeRoot=.] [outDir=design] [--dry-run]    (the same, run directly)
+//
+// Merges into design/components.json fill-missing-only (never clobbers hand-authored fields) and, for
+// forms that carry only a node-id, resolves it to the Figma component NAME via the export's design-system.json
+// (design/export/, or design/ itself on the older flat layout).
+
+import fs from "node:fs";
+import path from "node:path";
+import { ID, parseNodeId } from "./node-id.ts";
+import { ifDefined, isRecord, nullProto } from "./json-util.ts";
+import { exportInDesignDir, readComponentCatalog } from "./export-reader.ts";
+import { writeJsonLike } from "./json-file.ts";
+import { exitCli, runCli } from "./stdio.ts";
+import { SEED_HELP } from "./verbs.ts"; // the one help text, shared with `dtwin seed --help`
+
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "out", "vendor", "Pods", ".build"]);
+const CODE_EXT = /\.(tsx?|jsx?|mjs|cjs|swift|kt|kts)$/;
+
+// Hoisted: extractMappings runs once per candidate file and `walk` enumerates the whole repo tree, so
+// building these per call recompiled three regexes thousands of times. Safe to share — every one is
+// driven by a `while ((m = re.exec(text)))` loop that runs until exec returns null, which resets
+// lastIndex to 0.
+const URL_COMMENT_RE = new RegExp("\\/\\/\\s*url=(\\S*node-id=" + ID + "\\S*)", "g");
+const JS_CONNECT_RE = new RegExp("figma\\.connect\\(\\s*([A-Za-z0-9_$.]+)?\\s*,?\\s*[\"'`]([^\"'`]*node-id=" + ID + "[^\"'`]*)[\"'`]", "g");
+const NATIVE_URL_RE = new RegExp("[\"'`]([^\"'`]*node-id=" + ID + "[^\"'`]*)[\"'`]", "g");
+const NATIVE_COMP_RE = /component\s*=\s*([A-Za-z0-9_]+)\s*(?:\.self|::class)/g;
+
+function walk(dir: string, hits: string[]): void {
+  let entries: fs.Dirent[] = [];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) walk(full, hits);
+    } else if (CODE_EXT.test(e.name)) {
+      hits.push(full);
+    }
+  }
+}
+
+/** One Code Connect mapping found in a source file. */
+// `| undefined`: an optional regex capture (JS_CONNECT_RE's identifier) or a `(match || [])[1]` read is
+// assigned straight in; every reader tests these fields for truthiness, so undefined and absent read alike.
+interface Mapping { identifier?: string | undefined; url: string; source?: string | undefined }
+
+// Extract { identifier?, url, source? } mappings from one file's text, across all three shapes.
+function extractMappings(text: string): Mapping[] {
+  const out: Mapping[] = [];
+  const seen = new Set<string>();
+  const push = (o: Mapping) => { if (o.url && !seen.has(o.url)) { seen.add(o.url); out.push(o); } };
+
+  // 1) Template files: header comments. `url=` may be a placeholder (documentUrlSubstitutions),
+  //    so key off node-id, not scheme. component/source are declared right there — no name lookup needed.
+  let m: RegExpExecArray | null;
+  while ((m = URL_COMMENT_RE.exec(text))) {
+    const win = text.slice(Math.max(0, m.index - 600), m.index + 600); // comments cluster together
+    const comp = (win.match(/\/\/\s*component=([^\s]+)/) || [])[1];
+    const src = (win.match(/\/\/\s*source=([^\s]+)/) || [])[1];
+    const url = m[1];
+    if (url === undefined) continue; // cannot happen: group 1 is not optional, so a match always sets it
+    push({ identifier: comp, url, source: src });
+  }
+
+  // 2) Legacy React call form.
+  while ((m = JS_CONNECT_RE.exec(text))) {
+    const url = m[2];
+    if (url === undefined) continue; // cannot happen: group 2 is not optional (group 1, the identifier, is)
+    push({ identifier: m[1], url });
+  }
+
+  // 3) SwiftUI / Compose: the real component is `component = X.self` / `X::class`, NOT the wrapper type.
+  if (/FigmaConnect/.test(text)) {
+    const comps: Array<{ name: string; index: number }> = [];
+    let c: RegExpExecArray | null;
+    while ((c = NATIVE_COMP_RE.exec(text))) {
+      const name = c[1];
+      if (name !== undefined) comps.push({ name, index: c.index }); // always set: group 1 is not optional
+    }
+    while ((m = NATIVE_URL_RE.exec(text))) {
+      // nearest `component = X.self` to this URL; fall back to the enclosing type name.
+      let best: string | undefined, bestD = Infinity;
+      for (const cc of comps) { const d = Math.abs(cc.index - m.index); if (d < bestD) { bestD = d; best = cc.name; } }
+      if (!best) {
+        const before = text.slice(Math.max(0, m.index - 500), m.index);
+        const t = (before.match(/(?:struct|class|object)\s+([A-Za-z0-9_]+)/g) || []).pop();
+        if (t) best = t.split(/\s+/).pop();
+      }
+      const url = m[1];
+      if (url === undefined) continue; // cannot happen: group 1 is not optional
+      push({ ...ifDefined("identifier", best), url });
+    }
+  }
+  return out;
+}
+
+function loadJson(p: string): unknown {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")) as unknown; } catch { return undefined; }
+}
+
+// id -> component name, from an existing export (optional; only needed for Code Connect forms that
+// give a node-id URL but no component identifier).
+//
+// The catalog is export-reader.ts readComponentCatalog's — design-system.json's `files.componentsLocal` pointer (inside
+// the export only), else the inline components[] of an export from before the design-system split — so a node-id-only
+// mapping is never silently dropped because the slim manifest has no `components` of its own (the silent-wrong-answer
+// failure design-to-code/catalog-input.ts exists to prevent). The export is the one the design dir holds (design/export,
+// or design/ itself on the older flat layout). `problem` is why an export that IS there could not be read (none when
+// nothing is exported); only a row whose `id` AND `name` are strings can be a lookup entry.
+function loadIdToName(designDir: string): { idToName: Map<string, string>; problem: string | null } {
+  const idToName = new Map<string, string>();
+  const catalog = readComponentCatalog(exportInDesignDir(designDir));
+  if ("error" in catalog) return { idToName, problem: catalog.missing ? null : catalog.error };
+  for (const c of catalog.components) {
+    if (!isRecord(c)) continue;
+    const { id, name } = c;
+    if (typeof id === "string" && id && typeof name === "string") idToName.set(id, name);
+  }
+  return { idToName, problem: null };
+}
+
+/** One components.json entry (hand-authored or seeded). */
+export interface ComponentsEntry { component?: unknown; source?: unknown; nodeId?: unknown; import?: unknown; props?: unknown }
+
+interface SeedOptions { codeRoot: string; outDir: string; dryRun: boolean }
+
+// argv is everything AFTER the command: `process.argv.slice(2)` when run directly, `argv.slice(1)` of
+// `dtwin seed …`. Positions are unchanged from the original script: [codeRoot=.] [outDir=design], with
+// an empty string falling back to the default exactly as `argv[n] || default` always did. A help probe
+// wins over everything else and has no side effects; an unknown flag is refused instead of being taken
+// as a codeRoot spelled `--something`.
+export function main(argv: string[]): void {
+  if (argv.some((a) => a === "--help" || a === "-h")) {
+    console.log(SEED_HELP);
+    exitCli(0);
+  }
+  let dryRun = false;
+  const positional: string[] = [];
+  for (const a of argv) {
+    if (a === "--dry-run") dryRun = true;
+    else if (a.startsWith("-") && a !== "-") {
+      console.error(`[seed-components] error: unknown flag ${a} — use: dtwin seed [codeRoot] [outDir] [--dry-run]`);
+      exitCli(2);
+    } else positional.push(a);
+  }
+  run({ codeRoot: positional[0] || ".", outDir: positional[1] || "design", dryRun });
+}
+
+function run({ codeRoot, outDir, dryRun }: SeedOptions): void {
+  const { idToName, problem } = loadIdToName(outDir);
+  if (problem) console.error(`[seed-components] warning: ${problem} — node-id-only mappings cannot be named`);
+
+  const files: string[] = [];
+  walk(codeRoot, files);
+
+  const found: Array<{ name: string; identifier: string | undefined; nodeId: string | undefined; source: string }> = [];
+  for (const f of files) {
+    let text = "";
+    try { text = fs.readFileSync(f, "utf8"); } catch { continue; }
+    // Gate: a Code Connect signal of any kind — a node-id URL, the call form, or the native marker.
+    if (text.indexOf("node-id=") === -1 && text.indexOf("figma.connect") === -1 && text.indexOf("FigmaConnect") === -1) continue;
+    for (const mp of extractMappings(text)) {
+      const nodeId = parseNodeId(mp.url);
+      const name = (nodeId && idToName.get(nodeId)) || mp.identifier;
+      if (!name) continue;
+      found.push({ name, identifier: mp.identifier, nodeId, source: mp.source || path.relative(codeRoot, f) });
+    }
+  }
+
+  if (!found.length) {
+    console.error("[seed-components] no Code Connect mappings found under " + path.resolve(codeRoot) + ".");
+    console.error("[seed-components] (looked for `// url=`+`// component=` templates, `figma.connect(...)`, and `@FigmaConnect`.)");
+    exitCli(0);
+  }
+
+  const outPath = path.join(outDir, "components.json");
+  // Null-prototype: this map is keyed by UNTRUSTED component names. On a plain object a component
+  // named "__proto__" (or "constructor"/"toString") resolves to an inherited Object.prototype member,
+  // so the entry looks like it already exists — it is silently dropped from components.json AND the
+  // `cur.x = ...` backfills below land on Object.prototype, after which every OTHER entry's
+  // `=== undefined` check is false and its source/nodeId are never filled either. Object.assign onto
+  // a null-prototype target turns those names back into ordinary own keys. JSON.stringify is unaffected.
+  const existing: Record<string, ComponentsEntry | undefined> = Object.assign(nullProto<ComponentsEntry | undefined>(), loadJson(outPath) || {});
+  let added = 0, filled = 0;
+  for (const m of found) {
+    const cur = existing[m.name];
+    if (!cur) {
+      existing[m.name] = {
+        component: m.identifier || m.name,
+        source: m.source,
+        nodeId: m.nodeId,
+        import: "", // yours to fill — codegen reuses the component once you do
+        props: {},
+      };
+      added++;
+    } else {
+      if (cur.source === undefined) { cur.source = m.source; filled++; }
+      if (cur.nodeId === undefined && m.nodeId) { cur.nodeId = m.nodeId; filled++; }
+      if (cur.component === undefined) cur.component = m.identifier || m.name;
+    }
+  }
+
+  // --dry-run: everything above only READ; the merge result is computed in memory and dropped here.
+  const dry = dryRun ? "(dry run, nothing written) " : "";
+  if (!dryRun) {
+    writeJsonLike(outPath, existing); // a person's hand-edited map: atomic, in its own format
+  }
+  console.error(`[seed-components] ${dry}${found.length} mapping(s) from ${files.length} scanned file(s) → ${outPath}`);
+  console.error(`[seed-components] ${dry}${added} new entr(ies), ${filled} field(s) filled. Fill in each entry's "import" and "props".`);
+  if (!idToName.size && !problem) console.error("[seed-components] tip: export design-system.json first so node-id-only mappings resolve to real component names.");
+}
+
+// Only when RUN directly (it is a CLI, driven by the tests as a subprocess). `dtwin seed` imports this
+// module and calls main() itself, so the guard is what keeps that import from also scanning the tree.
+if (import.meta.main) runCli((argv) => { main(argv); return Number(process.exitCode ?? 0); }, { name: "[seed-components] error" });