lecodes-cli 2.0.3 → 2.0.5

package/src/dev/devServer.ts

@@ -1,6 +1,6 @@
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
 import { createReadStream, statSync } from "node:fs"
 import { join } from "node:path"
+import { Readable } from "node:stream"
 import type { Manifest } from "../project/manifest"
 import { resolveLocalPath } from "../project/localFiles"
 import { collectLocalEntries } from "../compile/collectLocal"
@@ -9,13 +9,16 @@ import { ambiguousEntryWarning, compileProject } from "../compile/projectCompile
 import { applyProjectFonts } from "../compile/fonts"
 import { applyAppAssetIcons } from "../compile/assetIcons"
 import { renderDevScreen, renderPrelude } from "./clientTemplates"
-import { upgradeWebSocket, type WsConnection } from "./wsServer"
+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"
 
 /*
- * The `lecodes dev` LAN server: serves the project to devices and hot-reloads it on change.
+ * The `lecodes dev` LAN server: serves the project to devices and hot-reloads it on change. It
+ * listens through ./serve.ts — requests and websockets in the web-standard shape, the same on Node
+ * and on Bun.
  *
  * All routes live under a capability-token base path (/t/<token>):
  *   GET /t/<tok>/dev.js          the bootstrap bundle the QR points at (placeholder screen + prelude)
@@ -33,10 +36,17 @@ import type { WebRunner } from "./webRunner"
  *                                polling) and the log backchannel. A phone is sent here at once
  *   GET /t/<tok>/lite/[file]     the page of Web Lite (lecodes-web-lite's dist), opened as
  *                                lite/?dev=.. — the same bundle.js?t=web, the same reload and logs
+ *   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
  *
  * 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).
  * A failed compile keeps the last good bundle — devices stay on it until the next good compile.
+ *
+ * A project with server files is compiled twice — its server bundle and the app with the backend's
+ * url in its stubs — and the backend takes the new bundle BEFORE devices are told to reload. A
+ * server bundle that does not load fails the compile like a code error.
  */
 
 export type DevServerOptions = {
@@ -57,6 +67,8 @@ export type DevServerOptions = {
   lite?: string | null
   /** Diagnostics (compile errors, device logs); defaults to stderr-style silence-safe noop. */
   log?: (msg: string) => void
+  /** The folder of the backend's database (default `.lecodes/db`; the browser tests keep their own). */
+  dbDir?: string
 }
 
 export type RecompileResult =
@@ -76,7 +88,10 @@ export type DevServer = {
   v: () => number
   clientCount: () => number
   recompile: () => Promise<RecompileResult>
-  close: () => void
+  /** The project's backend starts again on an empty database (a test's case). */
+  resetBackend: () => Promise<void>
+  /** Resolves once the project's backend (if one runs) has closed its database. */
+  close: () => Promise<void>
 }
 
 const MIME: Record<string, string> = {
@@ -95,47 +110,43 @@ export const contentType = (path: string): string => {
   return (i >= 0 && MIME[path.slice(i + 1).toLowerCase()]) || "application/octet-stream"
 }
 
-const sendText = (res: ServerResponse, status: number, type: string, body: string) => {
-  res.writeHead(status, { "content-type": type, "cache-control": "no-store" })
-  res.end(body)
-}
+const NO_STORE = { "cache-control": "no-store" }
+
+const text = (status: number, type: string, body: string, headers: Record<string, string> = {}) =>
+  new Response(body, { status, headers: { "content-type": type, ...NO_STORE, ...headers } })
+
+const json = (status: number, body: unknown, headers: Record<string, string> = {}) =>
+  text(status, "application/json", JSON.stringify(body), headers)
+
+/** A file on disk as a response body (a range of it when `start` / `end` are given). */
+const fileBody = (abs: string, range?: { start: number, end: number }) =>
+  Readable.toWeb(createReadStream(abs, range)) as unknown as ReadableStream
 
 /** A working-tree file with byte-range support. AVPlayer (the iOS host's video / audio players)
  *  opens an HTTP source with `Range: bytes=0-1` and fails the item with -11850 "The server is not
  *  correctly configured" when the answer is a plain 200, so an asset route must answer ranges. */
-const sendFile = (req: IncomingMessage, res: ServerResponse, abs: string, type: string) => {
+const fileResponse = (req: Request, abs: string, type: string): Response => {
   const size = statSync(abs).size
-  const headers = { "content-type": type, "cache-control": "no-store", "accept-ranges": "bytes" }
-  const m = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range ?? "")
+  const headers = { "content-type": type, ...NO_STORE, "accept-ranges": "bytes" }
+  const head = req.method === "HEAD"
+  const m = /^bytes=(\d*)-(\d*)$/.exec(req.headers.get("range") ?? "")
   if (m && (m[1] || m[2])) {
     // bytes=a-b, bytes=a- (to the end), bytes=-n (the last n bytes)
     const start = m[1] ? Number(m[1]) : Math.max(0, size - Number(m[2]))
     const end = m[1] && m[2] ? Math.min(Number(m[2]), size - 1) : size - 1
-    if (start >= size || start > end) {
-      res.writeHead(416, { ...headers, "content-range": `bytes */${size}` })
-      res.end()
-      return
-    }
-    res.writeHead(206, { ...headers, "content-range": `bytes ${start}-${end}/${size}`, "content-length": end - start + 1 })
-    if (req.method === "HEAD") return void res.end()
-    createReadStream(abs, { start, end }).pipe(res)
-    return
+    if (start >= size || start > end) return new Response(null, { status: 416, headers: { ...headers, "content-range": `bytes */${size}` } })
+    return new Response(head ? null : fileBody(abs, { start, end }), {
+      status: 206, headers: { ...headers, "content-range": `bytes ${start}-${end}/${size}`, "content-length": String(end - start + 1) },
+    })
   }
-  res.writeHead(200, { ...headers, "content-length": size })
-  if (req.method === "HEAD") return void res.end()
-  createReadStream(abs).pipe(res)
+  return new Response(head ? null : fileBody(abs), { status: 200, headers: { ...headers, "content-length": String(size) } })
 }
 
-const sendJson = (res: ServerResponse, status: number, body: unknown) =>
-  sendText(res, status, "application/json", JSON.stringify(body))
-
-const readBody = (req: IncomingMessage): Promise<string> =>
-  new Promise((resolve) => {
-    let body = ""
-    req.on("data", (c: Buffer) => { if (body.length < 256 * 1024) body += c.toString("utf8") })
-    req.on("end", () => resolve(body))
-    req.on("error", () => resolve(body))
-  })
+/** A request's body as text; null when it is larger than `limit`. */
+const readBody = async (req: Request, limit = 256 * 1024): Promise<string | null> => {
+  const body = await req.text().catch(() => "")
+  return body.length > limit ? null : body
+}
 
 export const startDevServer = async (options: DevServerOptions): Promise<DevServer> => {
   const { root, manifest, name, origin, token, entryOverride } = options
@@ -175,7 +186,11 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
         const ambiguous = ambiguousEntryWarning(entries)
         if (ambiguous) warnings.push(ambiguous)
       }
-      const js = await compileProject({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader, iconsHeader, onWarning: (w) => warnings.push(w) })
+      const onWarning = (w: string) => { warnings.push(w) }
+      const serverBundle = await backend.compile(entries, onWarning)
+      const js = await compileProject({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader, iconsHeader, onWarning, serverUrl: serverBundle ? serverUrl : undefined })
+      // the backend takes the new bundle once the app compiled, and before devices are told to reload
+      warnings.push(...await backend.run(serverBundle))
       const changed = bundleJs === null || stripVolatile(js) !== stripVolatile(bundleJs)
       if (changed) {
         bundleJs = js
@@ -188,6 +203,12 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     }
   }
 
+  // ---- 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" })
+  /** 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`
+
   // Serialized: a recompile requested mid-compile runs after it (compileOnce never rejects).
   const recompile = (): Promise<RecompileResult> => {
     const run = compileChain.then(compileOnce)
@@ -205,7 +226,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
   })
 
   // ---- websocket clients -------------------------------------------------------------------------
-  const clients = new Set<WsConnection>()
+  const clients = new Set<Socket>()
   const broadcast = (text: string) => {
     for (const client of clients) client.send(text)
   }
@@ -234,162 +255,145 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
   }
   // The prelude talks back to the origin THIS request came through (the Host header): a phone on
   // `adb reverse` reached us as 127.0.0.1:<port> and can't see the LAN address the QR carries.
-  const withPrelude = (js: string, url: URL, v: number, reqOrigin: string, forced?: "poll") => {
-    const transport = forced ?? transportOf(url)
+  const withPrelude = (js: string, url: URL, v: number, reqOrigin: string) => {
+    const transport = transportOf(url)
     return transport === "web" ? js : js + "\n" + renderPrelude({ origin: reqOrigin, base, transport, v })
   }
+  // The backend's url likewise: the app calls it through the origin the bundle was fetched from.
+  const rebased = (js: string, reqOrigin: string) =>
+    reqOrigin === origin ? js : js.split(serverUrl).join(`${reqOrigin}${base}/server`)
   const web = options.web ?? null
   const lite = options.lite ?? null
   /** A file of a built folder; the entry files revalidate — a CLI update swaps them under the same
    *  url — while what is under assets/ carries its hash in its name. */
-  const sendBuilt = (res: ServerResponse, dir: string, rel: string) => {
-    if (rel.split("/").some((seg) => seg === ".." || seg === "" || seg === ".")) return sendText(res, 400, "text/plain", "Bad path")
+  const built = (dir: string, rel: string): Response => {
+    if (rel.split("/").some((seg) => seg === ".." || seg === "" || seg === ".")) return text(400, "text/plain", "Bad path")
     const abs = join(dir, ...rel.split("/"))
     try {
       if (!statSync(abs).isFile()) throw new Error("not a file")
     } catch {
-      return sendText(res, 404, "text/plain", "Not found")
+      return text(404, "text/plain", "Not found")
     }
-    res.writeHead(200, { "content-type": contentType(rel), "cache-control": rel.startsWith("assets/") ? "max-age=31536000, immutable" : "no-store" })
-    createReadStream(abs).pipe(res)
+    return new Response(fileBody(abs), { headers: { "content-type": contentType(rel), "cache-control": rel.startsWith("assets/") ? "max-age=31536000, immutable" : "no-store" } })
   }
+  const redirect = (to: string) => new Response(null, { status: 302, headers: { location: to } })
 
-  const handle = async (req: IncomingMessage, res: ServerResponse) => {
-    const reqOrigin = req.headers.host ? `http://${req.headers.host}` : origin
-    const url = new URL(req.url ?? "/", reqOrigin)
+  const handle = async (req: Request, ip: string | undefined): Promise<Response> => {
+    const host = req.headers.get("host")
+    const reqOrigin = host ? `http://${host}` : origin
+    const url = new URL(req.url)
     const path = url.pathname
     // Browsers ask for it on every page load (the /web/ runner) — keep the console clean.
-    if (path === "/favicon.ico") { res.writeHead(204); res.end(); return }
-    if (!path.startsWith(base + "/")) return sendText(res, 404, "text/plain", "Not found")
+    if (path === "/favicon.ico") return new Response(null, { status: 204 })
+    if (!path.startsWith(base + "/")) return text(404, "text/plain", "Not found")
     const route = path.slice(base.length)
 
     if (route === "/dev.js") {
-      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1, reqOrigin))
-    }
-    // The poll transport as a PATH: the Android app's initial.js only fetches a launch url that ends
-    // in ".js" (anything else goes to le.codes/api/code), so `?t=poll` can't reach it. Same bundle,
-    // prelude polls instead of the websocket — what `dev --android` opens under Bun (no ws there).
-    if (route === "/dev-poll.js") {
-      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1, reqOrigin, "poll"))
+      return text(200, "text/javascript", withPrelude(devJs, url, -1, reqOrigin))
     }
     if (route === "/bundle.js") {
-      if (bundleJs === null) return sendText(res, 503, "text/plain", "No successful compile yet — check the terminal.")
-      res.setHeader("x-lecodes-v", String(v))   // the browser runner learns the version it runs
-      return sendText(res, 200, "text/javascript", withPrelude(bundleJs, url, v, reqOrigin))
+      if (bundleJs === null) return text(503, "text/plain", "No successful compile yet — check the terminal.")
+      // x-lecodes-v: the browser runner learns the version it runs
+      return text(200, "text/javascript", withPrelude(rebased(bundleJs, reqOrigin), url, v, reqOrigin), { "x-lecodes-v": String(v) })
     }
