lecodes-cli 0.20.2 → 2.0.0

package/src/commands/navmesh.ts

@@ -1,11 +1,11 @@
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { basename, join, relative, resolve } from "node:path"
-import { findProjectRoot } from "../manifest"
 import { buildBundle } from "./compile"
-import { readAppConfigAt, resolveDesktopRenderer } from "./appShared"
-import { runDesktopRender } from "../desktopRenderer"
-import { CliError, c, flagStr, flagBool, logErr, note, warnErr, type Args } from "../util"
+import { readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
+import { runDesktopRender } from "../hosts/desktopRenderer"
+import { CliError, bool, c, defineCommand, logErr, note, num, str, warnErr } from "../cli"
+import { bundleFlags, bundleOptions, localProject } from "./shared"
 import { loadCreatorNav, NavBuilder, readNgeo, navMeshTriangles, type BuildParams } from "lecodes-creator-nav"
 
 /*
@@ -22,15 +22,18 @@ import { loadCreatorNav, NavBuilder, readNgeo, navMeshTriangles, type BuildParam
  *
  * Running the build in the CLI keeps the host generic (a geometry dump, useful on its own),
  * lets the bake parameters iterate without a host rebuild, and is the same code a future headless
- * bake reuses. The desktop host must know the dump (built from packages/desktop, or a release that
+ * bake reuses. The desktop host must know the dump (built from hosts/desktop, or a release that
  * ships it: LECODES_DESKTOP_EXE for a local build until then).
+ *
+ * The agent size (--radius/--height/--climb/--slope) defaults to what the scene declares — the
+ * host's `[navmesh] config` line carries it — so those flags have no static default.
  */
 
-const num = (args: Args, key: string, fallback: number, min: number, max: number): number => {
-  const raw = flagStr(args, key)
-  if (raw === undefined) return fallback
-  const n = Number(raw)
-  if (!Number.isFinite(n) || n < min || n > max) throw new CliError(`--${key} wants a number in ${min}..${max}, got "${raw}".`)
+/** A numeric flag Recast gets: the framework parses it, the range is checked here. `fallback` is
+ *  the scene's value for the agent-size flags. */
+const range = (name: string, value: number | undefined, fallback: number, min: number, max: number): number => {
+  const n = value ?? fallback
+  if (n < min || n > max) throw new CliError(`--${name} wants a number in ${min}..${max}, got "${n}".`)
   return n
 }
 
@@ -85,141 +88,168 @@ const writeObj = (path: string, tris: Float32Array): void => {
   writeFileSync(path, lines.join("\n") + "\n")
 }
 
-const bake = async (args: Args): Promise<void> => {
-  let root: string
-  try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() }
-  const outDir = resolve(root, flagStr(args, "out") ?? "assets/nav")
-  const entryFlag = flagStr(args, "entry")
-  const entryFile = entryFlag ?? "main.ts"
-  if (!existsSync(resolve(root, entryFile))) {
-    throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the level: a scene file with env.navmesh, or code calling NavMesh.load).`)
-  }
-  const name = flagStr(args, "name") ?? guessName(root) ?? "scene"
-  const frames = num(args, "frames", 900, 30, 100000)
-  const win = readAppConfigAt(root)?.desktop?.window
-  const width = Number(flagStr(args, "width")) || win?.width || 1280
-  const height = Number(flagStr(args, "height")) || win?.height || 720
-  const logs = flagBool(args, "logs")
-  const keepGeometry = flagBool(args, "keep-geometry")
-  const obj = flagBool(args, "obj")
-
-  // The navmesh file must exist BEFORE the compile: the scene references it through asset(), and a
-  // missing asset is a broken bundle. The first bake starts from a placeholder the real file overwrites.
-  mkdirSync(outDir, { recursive: true })
-  const navmeshPath = join(outDir, `${name}.navmesh`)
-  if (!existsSync(navmeshPath)) writeFileSync(navmeshPath, placeholderLnav())
+const bake = defineCommand({
+  name: "bake",
+  summary: "Build the level's navigation mesh for NavAgent / NavMesh",
+  description: "The desktop host dumps every STATIC body's collision triangles at the scene's env.navmesh (or NavMesh.load) point, then Recast builds the tiled mesh here → <out>/<name>.navmesh. The agent size defaults to what the scene declares. Needs a desktop host with the geometry dump (LECODES_DESKTOP_EXE for a local build).",
+  flags: {
+    out: str("where it lands", { value: "<dir>", default: "assets/nav" }),
+    name: str("file name (default: the scene file that declares navmesh:, else scene)", { value: "<n>" }),
+    ...bundleFlags,
+    entry: str("the file that builds the level: a scene file with env.navmesh, or code calling NavMesh.load", { value: "<file>", default: "main.ts" }),
+    radius: num("agent radius (m; default: the scene's)"),
+    height: num("agent height (m; default: the scene's)"),
+    climb: num("agent max step height (m; default: the scene's)"),
+    slope: num("agent max walkable slope (deg; default: the scene's)"),
+    cell: num("voxel size (m)", { default: 0.25 }),
+    "cell-height": num("voxel height (m)", { default: 0.1 }),
+    tile: num("tile size (cells; 0 = one tile)", { default: 48 }),
+    "region-min": num("min region area (cells²)", { default: 8 }),
+    "region-merge": num("regions smaller than this merge (cells²)", { default: 20 }),
+    "edge-max": num("max polygon edge length (voxels)", { default: 12 }),
+    "edge-error": num("max edge simplification error (voxels)", { default: 1.3 }),
+    detail: num("detail mesh sample distance (voxels)", { default: 6 }),
+    "detail-error": num("detail mesh max error (voxels)", { default: 1 }),
+    obj: bool("also write <name>.navmesh.obj to inspect the polygons"),
+    "keep-geometry": bool("keep the host's <name>.navgeo dump"),
+    frames: num("host frames to run before giving up — load headroom", { default: 900 }),
+    timeout: num("host time cap (ms)", { default: 600000 }),
+    width: num("host window width (default: app.json desktop.window, else 1280)"),
+    renderer: str("desktop host + shader variant (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
+    logs: bool("forward the host's output"),
+  },
+  examples: ["lecodes navmesh bake", "lecodes navmesh bake --name yard --cell 0.2 --obj --logs"],
+  run: async ({ flags }) => {
+    const { root } = localProject()
+    const outDir = resolve(root, flags.out)
+    const entryFile = flags.entry
+    if (!existsSync(resolve(root, entryFile))) {
+      throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the level: a scene file with env.navmesh, or code calling NavMesh.load).`)
+    }
+    const name = flags.name ?? guessName(root) ?? "scene"
+    const frames = range("frames", flags.frames, 900, 30, 100000)
+    const win = readAppConfigAt(root)?.desktop?.window
+    const width = flags.width || win?.width || 1280
+    const height = win?.height || 720
+    const logs = flags.logs
 
