lecodes-cli 2.6.0 → 2.8.0

package/src/dev/backendWorker.ts

@@ -4,8 +4,9 @@ import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { format } from "node:util"
 import {
-  createAuthHost, createFilesHost, createInvoker, createPushHost, createSubscribeGuard, describeServer, loadServerModules, runSeed,
-  setChannelPublisher, setDbTransport, setEnv, type AuthHost, type Heic, type LoadedServer, type PushRelay, type Sharp,
+  createAuthHost, createComputedHost, createFakeWatchSource, createFilesHost, createInvoker, createPushHost, createSubscribeGuard, describeServer,
+  embeddedWatchSource, isReadOp, loadServerModules, outsideRequests, runSeed, setChannelPublisher, setDbTransport, setEnv, setPresenceProvider, setServerClock,
+  type AuthHost, type ComputedHost, type EmbeddedWatchHandle, type Heic, type LoadedServer, type MarciOp, type PushRelay, type Sharp,
 } from "lecodes-sdk/server"
 import { loadPeer } from "../hosts/peerInstall"
 import { ApiError, sendPush } from "../platform/api"
@@ -21,9 +22,21 @@ import type { FromWorker, LogLevel, PushSender, ToWorker } from "./localBackend"
  * directory the parent names. The schema is synced on every load, more freely than the runner does
  * (this is the developer's own machine): what the models no longer have is dropped; a change the
  * engine can't migrate in place moves the old database aside and starts an empty one.
+ *
+ * A computed's reads are watched by the embedded engine (sdk/server `embeddedWatchSource` over the
+ * handle's `watch`, marcidb-embedded 0.18 on; an older package refuses a subscription to a computed that
+ * reads the database, with that reason), and the bundle's own `op.watch` is the same handle's. LECODES_WATCH=fake
+ * (a test's knob) puts a stand-in in the computeds' place: every write this process sends signals the
+ * watches of the model it wrote — the one process that holds the database sees every write.
+ *
+ * Presence (`watchers`, `members`) is the parent's hub's table: a read is a `presence` message, the answer
+ * a `presenceResult`; a `presenceChanged` runs the computeds that read that key again.
+ *
+ * Under `lecodes test` a case has one clock: the parent's `clock` message moves this process's `Date.now()`
+ * (sdk/server `setServerClock`) with the apps' virtual clocks; `load` carries the offset a process starts with.
  */
 
-type Embedded = {
+type Embedded = EmbeddedWatchHandle & {
   exec(op: unknown): Promise<any>
   batch(ops: unknown[]): Promise<any[]>
   $sync(schema: string): Promise<null>
@@ -45,9 +58,15 @@ const DEV_CODE = "000000"
 let db: Embedded | null = null
 let invoke: ReturnType<typeof createInvoker> | null = null
 let subscribe: ReturnType<typeof createSubscribeGuard> | null = null
+let computed: ComputedHost | null = null
 let authHost: AuthHost | null = null
+const fakeWatch = process.env.LECODES_WATCH === "fake" ? createFakeWatchSource() : null
+/** presence reads on their way to the parent's hub, by their `req` */
+const asks = new Map<number, (sessions: number[]) => void>()
+let nextAsk = 1
 
 const quit = () => {
+  try { computed?.close() } catch { /* nothing to let go */ }
   try { db?.close() } catch { /* already closed */ }
   process.exit(0)
 }
@@ -69,7 +88,8 @@ const openDb = async (dir: string, filesDir: string, schema: string): Promise<st
     db = openDatabase(dir)
   } catch (e) {
     // one process holds a database: the engine's lock is the sign of a second server on this project
-    if (/Locked/i.test((e as Error).message)) throw new Error(`The project's database (${dir}) is in use — this project's backend is already running (another \`lecodes dev\` or \`lecodes desktop run\`). Stop it first.`)
+    // ("is in use" is what the commands that run the app match on: dev/devLink.ts says who could hold it)
+    if (/Locked/i.test((e as Error).message)) throw new Error(`The project's database (${dir}) is in use — another process of this project holds it (a \`lecodes dev\`, a \`desktop run\`, a \`render\`). Stop it first.`)
     throw e
   }
   try {
@@ -114,10 +134,28 @@ const pushRelay = (sender: PushSender): PushRelay => async (to, message) => {
 
 const load = async (m: Extract<ToWorker, { t: "load" }>) => {
   const noDb = () => { throw new Error("db: the database is not open yet — query it inside an endpoint, not while the module loads") }
-  setDbTransport({ exec: (op) => (db ?? noDb()).exec(op), batch: (ops) => (db ?? noDb()).batch(ops) })
+  // the stand-in watch source hears of every write that went through (a test's knob, above)
+  const wrote = (ops: MarciOp[]) => { for (const op of ops) if (!isReadOp(op)) fakeWatch?.fireModel(op.model) }
+  setDbTransport({
+    exec: async (op) => { const r = await (db ?? noDb()).exec(op); wrote([op]); return r },
+    batch: async (ops) => { const r = await (db ?? noDb()).batch(ops); wrote(ops); return r },
+    // the bundle's `op.watch`: the handle's poll, made outside the request that asked (its callbacks outlive it)
+    watch: (op, listener) => {
+      const handle = db ?? noDb()
+      if (typeof handle.watch !== "function") throw new Error("db: this marcidb-embedded has no watch (it came with marcidb-embedded 0.18) — update it")
+      return outsideRequests(() => handle.watch!(op, listener))
+    },
+  })
   setChannelPublisher((ch, group, data) => post({ t: "publish", ch, group, data }))
-  // The project's keys (its .env), before any module-level code can read one
+  // who is subscribed where is the parent's hub's: `watchers` / `members` ask it
+  setPresenceProvider((id, key) => new Promise((resolve) => {
+    const req = nextAsk++
+    asks.set(req, resolve)
+    post({ t: "presence", req, id, key })
+  }))
+  // The project's keys (its .env), before any module-level code can read one; the clock a test runs on, too
   setEnv(m.env)
+  setServerClock(m.clock ?? 0)
   // The bundle is a plain script (chisel esm output with only side effects): registers globalThis.__lecodesServer
   ;(0, eval)(m.code)
   const server: LoadedServer = loadServerModules()
@@ -164,6 +202,7 @@ const load = async (m: Extract<ToWorker, { t: "load" }>) => {
   }
   invoke = createInvoker(server, { auth, files, onError })
   subscribe = createSubscribeGuard(server, { auth, onError })
+  computed = createComputedHost(server, { auth, onError, watch: fakeWatch ?? embeddedWatchSource(() => db) })
   post({ t: "loaded", describe, notes })
 }
 
@@ -177,9 +216,23 @@ process.on("message", async (m: ToWorker) => {
       return post({ t: "result", req: m.req, result })
     }
     case "subscribe": {
-      const result = subscribe ? await subscribe(m.ch, m.args, m.ctx) : { ok: false as const, status: 503, message: "server not loaded" }
+      const result = !subscribe || !computed ? { ok: false as const, status: 503, message: "server not loaded" }
+        : m.sub === undefined ? await subscribe(m.ch, m.args, m.ctx) : await computed.start(m.ch, m.args, m.ctx, m.sub)
       return post({ t: "result", req: m.req, result })
     }
+    case "unsubscribe":
+      computed?.end(m.sub)
+      return
+    case "presenceResult":
+      asks.get(m.req)?.(m.sessions)
+      asks.delete(m.req)
+      return
+    case "presenceChanged":
+      computed?.presenceChanged(m.id, m.key)
+      return
+    case "clock":
+      setServerClock(m.offsetMs)
+      return
     case "stop":
       return quit()
   }

package/src/dev/bots.ts

@@ -0,0 +1,133 @@
+import { existsSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { compileHeadlessBundle } from "../compile/headlessBundle"
+import { fileScenarioIO, parseNativeViews, requireRenderer, resolveSafeAreaChoice } from "../commands/render"
+import { isServerCase, readFlowFile, slug, type ClientEnvelope, type FlowCase } from "../commands/test"
+import { CliError, c } from "../cli"
+import { callEndpoint } from "./backendCall"
+import { devRunBackend, type RunningDev } from "./devLink"
+
+/*
+ * `lecodes dev --bots <flow.json>` — the players a developer does not have at hand. The phone (any device
+ * on the dev url) is a live player; the flow's clients are more of them: headless sessions in this
+ * process, each with its own storage and session, on the SAME backend as the phone — the dev server's —
+ * driven by the case runner of `lecodes test` (lecodes-headless runCase) on REAL time:
+ *
+ *   - the backend's clock is the phone's: a `clock` step is refused, a `wait` waits, and every bot's
+ *     clock follows the machine's (its deadlines come when the phone's do);
+ *   - an `expect` with a long `timeout` is how a bot waits for the human
+ *     (`{ "clients": "*", "expect": { "text": "Фаза 1" }, "timeout": 600000 }`);
+ *   - a failing step is told here (`[bots] ✗ …`, its frame under the flow's .artifacts) and the next one
+ *     runs — the human is mid-game;
+ *   - the flow runs once; then the bots stay in the game (subscribed, their timers alive) until Ctrl+C —
+ *     unless the flow ends them: `{ "clients": "*", "close": true }`;
+ *   - `--var code=4821` gives `${code}` before the flow runs (the room the human made on the phone).
+ *
+ * The bots run the app as it was compiled when they started (a save reloads the phone, not them).
+ */
+
+export type BotsPlan = {
+  kase: FlowCase
+  /** The flow's steps, checked (lecodes-headless parseScenarioSteps, on real time). */
+  steps: import("lecodes-headless/headless").ScenarioStep[]
+  vars: Record<string, string>
+  /** Where a failing step's frame goes. */
+  artifacts: string
+}
+
+export type Bots = {
+  /** The bots leave (their apps disposed, their sockets closed); resolves once they have. */
+  stop: () => Promise<void>
+}
+
+/** `code=4821,name=Боб` → { code: "4821", name: "Боб" } (a repeated flag keeps the last value: commas list them). */
+export const parseBotVars = (raw: string | undefined): Record<string, string> => {
+  const vars: Record<string, string> = {}
+  if (raw === undefined || raw === "") return vars
+  for (const part of raw.split(",")) {
+    const eq = part.indexOf("=")
+    const name = (eq < 0 ? part : part.slice(0, eq)).trim()
+    if (!name || eq < 0) throw new CliError(`--var wants name=value (several: name=value,other=value) — got "${part}".`)
+    vars[name] = part.slice(eq + 1).trim()
+  }
+  return vars
+}
+
+/** Read and check the flow before the dev server starts: a typo is an error now, not after the first compile. */
+export const loadBotsFlow = async (root: string, given: string, vars: Record<string, string>): Promise<BotsPlan> => {
+  const testsDir = resolve(root, "tests")
+  // a path from here, or from the project's root; a name under its tests folder
+  const abs = [resolve(given), resolve(root, given), resolve(testsDir, given), resolve(testsDir, `${given}.flow.json`)].find((p) => existsSync(p))
+  if (!abs) throw new CliError(`--bots: no such flow "${given}" (looked here and in ${testsDir}).`)
+  const kase = readFlowFile(abs, given)
+  // the names the flow says its run gives (`"vars": ["code"]`) must be given
+  const missing = (kase.vars ?? []).filter((name) => !(name in vars))
+  if (missing.length > 0) throw new CliError(`--bots ${given}: the flow takes ${missing.map((n) => `--var ${n}=…`).join(", ")} (its "vars").`)
+  const renderer = await requireRenderer()
+  let steps
+  try {
+    steps = renderer.parseScenarioSteps(kase.steps, isServerCase(kase)
+      ? { server: true, vars: Object.keys(vars), realTime: true }
+      : { clients: kase.clients ? Object.keys(kase.clients) : undefined, vars: Object.keys(vars), realTime: true })
+  } catch (e) {
+    throw new CliError(`--bots ${given}: ${(e as Error).message}`)
+  }
+  return { kase, steps, vars, artifacts: resolve(dirname(abs), ".artifacts", slug(kase.name)) }
+}
+
+/** Start the bots of `plan` on the dev backend `dev` (the dev server's own url, on this machine). */
+export const startBots = async (plan: BotsPlan, dev: RunningDev, say: (line: string) => void): Promise<Bots> => {
+  const { kase, steps } = plan
+  const tell = (line: string) => say(`${c.cyan("[bots]")} ${line}`)
+  const renderer = await requireRenderer()
+  const headless = await compileHeadlessBundle({ backend: devRunBackend(dev) })
+  for (const w of headless.warnings) tell(c.dim(w))
+  const serverUrl = headless.serverUrl
+  const names = kase.clients ? Object.keys(kase.clients) : isServerCase(kase) ? [] : ["app"]
+  tell(names.length > 0 ? `${names.join(", ")} join${names.length === 1 ? "s" : ""} the game (${steps.length} step${steps.length === 1 ? "" : "s"}, on real time)` : `${steps.length} call step${steps.length === 1 ? "" : "s"}, on real time`)
+
+  const sessionOptions = (name: string, own: ClientEnvelope = {}) => ({
+    width: own.width || kase.width || 390,
+    height: own.height || kase.height || 844,
+    settleMs: kase.settle,
+    backend: serverUrl,
+    localAssets: headless.useLocalAssets,
+    fixtures: kase.fixtures,
+    ...resolveSafeAreaChoice(own.safeArea ?? kase.safeArea, own.device ?? kase.device),
+    nativeViews: parseNativeViews(undefined),
+    // the app's own errors are worth seeing; its chatter is not
+    onConsole: (level: string, text: string) => { if (level === "error" || level === "warn") tell(`${c.dim(`${name}:${level}`)} ${text}`) },
+  })
+  const clients = names.map((name) => ({
+    name,
+    start: (env: import("lecodes-headless/headless").ClientStart) => renderer.createSession(headless.js, { ...sessionOptions(name, kase.clients?.[name]), ...env }),
+  }))
+
+  let release = () => {}
+  const released = new Promise<void>((r) => { release = r })
+  const long = (i: number) => (steps[i]?.timeout ?? kase.timeout ?? 0) > 10_000
+  const done = renderer.runCase({
+    clients, single: !kase.clients, steps, io: fileScenarioIO(plan.artifacts), timeoutMs: kase.timeout,
+    realTime: true, keepGoing: true, vars: plan.vars,
+    backend: serverUrl ? { url: serverUrl, call: (id, args, device) => callEndpoint(serverUrl, id, args, device) } : undefined,
+    // a step that may wait long for the human says so when it begins
+    onStepStart: (i, desc) => { if (long(i)) tell(c.dim(`… ${desc}`)) },
+    onStep: (o) => {
+      if (o.ok) tell(`${c.green("✓")} ${o.desc}`)
+      else tell(`${c.red("✗")} ${o.desc} — ${o.error ?? "failed"}${o.index >= 0 ? c.dim(` (its frame: ${plan.artifacts})`) : ""}`)
+    },
+    linger: async (outcome, open) => {
+      const failed = outcome.steps.filter((s) => !s.ok).length
+      const ran = `the flow ran: ${outcome.steps.length - failed} of ${outcome.steps.length} steps passed`
+      tell(open.length > 0 ? `${ran} — ${open.join(", ")} stay${open.length === 1 ? "s" : ""} in the game until Ctrl+C` : `${ran}; every bot has left`)
+      await released
+    },
+  })
+  done.catch((e: unknown) => tell(`${c.red("✗")} ${(e as Error)?.message ?? e}`))
+  return {
+    stop: async () => {
+      release()
+      await done.catch(() => {})
+    },
+  }
+}

package/src/dev/devLink.ts

@@ -0,0 +1,136 @@
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { hasServerFiles } from "../compile/projectCompile"
+import { LECODES_DIR } from "../project/manifest"
+import { CliError } from "../cli"
+import { runBackend, type RunBackend } from "./projectBackend"
+
+/*
+ * ONE backend per project on this machine: while a `lecodes dev` of the project runs, it holds the
+ * project's database (`.lecodes/db` — the embedded engine locks it for one process), and every other
+ * command of the project talks to ITS backend over HTTP instead of opening the database:
+ *
+ *   render (headless, --desktop, --sim), desktop run   the app's stubs call the dev backend's url
+ *   call                                               the call goes there (else: the test backend)
+ *   web dev, a second lecodes dev                      the dev server forwards its /server routes there
+ *   dev --bots                                         the bots are clients of it, as the phone is
+ *
+ * `lecodes test` never does: a test runs on its own database (`.lecodes/test-db`) and must not touch the
+ * data a developer plays with.
+ *
+ * How a running dev is found: `.lecodes/dev.json` has the project's dev token (the url's capability) and the
+ * port the dev server that runs the backend listens on (`recordDevPort`, written when it starts; 4499 when the
+ * file names none); that server answers `GET /t/<token>/server/status` — to this machine only — with the
+ * project root it serves, and a root that is not this project's is not this project's dev. No answer: the
+ * command runs the backend itself, on `.lecodes/db`, as before; and when the database is still locked then,
+ * the error says who could hold it.
+ */
+
+export const DEV_DEFAULT_PORT = 4499
+
+/** A dev server of this project that runs its backend, answering on this machine. */
+export type RunningDev = {
+  port: number
+  token: string
+  /** The backend's url on this machine (`http://127.0.0.1:<port>/t/<token>/server`): what the stubs call. */
+  url: string
+}
+
+type DevFile = { token?: string, port?: number }
+
+const devFile = (root: string) => join(root, LECODES_DIR, "dev.json")
+
+export const readDevFile = (root: string): DevFile => {
+  try {
+    const raw = JSON.parse(readFileSync(devFile(root), "utf8")) as DevFile
+    return raw && typeof raw === "object" ? raw : {}
+  } catch {
+    return {}
+  }
+}
+
+/** The dev server that runs the project's backend listens on `port`: the other commands look for it there. */
+export const recordDevPort = (root: string, port: number): void => {
+  const file = readDevFile(root)
+  if (file.port === port) return
+  mkdirSync(join(root, LECODES_DIR), { recursive: true })
+  writeFileSync(devFile(root), JSON.stringify({ ...file, port }, null, 2) + "\n")
+}
+
+const sameDir = (a: string, b: string): boolean => {
+  const real = (p: string) => { try { return realpathSync(p) } catch { return p } }
+  return real(a) === real(b)
+}
+
+/** The running dev of this project, or null (nothing answers where dev.json says, or it serves another folder). */
+export const findRunningDev = async (root: string, opts: { timeoutMs?: number } = {}): Promise<RunningDev | null> => {
+  const file = readDevFile(root)
+  if (!file.token || !/^[a-z0-9]{8,}$/.test(file.token)) return null
+  const port = typeof file.port === "number" && file.port > 0 ? file.port : DEV_DEFAULT_PORT
+  const url = `http://127.0.0.1:${port}/t/${file.token}/server`
+  try {
+    const res = await fetch(`${url}/status`, { signal: AbortSignal.timeout(opts.timeoutMs ?? 1500) })
+    const body = await res.json() as { ok?: boolean, root?: unknown }
+    if (body?.ok === true && typeof body.root === "string" && sameDir(body.root, root)) return { port, token: file.token, url }
+  } catch { /* nothing there, or not a dev server */ }
+  return null
+}
+
+/** The port a command expected a running dev on (for the message of a database that is locked). */
+export const expectedDevPort = (root: string): number => {
+  const port = readDevFile(root).port
+  return typeof port === "number" && port > 0 ? port : DEV_DEFAULT_PORT
+}
+
+/**
+ * A run's backend that is a running `lecodes dev`'s: nothing is started — the url is the dev backend's —
+ * `reset` empties ITS database (the admin route; a run asks for it explicitly: `render --fresh`), and the
+ * clock is the devices' own: it is never moved.
+ */
+export const devRunBackend = (dev: RunningDev): RunBackend => ({
+  dev: { port: dev.port, url: dev.url },
+  start: async (entries) => (hasServerFiles(entries) ? dev.url : undefined),
+  reset: async () => {
+    const body = await fetch(`${dev.url}/reset`, { method: "POST" }).then((r) => r.json() as Promise<{ ok?: boolean, message?: string } | null>, (e: Error) => {
+      throw new CliError(`The running lecodes dev (port ${dev.port}) did not empty its database: ${e.message}`)
+    })
+    if (body?.ok !== true) throw new CliError(`The running lecodes dev (port ${dev.port}) did not empty its database: ${body?.message ?? "no answer"}`)
+  },
+  setClock: () => { throw new Error("the backend of a running lecodes dev keeps the devices' clock: a run on it moves in real time") },
+  close: async () => {},
+})
+
+/** What the commands say when the database is locked and no dev of the project answers. */
+const lockedMessage = (root: string): string => {
+  const port = expectedDevPort(root)
+  return `The project's database (.lecodes/db) is held by another process, and no lecodes dev of this project answers on port ${port} (.lecodes/dev.json). ` +
+    `It is a dev backend that does not answer there (a lecodes dev of an older CLI, or one that hangs), or another run of the project (desktop run, render) — stop it and run this again.`
+}
+
+/**
+ * The backend of a command that runs the app on this machine (`render`, `desktop run`): a running
+ * `lecodes dev`'s when one answers, else one started for the run on `.lecodes/db` (runBackend) — whose
+ * locked database is a clear error, never a run without a backend.
+ */
+export const projectRunBackend = async (options: { root: string, command: string, log: (msg: string) => void, note?: (msg: string) => void }): Promise<RunBackend> => {
+  const dev = await findRunningDev(options.root)
+  if (dev) {
+    const b = devRunBackend(dev)
+    return {
+      ...b,
+      start: async (entries, onWarning) => {
+        const url = await b.start(entries, onWarning)
+        if (url) options.note?.(`The backend: the running lecodes dev's (port ${dev.port}) — its database, its data.`)
+        return url
+      },
+    }
+  }
+  const local = runBackend({ root: options.root, command: options.command, log: options.log })
+  return {
+    ...local,
+    start: (entries, onWarning) => local.start(entries, onWarning).catch((e: Error) => {
+      if (/is in use/.test(e?.message ?? "")) throw new CliError(lockedMessage(options.root))
+      throw e
+    }),
+  }
+}

package/src/dev/devServer.ts

@@ -7,7 +7,7 @@ import type { Manifest } from "../project/manifest"
 import { resolveLocalPath } from "../project/localFiles"
 import { collectLocalEntries } from "../compile/collectLocal"
 import { applyLocalShaders, isShaderArtifactName, shadersCacheDir } from "../compile/shaders"
-import { ambiguousEntryWarning, compileProject } from "../compile/projectCompile"
+import { ambiguousEntryWarning, compileProject, requireUnambiguousEntry, type AmbiguousEntryPolicy } from "../compile/projectCompile"
 import { applyProjectFonts } from "../compile/fonts"
 import { applyAppAssetIcons } from "../compile/assetIcons"
 import { renderDevScreen, renderPrelude } from "./clientTemplates"
@@ -15,7 +15,7 @@ import { serve, type Socket, type SocketHandlers } from "./serve"
 import { toKey } from "../project/paths"
 import { makeStackDemangler } from "../compile/nativeStack"
 import type { WebRunner } from "./webRunner"
-import { createProjectBackend } from "./projectBackend"
+import { createProjectBackend, forwardedBackend, type ProjectBackend } from "./projectBackend"
 import { buildHalf, halfModule, projectHalves, type ProjectHalf } from "../web/halves"
 
 /*
@@ -46,7 +46,9 @@ import { buildHalf, halfModule, projectHalves, type ProjectHalf } from "../web/h
  *                                first-party half of the id: its fallback)
  *   POST /t/<tok>/server/api/<id>  the project's backend (its `*.server.ts` files, run on this
  *   WS   /t/<tok>/server/ws        machine — projectBackend.ts): the wire of sdk/src/runtime/rpc.ts,
- *                                the one the runner serves on le.codes
+ *                                the one the runner serves on le.codes. With `backendUrl` (another dev
+ *                                server of the project runs its backend: devLink.ts) they are
+ *                                forwarded there instead, and nothing is run here
  *
  * Compile is eager: the command calls recompile() on every file change; a successful compile bumps
  * `v` and broadcasts {type:"reload", v} to connected sockets (polling clients see /version move).
@@ -81,6 +83,12 @@ export type DevServerOptions = {
   log?: (msg: string) => void
   /** The folder of the backend's database (default `.lecodes/db`; the browser tests keep their own). */
   dbDir?: string
+  /** The project's backend is another dev server's (a `lecodes dev` of it already runs it — devLink.ts
+   *  `findRunningDev`): the /server routes are forwarded to this url, no backend runs here. */
+  backendUrl?: string
+  /** A guessed entry (several import-graph roots, no main.ts): `warn` (default, `dev` / `web dev`) or
+   *  `error`, which fails the compile (`test --lite|--web`). */
+  ambiguousEntry?: AmbiguousEntryPolicy
 }
 
 export type RecompileResult =
@@ -194,7 +202,8 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
       // assetIcon() macro: resolve from the user-level cache (~/.lecodes/cache/icons) and inline —
       // one registry fetch per icon ever, so hot recompiles stay LAN/offline friendly.
       const iconsHeader = await applyAppAssetIcons(entries)
-      if (!entryOverride) {
+      if (options.ambiguousEntry === "error") requireUnambiguousEntry(entries, entryOverride)
+      else if (!entryOverride) {
         const ambiguous = ambiguousEntryWarning(entries)
         if (ambiguous) warnings.push(ambiguous)
       }
@@ -248,8 +257,12 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     return table
   }
 
-  // ---- the project's backend (projectBackend.ts), started with the first compile that has server files
-  const backend = createProjectBackend({ root, log, dbDir: options.dbDir, command: "lecodes dev" })
+  // ---- the project's backend (projectBackend.ts), started with the first compile that has server files —
+  // or another dev server's, forwarded to (`backendUrl`). Two shapes of bundle: the compile's answer goes
+  // back to the same backend's `run`.
+  const backend: ProjectBackend<any> = options.backendUrl
+    ? forwardedBackend(options.backendUrl, log)
+    : createProjectBackend({ root, log, dbDir: options.dbDir, command: "lecodes dev" })
   /** What the app's stubs call. Baked with the advertised origin; a bundle is served with the origin
    *  its request came through instead (see `rebased`). */
   const serverUrl = `${origin}${base}/server`

package/src/dev/localBackend.ts

@@ -16,6 +16,12 @@ import { LECODES_DIR } from "../project/manifest"
  * devices' reload channel with it, and a deploy starts from nothing. A deploy stops the running
  * process FIRST (one process holds the database), then starts the new bundle; when that one fails
  * to load, the bundle that ran before is started again and the failure is the deploy's error.
+ *
+ * Computed subscriptions (sdk/server `createComputedHost`) live in that process and in the hub
+ * (projectBackend.ts): every process that starts is announced (`onStart`), and the hub runs the live
+ * ones there again — a deploy, a restart after a crash or a timeout lose none. Presence (`watchers`,
+ * `members`) is the hub's table, here in the parent: the process asks it (`presence`), and the hub's word
+ * that a key's sessions changed goes to the process (`presenceChanged`).
  */
 
 /** argv[2] of the CLI when it is started as the backend's process (src/index.ts). */
@@ -25,9 +31,19 @@ export type LogLevel = "log" | "info" | "warn" | "error" | "debug"
 type Ctx = Omit<RequestContext, "id">
 
 export type ToWorker =
-  | { t: "load", code: string, dbDir: string, filesDir: string, root: string, push: PushSender | null, env: Record<string, string> }
+  /** `clock`: the server's clock offset, ms (`setClock` — a test's case clock; 0 = the machine's) */
+  | { t: "load", code: string, dbDir: string, filesDir: string, root: string, push: PushSender | null, env: Record<string, string>, clock: number }
   | { t: "invoke", req: number, id: string, args: unknown[], ctx: Ctx }
-  | { t: "subscribe", req: number, ch: string, args: unknown[], ctx: Ctx }
+  /** `sub`: a computed subscription (the hub's number) — the value is the result, and the process keeps it fresh */
+  | { t: "subscribe", req: number, ch: string, args: unknown[], ctx: Ctx, sub?: number }
+  /** a computed subscription is over (`null` = every one) */
+  | { t: "unsubscribe", sub: number | null }
+  /** the answer to the process's `presence` (its `req`): the sessions subscribed there now */
+  | { t: "presenceResult", req: number, sessions: number[] }
+  /** the sessions subscribed to (`id`, `key`) changed: the computeds that read them run again */
+  | { t: "presenceChanged", id: string, key: string }
+  /** the server's `Date.now()` reads this many ms ahead of the machine's from now on (sdk/server `setServerClock`) */
+  | { t: "clock", offsetMs: number }
   | { t: "stop" }
 
 export type FromWorker =
@@ -36,6 +52,8 @@ export type FromWorker =
   | { t: "result", req: number, result: InvokeResult }
   | { t: "publish", ch: string, group: ChannelGroup | null, data: unknown }
   | { t: "log", level: LogLevel, text: string }
+  /** `watchers` / `members`: who is subscribed to export `id` under `key` now — the hub answers (`presenceResult`) */
+  | { t: "presence", req: number, id: string, key: string }
 
 /** How `pushChannel.send` reaches the platform's sender from this machine: the linked project and the developer's
  *  own login (what `lecodes pn send` sends with). `null` = not linked or not logged in: sends answer 0, said once. */
@@ -50,6 +68,10 @@ export type LocalBackendOptions = {
   filesDir?: string
   log: (msg: string) => void
   onPublish: (ch: string, group: ChannelGroup | null, data: unknown) => void
+  /** A process took over (a deploy, a start after a crash): the hub runs the live computed subscriptions there. */
+  onStart?: () => void
+  /** Who is subscribed to (`id`, `key`) now: the hub's answer to the process's `watchers` / `members`. */
+  presence?: (id: string, key: string) => number[]
   invokeTimeoutMs?: number
   loadTimeoutMs?: number
 }
@@ -61,8 +83,17 @@ export type LocalBackend = {
    *  A changed key alone is a deploy too. Rejects with the reason when it does not load. */
   deploy: (code: string, env: Record<string, string>) => Promise<DeployResult>
   invoke: (id: string, args: unknown[], ctx: Ctx) => Promise<InvokeResult>
-  /** A channel subscription: its hooks → the subscriber's group (the envelope's `result`). */
-  subscribe: (ch: string, args: unknown[], ctx: Ctx) => Promise<InvokeResult>
+  /** A channel subscription: its hooks → the subscriber's group (the envelope's `result`). With `sub`, a
+   *  computed subscription: its first run → its value. */
+  subscribe: (ch: string, args: unknown[], ctx: Ctx, sub?: number) => Promise<InvokeResult>
+  /** A computed subscription is over. A process that is not running holds none: nothing is started for it. */
+  unsubscribe: (sub: number) => void
+  /** The sessions subscribed to (`id`, `key`) changed: the process runs the computeds that read them again.
+   *  None running, none read them: nothing is started for it. */
+  presenceChanged: (id: string, key: string) => void
+  /** The server's clock reads `offsetMs` ahead of the machine's — in the running process at once (before any
+   *  call sent after this), and in every process started from now on (a crash, a deploy). A test's case clock. */
+  setClock: (offsetMs: number) => void
   close: () => Promise<void>
 }
 
@@ -104,6 +135,8 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
   let chain: Promise<unknown> = Promise.resolve()
   let nextReq = 1
   let closed = false
+  /** the server's clock offset: what every process is started with (`setClock`) */
+  let clock = 0
 
   // However this process ends, the server's process goes with it (it holds the database).
   process.once("exit", () => { live?.child.kill() })
@@ -146,6 +179,9 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
         }
         case "publish":
           return options.onPublish(m.ch, m.group, m.data)
+        case "presence":
+          try { child.send({ t: "presenceResult", req: m.req, sessions: options.presence?.(m.id, m.key) ?? [] } satisfies ToWorker) } catch { /* the process is going */ }
+          return
         case "log":
           return log(`[server:${m.level}] ${m.text}`)
       }
@@ -160,7 +196,7 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
         if (!closed) log(`[server:error] the server process exited (${status ?? "killed"}) — it starts again with the next call`)
       }
     })