+    if (route.startsWith("/server/")) return backend.handle(req, route.slice("/server".length), ip)
     // The browser: built folders with relative asset paths, so each needs its trailing slash. The
     // player is told the server it runs the project of (`dev`: this one, two folders up).
     if (route === "/web" || route.startsWith("/web/")) {
-      if (!web) return sendText(res, 404, "text/plain", "No web player vendored with this CLI (lecodes-web-player's dist).")
-      const redirect = (to: string) => { res.writeHead(302, { location: to }); res.end() }
+      if (!web) return text(404, "text/plain", "No web player vendored with this CLI (lecodes-web-player's dist).")
       const query = (extra?: [string, string]) => { if (extra) url.searchParams.set(...extra); const q = url.searchParams.toString(); return q ? `?${q}` : "" }
       const rel = route.slice("/web".length)
       if (rel === "/player" || (rel === "/player/" && !url.searchParams.has("dev"))) return redirect(`${base}/web/player/${query(["dev", "../.."])}`)
-      if (rel.startsWith("/player/")) return sendBuilt(res, web.player, rel === "/player/" ? "index.html" : rel.slice("/player/".length))
+      if (rel.startsWith("/player/")) return built(web.player, rel === "/player/" ? "index.html" : rel.slice("/player/".length))
       // no page around the player in this CLI: the player alone
       if (!web.page) return redirect(`${base}/web/player/${query(["dev", "../.."])}`)
       if (rel === "") return redirect(`${base}/web/${query()}`)
-      return sendBuilt(res, web.page, rel === "/" ? "index.html" : rel.slice(1))
+      return built(web.page, rel === "/" ? "index.html" : rel.slice(1))
     }
     if (route === "/lite" || route.startsWith("/lite/")) {
-      if (!lite) return sendText(res, 404, "text/plain", "No Web Lite page with this CLI (lecodes-web-lite's dist).")
+      if (!lite) return text(404, "text/plain", "No Web Lite page with this CLI (lecodes-web-lite's dist).")
       const rel = route.slice("/lite".length)
       if (rel === "" || (rel === "/" && !url.searchParams.has("dev"))) {
         url.searchParams.set("dev", "..")
-        res.writeHead(302, { location: `${base}/lite/?${url.searchParams.toString()}${url.hash}` })
-        res.end()
-        return
+        return redirect(`${base}/lite/?${url.searchParams.toString()}${url.hash}`)
       }
-      return sendBuilt(res, lite, rel === "/" ? "index.html" : rel.slice(1))
+      return built(lite, rel === "/" ? "index.html" : rel.slice(1))
     }
     if (route === "/version") {
-      return sendJson(res, 200, { v })
+      return json(200, { v })
     }
     if (route === "/log" && req.method === "POST") {
-      printDeviceMessage(await readBody(req))
-      return sendJson(res, 200, { ok: true })
+      printDeviceMessage(await readBody(req) ?? "")
+      return json(200, { ok: true })
     }
     if (route.startsWith("/shaders/")) {
       const name = route.slice("/shaders/".length)
-      if (!isShaderArtifactName(name)) return sendText(res, 400, "text/plain", "Bad path")
+      if (!isShaderArtifactName(name)) return text(400, "text/plain", "Bad path")
       const abs = join(shadersCacheDir(root), name)
       try {
         if (!statSync(abs).isFile()) throw new Error("not a file")
       } catch {
-        return sendText(res, 404, "text/plain", "Not found")
+        return text(404, "text/plain", "Not found")
       }
-      res.writeHead(200, { "content-type": "application/octet-stream", "cache-control": "no-store" })
-      createReadStream(abs).pipe(res)
-      return
+      return new Response(fileBody(abs), { headers: { "content-type": "application/octet-stream", ...NO_STORE } })
     }
     if (route.startsWith("/assets/")) {
       let key: string
       try {
         key = toKey(decodeURIComponent(route.slice("/assets".length)))
       } catch {
-        return sendText(res, 400, "text/plain", "Bad path")
+        return text(400, "text/plain", "Bad path")
       }
       const abs = resolveLocalPath(root, key)
-      if (!abs || !statSync(abs).isFile()) return sendText(res, 404, "text/plain", "Not found")
-      return sendFile(req, res, abs, contentType(key))
+      if (!abs || !statSync(abs).isFile()) return text(404, "text/plain", "Not found")
+      return fileResponse(req, abs, contentType(key))
     }
