lecodes-cli 0.20.2 → 1.0.0

package/src/commands/design.ts

@@ -1,846 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, appendFileSync } from "node:fs"
-import { basename, join } from "node:path"
-import { findProjectRoot, readManifest, type Manifest } from "../manifest"
-import { compileDesignScreen } from "../compile/designCompile"
-import { openBrowser } from "../browserAuth"
-import { CLAUDE_MD, DESIGN_MACROS_DTS, HOME_SCREEN_TS, META_JSON, META_JSON_DESKTOP, README_HINT, SPEC_MD, TABS_TS, TOKENS_TS } from "./designTemplates"
-import { CliError, c, flagBool, flagStr, log, logErr, note, warnErr, type Args } from "../util"
-import { loadPeer } from "../peerInstall"
-import { loadConfig, normalizeApiUrl, requireApiUrl, requireToken } from "../config"
-import {
-  createDesignComment, deleteDesignComment, deleteDesignCommentMessage, disableDesignShare,
-  editDesignCommentMessage, enableDesignShare, listDesignComments, moveDesignComment,
-  replyDesignComment, resolveDesignComment, setDesignCommentsOpen, type DesignCommentsSnapshot,
-} from "../api"
-import type { CommentOrigin, CommentThread, MirrorSummary } from "lecodes-design/server"
-import { materializeTypesLocal, writeTsconfig } from "../types"
-import { readMetaFrames } from "../designMeta"
-
-/*
- * `lecodes design` — the LeCodes Design canvas: prototype an app as live screens + a flow graph.
- *
- *   lecodes design [serve]      start the dev server + browser canvas (needs `lecodes-design`)
- *                               --no-sync  don't reconcile comments with the platform while serving
- *   lecodes design init         scaffold the design folder (screens/, shared/, meta.json, spec.md, CLAUDE.md)
- *   lecodes design snapshot [--state <s> | --all-states]  render screens headless to JSON/PNG (needs `lecodes-renderer`)
- *   lecodes design arrange [--new]  auto-layout the flow graph (--new: only place unplaced screens)
- *   lecodes design check        static coherence: spec.md links, flow warnings, untagged screens
- *   lecodes design share [--off] toggle the public share link (design must be pushed first)
- *                               --comments <on|off>  let link visitors leave comments
- *   lecodes design comments [--all]  the board's review comments, grouped by screen (open first)
- *   lecodes design comments add "<text>" [--screen <id>] [--state <s>] [--element <name>] [--ai]
- *   lecodes design comments reply <number> "<text>" [--ai]
- *   lecodes design comments resolve <number> [--reply "<text>"] [--reopen] [--ai]
- *   lecodes design comments pull     mirror the platform's open threads into design/comments/
- *                                    (writes go the other way with `lecodes push`, never on their own)
- *
- * The design folder (default `design/`) holds one file per screen (screens/<id>.ts default-exports
- * a UIScreen), shared tokens/components (shared/), and meta.json — the human-owned graph of
- * positions, descriptions and edges. Screens compile per-file through the normal project pipeline
- * and render via canvas-ui, live in the browser and headless for AI feedback.
- */
-
-const DEFAULT_DIR = "design"
-const DEFAULT_PORT = 4477
-
-type DesignContext = {
-  root: string
-  /** Null in standalone mode: the design folder lives outside any cloned lecodes project. */
-  manifest: Manifest | null
-  name: string
-  dirName: string
-  designDir: string
-  designKey: string
-}
-
-const getContext = (args: Args): DesignContext => {
-  // Inside a cloned project the design folder sits at its root; anywhere else the tool runs
-  // standalone against the current directory (no login, no server project needed).
-  let root: string
-  let manifest: Manifest | null
-  try {
-    root = findProjectRoot(process.cwd())
-    manifest = readManifest(root)
-  } catch {
-    root = process.cwd()
-    manifest = null
-  }
-  const dirName = (flagStr(args, "dir") ?? DEFAULT_DIR).replace(/[/\\]+$/, "")
-  return {
-    root, manifest,
-    name: manifest?.name ?? basename(root),
-    dirName,
-    designDir: join(root, dirName),
-    designKey: "/" + dirName.replace(/\\/g, "/"),
-  }
-}
-
-/** The design canvas package, lazily: it's an optional dev dependency of the project, never a
- *  dependency of the CLI. Also asserts the folder exists, since every caller needs both.
- *
- *  `needs` names exports the caller will actually call. The two packages are versioned and installed
- *  independently, so a project can easily hold a CLI newer than its `lecodes-design` — without this
- *  check that surfaces as `undefined is not a function` halfway through a command. */
-const loadDesignServer = async (
-  ctx: DesignContext,
-  needs: (keyof typeof import("lecodes-design/server"))[] = [],
-): Promise<typeof import("lecodes-design/server")> => {
-  if (!existsSync(ctx.designDir)) {
-    throw new CliError(`No ${ctx.dirName}/ folder here. Run "lecodes design init" to scaffold it.`)
-  }
-  const mod = await loadPeer<typeof import("lecodes-design/server")>("lecodes-design", "server", { for: "lecodes design" })
-  const missing = needs.filter((name) => typeof mod[name] !== "function")
-  if (missing.length) {
-    throw new CliError(
-      `This needs a newer lecodes-design — the installed one has no \`${missing[0]}\`. Run:  npm install -g lecodes-design@latest`)
-  }
-  return mod
-}
-
-/** The platform link a comment sync needs. A standalone design folder has no database behind it —
- *  there `comments/` IS the store, so saying that beats prompting for a login. */
-const requirePlatform = (ctx: DesignContext, verb: string) => {
-  if (!ctx.manifest) {
-    throw new CliError(
-      `\`lecodes design comments ${verb}\` needs a cloned project. This folder is standalone, so ` +
-      `${ctx.dirName}/comments/ is already the only store — there is nothing to sync with.`)
-  }
-  const config = loadConfig()
-  return { apiUrl: requireApiUrl(config), token: requireToken(config), uuid: ctx.manifest.uuid }
-}
-
-/** The same link, but optional — null when standalone or not logged in. Used where syncing is a
- *  bonus rather than the point (the dev server's mirror, prune). */
-const optionalPlatform = (ctx: DesignContext) => {
-  if (!ctx.manifest) return null
-  const config = loadConfig()
-  if (!config.apiUrl || !config.token) return null
-  return { apiUrl: normalizeApiUrl(config.apiUrl), token: config.token, uuid: ctx.manifest.uuid }
-}
-
-const errText = (e: unknown) => (e instanceof Error ? e.message : String(e))
-
-/** First non-empty line, for one-line echoes of a comment body. */
-const firstLine = (body: string, max = 64): string => {
-  const line = body.split("\n").find((l) => l.trim())?.trim() ?? ""
-  return line.length > max ? line.slice(0, max - 1) + "…" : line
-}
-
-/** Screen ids from <designDir>/screens/*.ts. */
-const listScreens = (designDir: string): string[] => {
-  const dir = join(designDir, "screens")
-  if (!existsSync(dir)) return []
-  return readdirSync(dir)
-    .filter((f) => f.endsWith(".ts") && !f.startsWith("."))
-    .map((f) => f.slice(0, -3))
-    .sort()
-}
-
-// ---- init --------------------------------------------------------------------------------------
-
-/** Register the design server as a project-scoped MCP server so Claude Code auto-discovers it.
- *  Merges into an existing .mcp.json (never clobbers a hand-broken one). */
-const writeMcpConfig = (ctx: DesignContext, port: number) => {
-  const path = join(ctx.root, ".mcp.json")
-  const entry = { type: "http", url: `http://localhost:${port}/mcp` }
-  let config: { mcpServers?: Record<string, unknown> } = {}
-  if (existsSync(path)) {
-    try {
-      config = JSON.parse(readFileSync(path, "utf8"))
-    } catch {
-      warnErr(".mcp.json exists but isn't valid JSON — left it untouched. Add the lecodes-design server by hand.")
-      return
-    }
-  }
-  config.mcpServers ??= {}
-  const existing = config.mcpServers["lecodes-design"] as { url?: string } | undefined
-  if (existing?.url === entry.url) { note("kept      .mcp.json (lecodes-design MCP server)"); return }
-  config.mcpServers["lecodes-design"] = entry
-  writeFileSync(path, JSON.stringify(config, null, 2) + "\n")
-  log(`${c.green(existing ? "updated" : "created")}   .mcp.json (lecodes-design MCP → ${entry.url})`)
-}
-
-const init = async (ctx: DesignContext, args: Args) => {
-  // --desktop: scaffold a desktop-frame board (meta.defaultSize [1280, 800]; every consumer —
-  // board tiles, arrange, snapshots, render_screen — resolves frames from it).
-  const files: [string, string][] = [
-    ["meta.json", flagBool(args, "desktop") ? META_JSON_DESKTOP : META_JSON],
-    ["spec.md", SPEC_MD],
-    ["README.md", README_HINT],
-    ["CLAUDE.md", CLAUDE_MD],
-    [join("shared", "tokens.ts"), TOKENS_TS],
-    [join("shared", "tabs.ts"), TABS_TS],
-    [join("screens", "home.ts"), HOME_SCREEN_TS],
-  ]
-  mkdirSync(join(ctx.designDir, "screens"), { recursive: true })
-  mkdirSync(join(ctx.designDir, "shared"), { recursive: true })
-  let created = 0
-  for (const [rel, content] of files) {
-    const abs = join(ctx.designDir, rel)
-    if (existsSync(abs)) { note(`kept      ${ctx.dirName}/${rel.replace(/\\/g, "/")}`); continue }
-    writeFileSync(abs, content)
-    log(`${c.green("created")}   ${ctx.dirName}/${rel.replace(/\\/g, "/")}`)
-    created++
-  }
-
-  // Neither of these is a project file: snapshots are local render artifacts, and comments/
-  // mirrors rows the platform already owns (pushing it back would just duplicate the database).
-  const ignorePath = join(ctx.root, ".lecodesignore")
-  const ignoreLines = [ `${ctx.dirName}/.snapshots/`, `${ctx.dirName}/comments/` ]
-  const current = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : ""
-  const present = new Set(current.split(/\r?\n/))
-  const missing = ignoreLines.filter((line) => !present.has(line))
-  if (missing.length) {
-    appendFileSync(ignorePath, (current && !current.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n")
-    for (const line of missing) log(`${c.green("ignored")}   ${line} (in .lecodesignore)`)
-  }
-
-  // Let Claude Code reach the running board over MCP (render/check/state/activity tools).
-  writeMcpConfig(ctx, Number(flagStr(args, "port")) || DEFAULT_PORT)
-
-  // IDE types: materialize the SDK's import-free type surface + a design-scoped tsconfig so screens
-  // typecheck honestly (globals like UIScreen / UINode / UINodeChild resolve), standalone or in a
-  // project. .lecodes/ and tsconfig.json are skipped by the push scanner.
-  const wroteTypes = materializeTypesLocal(ctx.designDir)
-  writeTsconfig(ctx.designDir)
-  // Design-only compiler globals (assetIcon) that aren't in the shipped SDK type surface. Written
-  // alongside the bundle so the editor resolves them; rewritten every init to pick up upgrades.
-  mkdirSync(join(ctx.designDir, ".lecodes", "types"), { recursive: true })
-  writeFileSync(join(ctx.designDir, ".lecodes", "types", "design-macros.d.ts"), DESIGN_MACROS_DTS)
-  log(`${c.green("created")}   ${ctx.dirName}/tsconfig.json${wroteTypes ? ` + ${ctx.dirName}/.lecodes/types/` : ""}  (IDE types)`)
-  if (!wroteTypes) warnErr("Bundled SDK types not found — tsconfig written, but globals may show unresolved until the CLI is rebuilt with vendored types.")
-
-  log("")
-  log(created ? "Design canvas ready." : "Design canvas already initialized.")
-  log(`  ${c.bold("lecodes design")}                start the canvas (browser)`)
-  log(`  ${c.bold("lecodes design snapshot")}       render screens headless (for AI feedback)`)
-  log(`  Point Claude Code at ${c.bold(ctx.dirName + "/CLAUDE.md")} — it documents the conventions.`)
-}
-
-// ---- snapshot ----------------------------------------------------------------------------------
-
-const snapshot = async (ctx: DesignContext, args: Args) => {
-  const all = listScreens(ctx.designDir)
-  if (all.length === 0) throw new CliError(`No screens in ${ctx.dirName}/screens/ — run "lecodes design init" first.`)
-  const requested = args._.slice(1)
-  for (const id of requested) {
-    if (!all.includes(id)) throw new CliError(`No screen "${id}" (have: ${all.join(", ")}).`)
-  }
-  const targets = requested.length ? requested : all
-
-  const stateFlag = flagStr(args, "state")
-  const allStates = flagBool(args, "all-states")
-  if (stateFlag !== undefined && allStates) throw new CliError("Use either --state <name> or --all-states, not both.")
-
-  const renderer = await loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes design render" })
-
-  // Enumerating / validating states parses the screen source — that discovery lives in the design
-  // package. The canonical-only path (no flag) needs no discovery, so base snapshot stays lean.
-  let discover: ((source: string) => { states: string[], canonical: string }) | null = null
-  if (stateFlag !== undefined || allStates) {
-    const ds = await loadPeer<typeof import("lecodes-design/server")>("lecodes-design", "server", { for: "lecodes design render --state" })
-    discover = (src) => { const d = ds.discoverScreenStates(src); return { states: d.states, canonical: d.canonical } }
-  }
-
-  // A stuck screen (runaway loop) shouldn't hang the CLI forever.
-  const killer = setTimeout(() => {
-    warnErr("Snapshot timed out after 120s.")
-    process.exit(1)
-  }, 120000)
-  killer.unref?.()
-
-  const png = flagBool(args, "png") || flagStr(args, "png") !== undefined
-  const frames = readMetaFrames(ctx.designDir)
-  const outDir = flagStr(args, "out-dir") ?? join(ctx.designDir, ".snapshots")
-  const single = targets.length === 1 && requested.length === 1 && !png && !allStates && !flagStr(args, "out-dir")
-  const onConsole = flagBool(args, "logs")
-    ? (level: string, text: string) => logErr(`${c.dim(`[${level}]`)} ${text}`)
-    : undefined
-
-  if (!single) mkdirSync(outDir, { recursive: true })
-
-  for (const id of targets) {
-    const [ width, height ] = frames.screens[id]?.size ?? frames.defaultSize
-
-    // What to render, and the file base(s) for each. `undefined` state = a bare (canonical) render.
-    // The canonical state also writes the unsuffixed `<id>` for backward compatibility.
-    let plan: { state?: string, bases: string[] }[] = [{ state: undefined, bases: [id] }]
-    if (discover) {
-      const { states, canonical } = discover(readFileSync(join(ctx.designDir, "screens", `${id}.ts`), "utf8"))
-      if (stateFlag !== undefined) {
-        if (!states.includes(stateFlag)) {
-          if (requested.length === 1) throw new CliError(`No state "${stateFlag}" on ${id} (has: ${states.join(", ")}).`)
-          warnErr(`${id}: no state "${stateFlag}" (has: ${states.join(", ")}) — skipped.`)
-          continue
-        }
-        plan = [{ state: stateFlag, bases: [`${id}@${stateFlag}`] }]
-      } else {
-        plan = states.map((st) => ({ state: st, bases: st === canonical ? [`${id}@${st}`, id] : [`${id}@${st}`] }))
-      }
-    }
-
-    for (const { state, bases } of plan) {
-      const tag = state ? `${id}@${state}` : id
-      note(`Rendering ${tag}…`)
-      const js = await compileDesignScreen({
-        root: ctx.root, manifest: ctx.manifest, name: ctx.name, designDir: ctx.designDir, designKey: ctx.designKey, screenId: id, state, assets: "disk",
-      })
-      const result = await renderer.renderToJson(js, { width, height, localAssets: true, onConsole })
-      for (const w of result.warnings) warnErr(`${tag}: ${w}`)
-
-      if (single) {
-        const text = result.text.endsWith("\n") ? result.text : result.text + "\n"
-        process.stdout.write(text)
-        return
-      }
-      const pngResult = png ? await renderer.renderToPng(js, { width, height, localAssets: true, scale: 2, onConsole }) : null
-      if (pngResult) for (const w of pngResult.warnings) warnErr(`${tag}: ${w}`)
-
-      for (const base of bases) {
-        writeFileSync(join(outDir, `${base}.json`), result.text)
-        log(`${c.green("✓")} ${tag} → ${join(outDir, `${base}.json`)}`)
-        if (pngResult) {
-          writeFileSync(join(outDir, `${base}.png`), pngResult.png)
-          log(`${c.green("✓")} ${tag} → ${join(outDir, `${base}.png`)}`)
-        }
-      }
-    }
-  }
-}
-
-// ---- serve -------------------------------------------------------------------------------------
-
-const serve = async (ctx: DesignContext, args: Args) => {
-  const designServer = await loadDesignServer(ctx)
-
-  const port = Number(flagStr(args, "port")) || DEFAULT_PORT
-
-  // The MCP render_screen tool renders headless through lecodes-renderer, injected here so the
-  // design server keeps no dependency on it. Absent renderer → the tool returns an install hint.
-  // Opportunistic: never triggers an install from inside the MCP server (the tool reports the hint).
-  const renderer = await loadPeer<typeof import("lecodes-renderer/headless")>("lecodes-renderer", "headless", { for: "lecodes design (render_screen)", install: false })
-  const renderScreen = renderer
-    ? async (id: string, format: "json" | "png" | "both", state?: string) => {
-        const r = renderer!
-        const js = await compileDesignScreen({
-          root: ctx.root, manifest: ctx.manifest, name: ctx.name, designDir: ctx.designDir, designKey: ctx.designKey, screenId: id, state, assets: "disk",
-        })
-        const frames = readMetaFrames(ctx.designDir)
-        const [width, height] = frames.screens[id]?.size ?? frames.defaultSize
-        const warnings: string[] = []
-        let json: string | undefined
-        let png: Buffer | undefined
-        if (format === "json" || format === "both") {
-          const res = await r.renderToJson(js, { width, height, localAssets: true })
-          json = res.text
-          warnings.push(...res.warnings)
-        }
-        if (format === "png" || format === "both") {
-          const res = await r.renderToPng(js, { width, height, localAssets: true, scale: 2 })
-          png = res.png
-          warnings.push(...res.warnings)
-        }
-        return { json, png, warnings }
-      }
-    : undefined
-
-  const server = await designServer.startDesignServer({
-    root: ctx.root,
-    designDir: ctx.designDir,
-    name: ctx.name,
-    port,
-    log: note,
-    // Who owns the conversation: linked, the files mirror the platform's open threads and local
-    // writes queue for `lecodes push`; standalone, these files are the record.
-    linked: !!optionalPlatform(ctx),
-    compileScreen: async (id: string, state?: string) => ({
-      js: await compileDesignScreen({
-        root: ctx.root, manifest: ctx.manifest, name: ctx.name, designDir: ctx.designDir, designKey: ctx.designKey, screenId: id, state, assets: "server",
-      }),
-      warnings: [],
-    }),
-    renderScreen,
-  })
-
-  // Reconcile comments with the platform while we run, so review feedback from the share link shows
-  // up on the board (and in comments/) without a manual pull; answers go back with `lecodes push`.
-  // `--no-sync` opts out.
-  const sync = flagBool(args, "no-sync") ? null : startCommentSync(ctx, designServer)
-
-  log(`${c.bold("LeCodes Design")} — ${ctx.name}`)
-  log(`Canvas:   ${c.bold(server.url)}`)
-  log(`MCP:      ${c.bold(server.url + "/mcp")}${renderer ? "" : c.dim("  (render_screen off — npm install -g lecodes-renderer)")}`)
-  log(`Watching: ${ctx.dirName}/  (screens hot-reload on save; Ctrl+C to stop)`)
-  if (sync) log(`Comments: ${c.dim("in sync with the platform — replies and resolves go back automatically")}`)
-  if (!flagBool(args, "no-open")) openBrowser(server.url)
-}
-
-// ---- arrange -----------------------------------------------------------------------------------
-
-/**
- * Auto-layout the flow graph in meta.json. Full arrange re-lays-out every screen and always
- * applies (the board offers Undo; the structure-aware score delta is printed); `--new` places only
- * screens that have no explicit `pos` yet and never moves the rest — the mode Claude uses after
- * adding screens. If the dev server is running it picks up the meta.json change and refreshes.
- */
-const arrange = async (ctx: DesignContext, args: Args) => {
-  const designServer = await loadDesignServer(ctx)
-  const onlyNew = flagBool(args, "new")
-  const summary = designServer.arrangeDesign(ctx.designDir, { onlyNew })
-  const score = summary.score ? ` (score ${summary.score.before.toFixed(0)} → ${summary.score.after.toFixed(0)}, lower is better)` : ""
-  if (!summary.changed) {
-    log(onlyNew ? "No unplaced screens — nothing to arrange." : `Already in its arranged shape — nothing moved${score}.`)
-    return
-  }
-  log(`${c.green("✓")} ${onlyNew ? "Placed" : "Arranged"} ${summary.moved} screen${summary.moved === 1 ? "" : "s"} in ${ctx.dirName}/meta.json${score}.`)
-}
-
-// ---- share -------------------------------------------------------------------------------------
-
-/**
- * Toggle the project's public design share link on the platform. The design must already be pushed
- * (`lecodes push`) — this only flips the link, it doesn't upload anything. `--off` revokes it;
- * `--comments on|off` flips whether link visitors may WRITE comments (reading is never affected).
- */
-const share = async (ctx: DesignContext, args: Args) => {
-  if (!ctx.manifest) {
-    throw new CliError("`lecodes design share` needs a cloned project. Run it inside one, and push the design first (lecodes push).")
-  }
-  const config = loadConfig()
-  const apiUrl = requireApiUrl(config)
-  const token = requireToken(config)
-  const uuid = ctx.manifest.uuid
-
-  const commentsFlag = flagStr(args, "comments")
-  if (commentsFlag !== undefined) {
-    const value = commentsFlag.trim().toLowerCase()
-    if (value !== "on" && value !== "off") {
-      throw new CliError(`--comments takes "on" or "off" (got "${commentsFlag}").`)
-    }
-    const { commentsOpen } = await setDesignCommentsOpen(apiUrl, token, uuid, value === "on")
-    log(`${c.green("✓")} Comments on the shared design are ${commentsOpen ? "ON" : "OFF"}.`)
-    if (!commentsOpen) note("Existing comments stay readable — this only stops new ones.")
-    return
-  }
-
-  if (flagBool(args, "off")) {
-    await disableDesignShare(apiUrl, token, uuid)
-    log(`${c.green("✓")} Design sharing is off.`)
-    return
-  }
-  const res = await enableDesignShare(apiUrl, token, uuid)
-  log(`${c.bold("Design shared")} — anyone with this link can view the mockups (your app code stays private):`)
-  log(`  ${c.bold(res.url ?? "")}`)
-  log(`  ${c.dim(`comments: ${res.commentsOpen === false ? "off" : "on"}`)}`)
-  note('Turn it off with:  lecodes design share --off   ·   comments:  --comments off')
-}
-
-// ---- check -------------------------------------------------------------------------------------
-
-/**
- * Static coherence check for a design folder — the terminal/CI sibling of the `check_concept` MCP
- * tool. Reports the flow warnings meta.json/screens/spec.md already carry (broken edges, missing
- * screens, edges targeting an undeclared `@state`, duplicate state names, dangling `[[spec]]` links)
- * plus concept completeness (spec.md present? screens with no role?) and discovered states. Hard
- * warnings exit non-zero; soft hints never fail the check. No compile, no render — fast, and needs
- * only lecodes-design (not the renderer).
- */
-const check = async (ctx: DesignContext, args: Args) => {
-  const designServer = await loadDesignServer(ctx)
-  const state = designServer.readDesignState(ctx.designDir)
-  const concept = designServer.conceptReport(ctx.designDir, state.screens)
-
-  if (state.warnings.length) {
-    log(c.bold(`Warnings (${state.warnings.length})`))
-    for (const w of state.warnings) log(`  ${c.yellow("!")} ${w}`)
-    log("")
-  }
-
-  log(c.bold("Concept"))
-  log(`  spec.md:  ${concept.hasSpec ? c.green("present") : c.dim("missing (optional)")}`)
-  if (concept.screenRefs.length) {
-    const resolved = concept.screenRefs.filter((r) => r.exists).length
-    log(`  [[links]]: ${resolved}/${concept.screenRefs.length} resolve`)
-  }
-  if (concept.screensWithoutRole.length) log(`  ${c.dim("no role:")} ${concept.screensWithoutRole.join(", ")}`)
-  log("")
-
-  // States: list multi-state screens (canonical highlighted) + soft "not discoverable" hints.
-  const stateful = state.screens.filter((s) => s.states.length > 1)
-  const undiscoverable = state.screens.filter((s) => s.statesWarning)
-  if (stateful.length || undiscoverable.length) {
-    log(c.bold("States"))
-    for (const s of stateful) {
-      log(`  ${s.id}: ${s.states.map((st) => st === s.canonical ? c.green(st) : st).join(", ")}`)
-    }
-    for (const s of undiscoverable) log(`  ${c.yellow("!")} ${s.id}: ${s.statesWarning}`)
-    log("")
-  }
-
-  // Tab bars: the source-discovered hubs (defineTabs) — tabs in order + how many screens sit on
-  // each bar. Problems (missing roots, unknown tabs, bar-implied edges) surface in Warnings above.
-  if (state.hubs.length) {
-    log(c.bold("Tab bars"))
-    for (const h of state.hubs) {
-      const mounted = Object.keys(h.lanes).length
-      log(`  ${h.name} (${h.file}): ${h.tabs.join(" · ")} — ${mounted} screen${mounted === 1 ? "" : "s"} on the bar`)
-    }
-    log("")
-  }
-
-  // Review comments: open threads are outstanding work on this design, so a coherence check that
-  // stayed silent about them would report "no problems" over a board full of unanswered feedback.
-  // They never fail the check — feedback isn't an error, and the file may be a stale mirror. An
-  // older lecodes-design without the comment store simply omits the section rather than failing.
-  const commentThreads = typeof designServer.listDesignComments === "function"
-    ? designServer.listDesignComments(ctx.designDir).threads
-    : []
-  if (commentThreads.length) {
-    const open = commentThreads.filter((t) => !t.resolved)
-    log(c.bold("Comments"))
-    log(`  ${open.length} open · ${commentThreads.length} total`)
-    for (const thread of open.slice(0, 5)) {
-      const where = thread.anchor.screen ?? "(board)"
-      log(`  ${c.dim(`#${thread.number}`)} ${where}  ${c.dim(firstLine(thread.messages[0]?.body ?? ""))}`)
-    }
-    if (open.length > 5) log(`  ${c.dim(`…and ${open.length - 5} more — lecodes design comments`)}`)
-    log("")
-  }
-
-  const hard = state.warnings.length
-  if (hard === 0) {
-    const n = state.screens.length
-    log(`${c.green("✓")} No coherence problems${n ? ` across ${n} screen${n === 1 ? "" : "s"}` : ""}.`)
-    return
-  }
-  log(`${c.red("✗")} ${hard} coherence warning${hard === 1 ? "" : "s"} — see above.`)
-  process.exitCode = 1
-}
-
-// ---- comments ----------------------------------------------------------------------------------
-
-/**
- * Read the board's review comments in the terminal — the same threads the canvas pins, grouped by
- * screen. Open first, because the open ones are the work; `--all` includes resolved.
- *
- * Reads `design/comments/` directly (no server needed). On the platform those files mirror the
- * database — `lecodes design comments pull` refreshes them — but for a standalone design folder they
- * are the store, so this works with or without a project.
- */
-const commentsCmd = async (ctx: DesignContext, args: Args) => {
-  const sub = args._[1]
-  if (sub === "pull") return commentsPull(ctx)
-  if (sub === "add") return commentsAdd(ctx, args)
-  if (sub === "reply") return commentsReply(ctx, args)
-  if (sub === "resolve") return commentsResolve(ctx, args)
-  if (sub === "push") {
-    throw new CliError(
-      "Comments go up with the design, not on their own — run `lecodes push`.\n" +
-      "  (A reply that arrives before the change it describes is worse than one that arrives late.)")
-  }
-  if (sub !== undefined) {
-    throw new CliError(`Unknown comments subcommand "${sub}" (add, reply, resolve, pull, or nothing to list).`)
-  }
-  const designServer = await loadDesignServer(ctx)
-
-  const all = flagBool(args, "all")
-  const { threads } = designServer.listDesignComments(ctx.designDir)
-  const shown = all ? threads : threads.filter((t) => !t.resolved)
-  const open = threads.filter((t) => !t.resolved).length
-
-  if (threads.length === 0) {
-    log("No comments on this design yet.")
-    note("Open the board (lecodes design) and use 💬 Comment, or share it for review.")
-    return
-  }
-  if (shown.length === 0) {
-    log(`${c.green("✓")} Nothing open — all ${threads.length} comment${threads.length === 1 ? "" : "s"} resolved.`)
-    note("See them with:  lecodes design comments --all")
-    return
-  }
-
-  // Group by anchor so the list reads like a walk of the board, not a feed.
-  const byScreen = new Map<string, typeof shown>()
-  for (const thread of shown) {
-    const key = thread.anchor.screen ?? "(detached)"
-    byScreen.set(key, [ ...(byScreen.get(key) ?? []), thread ])
-  }
-  // Unpushed drafts have no number yet; they sort last rather than pretending to be #0.
-  const order = (t: { number?: number }) => t.number ?? Number.MAX_SAFE_INTEGER
-  for (const [ screen, list ] of [ ...byScreen ].sort((a, b) => a[0].localeCompare(b[0]))) {
-    log(c.bold(screen))
-    for (const thread of list.sort((a, b) => order(a) - order(b))) {
-      const target = thread.anchor.target
-      const where = [ thread.anchor.state && `@${thread.anchor.state}`, target?.name ?? target?.text ]
-        .filter(Boolean).join(" · ")
-      const head = `  ${c.bold(threadRef(thread))} ${thread.messages[0]?.author ?? "—"}`
-      log(`${head}${where ? c.dim(`  ${where}`) : ""}${thread.resolved ? c.green("  ✓ resolved") : ""}`)
-      for (const message of thread.messages) {
-        for (const line of message.body.split("\n")) log(`     ${c.dim("│")} ${line}`)
-      }
-      if (thread.messages.length > 1) log(`     ${c.dim(`${thread.messages.length} messages`)}`)
-    }
-    log("")
-  }
-  log(`${open} open · ${threads.length} total`)
-}
-
-// ---- comments: write verbs (the server-down path — same store, same rules as the MCP tools) ----
-
-/**
- * Attribution for a CLI write. The developer's git name by default; Claude when `--ai` says so, or
- * when the command is visibly running inside a Claude session (Claude Code's shell sets CLAUDECODE).
- * The reviewer reading the answer is owed knowing a machine wrote it, so err toward the badge.
- */
-const cliAuthor = (args: Args): { author: string, origin: CommentOrigin } | undefined =>
-  flagBool(args, "ai") || process.env.CLAUDECODE ? { author: "Claude", origin: "ai" } : undefined
-
-/** Where a write just went — said after every verb, because a finished-looking comment that hasn't
- *  reached the reviewer yet is the misunderstanding this whole queue exists to prevent. */
-const commentDelivery = (ctx: DesignContext) =>
-  optionalPlatform(ctx)
-    ? "queued — it goes out with the next `lecodes push`, after the design it describes"
-    : "saved — this folder is the record"
-
-const findThreadByNumber = (
-  designServer: typeof import("lecodes-design/server"),
-  ctx: DesignContext,
-  raw: unknown,
-): CommentThread => {
-  const number = Number(raw)
-  if (!Number.isInteger(number) || number <= 0) {
-    throw new CliError(`"${String(raw ?? "")}" is not a thread number — see:  lecodes design comments`)
-  }
-  const thread = designServer.listDesignComments(ctx.designDir).threads.find((t) => t.number === number)
-  if (!thread) throw new CliError(`No comment #${number} on this design — see:  lecodes design comments`)
-  return thread
-}
-
-/** Start a thread from the terminal — Claude asking the reviewer something with no server running,
- *  or the developer leaving themselves a note. Pin it to a real screen so it never lands detached. */
-const commentsAdd = async (ctx: DesignContext, args: Args) => {
-  const body = String(args._[2] ?? "").trim()
-  if (!body) {
-    throw new CliError('Usage: lecodes design comments add "<text>" [--screen <id>] [--state <s>] [--element <name>] [--ai]')
-  }
-  const designServer = await loadDesignServer(ctx, [ "startThread", "readDesignState" ])
-  const screen = flagStr(args, "screen")?.trim() || undefined
-  if (screen) {
-    const ids = designServer.readDesignState(ctx.designDir).screens.map((s) => s.id)
-    if (!ids.includes(screen)) {
-      throw new CliError(`No screen "${screen}" in ${ctx.dirName}/ — the pin would point at nothing. Have: ${ids.join(", ") || "(none)"}.`)
-    }
-  }
-  const element = flagStr(args, "element")?.trim() || undefined
-  const thread = designServer.startThread(ctx.designDir, {
-    anchor: {
-      screen,
-      state: flagStr(args, "state")?.trim() || undefined,
-      ...(element ? { target: { name: element } } : {}),
-    },
-    body,
-    ...cliAuthor(args),
-  }, { linked: !!optionalPlatform(ctx) })
-  log(`${c.green("✓")} ${threadRef(thread)} added — ${commentDelivery(ctx)}`)
-}
-
-const commentsReply = async (ctx: DesignContext, args: Args) => {
-  const body = String(args._[3] ?? "").trim()
-  if (!body) throw new CliError('Usage: lecodes design comments reply <number> "<text>" [--ai]')
-  const designServer = await loadDesignServer(ctx, [ "replyToThread" ])
-  const thread = findThreadByNumber(designServer, ctx, args._[2])
-  designServer.replyToThread(ctx.designDir, thread.id, body, cliAuthor(args))
-  log(`${c.green("✓")} replied to #${thread.number} — ${commentDelivery(ctx)}`)
-}
-
-/** Close (or `--reopen`) a thread, optionally replying first — same order as the MCP tool, so the
- *  reviewer always sees the "what was done" before the checkmark that claims it. */
-const commentsResolve = async (ctx: DesignContext, args: Args) => {
-  const designServer = await loadDesignServer(ctx, [ "resolveThread", "replyToThread" ])
-  const thread = findThreadByNumber(designServer, ctx, args._[2])
-  const reopen = flagBool(args, "reopen")
-  const reply = flagStr(args, "reply")?.trim()
-  if (reply) designServer.replyToThread(ctx.designDir, thread.id, reply, cliAuthor(args))
-  designServer.resolveThread(ctx.designDir, thread.id, !reopen)
-  log(`${c.green("✓")} #${thread.number} ${reopen ? "reopened" : "resolved"} — ${commentDelivery(ctx)}`)
-}
-
-// ---- comments: pull down, and the queue `lecodes push` drains ---------------------------------
-
-/*
- * Direction is fixed and it is what keeps this small: the platform owns the conversation, the design
- * folder mirrors its OPEN threads, and **nothing leaves this machine except via `lecodes push`**.
- *
- * So there are exactly two moving parts here — a pull (safe any time, feedback arriving early is just
- * feedback) and a flush that rides along with the design push. A reply cannot reach a reviewer before
- * the work it describes, because they are the same command in that order.
- */
-
-type Platform = { apiUrl: string, token: string, uuid: string }
-
-/** How a thread is referred to. Duplicated from the design package rather than imported: that package
- *  is an optional peer, so a value import here would break the CLI wherever it isn't installed. */
-const threadRef = (thread: { number?: number }) => (thread.number === undefined ? "new" : `#${thread.number}`)
-
-const reportMirror = (ctx: DesignContext, summary: MirrorSummary, open: number) => {
-  const parts = [
-    summary.added ? `+${summary.added} new` : null,
-    summary.updated ? `${summary.updated} updated` : null,
-    summary.closed ? `${summary.closed} closed` : null,
-  ].filter((p): p is string => p !== null)
-  if (parts.length === 0) {
-    log(`Already up to date — ${open} open.`)
-    return
-  }
-  log(`${c.green("✓")} ${ctx.dirName}/comments/ — ${parts.join(", ")}  ${c.dim(`(${open} open)`)}`)
-}
-
-/** The platform's open threads. Resolved ones aren't mirrored: the mirror is the work queue, and the
- *  platform keeps the record. */
-const fetchOpen = async (platform: Platform) => {
-  const snapshot = await listDesignComments(platform.apiUrl, platform.token, platform.uuid)
-  return snapshot.threads.filter((t) => !t.resolved)
-}
-
-const commentsPull = async (ctx: DesignContext) => {
-  const designServer = await loadDesignServer(ctx, [ "mirrorThreads" ])
-  const platform = requirePlatform(ctx, "pull")
-  const open = await fetchOpen(platform)
-  const summary = designServer.mirrorThreads(ctx.designDir, open)
-  reportMirror(ctx, summary, open.length)
-  if (open.length) note("Read them with:  lecodes design comments")
-}
-
-export type CommentFlush = { sent: number, threads: number, failures: string[] }
-
-/**
- * Send everything the design folder has queued, and settle each thread against what the platform says
- * it is afterwards. Called by `lecodes push` once the design itself has landed — never before, which
- * is the whole reason a reply can't claim a fix nobody can see yet.
- *
- * Returns null when there is nothing to do (no design folder, no project, no queue), so the caller
- * stays a single `if`.
- */
-export const flushDesignComments = async (args: Args): Promise<CommentFlush | null> => {
-  const ctx = getContext(args)
-  if (!existsSync(ctx.designDir)) return null
-  const platform = optionalPlatform(ctx)
-  if (!platform) return null
-
-  const designServer = await loadPeer<typeof import("lecodes-design/server")>("lecodes-design", "server", { for: "lecodes design", install: false })
-  if (!designServer) return null
-  // `settleQueued` must take `delivered` (4 params): settling a half-failed push with the older
-  // signature would drop the writes that DIDN'T go through instead of retrying them.
-  if (typeof designServer.queuedThreads !== "function") return null
-  if (typeof designServer.settleQueued !== "function" || designServer.settleQueued.length < 4) return null
-
-  const queued = designServer.queuedThreads(ctx.designDir)
-  if (queued.length === 0) return null
-
-  const { apiUrl, token, uuid } = platform
-  const result: CommentFlush = { sent: 0, threads: 0, failures: [] }
-
-  for (const item of queued) {
-    const { thread, pending } = item
-    /** What the platform says the thread is after the last delivered write. */
-    let upstream: CommentThread | null = null
-    /** LOCAL ids of what actually landed — a push can die halfway, and only these get settled. */
-    const delivered = { messageIds: new Set<string>(), resolve: false }
-    try {
-      if (pending.newThread) {
-        const [ opening, ...rest ] = thread.messages
-        if (!opening) continue
-        upstream = await createDesignComment(apiUrl, token, uuid, {
-          anchor: thread.anchor, body: opening.body, origin: opening.origin,
-        })
-        result.sent++
-        delivered.messageIds.add(opening.id)
-        for (const message of rest) {
-          upstream = await replyDesignComment(apiUrl, token, uuid, upstream.id, message.body, message.origin)
-          result.sent++
-          delivered.messageIds.add(message.id)
-        }
-      } else {
-        for (const message of pending.messages) {
-          upstream = await replyDesignComment(apiUrl, token, uuid, thread.id, message.body, message.origin)
-          result.sent++
-          delivered.messageIds.add(message.id)
-        }
-      }
-
-      if (pending.resolve) {
-        upstream = await resolveDesignComment(apiUrl, token, uuid, upstream?.id ?? thread.id, thread.resolved)
-        result.sent++
-        delivered.resolve = true
-      }
-    } catch (e) {
-      // The undelivered remainder stays queued: the next push retries it. What must never happen is
-      // the file claiming something was sent when it wasn't.
-      result.failures.push(`${threadRef(thread)}: ${errText(e)}`)
-    }
-    // Settle whatever DID land, even after a mid-thread failure — adopting the platform's copy is
-    // what stops the next push from sending it again as a duplicate.
-    if (upstream) {
-      designServer.settleQueued(ctx.designDir, item, upstream, delivered)
-      result.threads++
-    }
-  }
-  return result
-}
-
-/** How often the running board re-reads the platform's comments. */
-const COMMENT_SYNC_MS = 20_000
-
-/**
- * Keep `design/comments/` fed while the canvas runs, so feedback left on the share link reaches the
- * board — and Claude — without anyone remembering to pull.
- *
- * Strictly inbound. Writing the files is what refreshes the board: the fs watcher sees the directory
- * change and pushes the SSE `comments` flag, exactly as it does for a hand edit.
- */
-const startCommentSync = (ctx: DesignContext, designServer: typeof import("lecodes-design/server")) => {
-  const platform = optionalPlatform(ctx)
-  if (!platform) return null
-  // An older lecodes-design has no mirror to drive. The board still works off the files, so losing
-  // the sync is not a reason to refuse to serve.
-  if (typeof designServer.mirrorThreads !== "function") {
-    note("Comment sync needs a newer lecodes-design (npm install -g lecodes-design@latest) — serving without it.")
-    return null
-  }
-  let failures = 0
-  const timer: ReturnType<typeof setInterval> = setInterval(() => { void tick() }, COMMENT_SYNC_MS)
-  timer.unref?.()
-
-  async function tick() {
-    try {
-      const open = await fetchOpen(platform!)
-      failures = 0
-      const summary = designServer.mirrorThreads(ctx.designDir, open)
-      if (summary.added || summary.updated || summary.closed) {
-        note(`comments ← platform (${open.length} open)`)
-      }
-    } catch (e) {
-      // Offline, revoked token, project gone: say it once and give up rather than logging forever.
-      // The board keeps working off the files, and `comments pull` reports the real error on demand.
-      if (++failures === 1) warnErr(`Comment sync paused — ${errText(e)}`)
-      if (failures >= 3) clearInterval(timer)
-    }
-  }
-  void tick()
-  return () => clearInterval(timer)
-}
-
-// ---- dispatch ----------------------------------------------------------------------------------
-
-export const design = async (args: Args) => {
-  const sub = args._[0] ?? "serve"
-  const ctx = getContext(args)
-  if (sub === "serve") return serve(ctx, args)
-  if (sub === "init") return init(ctx, args)
-  if (sub === "snapshot") return snapshot(ctx, args)
-  if (sub === "arrange") return arrange(ctx, args)
-  if (sub === "check") return check(ctx, args)
-  if (sub === "share") return share(ctx, args)
-  if (sub === "comments") return commentsCmd(ctx, args)
-  throw new CliError(`Unknown design subcommand "${sub}" (serve | init | snapshot | arrange | check | share | comments).`)
-}