-    child.send({ t: "load", code: bundle, dbDir, filesDir, root: options.root, push: options.push ?? null, env: keys } satisfies ToWorker)
+    child.send({ t: "load", code: bundle, dbDir, filesDir, root: options.root, push: options.push ?? null, env: keys, clock } satisfies ToWorker)
   })
 
   const stop = async (l: Live) => {
@@ -177,7 +213,7 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
   const ensure = async (): Promise<Live | null> => {
     await chain.catch(() => {})
     if (live || code === null || closed) return live
-    starting ??= start(code, env).then((r) => { live = r.live; return r.live }).finally(() => { starting = null })
+    starting ??= start(code, env).then((r) => { live = r.live; options.onStart?.(); return r.live }).finally(() => { starting = null })
     try { return await starting } catch (e) { log(`[server:error] ${(e as Error).message}`); return null }
   }
 
@@ -188,7 +224,7 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
       const req = nextReq++
       const timer = setTimeout(() => {
         if (!l.pending.delete(req)) return
-        const what = msg.t === "invoke" ? `endpoint ${msg.id}` : `subscription to ${msg.ch}`
+        const what = msg.t === "invoke" ? `endpoint ${msg.id}` : msg.sub !== undefined ? `computed ${msg.ch}` : `subscription to ${msg.ch}`
         log(`[server:error] ${what} exceeded ${invokeTimeoutMs} ms — the server process is restarted`)
         resolve({ ok: false, status: 504, message: `Endpoint timed out after ${invokeTimeoutMs} ms` })
         if (live === l) live = null
@@ -209,10 +245,11 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
       live = next.live
       code = bundle
       env = keys
+      options.onStart?.()
       return { changed: true, describe: next.live.describe, notes: next.notes }
     } catch (e) {
       // the bundle that ran before answers the devices again (they still run its client)
-      if (before !== null) await start(before, beforeEnv).then((r) => { live = r.live }, () => {})
+      if (before !== null) await start(before, beforeEnv).then((r) => { live = r.live; options.onStart?.() }, () => {})
       throw e
     }
   }
@@ -224,7 +261,18 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
       return run
     },
     invoke: (id, args, ctx) => roundTrip({ t: "invoke", req: 0, id, args, ctx }),
-    subscribe: (ch, args, ctx) => roundTrip({ t: "subscribe", req: 0, ch, args, ctx }),
+    subscribe: (ch, args, ctx, sub) => roundTrip({ t: "subscribe", req: 0, ch, args, ctx, ...(sub !== undefined ? { sub } : {}) }),
+    unsubscribe: (sub) => {
+      try { if (live?.child.connected) live.child.send({ t: "unsubscribe", sub } satisfies ToWorker) } catch { /* the process is going: it holds nothing then */ }
+    },
+    presenceChanged: (id, key) => {
+      try { if (live?.child.connected) live.child.send({ t: "presenceChanged", id, key } satisfies ToWorker) } catch { /* the process is going: a new one reads presence afresh */ }
+    },
+    // the same channel as the calls: a call sent after this reads the new clock
+    setClock: (offsetMs) => {
+      clock = offsetMs
+      try { if (live?.child.connected) live.child.send({ t: "clock", offsetMs } satisfies ToWorker) } catch { /* the process is going: the next one starts with it */ }
+    },
     close: async () => {
       closed = true
       await chain.catch(() => {})