lecodes-cli 0.20.2 → 2.0.0

package/src/api.ts

@@ -1,302 +1 @@
-import { CliError } from "./util"
-
-/* Thin client over the backend HTTP API. All project/account calls go through `${apiUrl}/api/...`;
- * blob downloads hit `${apiUrl}<src>` (the public /uploads/* route). Mirrors the contract the
- * frontend uses (see packages/frontend/src/api). */
-
-export type ProjectAsset = {
-  id: number
-  name: string
-  type: "folder" | "file" | "text" | "shader" | "scene"
-  parentId: number | null
-  meta?: Record<string, unknown> | null
-  text?: string | null
-  file?: { src: string, previewSrc?: string | null, size?: number } | null
-  shaders?: { platform: string, src: string }[]
-}
-
-export type Project = {
-  uuid: string
-  name: string
-  role: "owner" | "developer" | "viewer"
-  assets: ProjectAsset[]
-}
-
-export type CommitsResponse = { dirty: boolean, headId: number | null }
-
-export type SyncFileInput = {
-  path: string
-  assetId?: number
-  type: "text" | "shader" | "scene" | "resource"
-  text?: string | null
-  blobFileId?: number | null
-}
-export type SyncFolderInput = { path: string }
-export type SyncResponse = {
-  created: boolean
-  headId: number
-  seq?: number
-  nodes: { id: number, path: string, type: string, versionId: number | null }[]
-  /** Set when the push requested `publish` — whether the deploy (compile → live) succeeded. */
-  published?: boolean
-  /** A human-readable reason when `publish` was requested but the deploy failed (push still landed). */
-  publishError?: string
-}
-
-const errorMessage = (body: unknown, status: number): string => {
-  if (typeof body === "string" && body) return body
-  if (body && typeof body === "object") {
-    const b = body as Record<string, unknown>
-    if (typeof b.error === "string") return b.error
-    if (b.error && typeof b.error === "object") {
-      const first = Object.values(b.error)[0] as unknown
-      if (typeof first === "string") return first
-      if (first && typeof first === "object" && typeof (first as { message?: unknown }).message === "string") {
-        return (first as { message: string }).message
-      }
-    }
-    if (typeof b.message === "string") return b.message
-  }
-  return `Request failed with status ${status}`
-}
-
-type RequestOptions = { method?: string, body?: unknown, token?: string }
-
-export const apiRequest = async <T = unknown>(apiUrl: string, path: string, opts: RequestOptions = {}): Promise<T> => {
-  const headers: Record<string, string> = {}
-  const isForm = opts.body instanceof FormData
-  if (opts.token) headers["Authorization"] = "Bearer " + opts.token
-  if (opts.body !== undefined && !isForm) headers["Content-Type"] = "application/json"
-
-  let resp: Response
-  try {
-    resp = await fetch(`${apiUrl}/api${path}`, {
-      method: opts.method ?? (opts.body !== undefined ? "POST" : "GET"),
-      headers,
-      body: opts.body === undefined ? undefined : isForm ? (opts.body as FormData) : JSON.stringify(opts.body),
-    })
-  } catch (e) {
-    throw new CliError(`Cannot reach ${apiUrl} — is the server URL correct and online?`)
-  }
-
-  const contentType = resp.headers.get("content-type") ?? ""
-  const parsed: unknown = contentType.startsWith("application/json") ? await resp.json()
-    : contentType.startsWith("text/") ? await resp.text()
-    : null
-
-  if (resp.status >= 400) throw new CliError(errorMessage(parsed, resp.status), resp.status)
-  return parsed as T
-}
-
-export const login = (apiUrl: string, login: string, password: string) =>
-  apiRequest<{ accessToken: string, refreshToken: string }>(apiUrl, "/account/login", { body: { login, password } })
-
-export const createAccessToken = (apiUrl: string, jwt: string, name: string) =>
-  apiRequest<{ id: number, name: string, prefix: string, token: string }>(apiUrl, "/account/tokens", { token: jwt, body: { name } })
-
-export const getAccount = (apiUrl: string, token: string) =>
-  apiRequest<{ id: number, name: string, email: string }>(apiUrl, "/account", { token })
-
-export const getProject = (apiUrl: string, token: string, uuid: string) =>
-  apiRequest<Project>(apiUrl, `/projects/${uuid}`, { token })
-
-/** Create a new (empty) project on the server. Returns its uuid. */
-export const createProject = (apiUrl: string, token: string, name: string, teamUuid?: string) =>
-  apiRequest<{ uuid: string }>(apiUrl, "/projects", { token, body: { name, teamUuid } })
-
-export const getCommits = (apiUrl: string, token: string, uuid: string) =>
-  apiRequest<CommitsResponse>(apiUrl, `/projects/${uuid}/commits`, { token })
-
-export const getTypes = (apiUrl: string) =>
-  apiRequest<Record<string, string>>(apiUrl, "/types")
-
-export const uploadBlob = (apiUrl: string, token: string, uuid: string, name: string, bytes: Uint8Array) => {
-  const form = new FormData()
-  // Cast is type-only (TS 5.7 typed-array generics vs the Blob signature); Blob accepts a Uint8Array.
-  form.append("file", new Blob([bytes as unknown as ArrayBuffer]), name)
-  return apiRequest<{ id: number, src: string, size: number }>(apiUrl, `/projects/${uuid}/blobs`, { token, body: form })
-}
-
-export const sync = (apiUrl: string, token: string, uuid: string, payload: { message: string, files: SyncFileInput[], folders: SyncFolderInput[], publish?: boolean }) =>
-  apiRequest<SyncResponse>(apiUrl, `/projects/${uuid}/sync`, { token, body: payload })
-
-/** Deploy the project's current server state (compile → live bundle). Used by `push --publish` when
- *  there are no file changes to sync. */
-export const publishProject = (apiUrl: string, token: string, uuid: string) =>
-  apiRequest<{ published: boolean, size: number }>(apiUrl, `/projects/${uuid}/publish`, { token, body: {} })
-
-export type DesignShare = {
-  token: string | null
-  url: string | null
-  /** Whether share-link visitors may WRITE comments (reading is never gated on it). */
-  commentsOpen?: boolean
-}
-
-/** Current public share-link state for a project's design board. */
-export const getDesignShare = (apiUrl: string, token: string, uuid: string) =>
-  apiRequest<DesignShare>(apiUrl, `/projects/${uuid}/design/share`, { token })
-
-/** Enable the design share link (idempotent). */
-export const enableDesignShare = (apiUrl: string, token: string, uuid: string) =>
-  apiRequest<DesignShare>(apiUrl, `/projects/${uuid}/design/share`, { token, body: {} })
-
-/** Revoke the design share link. */
-export const disableDesignShare = (apiUrl: string, token: string, uuid: string) =>
-  apiRequest<DesignShare>(apiUrl, `/projects/${uuid}/design/share`, { token, method: "DELETE" })
-
-/** Let / stop share-link visitors WRITING comments. Reading the existing conversation is unaffected,
- *  so switching this off never hides feedback that already arrived. */
-export const setDesignCommentsOpen = (apiUrl: string, token: string, uuid: string, open: boolean) =>
-  apiRequest<{ commentsOpen: boolean }>(apiUrl, `/projects/${uuid}/design/comments/open`, { token, body: { open } })
-
-/* ---- Design-board comments (docs/design-comments-plan.md) ---------------------------------
- * The platform is the source of truth; `design/comments/` (one file per thread) is the mirror the
- * running `lecodes design` sync — or `comments pull` — fills. The shapes below are the same
- * document the design package's core defines —
- * spelled out here, like every other DTO in this file, because `lecodes-design` is an optional
- * peer the CLI must typecheck and run without. */
-
-export type CommentAnchor = {
-  screen?: string
-  state?: string
-  element?: string
-  point?: [number, number]
-  world?: [number, number]
-}
-export type CommentMessage = {
-  id: string
-  author: string
-  /** Provenance: `share` = unverified stranger on the link, `ai` = Claude on a member's behalf. */
-  origin: "share" | "editor" | "cli" | "ai"
-  at: string
-  body: string
-  editedAt?: string
-  mine?: boolean
-}
-export type CommentThread = {
-  id: string
-  number: number
-  anchor: CommentAnchor
-  resolved: boolean
-  resolvedAt?: string | null
-  createdAt: string
-  updatedAt: string
-  commitId?: number | null
-  messages: CommentMessage[]
-  mine?: boolean
-}
-
-export type DesignCommentsSnapshot = {
-  threads: CommentThread[]
-  cursor: string | null
-  canComment: boolean
-  shared?: boolean
-  commentsOpen?: boolean
-  /** The project's thread-number allocator, so a pull can't hand out a used number. */
-  nextNumber?: number
-}
-
-export const listDesignComments = (apiUrl: string, token: string, uuid: string) =>
-  apiRequest<DesignCommentsSnapshot>(apiUrl, `/projects/${uuid}/design/comments`, { token })
-
-/** `origin` is provenance, carried up so a reply Claude wrote doesn't reach the reviewer looking
- *  like one the developer typed. The account is the identity either way; the server rejects any
- *  value but `cli` / `ai` / `editor`. */
-export const createDesignComment = (
-  apiUrl: string, token: string, uuid: string,
-  input: { anchor: CommentAnchor, body: string, origin?: CommentMessage["origin"] },
-) => apiRequest<CommentThread>(apiUrl, `/projects/${uuid}/design/comments`, { token, body: input })
-
-export const replyDesignComment = (
-  apiUrl: string, token: string, uuid: string, threadId: string, body: string,
-  origin?: CommentMessage["origin"],
-) => apiRequest<CommentThread>(
-  apiUrl, `/projects/${uuid}/design/comments/${threadId}/messages`, { token, body: { body, origin } })
-
-export const resolveDesignComment = (apiUrl: string, token: string, uuid: string, threadId: string, resolved: boolean) =>
-  apiRequest<CommentThread>(apiUrl, `/projects/${uuid}/design/comments/${threadId}`, { token, method: "PATCH", body: { resolved } })
-
-export const deleteDesignComment = (apiUrl: string, token: string, uuid: string, threadId: string) =>
-  apiRequest<{ ok: boolean }>(apiUrl, `/projects/${uuid}/design/comments/${threadId}`, { token, method: "DELETE" })
-
-/** Re-anchor a pin. The anchor goes up whole — `element` is replaced, never merged, or a stale name
- *  silently re-anchors the pin to whatever else still answers to it. */
-export const moveDesignComment = (
-  apiUrl: string, token: string, uuid: string, threadId: string, anchor: CommentAnchor,
-) => apiRequest<CommentThread>(apiUrl, `/projects/${uuid}/design/comments/${threadId}`, {
-  token,
-  method: "PATCH",
-  body: { screen: anchor.screen, state: anchor.state, element: anchor.element, point: anchor.point },
-})
-
-export const editDesignCommentMessage = (
-  apiUrl: string, token: string, uuid: string, threadId: string, messageId: string, body: string,
-) => apiRequest<CommentThread>(
-  apiUrl, `/projects/${uuid}/design/comments/${threadId}/messages/${messageId}`, { token, method: "PATCH", body: { body } })
-
-export const deleteDesignCommentMessage = (
-  apiUrl: string, token: string, uuid: string, threadId: string, messageId: string,
-) => apiRequest<{ threadRemoved: boolean }>(
-  apiUrl, `/projects/${uuid}/design/comments/${threadId}/messages/${messageId}`, { token, method: "DELETE" })
-
-/* ---- Push notifications (`lecodes pn`, docs/push-plan.md) ---------------------------------
- * Every call here authenticates with the stored PAT: /push/send accepts a developer-role user
- * token exactly like a project push key, so test sends need no key at all. Keys are minted for
- * ONE purpose — the developer's own production server — and only an owner can manage them. */
-
-export type PushSendPayload = {
-  to?: string[]
-  users?: string[]
-  title: string
-  body?: string
-  url?: string
-  data?: Record<string, unknown>
-  badge?: number
-}
-export type PushSendResult = { sent: number, failed: { address: string, reason: string }[] }
-
-export type PushDevice = {
-  address: string
-  platform: "apns" | "fcm" | "webpush"
-  environment: "production" | "sandbox"
-  hostApp: string
-  user: string | null
-  createdAt: string
-  lastSeenAt: string
-  disabledAt: string | null
-}
-
-export type PushKey = {
-  id: number
-  name: string
-  prefix: string
-  createdAt: string
-  lastUsedAt: string | null
-}
-/** Only the mint response carries `key` — the plaintext exists in this one response and nowhere else. */
-export type CreatedPushKey = PushKey & { key: string }
-
-export const sendPush = (apiUrl: string, token: string, uuid: string, payload: PushSendPayload) =>
-  apiRequest<PushSendResult>(apiUrl, `/projects/${uuid}/push/send`, { token, body: payload })
-
-export const listPushDevices = (apiUrl: string, token: string, uuid: string, user?: string) =>
-  apiRequest<{ devices: PushDevice[], truncated: boolean }>(
-    apiUrl, `/projects/${uuid}/push/registrations${user ? `?user=${encodeURIComponent(user)}` : ""}`, { token })
-
-export const forgetPushDevice = (apiUrl: string, token: string, uuid: string, address: string) =>
-  apiRequest<void>(apiUrl, `/projects/${uuid}/push/registrations/${encodeURIComponent(address)}`, { token, method: "DELETE" })
-
-export const listPushKeys = (apiUrl: string, token: string, uuid: string) =>
-  apiRequest<PushKey[]>(apiUrl, `/projects/${uuid}/push/keys`, { token })
-
-export const createPushKey = (apiUrl: string, token: string, uuid: string, name?: string) =>
-  apiRequest<CreatedPushKey>(apiUrl, `/projects/${uuid}/push/keys`, { token, body: { name } })
-
-export const revokePushKey = (apiUrl: string, token: string, uuid: string, id: number) =>
-  apiRequest<void>(apiUrl, `/projects/${uuid}/push/keys/${id}`, { token, method: "DELETE" })
-
-export const downloadBlob = async (apiUrl: string, src: string): Promise<Uint8Array> => {
-  const resp = await fetch(`${apiUrl}${src}`)
-  if (!resp.ok) throw new CliError(`Failed to download ${src} (status ${resp.status})`)
-  return new Uint8Array(await resp.arrayBuffer())
-}
+export * from "./platform/api"

