lecodes-cli 0.18.2 → 0.19.2

package/src/commands/design.ts

@@ -0,0 +1,863 @@
+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 { 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.`)
+  }
+  let mod: typeof import("lecodes-design/server")
+  try {
+    mod = await import("lecodes-design/server")
+  } catch {
+    throw new CliError("The design canvas isn't installed. Run:  npm install -g 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.")
+
+  let renderer: typeof import("lecodes-renderer/headless")
+  try {
+    renderer = await import("lecodes-renderer/headless")
+  } catch {
+    throw new CliError("The renderer isn't installed. Run:  npm install -g lecodes-renderer")
+  }
+
+  // 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) {
+    try {
+      const ds = await import("lecodes-design/server")
+      discover = (src) => { const d = ds.discoverScreenStates(src); return { states: d.states, canonical: d.canonical } }
+    } catch {
+      throw new CliError("Rendering specific states needs the design canvas. Run:  npm install -g lecodes-design")
+    }
+  }
+
+  // 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.
+  let renderer: typeof import("lecodes-renderer/headless") | null = null
+  try { renderer = await import("lecodes-renderer/headless") } catch { renderer = null }
+  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
+
+  let designServer: typeof import("lecodes-design/server")
+  try {
+    designServer = await import("lecodes-design/server")
+  } catch {
+    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).`)
+}