lecodes-cli 2.5.1 → 2.8.0

package/src/commands/call.ts

@@ -0,0 +1,96 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { collectLocalEntries } from "../compile/collectLocal"
+import { callEndpoint, type CallDevice } from "../dev/backendCall"
+import { devRunBackend, findRunningDev } from "../dev/devLink"
+import { runBackend } from "../dev/projectBackend"
+import { filesDirOf } from "../dev/localBackend"
+import { LECODES_DIR } from "../project/manifest"
+import { CliError, bool, c, defineCommand, logErr, str } from "../cli"
+import { localProject } from "./shared"
+
+/*
+ * `lecodes call <id> [args…]` — call one endpoint of the project's backend from the terminal, as a device
+ * would (the transport's wire and first-call rule: src/dev/backendCall.ts), and print what it answered.
+ * While a `lecodes dev` of the project runs, the call goes to ITS backend — the one the phone plays on
+ * (devLink.ts: one backend per project); otherwise to the TEST backend (`lecodes test`'s: the database in
+ * .lecodes/test-db), started for the call. The database is kept from call to call (`lecodes test` empties
+ * the test one when it starts; `--reset` empties the one called), and so is the session of each `--as`
+ * name — one file per backend (.lecodes/dev-sessions.json, .lecodes/test-sessions.json): `--as ann` twice
+ * is one device.
+ */
+
+const SESSIONS_FILE = { dev: "dev-sessions.json", test: "test-sessions.json" }
+
+/** `["1234","Аня"]` (one JSON array) → the args; else every word is JSON, or a string when it is not. */
+export const parseCallArgs = (words: string[]): unknown[] => {
+  if (words.length === 1 && words[0].trim().startsWith("[")) {
+    try {
+      const all = JSON.parse(words[0])
+      if (Array.isArray(all)) return all
+    } catch { /* a word that happens to start with "[" */ }
+  }
+  return words.map((w) => { try { return JSON.parse(w) } catch { return w } })
+}
+
+export default defineCommand({
+  name: "call",
+  summary: "Call an endpoint of the project's backend (a running lecodes dev's, else the test one), as a device would",
+  usage: "<file#export> [args…]",
+  description: "Calls one server function (`game.server.ts#joinRoom`) and prints the result as JSON (an error: its status and message, exit 1). While a `lecodes dev` of the project runs, the call goes to its backend — the database the phone plays on; otherwise to the TEST backend, the one `lecodes test` runs on its own database (.lecodes/test-db), kept from call to call (`lecodes test` empties it when it starts). --reset empties the database called first (the running dev's, or the test one).\n\nArgs are JSON, one per word (a word that is not JSON is a string: `'\"1234\"'` for a string of digits), or one JSON array of them all. --as <name> calls as that device: its session token is kept per backend (.lecodes/dev-sessions.json, .lecodes/test-sessions.json), so `request.session` is the same from call to call; without --as every call is a new device.",
+  flags: {
+    as: str("call as this device (its session is kept between calls)", { value: "<name>" }),
+    reset: bool("empty the database called (a running dev's, else the test one) and forget its saved sessions first"),
+  },
+  examples: [
+    "lecodes call game.server.ts#clock",
+    "lecodes call game.server.ts#createRoom Аня --as ann",
+    "lecodes call game.server.ts#joinRoom '[\"1234\", \"Боб\"]' --as bob",
+  ],
+  run: async ({ args, flags }) => {
+    const [id, ...rest] = args
+    if (!id || !id.includes("#")) throw new CliError(`Name the endpoint: lecodes call <file>#<export> [args…] (e.g. "game.server.ts#joinRoom").`)
+    const callArgs = parseCallArgs(rest)
+    const { root } = localProject()
+    // one backend per project: a running dev's, else the test one
+    const dev = await findRunningDev(root)
+    const sessionsPath = join(root, LECODES_DIR, SESSIONS_FILE[dev ? "dev" : "test"])
+    if (flags.reset) {
+      if (!dev) {
+        const dbDir = join(root, LECODES_DIR, "test-db")
+        rmSync(dbDir, { recursive: true, force: true })
+        rmSync(filesDirOf(dbDir), { recursive: true, force: true })
+      }
+      rmSync(sessionsPath, { force: true })
+    }
+    const sessions: Record<string, string> = existsSync(sessionsPath) ? (() => { try { return JSON.parse(readFileSync(sessionsPath, "utf8")) } catch { return {} } })() : {}
+
+    const backend = dev ? devRunBackend(dev) : runBackend({ root, command: "lecodes call", test: true, keepTestDb: true, log: (msg) => { if (msg.includes("[server:")) logErr(msg) } })
+    try {
+      const { entries } = collectLocalEntries(root, null, "")
+      const url = await backend.start(entries, (w) => logErr(c.dim(w)))
+      if (!url) throw new CliError("This project has no server files (*.server.ts): there is nothing to call.")
+      if (dev) {
+        logErr(c.dim(`→ the running lecodes dev's backend (port ${dev.port})`))
+        if (flags.reset) await backend.reset()
+      }
+      let token: string | null = flags.as !== undefined ? sessions[flags.as] ?? null : null
+      const device: CallDevice = { token: () => token, store: (t) => { token = t } }
+      const out = await callEndpoint(url, id, callArgs, device)
+      if (flags.as !== undefined && token !== (sessions[flags.as] ?? null)) {
+        if (token) sessions[flags.as] = token
+        else delete sessions[flags.as]
+        mkdirSync(dirname(sessionsPath), { recursive: true })
+        writeFileSync(sessionsPath, JSON.stringify(sessions, null, 2) + "\n")
+      }
+      if (!out.ok) {
+        logErr(`${c.red("✗")} ${id}: ${out.status} ${out.message}`)
+        process.exitCode = 1
+        return
+      }
+      process.stdout.write(JSON.stringify(out.result, null, 2) + "\n")
+    } finally {
+      await backend.close()
+    }
+  },
+})