package/src/cli/args.ts

@@ -0,0 +1,37 @@
+/*
+ * The argv grammar, shared by every command:
+ *   --key value   --key=value   --flag   -k value   -k     positionals anywhere
+ * A token that starts with "-" followed by a digit (or ".5") is a negative NUMBER (or a vector
+ * starting with one: `--look-at -0.15,1,2`), never the next flag. A repeated flag keeps the LAST
+ * value (list-valued flags take commas). `--` ends flag parsing.
+ */
+
+export type RawFlags = Record<string, string | boolean>
+export type Parsed = { positional: string[], flags: RawFlags }
+
+const isNegativeNumber = (s: string): boolean => /^-(\d|\.\d)/.test(s)
+const isValue = (s: string): boolean => !s.startsWith("-") || isNegativeNumber(s)
+
+export const parseArgv = (argv: string[]): Parsed => {
+  const out: Parsed = { positional: [], flags: {} }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === "--") { out.positional.push(...argv.slice(i + 1)); break }
+    const long = arg.startsWith("--"), short = !long && arg.startsWith("-") && arg.length > 1 && !isNegativeNumber(arg)
+    if (!long && !short) { out.positional.push(arg); continue }
+    if (long) {
+      const eq = arg.indexOf("=")
+      if (eq >= 0) { out.flags[arg.slice(2, eq)] = arg.slice(eq + 1); continue }
+    }
+    const key = arg.slice(long ? 2 : 1)
+    const next = argv[i + 1]
+    if (next !== undefined && isValue(next)) { out.flags[key] = next; i++ }
+    else out.flags[key] = true
+  }
+  return out
+}
+
+// Output targets that mean "discard" — so `-o /dev/null` (or Windows NUL) doesn't create a real file.
+const NULL_SINKS = new Set(["/dev/null", "nul", "//./nul"])
+/** True if an `--out` value is a null device, i.e. the output should be thrown away, not written. */
+export const isNullSink = (path: string): boolean => NULL_SINKS.has(path.trim().replace(/\\/g, "/").toLowerCase())