-  const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "")
-  const entryPath = "/.navmesh-entry.ts"
-  const cfg = { outDir: outDir.replace(/\\/g, "/"), name }
-  const entryText = `globalThis.__lecodesNavmesh = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
+    // The navmesh file must exist BEFORE the compile: the scene references it through asset(), and a
+    // missing asset is a broken bundle. The first bake starts from a placeholder the real file overwrites.
+    mkdirSync(outDir, { recursive: true })
+    const navmeshPath = join(outDir, `${name}.navmesh`)
+    if (!existsSync(navmeshPath)) writeFileSync(navmeshPath, placeholderLnav())
 
-  const desktopRenderer = resolveDesktopRenderer(root, args)
-  const { js, resources } = await buildBundle(args, undefined, {
-    localAssets: true, desktopRenderer,
-    extraEntries: [{ path: entryPath, type: "text", text: entryText }],
-    entryOverride: entryPath,
-  })
+    const importPath = "./" + entryFile.replace(/\\/g, "/").replace(/\.tsx?$/, "")
+    const entryPath = "/.navmesh-entry.ts"
+    const cfg = { outDir: outDir.replace(/\\/g, "/"), name }
+    const entryText = `globalThis.__lecodesNavmesh = ${JSON.stringify(cfg)}\nimport ${JSON.stringify(importPath)}\n`
 
-  const scratch = mkdtempSync(join(tmpdir(), "lecodes-navmesh-"))
-  const outPng = join(scratch, "frame.png")
-  note(`Dumping the level's static collision geometry through the desktop host → ${relative(root, outDir) || "."}/${name}.navgeo…`)
-  let output = ""
-  try {
-    const timeoutMs = Number(flagStr(args, "timeout")) || 600000
-    const res = await runDesktopRender(js, resources, {
-      renderer: desktopRenderer, width, height, frames, outPng, logs, timeoutMs,
-      stopOnLine: (chunk) => chunk.includes("[navmesh] done") || chunk.includes("[navmesh] error"),
+    const desktopRenderer = resolveDesktopRenderer(root, flags.renderer)
+    const { js, resources } = await buildBundle(bundleOptions(flags), {
+      localAssets: true, desktopRenderer,
+      extraEntries: [{ path: entryPath, type: "text", text: entryText }],
+      entryOverride: entryPath,
     })
-    output = res.output
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e)
-    if (!/\[navmesh\] done/.test(msg)) throw e
-    output = msg
-  } finally {
-    rmSync(scratch, { recursive: true, force: true })
-  }
 
-  // the markers are console.log lines from the SDK — the host prefixes them ("[DEBUG] [navmesh] …")
-  const lines = output.split(/\r?\n/).filter((l) => l.includes("[navmesh]")).map((l) => l.slice(l.indexOf("[navmesh]")))
-  let config: BakeConfigLine | null = null
-  let triangles = 0
-  for (const l of lines) {
-    const text = l.slice("[navmesh]".length).trim()
-    if (text === "done") continue
-    if (text.startsWith("config ")) { try { config = JSON.parse(text.slice(7)) as BakeConfigLine } catch { /* reported below */ } continue }
-    const geo = /^geometry (\d+) triangles/.exec(text)
-    if (geo) triangles = Number(geo[1])
-    logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : c.dim(`  ${text}`))
-  }
-  if (!/\[navmesh\] done/.test(output)) {
-    if (lines.some((l) => /cannot dump collision geometry/.test(l))) {
-      throw new CliError("This desktop host has no collision-geometry dump. Build packages/desktop and point LECODES_DESKTOP_EXE at build/lecodes-desktop.exe, or update: lecodes desktop update.")
+    const scratch = mkdtempSync(join(tmpdir(), "lecodes-navmesh-"))
+    const outPng = join(scratch, "frame.png")
+    note(`Dumping the level's static collision geometry through the desktop host → ${relative(root, outDir) || "."}/${name}.navgeo…`)
+    let output = ""
+    try {
+      const res = await runDesktopRender(js, resources, {
+        renderer: desktopRenderer, width, height, frames, outPng, logs, timeoutMs: flags.timeout || 600000,
+        stopOnLine: (chunk) => chunk.includes("[navmesh] done") || chunk.includes("[navmesh] error"),
+      })
+      output = res.output
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      if (!/\[navmesh\] done/.test(msg)) throw e
+      output = msg
+    } finally {
+      rmSync(scratch, { recursive: true, force: true })
     }
-    if (lines.some((l) => /error/.test(l))) throw new CliError("The bake failed — see the lines above.")
-    warnErr("The host ran to its frame cap without dumping geometry. Make sure the level declares `env.navmesh` (a scene file) or calls NavMesh.load(...) after its static bodies exist, and skips menus when NavMesh.baking is true. More load headroom: --frames <n>. Host output: --logs.")
-    throw new CliError("Nothing was baked.")
-  }
-  if (!config) throw new CliError("The host reported a dump but no `[navmesh] config` line — SDK/host mismatch?")
-  const geoPath = join(outDir, `${name}.navgeo`)
-  if (!existsSync(geoPath)) throw new CliError(`The host reported a dump but ${geoPath} is missing.`)
 
-  // ---- Recast (wasm) ----
-  const geo = readNgeo(new Uint8Array(readFileSync(geoPath)))
-  const params: BuildParams = {
-    agentRadius: num(args, "radius", config.agent.radius, 0.05, 10),
-    agentHeight: num(args, "height", config.agent.height, 0.1, 20),
-    agentMaxClimb: num(args, "climb", config.agent.climb, 0, 10),
-    agentMaxSlope: num(args, "slope", config.agent.slope, 0, 89),
-    cellSize: num(args, "cell", 0.25, 0.01, 5),
-    cellHeight: num(args, "cell-height", 0.1, 0.01, 5),
-    tileSize: num(args, "tile", 48, 0, 1024),
-    regionMinSize: num(args, "region-min", 8, 0, 1000),
-    regionMergeSize: num(args, "region-merge", 20, 0, 1000),
-    edgeMaxLen: num(args, "edge-max", 12, 0, 1000),
-    edgeMaxError: num(args, "edge-error", 1.3, 0.1, 10),
-    detailSampleDist: num(args, "detail", 6, 0, 100),
-    detailMaxError: num(args, "detail-error", 1, 0, 100),
-  }
-  note(`Building the navmesh: ${geo.triangleCount} triangles from ${geo.bodyCount} static bodies, agent r ${params.agentRadius} / h ${params.agentHeight} / climb ${params.agentMaxClimb} / slope ${params.agentMaxSlope}°, cell ${params.cellSize} m…`)
-  const mod = await loadCreatorNav()
-  const builder = new NavBuilder(mod, params)
-  let result
-  try {
-    builder.addSoup(geo.triangles, geo.areas)
-    const meta = {
-      scene: name, areas: config.areas, costs: config.costs, bakedAt: new Date().toISOString(),
-      params, triangles: geo.triangleCount, bodies: geo.bodyCount,
+    // the markers are console.log lines from the SDK — the host prefixes them ("[DEBUG] [navmesh] …")
+    const lines = output.split(/\r?\n/).filter((l) => l.includes("[navmesh]")).map((l) => l.slice(l.indexOf("[navmesh]")))
+    let config: BakeConfigLine | null = null
+    let triangles = 0
+    for (const l of lines) {
+      const text = l.slice("[navmesh]".length).trim()
+      if (text === "done") continue
+      if (text.startsWith("config ")) { try { config = JSON.parse(text.slice(7)) as BakeConfigLine } catch { /* reported below */ } continue }
+      const geo = /^geometry (\d+) triangles/.exec(text)
+      if (geo) triangles = Number(geo[1])
+      logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : c.dim(`  ${text}`))
     }
-    let lastTile = -1
-    result = builder.run(meta, (tile, count, message) => {
-      if (message) logErr(c.dim(`  recast: ${message}`))
-      else if (count > 8 && tile !== lastTile && (tile + 1) % Math.max(1, Math.floor(count / 8)) === 0) { lastTile = tile; logErr(c.dim(`  tile ${tile + 1}/${count}`)) }
-    })
-  } finally {
-    builder.destroy()
-  }
-  if (result.polys === 0) {
-    throw new CliError("The build produced no polygons — nothing walkable for this agent. Check the cell size against the level's scale, the slope, and that the floor is a STATIC body (Shape + Physics { motion: 'static' }).")
-  }
-  writeFileSync(navmeshPath, result.data)
-  if (obj) {
-    const objPath = join(outDir, `${name}.navmesh.obj`)
-    writeObj(objPath, navMeshTriangles(mod, result.data))
-    logErr(c.dim(`  wrote ${relative(root, objPath)} (the polygon mesh, for inspection)`))
-  }
-  if (!keepGeometry) unlinkSync(geoPath)
-  const kb = Math.round(statSync(navmeshPath).size / 1024)
-  const b = result.bounds
-  logErr(c.dim(`  ${result.tiles} tiles, ${result.polys} polygons, ${(b.max[0] - b.min[0]).toFixed(0)} × ${(b.max[2] - b.min[2]).toFixed(0)} m, ${result.time.toFixed(1)} s`))
-  logErr(c.green(`✓ baked → ${relative(root, navmeshPath).replace(/\\/g, "/")} (${kb} KB)`))
-  if (!config.data) {
-    logErr(c.dim(`  load it with env.navmesh: { data: asset('<rel>/${basename(navmeshPath)}') } in the scene file, or NavMesh.load(scene, { data: asset(...) })`))
-  }
-}
+    if (!/\[navmesh\] done/.test(output)) {
+      if (lines.some((l) => /cannot dump collision geometry/.test(l))) {
+        throw new CliError("This desktop host has no collision-geometry dump. Build hosts/desktop and point LECODES_DESKTOP_EXE at build/lecodes-desktop.exe, or update: lecodes desktop update.")
+      }
+      if (lines.some((l) => /error/.test(l))) throw new CliError("The bake failed — see the lines above.")
+      warnErr("The host ran to its frame cap without dumping geometry. Make sure the level declares `env.navmesh` (a scene file) or calls NavMesh.load(...) after its static bodies exist, and skips menus when NavMesh.baking is true. More load headroom: --frames <n>. Host output: --logs.")
+      throw new CliError("Nothing was baked.")
+    }
+    if (!config) throw new CliError("The host reported a dump but no `[navmesh] config` line — SDK/host mismatch?")
+    const geoPath = join(outDir, `${name}.navgeo`)
+    if (!existsSync(geoPath)) throw new CliError(`The host reported a dump but ${geoPath} is missing.`)
 
