@design-twin/dtwin 0.0.0-stage → 0.1.0

package/src/init.ts

@@ -0,0 +1,424 @@
+// `dtwin init` — one command to set a PROJECT up for Design Twin, run from that project's root.
+//
+// Before this, onboarding was eleven manual steps across four docs: create design/, hand-write
+// target.json, find the bridge token, hand-write a .mcp.json with an absolute path, remember the two
+// `claude plugin` commands. Each is small; together they are where a new user gives up. init does
+// every one that can be done from a terminal and PRINTS the two that cannot (importing the plugin
+// into Figma and pasting the token are clicks in Figma's UI — nothing can do them for you).
+//
+// Rules it keeps:
+//   - Never overwrites. Every file it would write is skipped, and said so, if it already exists;
+//     .mcp.json is MERGED (an existing "figma" entry is left exactly as it is). The one exception is
+//     an entry of OURS that can no longer start (mcpEntryProblems: a bun or figma-mcp.ts that is gone,
+//     a Node-era `node …/dist/figma-mcp.js`, bun without its two flags, a `bunx @design-twin/dtwin mcp` that fetches the
+//     package at start-up): --mcp re-points that entry, under
+//     its own key and keeping its other fields, at this install — and says so (--dry-run only says so).
+//   - Needs no bridge, no plugin, no port: it only touches the project directory and the per-user
+//     token file, so it works while a daemon or the MCP server holds 8787.
+//   - The MCP registration is opt-in (--mcp): the MCP server binds the same port as the CLI, so a
+//     project that registers it cannot run one-shot `dtwin` pulls while Claude Code is open —
+//     a trade-off the user should choose, not inherit from a setup command.
+//
+//   dtwin init            # design/, design/target.json (detected stack), bridge token, next steps
+//   dtwin init --mcp      # …and register the MCP server in ./.mcp.json
+//   dtwin init --dry-run  # say what it would do, write nothing
+
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import * as tokenStore from "./token-store.ts";
+import type { ResolvedToken } from "./token-store.ts";
+import * as LAYOUT from "./project-layout.ts";
+import { ifDefined, isRecord } from "./json-util.ts";
+import { exitCli } from "./stdio.ts";
+
+/** One .mcp.json server entry, as init writes it. */
+export interface McpEntry {
+  command: string;
+  args: string[];
+}
+
+/** The part of .mcp.json init (and doctor) reads: `mcpServers`, when present, must be an object. A
+ *  `null`, array or string there would crash init or be spread character-by-character into the
+ *  rewritten file. Loose: every other key passes the check and is carried through untouched. */
+// A JSON value's kind, for a message a person reads ("not a string", not zod's "received string").
+const jsonKind = (x: unknown): string => (x === null ? "null" : Array.isArray(x) ? "an array" : typeof x === "object" ? "an object" : "a " + typeof x);
+const McpJsonSchema = z.looseObject(
+  { mcpServers: z.record(z.string(), z.unknown(), { error: (iss) => `\`mcpServers\` must be an object of server entries, not ${jsonKind(iss.input)}` }).optional() },
+  { error: (iss) => `must be a JSON object, not ${jsonKind(iss.input)}` },
+);
+
+/** Check a parsed .mcp.json. On success, `doc` and `servers` are the user's OWN objects, not zod's
+ *  copies: zod moves the keys it knows to the front and drops a key named "__proto__", and init
+ *  rewrites this file — it must keep its key order and every entry. `error` is one line. */
+function readMcpJson(raw: unknown): { doc: Record<string, unknown>; servers: Record<string, unknown> } | { error: string } {
+  const r = McpJsonSchema.safeParse(raw);
+  if (!r.success || !isRecord(raw)) return { error: r.success ? "must be a JSON object" : r.error.issues.map((i) => i.message).join("; ") };
+  return { doc: raw, servers: isRecord(raw.mcpServers) ? raw.mcpServers : {} };
+}
+
+/** One step of init's plan (see `plan`), discriminated on `kind`: the file-touching kinds carry their
+ *  `path`, "write" its `content` (and `merge` for the one write allowed onto an existing file). */
+export type InitAction =
+  | { kind: "skip"; path: string; note: string }
+  | { kind: "mkdir"; path: string; note: string }
+  | { kind: "write"; path: string; content: string; merge?: boolean; note: string }
+  | { kind: "note"; note: string }
+  | { kind: "token"; note: string };
+
+export interface PlanOptions {
+  mcp?: boolean;
+  mcpEntry?: McpEntry;
+  /** Why no entry may be written from this install (bunxRefusal), or absent. */
+  refuseMcp?: string;
+  /** How entries already in .mcp.json are looked at (mcpEntryProblems). */
+  probe?: EntryProbe;
+  /** The resolved bridge token (token-store resolve()) — only its source/path/created are read. */
+  token: Pick<ResolvedToken, "source" | "path" | "created">;
+}
+
+// The profiles build-screen ships. Named in target.json when detection finds nothing, so the user can
+// fill it in without going to look for the list.
+export const PROFILES = ["web-tailwind", "web-css-modules", "react-native", "swiftui", "android-compose", "flutter"];
+
+// The key the MCP server is registered under in .mcp.json — matches the server's own name
+// (bridge/src/figma-mcp.ts), so its tools surface as mcp__designtwin__figma_status etc.
+const MCP_KEY = "designtwin";
+
+// Is this .mcp.json entry Design Twin's server, under ANY key? It points at figma-mcp.{ts,js} (what
+// init writes: bridge/src/figma-mcp.ts — or the bridge/dist/figma-mcp.js / .mjs / .mts an older init
+// wrote), or runs `@design-twin/dtwin mcp` (the npx/bunx form — ours, but one init repairs; `designtwin` is the package's
+// name before it moved under the npm org). One rule for init (don't double-register) and doctor (report it).
+const PACKAGE_NAMES: readonly string[] = ["@design-twin/dtwin", "designtwin"];
+const isOurMcpEntry = (e: unknown): boolean => {
+  // Untyped JSON from the user's .mcp.json: only an object can carry `args` (JSON has no other shape that does).
+  const args: unknown = e && typeof e === "object" ? (e as { args?: unknown }).args : undefined;
+  return !!e && Array.isArray(args) && (args.some((a) => FIGMA_MCP_SCRIPT.test(String(a))) || (args.some((a) => PACKAGE_NAMES.includes(String(a))) && args.includes("mcp")));
+};
+const FIGMA_MCP_SCRIPT = /(^|[\\/])figma-mcp\.(mjs|mts|ts|js)$/;
+
+// The flags every user-facing bun invocation carries (the bin shebang's): no auto-install from the registry, and the
+// project's .env stays out of the server's environment.
+const BUN_FLAGS = ["--no-install", "--no-env-file"] as const;
+
+/** The bun to name in .mcp.json: the one on PATH (Bun.which) when it IS the bun running now — a stable spelling such as
+ *  ~/.bun/bin/bun or Homebrew's /opt/homebrew/bin/bun, which survives an upgrade — else this process's own executable.
+ *  process.execPath alone is the resolved file, and for a Homebrew (or any versioned) install that is a versioned path
+ *  (…/Cellar/bun/1.4.2/bin/bun) the next `brew upgrade` deletes, leaving Claude Code a server it cannot start. */
+function stableBunPath(execPath: string = process.execPath, onPath: string | null = Bun.which("bun")): string {
+  if (!onPath) return execPath;
+  try { return fs.realpathSync(onPath) === fs.realpathSync(execPath) ? onPath : execPath; } catch { return execPath; }
+}
+
+/** The bunx cache directory `dir` sits in, or null. `bunx @design-twin/dtwin …` installs the package into a cache tree
+ *  (`<tmp or install cache>/.bunx-<uid>/<pkg>`, `<tmp>/bunx-<uid>-<pkg>` on Windows and older Bun) that Bun refreshes
+ *  and deletes on its own schedule, so a .mcp.json path into it is a server that one day does not start. */
+function bunxCacheOf(dir: string): string | null {
+  const m = /^(.*?[\\/]\.?bunx-[^\\/]+)(?:[\\/]|$)/.exec(dir);
+  return m?.[1] ?? null;
+}
+const bunxRefusal = (cache: string): string =>
+  `this dtwin runs from a bunx cache (${cache}) that Bun replaces or deletes on its own — a .mcp.json entry pointing into it would stop starting one day. ` +
+  "Install it for good (`bun add -g @design-twin/dtwin`, or in a clone: `bun install`, then `cd bridge && bun link`), and run `dtwin init --mcp` from that install";
+
+/** How to look at the machine (seams for the suites): does a path exist, and what does a bare command resolve to. */
+export interface EntryProbe {
+  exists?: (p: string) => boolean;
+  which?: (cmd: string) => string | null;
+  /** Where a relative path in the entry resolves from (Claude Code starts the server in the project root). */
+  cwd?: string;
+}
+
+/** What is wrong with an .mcp.json entry of OURS (isOurMcpEntry), one phrase each — empty when it will start: its command
+ *  exists, it runs on Bun (not Node, not the old bridge/dist build), it names a server script (not a package bunx would
+ *  fetch), that script exists outside a bunx cache, and bun gets the two flags before that script. The ONE rule for init (repair it) and doctor (report it). */
+function mcpEntryProblems(e: unknown, { exists = fs.existsSync, which = (c) => Bun.which(c), cwd = process.cwd() }: EntryProbe = {}): string[] {
+  if (!isRecord(e) || typeof e.command !== "string" || e.command === "") return ["it has no `command`"];
+  const command = e.command;
+  const args = Array.isArray(e.args) ? e.args.map(String) : [];
+  const out: string[] = [];
+  const base = path.basename(command).toLowerCase().replace(/\.(exe|cmd|bat)$/, "");
+  const nodeShaped = ["node", "nodejs", "npx", "npm"].includes(base);
+  if (nodeShaped) out.push(`it runs on Node (\`${command}\`) — Design Twin runs on Bun only`);
+  const found = /[\\/]/.test(command) ? exists(path.resolve(cwd, command)) : which(command) !== null;
+  if (!found) out.push(`its command \`${command}\` ${/[\\/]/.test(command) ? "does not exist" : "is not on PATH"}`);
+  const i = args.findIndex((a) => FIGMA_MCP_SCRIPT.test(a));
+  const script = args[i];
+  // No server script: the package-runner form (`bunx @design-twin/dtwin mcp`, `bun x @design-twin/dtwin mcp`, an older `npx designtwin
+  // mcp`). It names a package, not this install: bunx fetches it from the registry at start-up (network, unpinned, outside
+  // any lockfile) and, with or without --no-install, may run whatever copy sits in its own cache — the one Bun replaces or
+  // deletes on its own. That is the ephemeral registration init refuses to write, so it is one to repair, not to keep.
+  if (script === undefined) {
+    out.push(`it runs the server by package name (\`${[command, ...args].join(" ")}\`) — bunx fetches that from the registry, or a bunx cache Bun replaces or deletes on its own, at every start`);
+    return out;
+  }
+  const abs = path.resolve(cwd, script);
+  // figma-mcp.js / .mjs (bridge/dist, or the older bridge/figma-mcp.mjs) is the Node-era build: the package ships .ts now
+  if (/\.m?js$/.test(script)) out.push(`it points at the old Node build (${script})`);
+  else if (!exists(abs)) out.push(`its server script ${script} does not exist`);
+  const cache = bunxCacheOf(abs);
+  if (cache) out.push(`its server script is in a bunx cache (${cache}) that Bun replaces or deletes on its own`);
+  if (!nodeShaped) {
+    if (base !== "bun") out.push(`it does not run the server with bun (\`${command}\`)`);
+    else {
+      const missing = BUN_FLAGS.filter((f) => { const at = args.indexOf(f); return at < 0 || at > i; });
+      if (missing.length) out.push(`bun runs it without ${missing.join(" and ")} (a project's .env would reach the server, and a missing import would be fetched from the registry)`);
+    }
+  }
+  return out;
+}
+
+// Does package.json list vite in dependencies or devDependencies?
+function usesVite(cwd: string): boolean {
+  let raw: unknown;
+  try { raw = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")) as unknown; } catch { return false; }
+  return isRecord(raw) && [raw.dependencies, raw.devDependencies].filter(isRecord).some((d) => "vite" in d);
+}
+
+// Does package.json list Tailwind v4 (tailwindcss not pinned to v3, or its v4-only Vite/PostCSS plugin) in dependencies or devDependencies?
+function usesTailwind(cwd: string): boolean {
+  let raw: unknown;
+  try { raw = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")) as unknown; } catch { return false; }
+  if (!isRecord(raw)) return false;
+  const deps = [raw.dependencies, raw.devDependencies].filter(isRecord);
+  // @tailwindcss/vite and @tailwindcss/postcss exist only for v4. `tailwindcss` itself counts unless its
+  // range is clearly v3 (^3 / ~3 / 3.x / >=3 <4): v3 scans only its `content` globs, so the note would be wrong.
+  if (deps.some((d) => "@tailwindcss/vite" in d || "@tailwindcss/postcss" in d)) return true;
+  const range = deps.map((d) => d.tailwindcss).find((v) => v !== undefined);
+  if (range === undefined) return false;
+  // Each `||` alternative on its own: "^3.0.0 || ^4.0.0" allows v4, so it still gets the note.
+  const isV3 = (r: string): boolean => /^\s*(?:[\^~]|>=?\s*)?v?3(?:$|[.\s<x*])/.test(r) && (!/^\s*>/.test(r) || /<\s*v?4/.test(r)); // ">=3" alone may be v4
+  return !(typeof range === "string" && range.split("||").every(isV3));
+}
+
+// Same detection order build-screen's step 0 documents — first match wins, most specific first.
+function detectProfile(cwd: string): { profile: string; because: string } | null {
+  const has = (f: string) => fs.existsSync(path.join(cwd, f));
+  const read = (f: string): string => { try { return fs.readFileSync(path.join(cwd, f), "utf8"); } catch { return ""; } };
+  const ls: string[] = (() => { try { return fs.readdirSync(cwd); } catch { return []; } })();
+  type PackageJson = { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
+  let pkg: PackageJson | null = null;
+  try { pkg = JSON.parse(read("package.json")) as PackageJson; } catch { /* no/invalid package.json */ }
+  if (pkg) {
+    const deps: Record<string, string | undefined> = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (deps["react-native"] || deps.expo) return { profile: "react-native", because: "react-native/expo in package.json" };
+    if (deps.tailwindcss || deps["@tailwindcss/vite"] || deps["@tailwindcss/postcss"]) return { profile: "web-tailwind", because: "tailwindcss in package.json" };
+  }
+  if (has("pubspec.yaml") && /^\s*flutter\s*:/m.test(read("pubspec.yaml"))) return { profile: "flutter", because: "flutter in pubspec.yaml" };
+  if (has("Package.swift") || ls.some((f) => f.endsWith(".xcodeproj") || f.endsWith(".xcworkspace"))) return { profile: "swiftui", because: "an Xcode project / Package.swift" };
+  for (const g of ["build.gradle.kts", "build.gradle", "app/build.gradle.kts", "app/build.gradle"]) {
+    if (/compose/i.test(read(g))) return { profile: "android-compose", because: "Compose in " + g };
+  }
+  if (pkg) return { profile: "web-css-modules", because: "a package.json with no Tailwind/React Native (the generic web profile)" };
+  return null;
+}
+
+// Pure planner: what init WOULD do in `cwd`. Returns { actions:[{kind, path?, content?, note}], steps:[…] }.
+// Split from the writer so the test suite can assert the plan without touching a real HOME.
+function plan(cwd: string, { mcp = false, mcpEntry, refuseMcp, probe, token }: PlanOptions): InitAction[] {
+  const actions: InitAction[] = [];
+  const rel = (p: string) => path.relative(cwd, p) || ".";
+
+  const designDir = path.join(cwd, LAYOUT.DESIGN_DIR);
+  actions.push(fs.existsSync(designDir) ? { kind: "skip", path: rel(designDir), note: "exists" } : { kind: "mkdir", path: rel(designDir), note: "your decisions live here" });
+
+  // design/export/ is created up front, empty, precisely so the split is visible BEFORE the first
+  // pull rather than discovered after one. dtwin writes only here.
+  const exportDir = path.join(cwd, LAYOUT.EXPORT_DIR);
+  actions.push(fs.existsSync(exportDir) ? { kind: "skip", path: rel(exportDir), note: "exists" } : { kind: "mkdir", path: rel(exportDir), note: "where every pull lands — safe to delete and re-pull" });
+
+  // The README is the only thing that can tell a future reader which half of design/ a re-pull is
+  // allowed to destroy. A comment in our source cannot; a directory name alone only hints.
+  const readme = path.join(designDir, "README.md");
+  if (fs.existsSync(readme)) actions.push({ kind: "skip", path: rel(readme), note: "exists — left as is" });
+  else actions.push({ kind: "write", path: rel(readme), content: LAYOUT.README, note: "what dtwin owns vs what you own" });
+
+  // target.json is written ALWAYS, even when no stack could be detected.
+  //
+  // Skipping it in that case would make `dtwin init --help`'s own promise ("Creates design/
+  // and design/target.json") false, and leave every later step reading a file that is simply not there
+  // — the verify skill's step 1 `cat`s it and would move on in silence. A file that
+  // says "nobody has decided yet" is a far better artifact than an absent one: build-screen can fill
+  // it in, and everything downstream has one place to look.
+  const targetFile = path.join(cwd, LAYOUT.TARGET_FILE);
+  if (fs.existsSync(targetFile)) actions.push({ kind: "skip", path: rel(targetFile), note: "exists — left as is" });
+  else {
+    const d = detectProfile(cwd);
+    const doc = d
+      ? { profile: d.profile, detectedFrom: d.because }
+      : { profile: null, note: "No stack was detected in this directory. build-screen asks on its first run and writes the answer here; audit-design reads it to pick touch-target minimums. Set it by hand if you already know: one of " + PROFILES.join(", ") + "." };
+    actions.push({
+      kind: "write",
+      path: rel(targetFile),
+      content: JSON.stringify(doc, null, 2) + "\n",
+      note: d ? `stack detected: ${d.profile} (${d.because})` : "no stack detected here — written with profile:null so build-screen has somewhere to record the answer",
+    });
+  }
+
+  // design/ holds regenerable exports AND hand-owned decisions; only the second kind is lost forever.
+  // Say so where the user will see it, rather than editing their .gitignore for them.
+  const gi = path.join(cwd, ".gitignore");
+  const ignored = fs.existsSync(gi) && /^\/?design\/?\s*$/m.test(fs.readFileSync(gi, "utf8"));
+  if (ignored) actions.push({ kind: "note", note: ".gitignore ignores design/ — target.json, codeconnect.local.json, plan/ and audit/ under it are hand-authored and are NOT regenerable. Ignore only the export: replace `design/` with `design/export/`" });
+
+  // Suggest only: a Tailwind project would otherwise compile class names quoted in design/.
+  const tailwind = usesTailwind(cwd);
+  if (tailwind) actions.push({ kind: "note", note: LAYOUT.TAILWIND_SOURCE_NOT_NOTE });
+
+  // Suggest only: with Tailwind v4 scanning design/, a rewrite there makes Vite reload the open page
+  // (proven only for vite + Tailwind v4 — see VITE_WATCH_IGNORED_NOTE for why vite alone gets no note).
+  if (tailwind && usesVite(cwd)) actions.push({ kind: "note", note: LAYOUT.VITE_WATCH_IGNORED_NOTE });
+  // design/verify/ already ignored — any spelling: design/verify, /design/verify/, design/verify/**, design/verify/*
+  // (or the whole design/ tree, which the note above already warns about)
+  const verifyIgnored = /^\/?design(?:\/verify)?(?:\/(?:\*\*?)?)?\s*$/m.test(fs.existsSync(gi) ? fs.readFileSync(gi, "utf8") : "");
+  if (!verifyIgnored) actions.push({ kind: "note", note: LAYOUT.VERIFY_GITIGNORE_NOTE });
+
+  if (mcp) {
+    const file = path.join(cwd, ".mcp.json");
+    let doc: object = {};
+    let servers: Record<string, unknown> = {};
+    let bad: string | null = null;
+    if (fs.existsSync(file)) {
+      let raw: unknown;
+      try { raw = JSON.parse(fs.readFileSync(file, "utf8")) as unknown; } catch { bad = "exists but is not valid JSON"; }
+      if (bad === null) {
+        const r = readMcpJson(raw);
+        if ("error" in r) bad = r.error;
+        else { doc = r.doc; servers = r.servers; }
+      }
+    }
+    if (bad !== null) actions.push({ kind: "skip", path: rel(file), note: bad + " — fix it, then re-run with --mcp" });
+    else {
+      // Registered as "designtwin", never "figma": that is the name Figma's own MCP server is usually
+      // given, and Claude Code loads only one server per name — sharing it would silently drop one.
+      // Ours under ANY key (older inits wrote "figma"): a second entry would start a second server
+      // and the two would fight over port 8787.
+      const mine = Object.keys(servers).find((k) => isOurMcpEntry(servers[k]));
+      // Ours, but it cannot start: a bun or a figma-mcp.ts that has since moved (a deleted clone, a Homebrew upgrade, a
+      // bunx cache Bun cleaned), a Node-era entry (`node …/bridge/dist/figma-mcp.js`), or one that starts only as long
+      // as bunx can fetch the package (`bunx @design-twin/dtwin mcp`). Left as is, Claude Code would
+      // show a failed server and no tools; the one write that fixes it is re-pointing THAT entry, under its own key, at
+      // this install. Every other field the user put on it (env, …) is kept.
+      const broken = mine === undefined ? [] : mcpEntryProblems(servers[mine], { cwd, ...probe });
+      const old = mine === undefined ? undefined : servers[mine];
+      if (mine !== undefined && broken.length && refuseMcp) actions.push({ kind: "skip", path: rel(file), note: `the "${mine}" entry needs repair (${broken.join("; ")}), but ${refuseMcp}` });
+      else if (mine !== undefined && broken.length && mcpEntry && isRecord(old)) {
+        const next = { ...doc, mcpServers: { ...servers, [mine]: { ...old, command: mcpEntry.command, args: mcpEntry.args } } };
+        actions.push({ kind: "write", merge: true, path: rel(file), content: JSON.stringify(next, null, 2) + "\n", note: `REPAIRED the "${mine}" MCP server entry — ${broken.join("; ")}. It now runs ${[mcpEntry.command, ...mcpEntry.args].join(" ")} (restart Claude Code to pick it up)` });
+      }
+      else if (mine) actions.push({ kind: "skip", path: rel(file), note: `Design Twin's MCP server is already registered as "${mine}" — left as is${broken.length ? ` (it needs repair: ${broken.join("; ")})` : ""}` });
+      else if (servers[MCP_KEY]) actions.push({ kind: "skip", path: rel(file), note: `already has a "${MCP_KEY}" server that is not Design Twin's — left as is` });
+      else if (refuseMcp) actions.push({ kind: "skip", path: rel(file), note: `not registered: ${refuseMcp}` });
+      else {
+        const next = { ...doc, mcpServers: { ...servers, [MCP_KEY]: mcpEntry } };
+        // merge:true — the ONE write allowed onto an existing file: it re-serialises the user's own
+        // document with one key added. Everything else is written with "wx" and cannot clobber.
+        actions.push({ kind: "write", merge: fs.existsSync(file), path: rel(file), content: JSON.stringify(next, null, 2) + "\n", note: `registered the "${MCP_KEY}" MCP server (enable it with /mcp, then restart Claude Code). While it runs it holds port 8787 — use its writeToDisk:true instead of one-shot dtwin pulls` });
+      }
+    }
+  }
+
+  actions.push({ kind: "token", note: token.created ? `bridge token created (${token.path})` : token.source === "env" ? "bridge token: using FIGMA_BRIDGE_TOKEN from the environment" : token.source === "ephemeral" ? "bridge token could NOT be saved (read-only config dir?) — it will change every run" : `bridge token already saved (${token.path})` });
+  return actions;
+}
+
+function apply(cwd: string, actions: InitAction[], log: (m: string) => void): void {
+  for (const a of actions) {
+    if (a.kind === "mkdir") fs.mkdirSync(path.join(cwd, a.path), { recursive: true });
+    if (a.kind === "write") { fs.mkdirSync(path.dirname(path.join(cwd, a.path)), { recursive: true }); fs.writeFileSync(path.join(cwd, a.path), a.content, { flag: a.merge ? "w" : "wx" }); }
+    const tag = a.kind === "write" ? "wrote " : a.kind === "mkdir" ? "created" : a.kind === "skip" ? "skipped" : a.kind === "note" ? "note   " : "token  ";
+    log(`${tag} ${"path" in a ? a.path + " — " : ""}${a.note}`);
+  }
+}
+
+function main(argv: string[]): void {
+  const known = ["--mcp", "--dry-run", "--help", "-h"];
+  const bad = argv.filter((a) => !known.includes(a));
+  if (bad.length) { console.error(`[dtwin init] error: unknown argument${bad.length > 1 ? "s" : ""}: ${bad.join(", ")}. Usage: dtwin init [--mcp] [--dry-run]`); exitCli(1); }
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(
+      "dtwin init [--mcp] [--dry-run]\n\n" +
+      "  Run in the root of the project you are BUILDING. Creates exactly these four things:\n" +
+      "    design/                  the directory your decisions live under\n" +
+      "    design/export/           where every dtwin pull lands, empty at first — safe to delete and re-pull\n" +
+      "    design/README.md         which half of design/ a re-pull is allowed to destroy\n" +
+      "    design/target.json       the detected stack, or profile:null for build-screen to fill in\n" +
+      "  It does NOT create codeconnect.local.json, plan/, audit/ or verify/ — those are written later,\n" +
+      "  on demand, by map-bootstrap.ts, build-screen, audit-design and verify respectively.\n" +
+      "  …makes sure a bridge token exists, and prints the remaining steps.\n\n" +
+      "  --mcp      also register the Design Twin MCP server in ./.mcp.json (merged, never overwritten;\n" +
+      "             an entry of ours that can no longer start — a moved bun or figma-mcp.ts, a Node-era\n" +
+      "             entry — is repaired in place, and the output says so)\n" +
+      "  --dry-run  print what would happen; write nothing (no token is created either)\n\n" +
+      "  Never overwrites an existing file."
+    );
+    exitCli(0);
+  }
+  const dry = argv.includes("--dry-run");
+  const cwd = process.cwd();
+  const log = (m: string) => console.error("[dtwin init] " + (dry ? "(dry run) " : "") + m);
+
+  const token = tokenStore.resolve({ persist: !dry });
+  // Absolute paths to THIS install's server and to the bun running it now: works for a repo clone and a
+  // global install alike, and needs no network at Claude Code start-up (unlike `bunx @design-twin/dtwin mcp`).
+  // The server is the figma-mcp.ts that sits beside THIS file (a checkout and an install both carry the
+  // source; there is no build). The command is an absolute bun, not "bun": Claude Code starts the server
+  // with ITS environment, whose PATH may not have the ~/.bun/bin a shell profile adds — and the bun that
+  // ran init is one this package is known to work with, spelt the way that survives its upgrades
+  // (stableBunPath). The flags are the shebang's (figma-pull.ts): no auto-install from the network, and
+  // the project's .env stays out of the server's environment.
+  const mcpEntry: McpEntry = { command: stableBunPath(), args: [...BUN_FLAGS, path.join(import.meta.dirname, "figma-mcp.ts")] };
+  // Run through `bunx @design-twin/dtwin init`: this very file is in bunx's cache, so no entry may point at it.
+  const cache = bunxCacheOf(import.meta.dirname);
+  const refuseMcp = cache ? bunxRefusal(cache) : undefined;
+  if (cache && !argv.includes("--mcp")) log(`note    this dtwin runs from a bunx cache (${cache}) — install it for good (\`bun add -g @design-twin/dtwin\`, or in a clone: \`bun install\`, then \`cd bridge && bun link\`) to have \`dtwin\` on PATH and to register the MCP server`);
+  const actions = plan(cwd, { mcp: argv.includes("--mcp"), mcpEntry, ...ifDefined("refuseMcp", refuseMcp), token });
+  if (dry) for (const a of actions) log(`${a.kind === "write" ? "would write" : a.kind === "mkdir" ? "would create" : a.kind} ${"path" in a ? a.path + " — " : ""}${a.note}`);
+  else apply(cwd, actions, log);
+
+  // The Figma plugin's manifest: a repo checkout's (bridge/src/ -> ../../figma-plugin/), else the copy the npm
+  // package carries (../figma-plugin/, put there by bridge/pack.ts). Neither: the step names the repo instead.
+  const manifest = [path.join(import.meta.dirname, "..", "..", "figma-plugin", "manifest.json"), path.join(import.meta.dirname, "..", "figma-plugin", "manifest.json")].find((m) => fs.existsSync(m));
+  // Step 3 is already done for anyone who reached init THROUGH the installed plugin's help skill —
+  // which is the documented path. Claude Code records installed plugins under ~/.claude; when the
+  // marker is there, saying "install the plugin" is noise at best and confusing at worst.
+  const pluginInstalled = (() => {
+    const home = process.env.HOME || process.env.USERPROFILE;
+    if (!home) return false;
+    const root = path.join(home, ".claude", "plugins");
+    // installed_plugins.json is the authoritative record; the per-plugin directories under data/ and
+    // repos/ are the fallback for older layouts. Any of them naming designtwin means step 3 is done.
+    try {
+      if (/designtwin/i.test(fs.readFileSync(path.join(root, "installed_plugins.json"), "utf8"))) return true;
+    } catch { /* absent — try the directories */ }
+    for (const p of ["data", "repos", "marketplaces", "."]) {
+      try {
+        if (fs.readdirSync(path.join(root, p)).some((d) => /designtwin/i.test(d))) return true;
+      } catch { /* not there — fall through */ }
+    }
+    return false;
+  })();
+
+  const steps = [
+    "In Figma DESKTOP: Plugins → Development → Import plugin from manifest… → " + (manifest ?? "figma-plugin/manifest.json from a clone of the Design Twin repo (this install does not include it)"),
+    "Run the plugin (Plugins → Development → Design Twin), paste the bridge token into its \"Bridge token\" field, Save:  dtwin --show-token | pbcopy",
+  ];
+  if (!pluginInstalled) {
+    steps.push("In Claude Code, once:  claude plugin marketplace add <path-or-repo of Design Twin>  then  claude plugin install designtwin@designtwin-marketplace");
+  }
+  steps.push(
+    "Then, with the Figma file open and the plugin running:  dtwin list   →  /designtwin:extract  →  /designtwin:audit-design <screen>  →  /designtwin:build-screen <screen>"
+  );
+  console.log("\nNext — the steps only you can do:\n" + steps.map((s, i) => `  ${i + 1}. ${s}`).join("\n"));
+  // The one refusal a first command reliably hits. doctor names it after the fact; saying it here, in
+  // the output whose whole job is "the steps left", is what stops `dtwin list` failing on step 4
+  // for anyone with two Figma files open.
+  console.log(
+    "\n  If more than one Figma file is connected, every command needs to say which:\n" +
+    "    dtwin list clients                 # the address book\n" +
+    "    dtwin list --client <part of the file name>\n" +
+    "  `dtwin doctor` tells you how many are connected and lists them.\n"
+  );
+}
+
+export { detectProfile, plan, apply, main, isOurMcpEntry, mcpEntryProblems, stableBunPath, bunxCacheOf, readMcpJson, usesTailwind, usesVite };

package/src/instance-overrides.ts

@@ -0,0 +1,7 @@
+// The length an INSTANCE's `overrides` list is cut to. The plugin (components.ts instanceOverrides)
+// keeps the first OVERRIDE_CAP entries and warns; a consumer that sees a list this long cannot know
+// what was cut, so it treats the list as possibly incomplete (asset-owners.ts, design-to-code's
+// audit). Defined once because the consumers infer truncation from the producer's cap: two copies
+// that drift apart would read a cut list as complete. ES2019-safe and import-free: the plugin
+// bundles it.
+export const OVERRIDE_CAP = 100;

package/src/json-file.ts

@@ -0,0 +1,79 @@
+// The writer for JSON files a person also edits (plans, the component map): atomic, and in the file's own format.
+// Shared by bridge/ and design-to-code/ (the layer may import bridge/src; bridge cannot import the layer).
+import fs from "node:fs";
+import { writeFileAtomic } from "./atomic-write.ts";
+import { errCode } from "./errmsg.ts";
+import { acquireFileLock, lockFileOf } from "./file-lock.ts";
+import type { FileLockOpts, HeldLock } from "./file-lock.ts";
+
+// The file's own indentation: the first indented line's leading whitespace (2 spaces when the file has none).
+const indentOf = (text: string): string => /\n([ \t]+)\S/.exec(text)?.[1] ?? "  ";
+
+/** `value` as the text of the file it replaces — that file's BOM, indentation, line endings and final newline.
+ *  `raw` is the file as read; null (no file yet) → 2 spaces, LF, a final newline. */
+export function formatJsonLike(value: unknown, raw: string | null): string {
+  if (raw === null) return JSON.stringify(value, null, 2) + "\n";
+  const bom = raw.charCodeAt(0) === 0xfeff ? "\ufeff" : "";
+  const text = raw.slice(bom.length);
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  return bom + JSON.stringify(value, null, indentOf(text)).split("\n").join(eol) + (/\n$/.test(text) ? eol : "");
+}
+
+/** Formats `value` like the file (formatJsonLike over `raw`, else the file as it is on disk now) and writes it
+ *  atomically — a tmp file beside it, then a rename, so a kill mid-write leaves the old file whole — only when the
+ *  bytes change. True when written. */
+export function writeJsonLike(file: string, value: unknown, raw?: string | null): boolean {
+  let was: string | null = raw ?? null;
+  if (raw === undefined) try { was = fs.readFileSync(file, "utf8"); } catch { was = null; }
+  const out = formatJsonLike(value, was);
+  if (out === was) return false;
+  writeFileAtomic(file, out);
+  return true;
+}
+
+/** How often updateJsonLike starts over when the file changed under it. */
+const UPDATE_TRIES = 3;
+const readIfThere = (file: string): string | null => {
+  try { return fs.readFileSync(file, "utf8"); } catch (e) { if (errCode(e) === "ENOENT") return null; throw e; }
+};
+export interface UpdateJsonOpts extends FileLockOpts {
+  /** the lock file to hold (default `<file>.lock` beside it) */
+  lockFile?: string;
+  /** runs right after the write, still under the lock — only when the file was written */
+  afterWrite?: () => void;
+  /** maps what taking the lock throws to what is thrown instead (returned unchanged: kept) — the lock may live somewhere
+   *  other than the file (a plan's, in the run cache), so its caller words a refusal there */
+  lockRefused?: (e: unknown) => unknown;
+}
+/**
+ * Read-modify-write of a JSON file several writers share (a plan: --record-plan, --accept, plan-skeleton --out, the
+ * verify-build hook). Under the lock `opts.lockFile` (default `<file>.lock`; file-lock.ts) it reads the file (null
+ * when there is none), gives the text to `fn`, which returns the new value, and writes it like writeJsonLike —
+ * formatted like the file, atomic, only when the bytes change; true when written. Two tool writers never interleave:
+ * the second reads what the first wrote. A writer that takes no lock (an agent's Edit/Write) is caught by reading the
+ * file again before the rename — changed bytes start over from them (up to UPDATE_TRIES times, then it throws); its
+ * write landing between that re-read and the rename is still lost. `fn` may run more than once, so it computes from
+ * its argument only. Throws LockBusy (file-lock.ts) when another writer holds the lock past `opts.waitMs`, LockLost
+ * when the lock was taken from this writer before its write (nothing written), and whatever reading the file throws
+ * other than ENOENT (an unreadable plan is never treated as absent and overwritten); an error taking the lock as
+ * `opts.lockRefused` maps it.
+ */
+export function updateJsonLike(file: string, fn: (raw: string | null) => unknown, opts: UpdateJsonOpts = {}): boolean {
+  const { lockFile = lockFileOf(file), afterWrite, lockRefused, ...lockOpts } = opts;
+  let lock: HeldLock;
+  try { lock = acquireFileLock(lockFile, lockOpts); } catch (e) { throw lockRefused ? lockRefused(e) : e; }
+  try {
+    for (let tries = 1; ; tries++) {
+      const raw = readIfThere(file);
+      const out = formatJsonLike(fn(raw), raw);
+      if (out === raw) return false;
+      if (readIfThere(file) === raw) {
+        lock.assertMine();
+        writeFileAtomic(file, out);
+        afterWrite?.();
+        return true;
+      }
+      if (tries >= UPDATE_TRIES) throw new Error(`${file} kept changing while it was being updated (${UPDATE_TRIES} tries) — retry once its other writer is done`);
+    }
+  } finally { lock.release(); }
+}

package/src/json-size.ts

@@ -0,0 +1,108 @@
+// A bounded measure of `JSON.stringify(value, null, 2).length`: answers "does the pretty-printed text fit in
+// `limit` UTF-16 code units?" without building the text, and stops walking the moment the running total passes
+// the limit. The inline-vs-spill decision for an MCP export reply needs only that answer, and a real export is
+// tens of megabytes — serialising it just to learn it is over a ~48 KB cap costs seconds of CPU and a
+// second copy of the export in memory, for a string that is then thrown away.
+//
+// The length is the one JSON.stringify produces (ECMA-262 SerializeJSONProperty / QuoteJSONString;
+// https://tc39.es/ecma262/#sec-serializejsonproperty): numbers print as Number::toString (non-finite → null),
+// strings escape `"`, `\`, control characters (< 0x20) and lone surrogates (a well-formed surrogate pair is
+// left as is), a property whose value is undefined / a function / a symbol is skipped (null inside an array),
+// an empty object or array prints as `{}` / `[]`, and with a 2-space indent each member sits on its own line
+// with `": "` after a key.
+//
+// Anything whose size JSON.stringify decides through code this walker does not mirror (a toJSON method, a
+// bigint, a boxed primitive, a class instance, a very deep or cyclic value) is reported as "unsupported" so the
+// caller measures it the old way; the answer is never a guess.
+
+export type JsonSize =
+  | { kind: "fits"; length: number }
+  | { kind: "over" }
+  | { kind: "unsupported" };
+
+// Deeper than any real export (an IR tree is a few dozen levels); past it the recursion could overflow the
+// stack, so the value is measured by JSON.stringify itself, which reports a cycle or a too-deep value its own way.
+const MAX_DEPTH = 200;
+
+// Characters that make a string's quoted form longer than its length + 2.
+const NEEDS_ESCAPE = /["\\\u0000-\u001f\ud800-\udfff]/;
+
+/** Length of `JSON.stringify(s)`. */
+function quotedLength(s: string): number {
+  if (!NEEDS_ESCAPE.test(s)) return s.length + 2;
+  let n = s.length + 2;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c === 0x22 || c === 0x5c) n += 1; // \" \\
+    else if (c < 0x20) n += c === 8 || c === 9 || c === 10 || c === 12 || c === 13 ? 1 : 5; // \b \t \n \f \r, else \u00XX
+    else if (c >= 0xd800 && c <= 0xdbff) {
+      const d = s.charCodeAt(i + 1);
+      if (d >= 0xdc00 && d <= 0xdfff) i++; // a pair is written raw
+      else n += 5; // a lone high surrogate becomes \udXXX
+    } else if (c >= 0xdc00 && c <= 0xdfff) n += 5; // a lone low surrogate
+  }
+  return n;
+}
+
+// The three kinds JSON.stringify drops from an object and turns into null inside an array. (At the top level
+// they have no JSON text at all; walk() reports them as unsupported there.)
+const isOmitted = (v: unknown): boolean => v === undefined || typeof v === "function" || typeof v === "symbol";
+
+/** Whether `JSON.stringify(value, null, 2)` is at most `limit` characters long — and its exact length when it is. */
+export function prettyJsonSize(value: unknown, limit: number): JsonSize {
+  let total = 0;
+  let unsupported = false;
+  // Adds to the running total; false once the limit is passed or the value is unsupported, which unwinds the walk.
+  const add = (n: number): boolean => { total += n; return total <= limit; };
+
+  const walk = (v: unknown, depth: number): boolean => {
+    if (v === null) return add(4);
+    if (typeof v === "string") return add(quotedLength(v));
+    if (typeof v === "number") return add(Number.isFinite(v) ? String(v).length : 4);
+    if (typeof v === "boolean") return add(v ? 4 : 5);
+    if (typeof v !== "object") { unsupported = true; return false; } // a bigint (stringify throws), or a top-level undefined / function / symbol
+    if (depth > MAX_DEPTH) { unsupported = true; return false; }
+    if (Array.isArray(v)) {
+      if (Object.getPrototypeOf(v) !== Array.prototype) { unsupported = true; return false; }
+      if (v.length === 0) return add(2);
+      const pad = 1 + (depth + 1) * 2; // "\n" + the member indent
+      if (!add(2 + (v.length - 1) + v.length * pad + 1 + depth * 2)) return false; // [ ] , between members, the lines
+      for (let i = 0; i < v.length; i++) {
+        const item: unknown = v[i];
+        if (isOmitted(item)) { if (!add(4)) return false; } else if (!walk(item, depth + 1)) return false;
+      }
+      return true;
+    }
+    const proto: unknown = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null) { unsupported = true; return false; }
+    const rec = v as Record<string, unknown>;
+    if (typeof rec["toJSON"] === "function") { unsupported = true; return false; }
+    let members = 0;
+    const pad = 1 + (depth + 1) * 2;
+    if (!add(2)) return false; // { }
+    for (const key of Object.keys(rec)) {
+      const member = rec[key];
+      if (isOmitted(member)) continue;
+      // "\n" + indent, the quoted key, ": ", and a "," before every member but the first
+      if (!add(pad + quotedLength(key) + 2 + (members ? 1 : 0))) return false;
+      members++;
+      if (!walk(member, depth + 1)) return false;
+    }
+    if (members) return add(1 + depth * 2); // the closing "\n" + indent
+    return true;
+  };
+
+  const done = walk(value, 0);
+  if (unsupported) return { kind: "unsupported" };
+  return done ? { kind: "fits", length: total } : { kind: "over" };
+}
+
+/** `JSON.stringify(value, null, 2)` when its text is at most `limit` characters, else null — the same answer as
+ *  stringifying first and comparing `.length`, without serialising a value that is over the limit. */
+export function prettyJsonWithin(value: unknown, limit: number): string | null {
+  const size = prettyJsonSize(value, limit);
+  if (size.kind === "over") return null;
+  const text = JSON.stringify(value, null, 2);
+  // Unsupported shapes were not measured: the text is the measure.
+  return size.kind === "fits" || text.length <= limit ? text : null;
+}