package/src/cli/command.ts

@@ -0,0 +1,113 @@
+import { CliError } from "./errors"
+import type { RawFlags } from "./args"
+
+/*
+ * A command is DATA: its name, one summary line, the flags it takes, its subcommands, and `run`.
+ * The runner (run.ts) builds the command tree from it, the help (help.ts) renders it, and the
+ * flags arrive in `run` already typed — a misspelled flag name in the code is a compile error, a
+ * misspelled one on the command line is a warning naming the real ones.
+ *
+ *   export default defineCommand({
+ *     name: "push",
+ *     summary: "Push local changes as one new checkpoint",
+ *     flags: {
+ *       message: str("checkpoint message", { alias: "m", value: "<text>" }),
+ *       force: bool("push even if the server moved on"),
+ *     },
+ *     run: async ({ flags }) => { … flags.message: string | undefined, flags.force: boolean … },
+ *   })
+ *
+ * Flag names are their command-line spelling (`"no-header"`, `"public-url"`); read them as
+ * `flags["no-header"]`. Groups of flags several commands share are plain objects spread into
+ * `flags:` (see `../commands/shared`).
+ */
+
+export type FlagSpec =
+  | { type: "string", help: string, value?: string, alias?: string, default?: string, optional?: boolean }
+  | { type: "number", help: string, value?: string, alias?: string, default?: number }
+  | { type: "boolean", help: string, alias?: string }
+
+export type Flags = Record<string, FlagSpec>
+
+type Opts<D> = { alias?: string, value?: string, default?: D }
+// The helpers are generic in their options so a literal `default` survives into the flag's type:
+// `num("…", { default: 4488 })` reads as `number`, a plain `num("…")` as `number | undefined`.
+/** A string-valued flag (`--out <file>`). `value` is the placeholder shown in help. `optional: true`
+ *  lets the flag stand alone (`--png` as well as `--png shot.png`): a bare one reads as `""`. */
+export const str = <O extends Opts<string> & { optional?: boolean }>(help: string, opts?: O): { type: "string", help: string } & O => ({ type: "string", help, ...(opts as O) })
+/** A numeric flag — parsed and validated for you (`--port 4499`). */
+export const num = <O extends Opts<number>>(help: string, opts?: O): { type: "number", help: string } & O => ({ type: "number", help, ...(opts as O) })
+/** A switch (`--force`). */
+export const bool = <O extends { alias?: string }>(help: string, opts?: O): { type: "boolean", help: string } & O => ({ type: "boolean", help, ...(opts as O) })
+
+type ValueOf<S extends FlagSpec> =
+  S extends { type: "boolean" } ? boolean
+  : S extends { type: "number" } ? (S extends { default: number } ? number : number | undefined)
+  : S extends { default: string } ? string : string | undefined
+
+export type FlagValues<F extends Flags> = { [K in keyof F]: ValueOf<F[K]> }
+
+export type Context<F extends Flags = Flags> = {
+  /** Positional arguments after the command path. */
+  args: string[]
+  /** The declared flags, typed and validated. */
+  flags: FlagValues<F>
+  /** Every flag as parsed, declared or not — for helpers shared between commands. Prefer `flags`. */
+  raw: RawFlags
+  /** The argv after the command path, untouched — what a `passthrough` command forwards. */
+  argv: string[]
+  /** The command path that was run (`["app", "keystore", "create"]`). */
+  path: string[]
+}
+
+export type Command<F extends Flags = Flags> = {
+  name: string
+  /** One line for the command list. */
+  summary: string
+  /** The positional syntax after the name: `"<uuid|url> [dir]"`. Omit for none. */
+  usage?: string
+  /** Paragraphs for `lecodes <name> --help`; blank lines separate paragraphs. */
+  description?: string
+  flags?: F
+  commands?: Command<any>[]
+  examples?: string[]
+  /** Other names that run this command (kept out of the help). */
+  aliases?: string[]
+  /** Left out of every command list (still runs). */
+  hidden?: boolean
+  /** The command parses its own argv (`ctx.argv`): unknown flags are not checked. */
+  passthrough?: boolean
+  /** What runs. A command with subcommands and no `run` prints its help when called bare. */
+  run?: (ctx: Context<F>) => Promise<void> | void
+}
+
+export const defineCommand = <F extends Flags>(cmd: Command<F>): Command<F> => cmd
+
+/** The typed values for a flag set from the raw parse; numbers validated, defaults applied. */
+export const readFlags = <F extends Flags>(spec: F, raw: RawFlags, path: string[]): FlagValues<F> => {
+  const out: Record<string, unknown> = {}
+  const where = `lecodes ${path.join(" ")}`
+  for (const [name, s] of Object.entries(spec)) {
+    const present = raw[name] !== undefined ? raw[name] : s.alias !== undefined && raw[s.alias] !== undefined ? raw[s.alias] : undefined
+    if (s.type === "boolean") { out[name] = present === true || present === "true"; continue }
+    if (present === undefined) { out[name] = s.default; continue }
+    if (present === true) {
+      if (s.type === "number" && s.default !== undefined) { out[name] = s.default; continue }
+      if (s.type === "string" && s.optional) { out[name] = ""; continue }
+      throw new CliError(`${where}: --${name} needs a value${s.value ? ` (${s.value})` : ""}`)
+    }
+    if (s.type === "number") {
+      const n = Number(present)
+      if (!Number.isFinite(n)) throw new CliError(`${where}: --${name} must be a number (got "${present}")`)
+      out[name] = n
+    } else out[name] = present
+  }
+  return out as FlagValues<F>
+}
+
+/** Flags on the line that no spec names — reported as a warning by the runner. */
+export const unknownFlags = (spec: Flags, raw: RawFlags): string[] => {
+  const known = new Set<string>()
+  for (const [name, s] of Object.entries(spec)) { known.add(name); if (s.alias) known.add(s.alias) }
+  return Object.keys(raw).filter(k => !known.has(k))
+}

