lecodes-cli 0.20.2 → 2.0.0

package/src/commands/design/comments.ts

@@ -0,0 +1,361 @@
+import { existsSync } from "node:fs"
+import type { CommentOrigin, CommentThread, MirrorSummary } from "lecodes-design/server"
+import { CliError, UsageError, bool, c, defineCommand, log, note, str, warnErr } from "../../cli"
+import { loadPeer } from "../../hosts/peerInstall"
+import { createDesignComment, listDesignComments, replyDesignComment, resolveDesignComment } from "../../platform/api"
+import {
+  DEFAULT_DIR, dirFlag, errText, getContext, loadDesignServer, optionalPlatform, requirePlatform, threadRef,
+  type DesignContext, type DesignServer, type Platform,
+} from "./context"
+
+/*
+ * `lecodes design comments` — the board's review comments in the terminal: the same threads the
+ * canvas pins, grouped by screen, open first. The write verbs (add / reply / resolve) are the
+ * server-down path — same store, same rules as the MCP tools.
+ *
+ * Reads `design/comments/` directly (no server needed). On the platform those files mirror the
+ * database — `comments pull` refreshes them, and the running board keeps them fed — but for a
+ * standalone design folder they ARE the store, so everything here works with or without a project.
+ *
+ * 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 — a pull (safe any time, feedback arriving early is just
+ * feedback) and `flushDesignComments`, which 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.
+ */
+
+// ---- write verbs -------------------------------------------------------------------------------
+
+const aiFlag = { ai: bool("sign the write as Claude (automatic inside a Claude Code session)") }
+
+/**
+ * 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 = (ai: boolean): { author: string, origin: CommentOrigin } | undefined =>
+  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): string =>
+  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: DesignServer, ctx: DesignContext, raw: string | undefined): CommentThread => {
+  const number = Number(raw)
+  if (!Number.isInteger(number) || number <= 0) {
+    throw new CliError(`"${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 add = defineCommand({
+  name: "add",
+  summary: "Start a thread from the terminal, pinned to a screen",
+  usage: '"<text>"',
+  flags: {
+    ...dirFlag,
+    screen: str("pin it to this screen (checked against the design)", { value: "<id>" }),
+    state: str("…in this state of the screen", { value: "<s>" }),
+    element: str("…on this named element", { value: "<name>" }),
+    ...aiFlag,
+  },
+  examples: ['lecodes design comments add "Is the CTA meant to be this small?" --screen login --element cta'],
+  run: async ({ args, flags }) => {
+    const ctx = getContext(flags.dir)
+    const body = (args[0] ?? "").trim()
+    if (!body) throw new UsageError("add needs the comment text.")
+    const designServer = await loadDesignServer(ctx, [ "startThread", "readDesignState" ])
+    const screen = flags.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 = flags.element?.trim() || undefined
+    const thread = designServer.startThread(ctx.designDir, {
+      anchor: {
+        screen,
+        state: flags.state?.trim() || undefined,
+        ...(element ? { target: { name: element } } : {}),
+      },
+      body,
+      ...cliAuthor(flags.ai),
+    }, { linked: !!optionalPlatform(ctx) })
+    log(`${c.green("✓")} ${threadRef(thread)} added — ${commentDelivery(ctx)}`)
+  },
+})
+
+const reply = defineCommand({
+  name: "reply",
+  summary: "Answer a thread",
+  usage: '<number> "<text>"',
+  flags: { ...dirFlag, ...aiFlag },
+  examples: ['lecodes design comments reply 3 "Bumped it to 48px — see the new login state."'],
+  run: async ({ args, flags }) => {
+    const ctx = getContext(flags.dir)
+    const body = (args[1] ?? "").trim()
+    if (!body) throw new UsageError("reply needs a thread number and the reply text.")
+    const designServer = await loadDesignServer(ctx, [ "replyToThread" ])
+    const thread = findThreadByNumber(designServer, ctx, args[0])
+    designServer.replyToThread(ctx.designDir, thread.id, body, cliAuthor(flags.ai))
+    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 resolve = defineCommand({
+  name: "resolve",
+  summary: "Close a thread (or reopen it), optionally replying first",
+  usage: "<number>",
+  flags: {
+    ...dirFlag,
+    reply: str("post this reply before closing", { value: "<text>" }),
+    reopen: bool("reopen the thread instead of closing it"),
+    ...aiFlag,
+  },
+  examples: ['lecodes design comments resolve 3 --reply "Done."', "lecodes design comments resolve 3 --reopen"],
+  run: async ({ args, flags }) => {
+    const ctx = getContext(flags.dir)
+    const designServer = await loadDesignServer(ctx, [ "resolveThread", "replyToThread" ])
+    const thread = findThreadByNumber(designServer, ctx, args[0])
+    const text = flags.reply?.trim()
+    if (text) designServer.replyToThread(ctx.designDir, thread.id, text, cliAuthor(flags.ai))
+    designServer.resolveThread(ctx.designDir, thread.id, !flags.reopen)
+    log(`${c.green("✓")} #${thread.number} ${flags.reopen ? "reopened" : "resolved"} — ${commentDelivery(ctx)}`)
+  },
+})
+
+// ---- pull down, and the queue `lecodes push` drains --------------------------------------------
+
+const reportMirror = (ctx: DesignContext, summary: MirrorSummary, open: number): void => {
+  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): Promise<CommentThread[]> => {
+  const snapshot = await listDesignComments(platform.apiUrl, platform.token, platform.uuid)
+  return snapshot.threads.filter((t) => !t.resolved)
+}
+
+const pull = defineCommand({
+  name: "pull",
+  summary: "Mirror the platform's open threads into <dir>/comments/",
+  description: "Inbound only — writes go the other way with `lecodes push`, never on their own. Needs a cloned project; a standalone folder's comments/ is already the only store.",
+  flags: dirFlag,
+  examples: ["lecodes design comments pull"],
+  run: async ({ flags }) => {
+    const ctx = getContext(flags.dir)
+    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")
+  },
+})
+
+/** Not a verb — the answer to the question, kept as a hidden node so the reflex gets the reason. */
+const push = defineCommand({
+  name: "push",
+  summary: "(comments go up with `lecodes push`)",
+  hidden: true,
+  run: () => {
+    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.)")
+  },
+})
+
+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 (dir: string = DEFAULT_DIR): Promise<CommentFlush | null> => {
+  const ctx = getContext(dir)
+  if (!existsSync(ctx.designDir)) return null
+  const platform = optionalPlatform(ctx)
+  if (!platform) return null
+
+  const designServer = await loadPeer<DesignServer>("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.
+ */
+export const startCommentSync = (ctx: DesignContext, designServer: DesignServer): (() => void) | null => {
+  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?.()
+
+  const tick = async (): Promise<void> => {
+    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)
+}
+
+// ---- the list (bare `comments`) ----------------------------------------------------------------
+
+export default defineCommand({
+  name: "comments",
+  summary: "Review comments pinned to the board, grouped by screen (open first)",
+  description: "Reads <dir>/comments/ directly, no server needed. Inside a cloned project those files mirror the platform's open threads (`comments pull` refreshes them; the running board keeps them in sync); standalone they are the store. Writes (add / reply / resolve) queue locally and go up with the next `lecodes push`, after the design they describe.",
+  flags: { ...dirFlag, all: bool("include resolved threads") },
+  commands: [add, reply, resolve, pull, push],
+  examples: ["lecodes design comments", "lecodes design comments --all"],
+  run: async ({ args, flags }) => {
+    if (args.length) throw new UsageError(`Unknown comments subcommand "${args[0]}" (add, reply, resolve, pull, or nothing to list).`)
+    const ctx = getContext(flags.dir)
+    const designServer = await loadDesignServer(ctx)
+
+    const { threads } = designServer.listDesignComments(ctx.designDir)
+    const shown = flags.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`)
+  },
+})

package/src/commands/design/context.ts

@@ -0,0 +1,101 @@
+import { existsSync } from "node:fs"
+import { basename, join } from "node:path"
+import { CliError, str } from "../../cli"
+import { loadPeer } from "../../hosts/peerInstall"
+import { loadConfig, normalizeApiUrl } from "../../platform/config"
+import { findProjectRoot, readManifest, type Manifest } from "../../project/manifest"
+import { session } from "../shared"
+
+/*
+ * What every `lecodes design …` verb starts from: where the design folder is (a cloned project's
+ * root, else the current directory standing alone), the optional `lecodes-design` server package,
+ * and the platform link a comment sync needs. Kept apart from the verbs so comments.ts and
+ * snapshot.ts share it without importing the command tree.
+ */
+
+export const DEFAULT_DIR = "design"
+export const DEFAULT_PORT = 4477
+
+/** `--dir`, on every verb: the design folder, relative to the project root. */
+export const dirFlag = { dir: str("design folder", { value: "<folder>", default: DEFAULT_DIR }) }
+
+export type DesignServer = typeof import("lecodes-design/server")
+
+export 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
+}
+
+/** 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). */
+export const getContext = (dir: string): DesignContext => {
+  let root: string
+  let manifest: Manifest | null
+  try {
+    root = findProjectRoot(process.cwd())
+    manifest = readManifest(root)
+  } catch {
+    root = process.cwd()
+    manifest = null
+  }
+  const dirName = 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. */
+export const loadDesignServer = async (ctx: DesignContext, needs: (keyof DesignServer)[] = []): Promise<DesignServer> => {
+  if (!existsSync(ctx.designDir)) {
+    throw new CliError(`No ${ctx.dirName}/ folder here. Run "lecodes design init" to scaffold it.`)
+  }
+  const mod = await loadPeer<DesignServer>("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
+}
+
+export type Platform = { apiUrl: string, token: string, uuid: string }
+
+/** 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. */
+export const requirePlatform = (ctx: DesignContext, verb: string): Platform => {
+  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.`)
+  }
+  return { ...session(), 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, the push-time flush). */
+export const optionalPlatform = (ctx: DesignContext): Platform | null => {
+  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 }
+}
+
+export const errText = (e: unknown): string => (e instanceof Error ? e.message : String(e))
+
+/** 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. */
+export const threadRef = (thread: { number?: number }): string => (thread.number === undefined ? "new" : `#${thread.number}`)