package/src/commands/compile.ts

@@ -5,7 +5,7 @@ import { getProject } from "../platform/api"
 import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
 import { collectEntries } from "../compile/collect"
 import { collectLocalEntries } from "../compile/collectLocal"
-import { ambiguousEntryWarning, compileProjectBundle, localAssetNames, type CompileEntry } from "../compile/projectCompile"
+import { ambiguousEntryWarning, compileProjectBundle, localAssetNames, requireUnambiguousEntry, type AmbiguousEntryPolicy, type CompileEntry } from "../compile/projectCompile"
 import { applyProjectFonts } from "../compile/fonts"
 import { applyLocalShaders, desktopShaderPlatform, type StagedShader } from "../compile/shaders"
 import type { DesktopRenderer } from "../hosts/desktopRenderer"
@@ -96,6 +96,9 @@ export type BuildBundleOptions = {
    *  started here (dev/projectBackend.ts) and that backend's url in its stubs. Without it the stubs
    *  of a `*.server.ts` have no server to call. */
   backend?: RunBackend
+  /** A guessed entry (several import-graph roots, no main.ts): `warn` (default — compile, desktop run, …)
+   *  or `error`, thrown before the compile (`render --desktop|--sim`, `test --desktop|--sim`). */
+  ambiguousEntry?: AmbiguousEntryPolicy
 }
 
 export default defineCommand({
@@ -221,13 +224,14 @@ export const buildBundle = async (bundle: BundleOptions, opts: BuildBundleOption
   const iconsHeader = await applyAppAssetIcons(entries)
   note(`Prepared shaders, fonts and icons in ${((performance.now() - tPrep) / 1000).toFixed(1)} s`)
 
-  note("Compiling…")
-  const tCompile = performance.now()
   const entryOverride = opts.entryOverride ?? bundle.entry
-  if (!entryOverride) {
+  if (opts.ambiguousEntry === "error") requireUnambiguousEntry(entries, entryOverride)
+  else if (!entryOverride) {
     const ambiguous = ambiguousEntryWarning(entries)
     if (ambiguous) warnErr(ambiguous)
   }
+  note("Compiling…")
+  const tCompile = performance.now()
   const serverUrl = await opts.backend?.start(entries, (w) => warnings.push(w))
   const { js, bakes } = await compileProjectBundle({
     entries, name, publicUrl, entryOverride, serverUrl, env: readAppEnv(root),

package/src/commands/desktop.ts

@@ -7,7 +7,7 @@ import {
 import { desktopBuild } from "./app/desktop"
 import { desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
 import { buildBundle } from "./compile"
-import { runBackend } from "../dev/projectBackend"
+import { projectRunBackend } from "../dev/devLink"
 import { bundleFlags, bundleOptions, localProject } from "./shared"
 
 /*
@@ -41,7 +41,7 @@ export const resolveRenderScale = (flag: string | undefined, cfg: number | undef
 const run = defineCommand({
   name: "run",
   summary: "Compile the current project and open it in a desktop window",
-  description: "Window size / min size / title default from app.json's desktop block; asset() resources load from the working tree. A project with *.server.ts files gets its backend run on this machine for as long as the window is open (the database of `lecodes dev`: .lecodes/db). Multiplayer: --server starts the host as a dedicated server, --connect joins one — both only set Net.launch (the app decides).",
+  description: "Window size / min size / title default from app.json's desktop block; asset() resources load from the working tree. A project with *.server.ts files gets its backend: a running `lecodes dev`'s when one answers (its database and data — the app is one more device of it), else one run on this machine for as long as the window is open, on the database of `lecodes dev` (.lecodes/db). Multiplayer: --server starts the host as a dedicated server, --connect joins one — both only set Net.launch (the app decides).",
   flags: {
     width: num("window width (logical px)"),
     height: num("window height (logical px)"),
@@ -69,8 +69,9 @@ const run = defineCommand({
     // ONE renderer decision per run: it picks the host binary AND which .filamat gets staged beside
     // the bundle. Reading the config twice is how a Vulkan exe ends up next to an OpenGL shader.
     const renderer = resolveDesktopRenderer(root, flags.renderer)
-    // The project's backend (its *.server.ts files), when it has one: run here while the window is open.
-    const backend = runBackend({ root, command: "lecodes desktop run", log: logErr })
+    // The project's backend (its *.server.ts files), when it has one: a running `lecodes dev`'s, else run here
+    // while the window is open.
+    const backend = await projectRunBackend({ root, command: "lecodes desktop run", log: logErr, note })
     const { js, resources } = await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer: renderer, backend })
     // Native plugins: the project's plugins/ dir + declared plugin libraries, scanned by the host.
     const { dirs: pluginDirs, files: pluginFiles } = desktopPluginLibraries(root)

package/src/commands/dev.ts

@@ -14,6 +14,8 @@ import { readAppConfigAt } from "./app/shared"
 import { resolveScale } from "./desktop"
 import { CliError, bool, c, defineCommand, log, note, num, str, warnErr } from "../cli"
 import { bundleFlags } from "./shared"
+import { DEV_DEFAULT_PORT, findRunningDev, recordDevPort } from "../dev/devLink"
+import { loadBotsFlow, parseBotVars, startBots, type BotsPlan } from "../dev/bots"
 
 /*
  * `lecodes dev` — run the project on a device straight from this machine, with hot reload.
@@ -48,12 +50,22 @@ import { bundleFlags } from "./shared"
  * connected, and re-running with --desktop is the reopen. Host errors degrade to a warning — the
  * QR path must keep working.
  *
+ * The project's backend runs here, and it is the ONE backend of the project on this machine
+ * (dev/devLink.ts): the port goes into .lecodes/dev.json, and while this runs `render`, `desktop run`,
+ * `call` and `web dev` talk to it instead of opening the database — only `lecodes test` keeps its own.
+ * A second dev server of the project (another `lecodes dev --port`, a `web dev` started first) finds
+ * the one that runs it and forwards its backend routes there.
+ *
+ * `--bots <flow.json>` (dev/bots.ts): the flow's clients join as headless players on this backend
+ * once the first compile is in — the phone is a live player among them; they run the flow once on
+ * real time and stay in the game until Ctrl+C. `--var name=value` gives the flow its `${name}`s.
+ *
  * Works inside a cloned project or standalone in any folder with an entry .ts file.
  * The desktop host speaks websocket since 1.0.0 (host_ws); `?t=poll` remains the fallback
  * for older desktop builds (or any host without a websocket bridge).
  */
 
-const DEFAULT_PORT = 4499
+const DEFAULT_PORT = DEV_DEFAULT_PORT
 /*
  * The origin a phone on the same Wi-Fi can reach, best first.
  *
@@ -111,7 +123,7 @@ const printQr = async (url: string) => {
 export default defineCommand({
   name: "dev",
   summary: "Run the project on a device / the desktop / the browser from this machine, with hot reload",
-  description: "Starts a LAN dev server + prints a QR code; scan it with the LeCodes app. Saves recompile + hot-swap the running app; device logs/errors stream back here. No login needed. The /web/ URL (the web player) is served always; --web, --android and --desktop each also open the app on that host.",
+  description: "Starts a LAN dev server + prints a QR code; scan it with the LeCodes app. Saves recompile + hot-swap the running app; device logs/errors stream back here. No login needed. The /web/ URL (the web player) is served always; --web, --android and --desktop each also open the app on that host.\n\nThe project's backend (its *.server.ts files, the database in .lecodes/db) runs here, and while it does it is the project's one backend on this machine: `render`, `desktop run`, `call` and `web dev` talk to it instead of opening the database (`lecodes test` keeps its own). --bots <flow.json> adds headless players from a flow file — the phone is a live player among them: they run the flow once on real time (a `clock` step is refused, a `wait` waits, an expect with a long \"timeout\" waits for you), a failing step is told and the next runs, and then they stay in the game until Ctrl+C. --var code=4821 sets ${code} for the flow (the room you made on the phone).",
   flags: {
     port: num("server port", { default: DEFAULT_PORT }),
     host: str("LAN address to advertise (default: auto-detect)", { value: "<ip>" }),
@@ -130,8 +142,10 @@ export default defineCommand({
     web: bool("also open the app in the browser (the web player in a device: same bundle + hot reload, the console)"),
     desktop: bool("also open the app in the native desktop host (same hot reload; window from app.json's desktop block; closing it keeps the server)"),
     fps: bool("(--desktop) draw the host's frame counter"),
+    bots: str("headless players from a flow file on this dev backend (its clients join as the phone does), on real time: the flow runs once, then they stay in the game until Ctrl+C — unless it ends with { \"clients\": \"*\", \"close\": true }", { value: "<flow.json>" }),
+    var: str("(--bots) values for ${name} in the flow, before it runs: code=4821 (several: a=1,b=2)", { value: "<name=value>" }),
   },
-  examples: ["lecodes dev", "lecodes dev --web", "lecodes dev --android --time 12 --png phone.png", "lecodes dev --ios --time 12 --png sim.png", "lecodes dev --desktop --fps"],
+  examples: ["lecodes dev", "lecodes dev --web", "lecodes dev --android --time 12 --png phone.png", "lecodes dev --ios --time 12 --png sim.png", "lecodes dev --desktop --fps", "lecodes dev --bots tests/bots.flow.json --var code=4821"],
   run: async ({ flags }) => {
     // Inside a cloned project the server runs at its root; anywhere else it runs standalone against
     // the current directory (no login / manifest needed) — same rule as `lecodes design`.
@@ -156,6 +170,14 @@ export default defineCommand({
     const origin = `http://${host}:${port}`
     const token = loadDevToken(root)
 
+    // --bots: the flow is read and checked now — a typo is an error before the server starts
+    if (flags.var !== undefined && flags.bots === undefined) throw new CliError("--var gives a value to a --bots flow: add --bots <flow.json>.")
+    const bots: BotsPlan | null = flags.bots !== undefined ? await loadBotsFlow(root, flags.bots, parseBotVars(flags.var)) : null
+
+    // one backend per project on this machine: when a dev server of the project already runs it, this one forwards there
+    const owner = await findRunningDev(root)
+    if (owner && owner.port === port) throw new CliError(`A lecodes dev of this project already runs on port ${port}. Use that one — or pass --port <n> for a second dev server (it forwards to the first one's backend).`)
+
     const web = resolveWebRunner(note)
     if (flags.web && !web) {
       throw new CliError("No web player found for --web: this CLI has no runtime/web (a monorepo checkout needs `bun run build` in hosts/web-player).")
@@ -165,10 +187,24 @@ export default defineCommand({
       entryOverride: flags.entry,
       web,
       log: note,
+      backendUrl: owner?.url,
     }).catch((e: unknown) => {
       const msg = e instanceof Error ? e.message : String(e)
       throw new CliError(msg.includes("EADDRINUSE") ? `Port ${port} is already in use — pass --port <n>.` : msg)
     })
+    if (owner) note(`The project's backend runs in the lecodes dev on port ${owner.port} (its database): this server forwards to it.`)
+    else recordDevPort(root, server.port)
+
+    // the bots join once the app compiled (the first good compile)
+    let botsStarted = false
+    const startBotsOnce = () => {
+      if (!bots || botsStarted) return
+      botsStarted = true
+      // they live as long as this process (Ctrl+C ends them with it: their sockets close, the backend sees them leave)
+      startBots(bots, { port: server.port, token, url: `http://127.0.0.1:${server.port}${server.base}/server` }, note).catch(
+        (e: unknown) => warnErr(`[bots] could not start: ${e instanceof Error ? e.message : String(e)}`),
+      )
+    }
 
     note("Compiling…")
     const first = await server.recompile()
@@ -181,6 +217,7 @@ export default defineCommand({
     // ---- watcher: debounced whole-project recompile; a successful compile broadcasts the reload ----
     const watcher = watchProject(root, async () => {
       const result = await server.recompile()
+      if (result.ok) startBotsOnce()
       if (!result.ok) {
         warnErr(`Compile failed (devices keep the last good version):\n${result.error}`)
       } else if (result.changed) {
@@ -215,6 +252,8 @@ export default defineCommand({
       openBrowser(webLocal)
     }
 
+    if (first.ok) startBotsOnce()
+
     if (flags.android) {
       const seconds = flags.time ?? 0
       const png = flags.png

package/src/commands/index.ts

@@ -1,6 +1,7 @@
 import type { Group } from "../cli"
 import app from "./app"
 import assets from "./assets"
+import call from "./call"
 import clone from "./clone"
 import compile from "./compile"
 import create from "./create"
@@ -45,6 +46,7 @@ export const commandGroups = (opts: { install: boolean }): Group[] => [
     compile,
     render,
     test,
+    call,
     desktop,
     serve,
   ] },

package/src/commands/init/templates.ts

@@ -71,7 +71,42 @@ resolved style of a named node, \`audio: { played, playing }\`), then outputs
 runtime's tree with every node's box + resolved paint, identical on every host). Targets resolve
 by \`name\` → exact visible text → substring → input placeholder; a tap/drag on empty space reaches
 the 2D scene (sprite \`click\`/\`touchstart\`, \`ev.track()\`). Envelope keys: \`name\`,
-\`width\`/\`height\`, \`settle\`, \`fixtures\`, \`steps\`.
+\`width\`/\`height\`, \`settle\`, \`fixtures\`, \`timeout\`, \`clients\`, \`steps\`.
+
+An \`expect\` WAITS by itself until it holds — up to \`timeout\` ms (default 5000; per step, or the
+envelope's \`timeout\`), stepping frames meanwhile at the pace of real time, so what the backend sends
+lands; \`notText\`/\`notNode\` pass as soon as they hold; a failing one says what was on screen. An
+action's target is waited for the same way. So no \`wait\` before an expect: \`wait\` is for time
+itself to pass. \`save\` keeps a value for later steps: \`{ "tap": "create", "save": { "code": "room-code" } }\`
+reads the named node's text (an input's value) once the step settled; \`\${code}\` then stands for it
+in any later step's strings (targets, \`text\`, \`args\`, expect values), and \`\${client}\` for the
+name of the client the step runs on. A variable no earlier step saved is an error naming the step.
+
+**A case has one clock.** The app's \`Date.now()\` / \`new Date()\` / \`performance.now()\` read the
+flow's virtual clock (from the real time the case started), and so does the backend: \`wait\` moves
+both by its ms; \`{ "clock": "+92s" }\` (\`"+1500ms"\`, \`"+2m"\`) JUMPS every client and the server
+at once without stepping frames — the timers due meanwhile fire once, as on a phone that was asleep
+(a \`setLoop\` sees one long frame; the 2D/3D simulations do not run the span). Past a server
+deadline: jump its length plus a margin — the server's clock also runs in real time between steps.
+
+**Several clients** (headless, \`lecodes test\`): \`"clients": { "ann": {}, "bob": {}, "eve": { "height": 640 } }\`
+starts the app once per client (each its own storage, socket and session token; a client may set its
+own \`width\`/\`height\`/\`device\`/\`safeArea\`), all against the project's backend. Every step then
+says where it runs — \`"client": "ann"\`, \`"clients": ["bob", "eve"]\` or \`"clients": "*"\` (in
+parallel, one verdict) — except \`clock\` and \`call\`; after each step every client is at the same
+time. \`{ "client": "bob", "offline": true }\` takes bob off the network (his calls fail, his socket
+drops, \`online\` turns false; \`false\` brings him back); \`{ "restart": "bob" }\` starts his app again
+on the same storage (\`signal().stored()\` values and his session survive, as a phone's restart);
+\`{ "clients": "*", "close": true }\` ends clients (their sockets close; \`restart\` opens one again). A
+\`screenshot\` on several clients is ONE picture, side by side in envelope order, each under its name.
+A failure dumps every client's frame: tests/.artifacts/<case>/<client>/failure.json + .png.
+
+\`call\` calls a server function directly: \`{ "call": "game.server.ts#submitVote", "as": "bob", "args":
+["\${code}", "x"], "expect": { "result": { "ok": true } }, "save": { "id": "players.0.id" } }\` — as
+client bob's device (his session token), or, for a name no client has, as a device of its own
+(\`"as": "guest1"\`; a list calls once per name, all at once). Its expect: \`result\` (matched by the
+keys it names), \`error: { status?, message?, count? }\`, \`ok: <how many answered>\`. A case of only
+\`call\`/\`clock\` steps and no \`clients\` starts no app: a server test.
 
 Three hosts run the same file, at a fixed 16 ms clock on all of them:
 
@@ -97,6 +132,18 @@ it (appends); the sim has no UI, so it takes coordinates and \`expect.log\` / \`
 ] }
 \`\`\`
 
+\`\`\`json
+{ "clients": { "ann": {}, "bob": {} },
+  "steps": [
+  { "client": "ann", "tap": "create", "expect": { "screen": "lobby" }, "save": { "code": "room-code" } },
+  { "client": "bob", "type": "code", "text": "\${code}" },
+  { "client": "bob", "tap": "join", "expect": { "text": "2 players" } },
+  { "clock": "+46s" },
+  { "clients": "*", "expect": { "text": "Time is up" }, "screenshot": "both.png" },
+  { "call": "game.server.ts#join", "as": "guest", "args": ["\${code}"], "expect": { "error": { "status": 409 } } }
+] }
+\`\`\`
+
 Game time is deterministic on every host: the Aspect / System phases (\`updateBefore\` / \`update\`),
 2D physics and animation advance in fixed 1/60 steps driven by \`wait\`/\`frames\`/\`drag\`/\`key\` —
 never by a wall clock — so a flow that passes once passes every time. \`Input.key(code)\` reads the
@@ -118,11 +165,28 @@ assertion channel for game state that has no UI.
   automatically (conventions in design/CLAUDE.md).
 - Backend-gated screens: canned responses in \`tests/fixtures.json\` (URL pattern →
   \`{ status?, json?, text? }\`; \`*\` wildcards full-match, plain strings substring-match, first
-  match wins). \`lecodes test\` auto-loads it for design-derived flows; a scenario file opts in
+  match wins). A key may name a server function, \`"game.server.ts#submitGuess"\` (or \`…%23submitGuess\`):
+  its body is then the RPC envelope, \`{ "json": { "ok": true, "result": … } }\`. Fixtures are
+  headless-only, and a \`computed\` subscription can't be mocked (it goes over the socket to the real
+  backend). \`lecodes test\` auto-loads it for design-derived flows; a scenario file opts in
   with \`"fixtures": "fixtures.json"\` in its envelope.
 - A project with \`*.server.ts\` files: \`lecodes test\` runs its backend for the run, on a database
   of its own that is EMPTY before every case (a flow signs up, it never finds yesterday's data). A
-  step waits for the server calls it started — no \`wait\` after a tap that saves.
+  step waits for the server calls it started — no \`wait\` after a tap that saves. Test a backend
+  app with its real backend and several \`clients\`, not fixtures; \`lecodes call <file#fn> [args]
+  [--as <name>]\` calls one function from the terminal.
+- **One backend per project on this machine: while \`lecodes dev\` runs, the other commands talk to
+  it.** \`render\` (headless, \`--desktop\`, \`--sim\`), \`desktop run\`, \`lecodes call\` and \`lecodes web
+  dev\` use the running dev's backend — its database and data (the room open on the phone) — instead of
+  opening \`.lecodes/db\`; \`render --fresh\` empties it first, and a \`render --script\` beside it runs on
+  real time (no \`clock\` step). With no dev running they run the backend themselves (\`call\`: on the
+  test database). \`lecodes test\` never uses the dev's: its own database, always.
+- Bots for a multiplayer app: \`lecodes dev --bots tests/bots.flow.json --var code=4821\` — the flow's
+  \`clients\` join the dev backend as headless players beside the phone, on REAL time (a \`clock\` step is
+  refused, \`wait\` waits; wait for the human with \`"expect": {…}, "timeout": 600000\`), run the flow once
+  and stay in the game until Ctrl+C (unless it ends with \`{ "clients": "*", "close": true }\`). A failing
+  step is printed (\`[bots] ✗ …\`) and the next runs. \`--var\` sets \`\${code}\`; the envelope's
+  \`"vars": ["code"]\` names what the flow needs, and \`lecodes test\` skips such a file.
 - A file dialog (\`openFilePicker\`) is answered by \`pick\`, on the step whose action opens it:
   \`{ "tap": "attach", "pick": "cat.png" }\` — a file beside the flow file, a list of them, or a
   file made for the run: \`{ "name": "me.png", "width": 400, "height": 300 }\`,

package/src/commands/plugin.ts

@@ -14,7 +14,7 @@ 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 repo of plugins also gets its Package.swift from the manifests: the iOS halves as one SwiftPM package, a target and a product per plugin, the SDK as a package on disk (LECODES_IOS_SDK_PATH, else the repo's package.json lecodes.iosSdkPath, else ../lecodes) — what an Xcode project links the halves as (a shell vendors the sources instead). A contract the generator does not understand is an error with its line, and every problem of a file is reported at once.\n\nA HALF FOLDER of a project — a manifest with `implements: \"<first-party id>\"`, no contract.d.ts and no sdk/ of its own — is generated from the contract of the plugin it implements (the one the SDK carries): `lecodes plugin gen plugins/ar-8thwall` writes web/ar.gen.ts, the half registers the service \"ar\", and app.json names the folder for that platform (`\"ar\": { \"web\": \"./plugins/ar-8thwall\" }`).\n\nGenerated files are committed. Reading a contract needs TypeScript in the plugin's repo.",
+  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 repo of plugins also gets its Package.swift from the manifests: the iOS halves as one SwiftPM package, a target and a product per plugin, the SDK as a package on disk (LECODES_IOS_SDK_PATH, else the repo's package.json lecodes.iosSdkPath, else ../lecodes) — what an Xcode project links the halves as (a shell vendors the sources instead). A contract the generator does not understand is an error with its line, and every problem of a file is reported at once.\n\nA HALF FOLDER of a project — a manifest with `implements: \"<first-party id>\"`, no contract.d.ts and no sdk/ of its own — is generated from the contract of the plugin it implements (the one the SDK carries): `lecodes plugin gen plugins/ar-8thwall` writes web/ar.gen.ts, the half registers the service \"ar\", and app.json names the folder for that platform (`\"ar\": { \"web\": \"./plugins/ar-8thwall\" }`).\n\nGenerated files are committed. Reading a contract needs the `typescript` package 5.x (TypeScript 6 is not read): the plugin's own, looked up from its folder upwards, else the one next to the CLI's install — a dependency of lecodes-cli after 2.4.9; a standalone binary of the CLI needs it in the plugin's repo (`npm install --save-dev \"typescript@^5.8.3\"`, or `bun add -g \"typescript@^5.8.3\"` next to a bun-installed CLI).",
   flags: {
     check: bool("write nothing; exit 1 when a generated file is missing or stale"),
   },

package/src/commands/render.ts

@@ -4,7 +4,8 @@ import { compileHeadlessBundle } from "../compile/headlessBundle"
 import { screenTargetFrom } from "../compile/screenEntry"
 import { findProjectRoot } from "../project/manifest"
 import { buildBundle } from "./compile"
-import { runBackend } from "../dev/projectBackend"
+import { projectRunBackend } from "../dev/devLink"
+import { callEndpoint } from "../dev/backendCall"
 import { resolvePicks } from "../hosts/flowPick"
 import { desktopDefaultViewport, desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
 import { runDesktopRender } from "../hosts/desktopRenderer"
@@ -139,6 +140,8 @@ type ScenarioFile = {
   device?: string
   safeArea?: string
   fixtures?: Record<string, unknown> | string
+  /** How long an expect waits by default, ms. */
+  timeout?: number
   steps: unknown
 }
 
@@ -175,6 +178,7 @@ const readScenarioFile = (path: string): ScenarioFile => {
   if (typeof raw !== "object" || raw === null) throw new CliError(`Scenario "${path}" must be a JSON object with "steps" (or a bare step array).`)
   const file = raw as ScenarioFile
   if (file.steps === undefined) throw new CliError(`Scenario "${path}" has no "steps".`)
+  if ((raw as { clients?: unknown }).clients !== undefined) throw new CliError(`"clients" (several clients in one case) runs under \`lecodes test\`: \`lecodes test ${path}\`.`)
   return { ...file, steps: resolvePicks(file.steps, dirname(resolve(path))) }
 }
 
@@ -209,6 +213,7 @@ const renderFlags = {
   "out-dir": str("where --script step outputs land", { value: "<dir>", default: "." }),
   clip: str("(--png) crop to one node's rect or a logical-px rect — a component / region render", { value: "<name|x,y,w,h>" }),
   fixtures: str("canned fetch responses (URL pattern → { status?, json?, text? }) — make backend-gated screens reachable headless; merged over the scenario file's own", { value: "<file>" }),
+  fresh: bool("start on an EMPTY database: the project's backend (a running lecodes dev's, else .lecodes/db) is emptied first — by default its data stays"),
   scale: num("PNG device-pixel scale", { default: 2 }),
   time: num("render at this animation time (0 = the initial frame-0 state)", { value: "<ms>" }),
   "no-after-animations": bool("keep frame 0 instead of advancing animations to their resting state"),
@@ -301,12 +306,14 @@ const renderDesktop = async (flags: RenderFlags, file: string | undefined): Prom
   const desktopRenderer = resolveDesktopRenderer(root, flags.renderer)
   // Native plugins (project plugins/ dir + declared libraries) — the host scans CREATOR_PLUGIN_DIRS.
   const { dirs: pluginDirs } = desktopPluginLibraries(root)
-  // The project's backend, when it has one (the database of `lecodes dev`).
-  const backend = runBackend({ root, command: "lecodes render", log: (msg) => { if (logs || msg.includes("[server:error]")) logErr(msg) } })
+  // The project's backend, when it has one: a running `lecodes dev`'s (it holds the database), else one
+  // started for the run on its database (.lecodes/db). --fresh empties it first.
+  const backend = await projectRunBackend({ root, command: "lecodes render", note, log: (msg) => { if (logs || msg.includes("[server:error]")) logErr(msg) } })
   const { js, resources } = await buildBundle(bundleOptions(flags), {
-    localAssets: true, desktopRenderer, backend,
+    localAssets: true, desktopRenderer, backend, ambiguousEntry: "error",
     extraEntries: screen ? [screen.entry] : undefined, entryOverride: screen?.entryPath,
   })
+  if (flags.fresh) await backend.reset()
   // The host writes PNGs but never creates folders — make every output dir up front.
   if (!sim) mkdirSync(dirname(resolve(pngFlag)), { recursive: true })
 
@@ -369,18 +376,11 @@ const renderHeadless = async (flags: RenderFlags, file: string | undefined): Pro
   }, timeoutMs)
   killer.unref?.()
 
-  // The project's backend, when it has one (the database of `lecodes dev`). Beside a running
-  // `lecodes dev`, which holds that database, the picture is still made — without the backend.
-  const run = runBackend({ root: projectRoot, command: "lecodes render", log: (msg) => { if (flags.logs || msg.includes("[server:error]")) logErr(msg) } })
-  const backend: typeof run = {
-    ...run,
-    start: (entries, onWarning) => run.start(entries, onWarning).catch((e: Error) => {
-      if (!/is in use/.test(e.message)) throw e
-      warnErr(`${e.message} Rendering without the backend: every call to the server fails.`)
-      return undefined
-    }),
-  }
+  // The project's backend, when it has one: a running `lecodes dev`'s (it holds the database), else one
+  // started for the run on its database (.lecodes/db). --fresh empties it first.
+  const backend = await projectRunBackend({ root: projectRoot, command: "lecodes render", note, log: (msg) => { if (flags.logs || msg.includes("[server:error]")) logErr(msg) } })
   const { js, warnings, useLocalAssets, root, serverUrl } = await compileHeadlessBundle({ screen, entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"], backend })
+  if (flags.fresh && serverUrl) await backend.reset()
   const renderer = await requireRenderer()
 
   // Flags override the scenario file's envelope; both fall back to the project default (a
@@ -427,16 +427,27 @@ const renderHeadless = async (flags: RenderFlags, file: string | undefined): Pro
 
   // --script: drive the compiled app through the scenario steps against a live session.
   if (scenario) {
-    const steps = renderer.parseScenarioSteps(scenario.steps)
+    // A running lecodes dev's backend keeps its devices' clock: the run is on real time then (no `clock`
+    // step; a `wait` waits), as `dev --bots` is.
+    const live = !!(serverUrl && backend.dev)
+    const steps = (() => {
+      try { return renderer.parseScenarioSteps(scenario.steps, live ? { realTime: true } : {}) }
+      catch (e) { throw new CliError(`${flags.script}: ${(e as Error).message}`) }
+    })()
     const outDir = flags["out-dir"]
     // Screenshots require pixels; otherwise rasterize opportunistically (napi installed → failure
     // PNGs and real Skia text metrics, absent → deterministic HeadlessHost metrics).
     const needsRaster = steps.some((s) => s.screenshot !== undefined)
     note(`Running ${steps.length} step${steps.length === 1 ? "" : "s"}…`)
-    const session = await renderer.createSession(js, { width, height, ...timing, raster: needsRaster ? true : "auto" })
-    try {
-      const result = await renderer.runScenario(session, steps, fileScenarioIO(outDir))
-      for (const w of [ ...warnings, ...session.warnings ]) warnErr(w)
+    // one client, the case runner's: its clock is the backend's too (not a dev's), and `call` steps reach the backend as it
+    let session: Awaited<ReturnType<typeof renderer.createSession>> | null = null
+    {
+      const result = await renderer.runCase({
+        clients: [{ name: "app", start: async (env) => (session = await renderer.createSession(js, { width, height, ...timing, raster: needsRaster ? true : "auto", ...env })) }],
+        single: true, steps, io: fileScenarioIO(outDir), timeoutMs: scenario.timeout, realTime: live,
+        backend: serverUrl ? { url: serverUrl, call: (id, args, device) => callEndpoint(serverUrl, id, args, device), ...(live ? {} : { setClock: (ms: number) => backend.setClock(ms) }) } : undefined,
+      })
+      for (const w of [ ...warnings, ...((session as { warnings: string[] } | null)?.warnings ?? []) ]) warnErr(w)
       for (const st of result.steps) {
         logErr(st.ok ? `${c.green("✓")} ${st.desc}` : `${c.red("✗")} ${st.desc}\n  ${c.red(st.error ?? "failed")}`)
       }
@@ -445,8 +456,6 @@ const renderHeadless = async (flags: RenderFlags, file: string | undefined): Pro
       }
       logErr(result.ok ? c.green(`✓ ${result.steps.length}/${steps.length} steps passed`) : c.red(`✗ failed at step ${result.steps.length} of ${steps.length}`))
       return done((cb) => cb(), result.ok ? 0 : 1)
-    } finally {
-      session.dispose()
     }
   }