package/src/cli/errors.ts

@@ -0,0 +1,13 @@
+/** A user-facing error: the runner prints its message without a stack trace and exits non-zero. */
+export class CliError extends Error {
+  /** HTTP status, when the failure came from the API. Lets a caller tell "already gone" (404) from
+   *  "refused" (403) — deleting something the server no longer has is a success, not an error. */
+  status?: number
+  constructor(message: string, status?: number) {
+    super(message)
+    this.status = status
+  }
+}
+
+/** A "how do I call this" mistake: the runner prints the message AND the command's help. */
+export class UsageError extends CliError {}

package/src/cli/help.ts

@@ -0,0 +1,158 @@
+import type { Command, FlagSpec } from "./command"
+import { c } from "./output"
+
+/*
+ * Two levels of help, both rendered from the command objects:
+ *   lecodes --help             the command list, grouped, one line each
+ *   lecodes <cmd> [sub] --help usage, description, options, subcommands, examples of that node
+ * Nothing here is hand-written per command; a command's help is its definition.
+ */
+
+export type Group = { title: string, commands: Command<any>[] }
+
+const WIDTH = Math.min(100, Math.max(60, process.stdout.columns ?? 90))
+
+/** Wrap a paragraph to `width`, continuation lines indented by `indent`. */
+const wrap = (text: string, width: number, indent = ""): string[] => {
+  const lines: string[] = []
+  for (const para of text.split("\n")) {
+    if (!para.trim()) { lines.push(""); continue }
+    let line = ""
+    for (const word of para.split(/\s+/)) {
+      if (line && (line + " " + word).length > width) { lines.push(line); line = indent + word }
+      else line = line ? line + " " + word : word
+    }
+    if (line) lines.push(line)
+  }
+  return lines
+}
+
+/** `-o, --out <file>` for a flag. */
+const flagLabel = (name: string, s: FlagSpec): string => {
+  const alias = s.alias ? `-${s.alias}, ` : ""
+  const value = s.type === "boolean" ? "" : ` ${s.value ?? (s.type === "number" ? "<n>" : "<value>")}`
+  return `${alias}--${name}${value}`
+}
+
+/** Two-column rows: label, then help wrapped into the remaining width. */
+const columns = (rows: [string, string][], indent = "  "): string[] => {
+  if (rows.length === 0) return []
+  const labelWidth = Math.min(30, Math.max(...rows.map(([l]) => l.length)))
+  const out: string[] = []
+  for (const [label, help] of rows) {
+    const textWidth = WIDTH - indent.length - labelWidth - 2
+    const text = wrap(help, textWidth)
+    if (label.length > labelWidth) {
+      out.push(indent + label)
+      for (const t of text) out.push(indent + " ".repeat(labelWidth + 2) + t)
+    } else {
+      out.push(indent + label.padEnd(labelWidth) + "  " + (text[0] ?? ""))
+      for (const t of text.slice(1)) out.push(indent + " ".repeat(labelWidth + 2) + t)
+    }
+  }
+  return out
+}
+
+const visible = (cmds: Command<any>[] | undefined): Command<any>[] => (cmds ?? []).filter(x => !x.hidden)
+
+/** The usage line: `lecodes app keystore create [--alias <a>] …` shortened to `[options]`. */
+const usageLine = (path: string[], cmd: Command<any>): string => {
+  const parts = ["lecodes", ...path]
+  if (cmd.usage) parts.push(cmd.usage)
+  if (visible(cmd.commands).length) parts.push(cmd.run ? "[command]" : "<command>")
+  if (cmd.flags && Object.keys(cmd.flags).length) parts.push("[options]")
+  return parts.join(" ")
+}
+
+/** `lecodes <path> --help`. */
+export const commandHelp = (path: string[], cmd: Command<any>): string => {
+  const lines: string[] = []
+  lines.push(`${c.bold(usageLine(path, cmd))}`)
+  lines.push(...wrap(cmd.summary, WIDTH - 2).map(l => "  " + l))
+  if (cmd.description) { lines.push(""); lines.push(...wrap(cmd.description, WIDTH - 2).map(l => l ? "  " + l : "")) }
+  const subs = visible(cmd.commands)
+  if (subs.length) {
+    lines.push("", c.bold("Commands"))
+    lines.push(...columns(subs.map(s => [s.usage ? `${s.name} ${s.usage}` : s.name, s.summary])))
+    lines.push("", c.dim(`  lecodes ${path.join(" ")} <command> --help for a command's options`))
+  }
+  const flags = Object.entries(cmd.flags ?? {}) as [string, FlagSpec][]
+  if (flags.length) {
+    lines.push("", c.bold("Options"))
+    lines.push(...columns(flags.map(([n, s]) => {
+      const def = "default" in s && s.default !== undefined ? c.dim(` (default ${s.default})`) : ""
+      return [flagLabel(n, s), s.help + def]
+    })))
+  }
+  if (cmd.examples?.length) {
+    lines.push("", c.bold("Examples"))
+    for (const e of cmd.examples) lines.push("  " + e)
+  }
+  return lines.join("\n")
+}
+
+/** `lecodes --help`: the grouped command list. */
+export const globalHelp = (version: string, groups: Group[], footer = ""): string => {
+  const lines: string[] = []
+  lines.push(`${c.bold("lecodes")} ${version} — build, run and ship LeCodes projects from your machine.`)
+  lines.push("", `${c.bold("Usage:")} lecodes <command> [options]`)
+  for (const g of groups) {
+    const cmds = visible(g.commands)
+    if (!cmds.length) continue
+    lines.push("", c.bold(g.title))
+    lines.push(...columns(cmds.map(x => [x.usage ? `${x.name} ${x.usage}` : x.name, x.summary])))
+  }
+  lines.push("", `Run ${c.bold("lecodes <command> --help")} for a command's options and examples.`)
+  if (footer) lines.push("", ...wrap(footer, WIDTH))
+  return lines.join("\n")
+}
+
+/** One command in `docs/commands.json`: `path` is what follows `lecodes` ("desktop run"). */
+export type CommandIndexEntry = { path: string, usage: string, summary: string, commands: CommandIndexEntry[] }
+export type CommandIndex = { groups: { title: string, slug: string, commands: CommandIndexEntry[] }[] }
+
+/**
+ * The tree as DATA — `docs/commands.json`, next to the Markdown reference and generated by the same
+ * script. Its reader is the le.codes site: /llms.txt lists every command with its summary line from
+ * here, and links each group to the matching `## ` section of the reference by `slug`. A summary
+ * written for `lecodes --help` is therefore also what a coding agent decides on — keep it a full
+ * answer to "what is this for", not a label.
+ */
+export const commandIndex = (groups: Group[]): CommandIndex => {
+  const entry = (path: string[], cmd: Command<any>): CommandIndexEntry => ({
+    path: path.join(" "), usage: cmd.usage ?? "", summary: cmd.summary,
+    commands: visible(cmd.commands).map(s => entry([...path, s.name], s)),
+  })
+  return {
+    groups: groups.map(g => ({
+      title: g.title,
+      slug: g.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, ""),
+      commands: visible(g.commands).map(cmd => entry([cmd.name], cmd)),
+    })),
+  }
+}
+
+/** The whole tree as Markdown — `docs/commands.md` is generated from this (scripts/gen-docs.ts). */
+export const markdownReference = (groups: Group[]): string => {
+  const out: string[] = ["# lecodes — command reference", "", "Generated from the command definitions by `bun run docs`; do not edit by hand.", ""]
+  const section = (path: string[], cmd: Command<any>, depth: number): void => {
+    out.push(`${"#".repeat(Math.min(6, depth))} \`${["lecodes", ...path].join(" ")}${cmd.usage ? " " + cmd.usage : ""}\``, "")
+    out.push(cmd.summary + (cmd.description ? "\n\n" + cmd.description : ""), "")
+    const flags = Object.entries(cmd.flags ?? {}) as [string, FlagSpec][]
+    if (flags.length) {
+      out.push("| Option | Meaning |", "|---|---|")
+      for (const [n, s] of flags) {
+        const def = "default" in s && s.default !== undefined ? ` (default \`${s.default}\`)` : ""
+        out.push(`| \`${flagLabel(n, s)}\` | ${s.help.replace(/\|/g, "\\|")}${def} |`)
+      }
+      out.push("")
+    }
+    if (cmd.examples?.length) { out.push("```", ...cmd.examples, "```", "") }
+    for (const s of visible(cmd.commands)) section([...path, s.name], s, depth + 1)
+  }
+  for (const g of groups) {
+    out.push(`## ${g.title}`, "")
+    for (const cmd of visible(g.commands)) section([cmd.name], cmd, 3)
+  }
+  return out.join("\n")
+}

package/src/cli/index.ts

@@ -0,0 +1,7 @@
+/* The command framework — what every command file imports. See CONTRIBUTING.md. */
+export { isNullSink, parseArgv, type RawFlags } from "./args"
+export { bool, defineCommand, num, readFlags, str, type Command, type Context, type Flags, type FlagValues } from "./command"
+export { CliError, UsageError } from "./errors"
+export { commandHelp, commandIndex, globalHelp, markdownReference, type CommandIndex, type Group } from "./help"
+export { c, confirm, endProgress, info, log, logErr, note, printedWidth, progress, prompt, promptHidden, relativeTime, success, table, warn, warnErr } from "./output"
+export { reportError, runCli, type Cli } from "./run"