-    return sendText(res, 404, "text/plain", "Not found")
+    return text(404, "text/plain", "Not found")
   }
 
-  const server: Server = createServer((req, res) => {
-    handle(req, res).catch((e) => {
-      log(`request failed: ${e instanceof Error ? e.message : String(e)}`)
-      if (!res.headersSent) sendText(res, 500, "text/plain", "Internal error")
-    })
-  })
-
-  server.on("upgrade", (req, socket) => {
-    const url = new URL(req.url ?? "/", origin)
-    if (url.pathname !== base + "/ws") {
-      socket.destroy()
-      return
-    }
-    const conn = upgradeWebSocket(req, socket, {
-      onMessage: (text) => {
+  // The reload channel: a (re)connecting world says what it runs, then sends its logs and errors.
+  const reloadSocket = (conn: Socket): SocketHandlers => {
+    clients.add(conn)
+    return {
+      onMessage: (raw) => {
         let m: { type?: string, v?: number } = {}
-        try { m = JSON.parse(text) } catch { /* not ours */ }
+        try { m = JSON.parse(raw) } catch { /* not ours */ }
         if (m.type === "hello") {
-          // A (re)connecting world announces what it runs; nudge it forward if it's stale.
-          if (typeof m.v === "number" && m.v !== v && bundleJs !== null) {
-            conn?.send(JSON.stringify({ type: "reload", v }))
-          }
+          // nudge it forward if it's stale
+          if (typeof m.v === "number" && m.v !== v && bundleJs !== null) conn.send(JSON.stringify({ type: "reload", v }))
         } else {
-          printDeviceMessage(text)
+          printDeviceMessage(raw)
         }
       },
-      onClose: () => { if (conn) clients.delete(conn) },
-    })
-    if (conn) clients.add(conn)
-  })
+      onClose: () => { clients.delete(conn) },
+    }
+  }
 
-  await new Promise<void>((resolve, reject) => {
-    server.once("error", reject)
-    server.listen(options.port, options.bind ?? "0.0.0.0", () => {
-      server.removeListener("error", reject)
-      resolve()
-    })
+  const server = await serve({
+    port: options.port,
+    hostname: options.bind,
+    fetch: (req, peer) => handle(req, peer.ip),
+    websocket: (req, peer) => {
+      const path = new URL(req.url).pathname
+      return path === base + "/ws" ? reloadSocket : path === base + "/server/ws" ? backend.socket(req, peer.ip) : null
+    },
+    onError: (e) => log(`request failed: ${e instanceof Error ? e.message : String(e)}`),
   })
 
-  const address = server.address()
-  const boundPort = typeof address === "object" && address !== null ? address.port : options.port
-
   return {
     url: `${origin}${base}/dev.js`,
     webUrl: web ? `${origin}${base}/web/` : null,
     liteUrl: lite ? `${origin}${base}/lite/` : null,
     base,
-    port: boundPort,
+    port: server.port,
     v: () => v,
     clientCount: () => clients.size,
     recompile,
-    close: () => {
-      for (const client of clients) client.close()
+    resetBackend: () => backend.reset(),
+    close: async () => {
+      for (const client of [...clients]) client.close()
       server.close()
+      await backend.close()
     },
   }
 }

package/src/dev/localBackend.ts

@@ -0,0 +1,214 @@
+import { spawn, type ChildProcess } from "node:child_process"
+import { basename, dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import type { ChannelGroup, InvokeResult, RequestContext, ServerDescription } from "lecodes-sdk/server"
+import { LECODES_DIR } from "../project/manifest"
+
+/*
+ * The app backend on this machine: the project's server bundle (its `*.server.ts` files) run here,
+ * with its database in `.lecodes/db` — what the runner (tools/runner) is on le.codes, for one
+ * project and one developer. projectBackend.ts puts it on the wire the SDK's client transport
+ * speaks (sdk/src/runtime/rpc.ts): under the dev server's `/t/<token>/server`, or on a port of its
+ * own for a host the CLI starts.
+ *
+ * The bundle runs in a process of its own (backendWorker.ts — this CLI started again with
+ * BACKEND_WORKER_ARG): server code that hangs or crashes takes neither the dev server nor the
+ * 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.
+ */
+
+/** argv[2] of the CLI when it is started as the backend's process (src/index.ts). */
+export const BACKEND_WORKER_ARG = "__backend-worker"
+
+export type LogLevel = "log" | "info" | "warn" | "error" | "debug"
+type Ctx = Omit<RequestContext, "id">
+
+export type ToWorker =
+  | { t: "load", code: string, dbDir: string }
+  | { t: "invoke", req: number, id: string, args: unknown[], ctx: Ctx }
+  | { t: "subscribe", req: number, ch: string, args: unknown[], ctx: Ctx }
+  | { t: "stop" }
+
+export type FromWorker =
+  | { t: "loaded", describe: ServerDescription, notes: string[] }
+  | { t: "loadError", message: string }
+  | { t: "result", req: number, result: InvokeResult }
+  | { t: "publish", ch: string, group: ChannelGroup | null, data: unknown }
+  | { t: "log", level: LogLevel, text: string }
+
+export type LocalBackendOptions = {
+  root: string
+  /** The database's folder (default `.lecodes/db`). */
+  dbDir?: string
+  log: (msg: string) => void
+  onPublish: (ch: string, group: ChannelGroup | null, data: unknown) => void
+  invokeTimeoutMs?: number
+  loadTimeoutMs?: number
+}
+
+export type DeployResult = { changed: boolean, describe: ServerDescription, notes: string[] }
+
+export type LocalBackend = {
+  /** Run this bundle from now on. Rejects with the reason when it does not load. */
+  deploy: (code: 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>
+  close: () => Promise<void>
+}
+
+type Live = {
+  child: ChildProcess
+  describe: ServerDescription
+  pending: Map<number, { resolve: (r: InvokeResult) => void, timer: ReturnType<typeof setTimeout> }>
+  gone: Promise<void>
+}
+
+/** How this CLI starts itself again: its entry under node / bun — this file IS the entry in the
+ *  built CLI (one bundle), and sits beside it in the sources — or the standalone binary alone. */
+const selfCommand = (): string[] => {
+  const here = fileURLToPath(import.meta.url)
+  if (/[\\/](\$bunfs|~BUN)[\\/]/.test(here)) return [process.execPath]
+  const entry = /^localBackend\.[cm]?[jt]s$/.test(basename(here)) ? join(dirname(here), "..", "index.ts") : here
+  return [process.execPath, ...process.execArgv, entry]
+}
+
+export const startLocalBackend = (options: LocalBackendOptions): LocalBackend => {
+  const { log } = options
+  const invokeTimeoutMs = options.invokeTimeoutMs ?? 30_000
+  const loadTimeoutMs = options.loadTimeoutMs ?? 15_000
+  const dbDir = options.dbDir ?? join(options.root, LECODES_DIR, "db")
+
+  let live: Live | null = null
+  /** The bundle that is deployed — what a crashed or timed-out process is started from again. */
+  let code: string | null = null
+  let starting: Promise<Live> | null = null
+  let chain: Promise<unknown> = Promise.resolve()
+  let nextReq = 1
+  let closed = false
+
+  // However this process ends, the server's process goes with it (it holds the database).
+  process.once("exit", () => { live?.child.kill() })
+
+  const failPending = (l: Live, message: string) => {
+    for (const [, p] of l.pending) { clearTimeout(p.timer); p.resolve({ ok: false, status: 503, message }) }
+    l.pending.clear()
+  }
+
+  const start = (bundle: string): Promise<{ live: Live, notes: string[] }> => new Promise((resolve, reject) => {
+    const [exe, ...args] = selfCommand()
+    const child = spawn(exe!, [...args, BACKEND_WORKER_ARG], { cwd: options.root, stdio: ["ignore", "inherit", "inherit", "ipc"] })
+    let exited!: () => void
+    const l: Live = { child, describe: null as unknown as ServerDescription, pending: new Map(), gone: new Promise<void>((r) => { exited = r }) }
+    let settled = false
+    const fail = (message: string) => {
+      if (settled) return
+      settled = true; clearTimeout(timer)
+      child.kill()
+      reject(new Error(message))
+    }
+    const timer = setTimeout(() => fail(`the server bundle did not load within ${loadTimeoutMs} ms`), loadTimeoutMs)
+    child.on("message", (m: FromWorker) => {
+      switch (m.t) {
+        case "loaded":
+          if (settled) return
+          settled = true; clearTimeout(timer)
+          l.describe = m.describe
+          return resolve({ live: l, notes: m.notes })
+        case "loadError":
+          return fail(m.message)
+        case "result": {
+          const p = l.pending.get(m.req)
+          if (!p) return
+          l.pending.delete(m.req)
+          clearTimeout(p.timer)
+          return p.resolve(m.result)
+        }
+        case "publish":
+          return options.onPublish(m.ch, m.group, m.data)
+        case "log":
+          return log(`[server:${m.level}] ${m.text}`)
+      }
+    })
+    child.on("error", (e) => fail(`the server process did not start: ${e.message}`))
+    child.on("exit", (status) => {
+      exited()
+      fail(`the server process exited (${status ?? "killed"}) while loading`)
+      failPending(l, "server restarting")
+      if (live === l) {
+        live = null
+        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 } satisfies ToWorker)
+  })
+
+  const stop = async (l: Live) => {
+    if (live === l) live = null
+    failPending(l, "server restarting")
+    if (l.child.exitCode !== null || l.child.signalCode !== null) return
+    try { l.child.send({ t: "stop" } satisfies ToWorker) } catch { /* channel already closed */ }
+    const forced = setTimeout(() => l.child.kill(), 2000)
+    await l.gone
+    clearTimeout(forced)
+  }
+
+  /** The running process, started from the deployed bundle when it is gone (a crash, a timeout). */
+  const ensure = async (): Promise<Live | null> => {
+    await chain.catch(() => {})
+    if (live || code === null || closed) return live
+    starting ??= start(code).then((r) => { live = r.live; return r.live }).finally(() => { starting = null })
+    try { return await starting } catch (e) { log(`[server:error] ${(e as Error).message}`); return null }
+  }
+
+  const roundTrip = async (msg: Extract<ToWorker, { t: "invoke" | "subscribe" }>): Promise<InvokeResult> => {
+    const l = await ensure()
+    if (!l) return { ok: false, status: 503, message: "The project's server is not running — see the terminal of the command that started it" }
+    return new Promise<InvokeResult>((resolve) => {
+      const req = nextReq++
+      const timer = setTimeout(() => {
+        if (!l.pending.delete(req)) return
+        const what = msg.t === "invoke" ? `endpoint ${msg.id}` : `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
+        failPending(l, "server restarting")
+        l.child.kill()
+      }, invokeTimeoutMs)
+      l.pending.set(req, { resolve, timer })
+      l.child.send({ ...msg, req })
+    })
+  }
+
+  const deployNow = async (bundle: string): Promise<DeployResult> => {
+    if (bundle === code && live) return { changed: false, describe: live.describe, notes: [] }
+    const before = code
+    if (live) await stop(live)
+    try {
+      const next = await start(bundle)
+      live = next.live
+      code = bundle
+      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).then((r) => { live = r.live }, () => {})
+      throw e
+    }
+  }
+
+  return {
+    deploy: (bundle) => {
+      const run = chain.catch(() => {}).then(() => deployNow(bundle))
+      chain = run
+      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 }),
+    close: async () => {
+      closed = true
+      await chain.catch(() => {})
+      if (live) await stop(live)
+    },
+  }
+}