-export const navmesh = async (args: Args): Promise<void> => {
-  const sub = args._[0]
-  if (sub === "bake") return bake({ ...args, _: args._.slice(1) })
-  throw new CliError("Usage: lecodes navmesh bake [--out assets/nav] [--name <scene>] [--entry main.ts] [--radius 0.4] [--height 1.8] [--climb 0.4] [--slope 50] [--cell 0.25] [--cell-height 0.1] [--tile 48] [--obj] [--keep-geometry] [--frames 900] [--logs]")
-}
+    // ---- Recast (wasm) ----
+    const geo = readNgeo(new Uint8Array(readFileSync(geoPath)))
+    const params: BuildParams = {
+      agentRadius: range("radius", flags.radius, config.agent.radius, 0.05, 10),
+      agentHeight: range("height", flags.height, config.agent.height, 0.1, 20),
+      agentMaxClimb: range("climb", flags.climb, config.agent.climb, 0, 10),
+      agentMaxSlope: range("slope", flags.slope, config.agent.slope, 0, 89),
+      cellSize: range("cell", flags.cell, 0.25, 0.01, 5),
+      cellHeight: range("cell-height", flags["cell-height"], 0.1, 0.01, 5),
+      tileSize: range("tile", flags.tile, 48, 0, 1024),
+      regionMinSize: range("region-min", flags["region-min"], 8, 0, 1000),
+      regionMergeSize: range("region-merge", flags["region-merge"], 20, 0, 1000),
+      edgeMaxLen: range("edge-max", flags["edge-max"], 12, 0, 1000),
+      edgeMaxError: range("edge-error", flags["edge-error"], 1.3, 0.1, 10),
+      detailSampleDist: range("detail", flags.detail, 6, 0, 100),
+      detailMaxError: range("detail-error", flags["detail-error"], 1, 0, 100),
+    }
+    note(`Building the navmesh: ${geo.triangleCount} triangles from ${geo.bodyCount} static bodies, agent r ${params.agentRadius} / h ${params.agentHeight} / climb ${params.agentMaxClimb} / slope ${params.agentMaxSlope}°, cell ${params.cellSize} m…`)
+    const mod = await loadCreatorNav()
+    const builder = new NavBuilder(mod, params)
+    let result
+    try {
+      builder.addSoup(geo.triangles, geo.areas)
+      const meta = {
+        scene: name, areas: config.areas, costs: config.costs, bakedAt: new Date().toISOString(),
+        params, triangles: geo.triangleCount, bodies: geo.bodyCount,
+      }
+      let lastTile = -1
+      result = builder.run(meta, (tile, count, message) => {
+        if (message) logErr(c.dim(`  recast: ${message}`))
+        else if (count > 8 && tile !== lastTile && (tile + 1) % Math.max(1, Math.floor(count / 8)) === 0) { lastTile = tile; logErr(c.dim(`  tile ${tile + 1}/${count}`)) }
+      })
+    } finally {
+      builder.destroy()
+    }
+    if (result.polys === 0) {
+      throw new CliError("The build produced no polygons — nothing walkable for this agent. Check the cell size against the level's scale, the slope, and that the floor is a STATIC body (Shape + Physics { motion: 'static' }).")
+    }
+    writeFileSync(navmeshPath, result.data)
+    if (flags.obj) {
+      const objPath = join(outDir, `${name}.navmesh.obj`)
+      writeObj(objPath, navMeshTriangles(mod, result.data))
+      logErr(c.dim(`  wrote ${relative(root, objPath)} (the polygon mesh, for inspection)`))
+    }
+    if (!flags["keep-geometry"]) unlinkSync(geoPath)
+    const kb = Math.round(statSync(navmeshPath).size / 1024)
+    const b = result.bounds
+    logErr(c.dim(`  ${result.tiles} tiles, ${result.polys} polygons, ${(b.max[0] - b.min[0]).toFixed(0)} × ${(b.max[2] - b.min[2]).toFixed(0)} m, ${result.time.toFixed(1)} s`))
+    logErr(c.green(`✓ baked → ${relative(root, navmeshPath).replace(/\\/g, "/")} (${kb} KB)`))
+    if (!config.data) {
+      logErr(c.dim(`  load it with env.navmesh: { data: asset('<rel>/${basename(navmeshPath)}') } in the scene file, or NavMesh.load(scene, { data: asset(...) })`))
+    }
+  },
+})
+
+export default defineCommand({
+  name: "navmesh",
+  summary: "Build the level's navigation mesh (bake)",
+  commands: [bake],
+})

package/src/commands/plugin.ts

@@ -0,0 +1,46 @@
+import { CliError, bool, c, defineCommand, info, log, success } from "../cli"
+import { generate } from "../plugin/generate"
+
+/*
+ * `lecodes plugin` — for the AUTHOR of a native plugin (the app's side is `lecodes app`, which
+ * installs plugins into a shell).
+ *
+ *   plugin gen   a plugin's contract.d.ts → the generated files beside its hand-written ones.
+ *                The contract is the one description of the channel; what is generated from it is
+ *                committed, and `--check` is what a CI runs to refuse a stale file.
+ */
+
+const gen = defineCommand({
+  name: "gen",
+  summary: "Generate a plugin's files from its contract.d.ts (--check: fail on a stale one)",
+  usage: "[path]",
+  description: "The path is one plugin (a directory with a contract.d.ts) or a repo that keeps its plugins in plugins/<id>/; the current directory when omitted.\n\nWrites sdk/<id>.gen.ts — the wrapper an app calls: the wire call by call, the class with the wire's methods as its own, and the public export when the plugin has no hand-written sdk/<id>.ts. Where the plugin has an ios/ folder, writes ios/<Name>.gen.swift — the contract's types, the protocol the plugin implements and the glue that reads a call off the wire. Where it has an android/ folder, writes the same as <Name>.gen.kt into the folder of the plugin's Kotlin package (android/ is laid out as a Gradle module: the package is the folder the path under android/src/main/java narrows down to). Where it has a web/ folder, writes web/<id>.gen.ts — the same for the web half, in a file that imports nothing; a web half that imports a LeCodes package is refused, because it would run on that host only. A contract the generator does not understand is an error with its line, and every problem of a file is reported at once.\n\nGenerated files are committed. Reading a contract needs TypeScript in the plugin's repo.",
+  flags: {
+    check: bool("write nothing; exit 1 when a generated file is missing or stale"),
+  },
+  examples: ["lecodes plugin gen", "lecodes plugin gen plugins/camera", "lecodes plugin gen --check"],
+  run: ({ args, flags }) => {
+    const report = generate(args[0] ?? ".", { check: flags.check })
+
+    for (const p of report.plugins) {
+      const channels = p.contract.channels.map(ch => `${ch.kind} "${ch.name}" v${ch.version}`).join(", ")
+      info(`${c.bold(p.id)}  ${c.dim(channels)}`)
+      for (const f of p.written) log(c.green(`  written   ${f}`))
+      for (const f of p.stale) log(c.red(`  stale     ${f}`))
+      for (const f of p.fresh) log(c.dim(`  fresh     ${f}`))
+    }
+    for (const failure of report.failures) log(c.red(failure))
+
+    const stale = report.plugins.reduce((n, p) => n + p.stale.length, 0)
+    if (report.failures.length) throw new CliError(`${report.failures.length} contract${report.failures.length === 1 ? "" : "s"} did not generate.`)
+    if (stale) throw new CliError(`${stale} generated file${stale === 1 ? " is" : "s are"} stale — run \`lecodes plugin gen\` and commit.`)
+    success(flags.check ? "Every generated file is fresh." : "Generated.")
+  },
+})
+
+export default defineCommand({
+  name: "plugin",
+  summary: "Write a native plugin: gen",
+  description: "For the author of a plugin — a capability an app reaches the same way on iOS, Android and the web. `lecodes app` is the other side: it installs plugins into an app's shell.",
+  commands: [gen],
+})