lecodes-cli 2.0.4 → 2.0.6

package/runtime/web-lite/plugins/qr-scanner/index-CK_cYoJR.js

@@ -0,0 +1 @@
+const h={present:e=>e!=null,f64:e=>typeof e=="number"&&Number.isFinite(e)?e:void 0,i32:e=>typeof e=="number"&&Number.isInteger(e)&&e>=-2147483648&&e<=2147483647?e:void 0,bool:e=>typeof e=="boolean"?e:void 0,string:e=>typeof e=="string"?e:void 0,json:e=>e,bytes:e=>Object.prototype.toString.call(e)==="[object Uint8Array]"?e.slice():void 0,object:e=>typeof e=="object"&&e!==null&&!Array.isArray(e)?e:void 0,array:(e,r)=>Array.isArray(e)&&(r===void 0||e.length===r)?e:void 0,list:(e,r)=>{if(!Array.isArray(e))return;const n=[];for(const c of e){const o=r(c);if(o===void 0)return;n.push(o)}return n},map:(e,r)=>{if(typeof e!="object"||e===null||Array.isArray(e))return;const n={};for(const[c,o]of Object.entries(e)){const s=r(o);if(s===void 0)return;n[c]=s}return n}},j=e=>!h.present(e)||h.object(e)?{}:void 0,v={name:"qrScanner",version:1},A=(e,r)=>{e.registerView(v.name,(n,c,o)=>{const s={scan:i=>c.emit("scan",i)},a=r(j(n)??{},s,o),t=async(i,p)=>{throw new Error(`Unknown method: ${i}`)};return{el:a.el,call:t,destroy:()=>{var i;return(i=a.destroy)==null?void 0:i.call(a)}}},v.version)},S=150,k=10,T=e=>{var n;const r=globalThis.BarcodeDetector;r&&(typeof navigator>"u"||typeof((n=navigator.mediaDevices)==null?void 0:n.getUserMedia)!="function"||A(e,(c,o,s)=>{const a=s.createElement("div");a.style.cssText="background:#000;overflow:hidden";const t=s.createElement("video");t.autoplay=!0,t.muted=!0,t.playsInline=!0,t.setAttribute("playsinline",""),t.style.cssText="position:absolute;inset:0;width:100%;height:100%;object-fit:cover",a.appendChild(t);const i=new r({formats:["qr_code"]}),p=s.defaultView??globalThis;let u=null,b=null,f=!1,m=!1,y=null,g=0;const w=async()=>{var l;if(!(m||f||t.videoWidth===0)){m=!0;try{const d=((l=(await i.detect(t))[0])==null?void 0:l.rawValue)??null;if(f)return;d!==null?(g=0,d!==y&&(y=d,o.scan({data:d}))):y!==null&&++g>=k&&(y=null,o.scan({data:null}))}catch{}finally{m=!1}}};return navigator.mediaDevices.getUserMedia({video:{facingMode:"environment"},audio:!1}).then(l=>{if(f){for(const d of l.getTracks())d.stop();return}u=l,t.srcObject=l,t.play().catch(()=>{}),b=p.setInterval(()=>{w()},S)},()=>{}),{el:a,destroy(){if(f=!0,b!==null&&p.clearInterval(b),u)for(const l of u.getTracks())l.stop();u=null,t.srcObject=null}}}))};export{T as register};

package/runtime/web-lite/plugins.json

@@ -0,0 +1,8 @@
+{
+  "plugins": {
+    "camera": "plugins/camera/index-5XOM8eHl.js",
+    "geolocation": "plugins/geolocation/index-BjTKN9_P.js",
+    "map": "plugins/map/index-BTBHQ264.js",
+    "qr-scanner": "plugins/qr-scanner/index-CK_cYoJR.js"
+  }
+}

package/src/commands/compile.ts

@@ -13,6 +13,7 @@ import { buildGlobMatcher } from "../project/ignore"
 import { readAppConfigAt } from "./app/shared"
 import { defineCommand, isNullSink, note, warnErr } from "../cli"
 import { bundleFlags, bundleOptions, outFlag, session, type BundleOptions } from "./shared"
+import type { RunBackend } from "../dev/projectBackend"
 
 /*
  * `lecodes compile` — the local project as one JS bundle (the server's pipeline), printed to stdout
@@ -81,6 +82,10 @@ export type BuildBundleOptions = {
   entryOverride?: string
   /** Shell mode (`lecodes app sync`) — see above. */
   shell?: ShellCompile
+  /** The bundle is about to RUN on this machine: a project with server files gets its backend
+   *  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
 }
 
 export default defineCommand({
@@ -213,8 +218,9 @@ export const buildBundle = async (bundle: BundleOptions, opts: BuildBundleOption
     const ambiguous = ambiguousEntryWarning(entries)
     if (ambiguous) warnErr(ambiguous)
   }
+  const serverUrl = await opts.backend?.start(entries, (w) => warnings.push(w))
   const js = await compileProject({
-    entries, name, publicUrl, entryOverride,
+    entries, name, publicUrl, entryOverride, serverUrl,
     header: bundle.header ?? true,
     localAssets, fontsHeader, iconsHeader,
     minify: bundle.minify,

package/src/commands/desktop.ts

@@ -1,5 +1,5 @@
 import { basename } from "node:path"
-import { CliError, bool, c, defineCommand, log, note, num, str } from "../cli"
+import { CliError, bool, c, defineCommand, log, logErr, note, num, str } from "../cli"
 import {
   DESKTOP_RENDERER_VERSION, fetchDesktopManifest, findMacHostExe, installedDesktopVersions, runDesktopApp,
   selectedDesktopVersion, semverNewer, updateDesktop,
@@ -7,6 +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 { bundleFlags, bundleOptions, localProject } from "./shared"
 
 /*
@@ -40,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. 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 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).",
   flags: {
     width: num("window width (logical px)"),
     height: num("window height (logical px)"),
@@ -68,7 +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)
-    const { js, resources } = await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer: 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 })
+    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)
     if (pluginFiles.length > 0) note(`Native plugins: ${pluginFiles.map((f) => basename(f)).join(", ")}`)
@@ -101,7 +104,7 @@ const run = defineCommand({
       net: flags.server
         ? { role: "server", port: flags.port, maxClients: flags["max-clients"] }
         : flags.connect ? { role: "client", address: flags.connect } : undefined,
-    })
+    }).finally(() => backend.close())
   },
 })
 

package/src/commands/dev.ts

@@ -22,7 +22,8 @@ import { bundleFlags } from "./shared"
  * working tree. The device opens the QR URL like any project URL; every save recompiles and
  * hot-swaps the running app (`_creatorApp.run` — fresh context, rollback on error). Device
  * console output and errors stream back to this terminal. Fully local: no login, no le.codes
- * backend. Custom shaders compile locally too (matc, downloaded on first use — matcTool.ts);
+ * backend — a project's own backend (its `*.server.ts` files) runs here too, its database in
+ * .lecodes/db (dev/localBackend.ts). Custom shaders compile locally too (matc, downloaded on first use — matcTool.ts);
  * only when matc can't be fetched do they fall back to server-compiled artifacts (push once).
  *
  * `--web` opens the same project in the browser: the dev server also serves, under /web/, the
@@ -145,16 +146,6 @@ export default defineCommand({
     }
     const name = manifest?.name ?? basename(root)
 
-    // Bun's node:http can't complete a websocket upgrade (writes to the upgraded socket are dropped),
-    // so the reload push would silently never reach devices: a phone that scanned a websocket url
-    // sat on "Connected — loading the project…" forever. Under Bun every device url — the QR, the
-    // printed one, what --ios / --android open — is the POLL form (/dev-poll.js: a path, since the
-    // launcher only fetches urls that end in .js). Node is the shipped runtime.
-    const underBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined"
-    if (underBun) {
-      warnErr("Running under Bun: no websocket reload channel here — devices poll instead (the QR points at /dev-poll.js). Node is the shipped runtime.")
-    }
-
     const port = flags.port || DEFAULT_PORT
     const candidates = lanCandidates()
     const host = flags.host ?? candidates[0]?.address
@@ -203,15 +194,14 @@ export default defineCommand({
     log("")
     log(`${c.bold("LeCodes Dev")} — ${name}`)
     log("")
-    // The url a device opens: the websocket form, or the poll form under Bun (see above).
-    const deviceUrl = underBun ? server.url.replace(/\/dev\.js$/, "/dev-poll.js") : server.url
+    const deviceUrl = server.url
     if (!flags["no-qr"]) await printQr(deviceUrl)
     log(`Scan the QR with the LeCodes app, or open:  ${c.bold(deviceUrl)}`)
     // The browser runner: localhost is a secure context (camera works there), the LAN address is
     // what a phone's browser can reach.
     const webLocal = server.webUrl ? server.webUrl.replace(`http://${host}:`, "http://localhost:") : null
     if (server.webUrl && webLocal) log(`In the browser:                             ${c.bold(webLocal)}   (LAN: ${server.webUrl})`)
-    if (!underBun) note(`Older desktop builds (no websocket bridge): ${server.url}?t=poll`)
+    note(`Older desktop builds (no websocket bridge): ${server.url}?t=poll`)
     if (alternatives.length > 0) {
       note(`Device can't reach it? This machine also has ${alternatives.map((a) => `${a.address} (${a.iface})`).join(", ")} — retry with --host <ip>.`)
     }

package/src/commands/render.ts

@@ -4,6 +4,7 @@ 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 { desktopDefaultViewport, desktopPluginLibraries, readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
 import { runDesktopRender } from "../hosts/desktopRenderer"
 import { evaluateDesktopRun, translateScenario } from "../hosts/desktopScript"
@@ -285,8 +286,10 @@ 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) } })
   const { js, resources } = await buildBundle(bundleOptions(flags), {
-    localAssets: true, desktopRenderer,
+    localAssets: true, desktopRenderer, backend,
     extraEntries: screen ? [screen.entry] : undefined, entryOverride: screen?.entryPath,
   })
   // The host writes PNGs but never creates folders — make every output dir up front.
@@ -305,6 +308,7 @@ const renderDesktop = async (flags: RenderFlags, file: string | undefined): Prom
       renderer: desktopRenderer, host: sim ? "server" : "desktop", pluginDirs,
       width, height, frames: plan.frameCap, outPng: pngFlag, logs, timeoutMs, script: plan.text, fixedDtMs,
     })
+    await backend.close()
     const result = evaluateDesktopRun(plan, output)
     if (!result.loaded) {
       throw new CliError("This desktop host doesn't support scripted input (CREATOR_SCRIPT) — it ran the frames and ignored the steps. Update it: lecodes desktop update (or point LECODES_DESKTOP_EXE at a newer build).")
@@ -326,7 +330,7 @@ const renderDesktop = async (flags: RenderFlags, file: string | undefined): Prom
   await runDesktopRender(js, resources, {
     renderer: desktopRenderer, pluginDirs,
     width, height, frames, outPng: pngFlag, logs, timeoutMs, fixedDtMs, camera, view,
-  })
+  }).finally(() => backend.close())
   note(`Wrote ${pngFlag} (${width}x${height}, native render${view ? `, ${view.split(";")[0]} view` : camera ? ", custom camera" : ""})`)
 }
 

package/src/commands/test.ts

@@ -4,11 +4,12 @@ import { compileHeadlessBundle } from "../compile/headlessBundle"
 import { desktopDefaultViewport, desktopPluginLibraries, resolveDesktopRenderer } from "./app/shared"
 import { desktopRenderFlags, fileScenarioIO, requireRenderer, resolveFixtures, resolveSafeAreaChoice, viewportFlags } from "./render"
 import { buildBundle } from "./compile"
+import { runBackend } from "../dev/projectBackend"
 import { findProjectRoot } from "../project/manifest"
 import { runDesktopRender } from "../hosts/desktopRenderer"
 import { evaluateDesktopRun, translateScenario } from "../hosts/desktopScript"
 import { startLiteSession, type LiteSession } from "../hosts/liteRunner"
-import { resolveLiteRunner } from "../dev/webRunner"
+import { resolveLiteRunner, resolveWebRunner } from "../dev/webRunner"
 import { readManifest, type Manifest } from "../project/manifest"
 import { CliError, bool, c, defineCommand, log, logErr, note, num, str, warnErr, type FlagValues } from "../cli"
 import { bundleFlags, bundleOptions } from "./shared"
@@ -157,6 +158,7 @@ const testFlags = {
   ...bundleFlags,
   ...desktopRenderFlags,
   lite: bool("run the file scenarios on Web Lite, in a browser (needs Playwright): the same steps, targets and expects; the clock is the browser's, so a step that expects a log line waits for it; design flows stay headless"),
+  web: bool("run the file scenarios on the web player, in a browser (needs Playwright): as --lite, on the runtime as wasm; no `fill` step (tap a field and `type`)"),
   desktop: bool("run the file scenarios through the NATIVE host: the same steps, targets and expects as headless (expect.audio and the json output excepted); design flows stay headless. --frames / --fixed-dt as in render --desktop"),
 }
 // (`sim` comes with desktopRenderFlags: the file scenarios through the WINDOWLESS host — no GPU, no
@@ -168,7 +170,7 @@ export default defineCommand({
   name: "test",
   summary: "Run the flow tests (tests/*.flow.json + design-derived flows)",
   usage: "[name…]",
-  description: "Headless flow tests: tests/*.flow.json scenarios, plus flows derived from the design graph (design/meta.json activator edges — checks the built app against the designed navigation; needs named elements + screen roots). Failing steps dump the frame (JSON + PNG) under tests/.artifacts/<flow>/.\n\nDesign flows read tests/fixtures.json automatically (canned fetch responses) so backend-gated transitions run headless; file scenarios declare their own via the \"fixtures\" envelope. [name…] runs only those files (a path, or a name under the tests folder).",
+  description: "Headless flow tests: tests/*.flow.json scenarios, plus flows derived from the design graph (design/meta.json activator edges — checks the built app against the designed navigation; needs named elements + screen roots). Failing steps dump the frame (JSON + PNG) under tests/.artifacts/<flow>/. On --desktop / --lite / --web a project with *.server.ts files gets its backend run for the tests, on a database of its own (.lecodes/test-db) that is emptied before every case. The headless renderer has no backend, and --sim does not wait for one: its frames are not tied to real time.\n\nDesign flows read tests/fixtures.json automatically (canned fetch responses) so backend-gated transitions run headless; file scenarios declare their own via the \"fixtures\" envelope. [name…] runs only those files (a path, or a name under the tests folder).",
   flags: testFlags,
   examples: ["lecodes test", "lecodes test hero --logs", "lecodes test --flows --json", "lecodes test --desktop"],
   run: ({ args, flags }) => runTests(args, flags),
@@ -177,9 +179,12 @@ export default defineCommand({
 const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
   // --sim is the native path on the windowless host: everything --desktop does, minus pixels.
   const sim = flags.sim
-  const lite = flags.lite
-  if (lite && (flags.desktop || sim)) throw new CliError("--lite is a host of its own — drop --desktop / --sim.")
-  if (lite && flags.flows) throw new CliError("--flows needs the headless renderer (design flows read expect.screen and fill inputs) — drop --lite.")
+  // --lite / --web: a browser run, on Web Lite or on the web player — one runner, two pages.
+  if (flags.lite && flags.web) throw new CliError("--lite and --web are two hosts — pick one.")
+  const lite = flags.lite || flags.web
+  const browserFlag = flags.web ? "--web" : "--lite"
+  if (lite && (flags.desktop || sim)) throw new CliError(`${browserFlag} is a host of its own — drop --desktop / --sim.`)
+  if (lite && flags.flows) throw new CliError(`--flows needs the headless renderer (design flows read expect.screen and fill inputs) — drop ${browserFlag}.`)
   const desktop = flags.desktop || sim
   if (desktop && flags.flows) throw new CliError(`--flows needs the headless renderer (design flows read expect.screen and fill inputs) — drop --${sim ? "sim" : "desktop"}.`)
   // --desktop: ONE renderer decision (host binary + the staged .filamat variant). The root is
@@ -187,7 +192,9 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
   let desktopRoot: string
   try { desktopRoot = findProjectRoot(process.cwd()) } catch { desktopRoot = process.cwd() }
   const desktopRenderer = desktop ? resolveDesktopRenderer(desktopRoot, flags.renderer) : undefined
-  const native = desktop ? await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer }) : null
+  // The project's backend, when it has one: on a database of its own, emptied before every case.
+  const backend = desktop ? runBackend({ root: desktopRoot, command: "lecodes test", test: true, log: (msg) => { if (flags.logs || msg.includes("[server:error]")) logErr(msg) } }) : null
+  const native = desktop ? await buildBundle(bundleOptions(flags), { localAssets: true, desktopRenderer, backend: backend! }) : null
   const headless = desktop || lite ? null : await compileHeadlessBundle({ entry: flags.entry, publicUrl: flags["public-url"], remoteAssets: flags["remote-assets"], waitNetwork: flags["wait-network"] })
   const warnings = headless?.warnings ?? []
   const useLocalAssets = headless?.useLocalAssets ?? false
@@ -338,11 +345,17 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
   // Web Lite: one compile, one browser; a page of its own per case.
   let liteSession: LiteSession | null = null
   if (lite) {
-    const page = resolveLiteRunner(note)
-    if (!page) throw new CliError("No Web Lite page found: this CLI has no runtime/web-lite (a monorepo checkout needs `bun run build` in hosts/web-lite).")
     let manifest: Manifest | null = null
     try { manifest = readManifest(root) } catch { /* a folder standing alone */ }
-    liteSession = await startLiteSession({ root, manifest, name: manifest?.name ?? "app", lite: page, entry: flags.entry })
+    if (flags.web) {
+      const web = resolveWebRunner(note)
+      if (!web) throw new CliError("No web player found: this CLI has no runtime/web (a monorepo checkout needs `bun run build` in hosts/web-player).")
+      liteSession = await startLiteSession({ root, manifest, name: manifest?.name ?? "app", web, entry: flags.entry })
+    } else {
+      const page = resolveLiteRunner(note)
+      if (!page) throw new CliError("No Web Lite page found: this CLI has no runtime/web-lite (a monorepo checkout needs `bun run build` in hosts/web-lite).")
+      liteSession = await startLiteSession({ root, manifest, name: manifest?.name ?? "app", lite: page, entry: flags.entry })
+    }
   }
   const runLiteCase = async (kase: FlowCase): Promise<CaseResult> => {
     const caseDir = resolve(artifactsRoot, slug(kase.name))
@@ -364,6 +377,8 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
 
   for (const kase of cases) {
     let result: CaseResult
+    // every case starts on an empty database, like it starts in a fresh host
+    if (backend && results.length > 0) await backend.reset()
     if (lite) {
       try {
         result = await runLiteCase(kase)
@@ -446,6 +461,7 @@ const runTests = async (args: string[], flags: TestFlags): Promise<void> => {
   }
 
   await liteSession?.close()
+  await backend?.close()
   clearTimeout(killer)
   process.exit(failed > 0 ? 1 : 0)
 }

package/src/commands/update/index.ts

@@ -7,6 +7,7 @@ import { CliError, bool, c, defineCommand, log, note, readFlags, type Command }
 import { OPTIONAL_PEERS, peerSource, peerVersion } from "../../hosts/peers"
 import { installPeers } from "../../hosts/peerInstall"
 import { archiveSpec, archivedVersion } from "../../hosts/archives"
+import { commandLine, installGlobalArgv, ownManager } from "../../hosts/packageManager"
 import { updateDesktop } from "../../hosts/desktopRenderer"
 import { updateMatc } from "../../hosts/matcTool"
 import { refreshTypes } from "./types"
@@ -94,7 +95,7 @@ const STANDALONE = existsSync(join(dirname(process.execPath), "runtime")) &&
 export default defineCommand({
   name: "update",
   summary: "Move everything the project depends on to its newest published state",
-  description: "In dependency order: the desktop host (`desktop update`), matc (`shaders update`), the project's shader compiles, the IDE types (.lecodes/types/ + tsconfig.json, from the server — the former `lecodes types`), the ios/android shell pins (`app update`), then the GLOBAL npm installs: every installed optional peer (lecodes-headless, lecodes-design, lecodes-3d-editor, lecodes-assets) and this CLI that is behind npm's latest gets `npm install -g`.\n\nPinned tools are skipped, not overridden: LECODES_DESKTOP_EXE / LECODES_MATC mean a local build. Keeps going when a step fails; the summary says which.",
+  description: "In dependency order: the desktop host (`desktop update`), matc (`shaders update`), the project's shader compiles, the IDE types (.lecodes/types/ + tsconfig.json, from the server — the former `lecodes types`), the ios/android shell pins (`app update`), then the GLOBAL installs: every installed optional peer (lecodes-headless, lecodes-design, lecodes-3d-editor, lecodes-assets) and this CLI that is behind npm's latest is installed again, with the package manager the CLI came by (`npm install -g`, or `bun add -g` for a CLI installed with bun).\n\nPinned tools are skipped, not overridden: LECODES_DESKTOP_EXE / LECODES_MATC mean a local build. Keeps going when a step fails; the summary says which.",
   flags: {
     local: bool("types from the SDK bundled in this CLI"),
     "no-shells": bool("leave ios/android pins alone (no re-sync)"),
@@ -159,8 +160,8 @@ export default defineCommand({
       return "ok"
     })
 
-    // 6. this CLI + its optional peers — the GLOBAL npm installs (`npm install -g`, how the CLI and its
-    // peers are installed): every installed one that is behind npm's latest moves forward. The peers go
+    // 6. this CLI + its optional peers — the GLOBAL installs (`npm install -g` or `bun install -g`,
+    // whichever this CLI came by: hosts/packageManager.ts): every installed one that is behind npm's latest moves forward. The peers go
     // first, the CLI itself last — replacing the running CLI's files is fine (this process already
     // holds its code), but its new version is what the next invocation runs, so nothing after it here.
     // Peers that are NOT installed stay that way: they're optional, installing one is a choice.
@@ -195,7 +196,7 @@ export default defineCommand({
       const prefixBehind = behind.filter((r) => r.where === "prefix")
       const globalSpecs = await Promise.all(behind.filter((r) => r.where !== "prefix").map(async (r) => await archiveSpec(r.name) ?? r.name + "@latest"))
       if (flags.check) {
-        return ["updated", behind.length + " behind — run: lecodes update" + (globalSpecs.length ? "  (global: npm install -g " + globalSpecs.join(" ") + ")" : "")]
+        return ["updated", behind.length + " behind — run: lecodes update" + (globalSpecs.length ? "  (global: " + commandLine(ownManager(), installGlobalArgv(ownManager(), globalSpecs)) + ")" : "")]
       }
       const done: string[] = []
       if (prefixBehind.length) {
@@ -207,9 +208,13 @@ export default defineCommand({
       }
       const toInstall = STANDALONE ? globalSpecs.filter((s) => !s.startsWith("lecodes-cli@")) : globalSpecs
       if (toInstall.length) {
-        log("  " + c.dim("$") + " npm install -g " + toInstall.join(" "))
-        const r = spawnSync("npm", ["install", "-g", ...toInstall], { stdio: "inherit", shell: true })
-        if (r.status !== 0) throw new CliError("npm install -g exited with " + (r.status ?? "a signal"))
+        // with the manager this CLI was installed by: another one's global dir is another copy
+        const tool = ownManager()
+        const argv = installGlobalArgv(tool, toInstall)
+        log("  " + c.dim("$") + " " + commandLine(tool, argv))
+        const r = spawnSync(tool, argv, { stdio: "inherit", shell: true })
+        if (r.error) throw new CliError(tool + " could not run: " + r.error.message)
+        if (r.status !== 0) throw new CliError(commandLine(tool, argv.slice(0, 2)) + " exited with " + (r.status ?? "a signal"))
         done.push(...behind.filter((r) => r.where !== "prefix" && (!STANDALONE || r.name !== "lecodes-cli")).map((r) => r.name))
       }
       if (done.length === 0) return ["skipped", "only the standalone CLI itself is behind — download the release"]

package/src/commands/update/types.ts

@@ -87,7 +87,7 @@ export const refreshTypes = async (opts: RefreshTypesOptions): Promise<void> =>
   // The compiler uses the SDK vendored in this CLI, not these declarations — worth saying when the
   // server's surface is a different one, since that gap shows up as "autocompletes but won't build".
   if (!opts.local && local && bundleHash(local) !== bundleHash(bundle)) {
-    warn("The server's SDK surface differs from the one this CLI compiles with — if something autocompletes but fails to compile, update the CLI (`npm install -g lecodes-cli@latest`) or re-run with --local.")
+    warn("The server's SDK surface differs from the one this CLI compiles with — if something autocompletes but fails to compile, update the CLI (`lecodes update`) or re-run with --local.")
   }
 
   log("")

package/src/compile/projectCompile.ts

@@ -3,7 +3,12 @@ import { createRequire } from "node:module"
 import { dirname, join } from "node:path"
 import type { FileKind } from "../project/manifest"
 import { distRoot } from "../hosts/distRoot"
-import { compileProject as sdkCompileProject, detectEntry, scanModulesChisel, localAssetNames, ENTRY_CONVENTION } from "lecodes-sdk/compile"
+import { installPeers } from "../hosts/peerInstall"
+import { peerDirInPrefix } from "../hosts/peers"
+import {
+  compileProject as sdkCompileProject, compileServerBundle, detectEntry, isServerPath, scanModulesChisel, localAssetNames, ENTRY_CONVENTION,
+  type CompileServerOptions,
+} from "lecodes-sdk/compile"
 
 // Every project compiles through the SDK's one import-free compiler, which bundles with chisel (the
 // Rust method-granular bundler, @letary/chisel) — the only bundler. The SDK resolves the chisel
@@ -84,6 +89,9 @@ export type CompileOptions = {
   /** What the compile has to say that is not an error (a plugin the app uses and app.json does not
    *  list). */
   onWarning?: (message: string) => void
+  /** Base URL of the project's backend, baked into the stubs of its `*.server.ts` modules; absent =
+   *  every call to the server rejects (status 0). */
+  serverUrl?: string
 }
 
 /** A warning when auto-detection has several import-graph roots and no main.ts to settle it —
@@ -110,6 +118,45 @@ export const compileProject = (opts: CompileOptions): Promise<string> =>
     sourcemap: opts.sourcemap,
     editor: opts.editor,
     onWarning: opts.onWarning,
+    serverUrl: opts.serverUrl,
+  })
+
+/** Does the project have a server side (`*.server.ts` files)? */
+export const hasServerFiles = (entries: CompileEntry[]): boolean =>
+  entries.some((e) => e.type === "text" && isServerPath(e.path))
+
+type Typescript = NonNullable<CompileServerOptions["typescript"]>
+
+/** TypeScript with its lib files on disk — the server code is checked, and the endpoint validators
+ *  derived, by its checker. The project's own, else one this CLI's install can see, else the CLI's
+ *  peer (installed on first use, like the database engine). One WITHOUT the compiler API is passed
+ *  over: TypeScript 7 — what `install typescript` brings today — is the native compiler, with no
+ *  `createProgram` to call. */
+const findTypescript = async (root: string): Promise<Typescript> => {
+  const from = (at: string): Typescript | null => {
+    try {
+      const mod = createRequire(at)("typescript")
+      return mod?.createProgram ? mod : mod?.default?.createProgram ? mod.default : null
+    } catch { return null }
+  }
+  const prefix = join(peerDirInPrefix("typescript"), "package.json")
+  const found = from(join(root, "package.json")) ?? from(import.meta.url) ?? from(prefix)
+  if (found) return found
+  await installPeers(["typescript"], "The project's server code (*.server.ts)")
+  return from(prefix) ?? (() => { throw new Error(`The typescript installed in ${peerDirInPrefix("typescript")} has no compiler API`) })()
+}
+
+/**
+ * The project's server bundle (its `*.server.ts` files and what they import), or null when it has
+ * none. `app` = app.json's name (the sign-in mail). Always checked with TypeScript, the way the
+ * le.codes build checks it: an endpoint that is not async, an unawaited `requireUser()` are errors
+ * only the checker finds.
+ */
+export const compileServer = async (opts: { entries: CompileEntry[], root: string, app?: CompileServerOptions["app"] }) =>
+  compileServerBundle({
+    entries: opts.entries.map((e) => ({ path: e.path, type: e.type as any, text: e.text })),
+    app: opts.app,
+    typescript: await findTypescript(opts.root),
   })
 
 /** Re-exported so the CALLERS that stage files next to the bundle name them the way the bundle asks

package/src/dev/androidDev.ts

@@ -12,7 +12,7 @@ import { CliError, note, warnErr } from "../cli"
  * app's VIEW filter is pinned to le.codes/qr, and an explicit start bypasses filter matching — with
  * the plain dev.js url: the app's initial.js only fetches a url that ends in ".js", anything else is
  * sent to le.codes/api/code, which answers 400 for a dev bundle (the "Произошла ошибка при открытии
- * проекта" screen). That is also why the poll transport is a PATH (/dev-poll.js), never `?t=poll`.
+ * проекта" screen).
  *
  * A device run has no frame cap (unlike the desktop host), so every exit path force-stops the app:
  * a 3D scene left rendering is a sustained GPU load on a charging phone.

package/src/dev/backendWorker.ts

@@ -0,0 +1,138 @@
+import { mkdirSync, mkdtempSync, renameSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { format } from "node:util"
+import {
+  createAuthHost, createInvoker, createSubscribeGuard, describeServer, loadServerModules,
+  setChannelPublisher, setDbTransport, type AuthHost, type LoadedServer,
+} from "lecodes-sdk/server"
+import { loadPeer } from "../hosts/peerInstall"
+import type { FromWorker, LogLevel, ToWorker } from "./localBackend"
+
+/*
+ * The process a project's server bundle runs in under `lecodes dev` — the local twin of the runner's
+ * worker (tools/runner/src/worker.ts), started by localBackend.ts as this same CLI with
+ * BACKEND_WORKER_ARG and spoken to over the IPC channel. One process per loaded bundle: a reload is
+ * a new process, so nothing of the old code (its timers, its module state) outlives it.
+ *
+ * The database is marcidb's embedded engine (the peer marcidb-embedded), opened here, in the
+ * directory the parent names. The schema is synced on every load, the way the runner syncs a draft
+ * slot: 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.
+ */
+
+type Embedded = {
+  exec(op: unknown): Promise<any>
+  batch(ops: unknown[]): Promise<any[]>
+  $sync(schema: string): Promise<null>
+  close(): void
+}
+type EmbeddedModule = { openDatabase(dir: string, options?: { disableFsync?: boolean }): Embedded }
+
+const post = (m: FromWorker) => { process.send?.(m) }
+
+// ── console → the parent (the dev terminal) ──
+const hook = (level: LogLevel) => (...args: unknown[]) => post({ t: "log", level, text: format(...args) })
+console.log = hook("log"); console.info = hook("info"); console.warn = hook("warn"); console.error = hook("error"); console.debug = hook("debug")
+process.on("unhandledRejection", (e) => post({ t: "log", level: "error", text: `Unhandled rejection: ${(e as Error)?.stack ?? e}` }))
+process.on("uncaughtException", (e) => post({ t: "log", level: "error", text: `Uncaught exception: ${(e as Error)?.stack ?? e}` }))
+
+/** The code `db.auth.signInWithCode` takes for any email under `lecodes dev` (no `sendCode` needed). */
+const DEV_CODE = "000000"
+
+let db: Embedded | null = null
+let invoke: ReturnType<typeof createInvoker> | null = null
+let subscribe: ReturnType<typeof createSubscribeGuard> | null = null
+let authHost: AuthHost | null = null
+
+const quit = () => {
+  try { db?.close() } catch { /* already closed */ }
+  process.exit(0)
+}
+// the dev server went away (Ctrl+C, a crash): nothing is left to serve
+process.on("disconnect", quit)
+// …and when it was killed outright the channel may never say so: a process left behind keeps the
+// database locked, and the next `lecodes dev` of the project could not open it.
+const parent = process.ppid
+setInterval(() => { try { process.kill(parent, 0) } catch { quit() } }, 1000).unref?.()
+process.on("SIGINT", quit)
+process.on("SIGTERM", quit)
+
+/** Open the project's database and bring it to `schema`. Returns what the developer should be told. */
+const openDb = async (dir: string, schema: string): Promise<string[]> => {
+  const { openDatabase } = await loadPeer<EmbeddedModule>("marcidb-embedded", undefined, { for: "lecodes dev", install: false })
+    ?? (() => { throw new Error("marcidb-embedded is not installed") })()
+  mkdirSync(dir, { recursive: true })
+  try {
+    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.`)
+    throw e
+  }
+  try {
+    await db.$sync(schema)
+    return []
+  } catch (e) {
+    if ((e as { kind?: string }).kind !== "bad_request") throw e
+    const reason = (e as Error).message
+    // Not migratable in place — or not a schema at all. An empty database tells the two apart, so a
+    // broken schema never costs the data.
+    const probeDir = mkdtempSync(join(tmpdir(), "lecodes-db-"))
+    const probe = openDatabase(probeDir, { disableFsync: true })
+    try { await probe.$sync(schema) } finally { probe.close(); rmSync(probeDir, { recursive: true, force: true }) }
+    db.close()
+    const aside = `${dir}-old`
+    rmSync(aside, { recursive: true, force: true })
+    renameSync(dir, aside)
+    mkdirSync(dir, { recursive: true })
+    db = openDatabase(dir)
+    await db.$sync(schema)
+    return [`database started over — the schema change couldn't be migrated (${reason}); the previous data is in ${aside}`]
+  }
+}
+
+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) })
+  setChannelPublisher((ch, group, data) => post({ t: "publish", ch, group, data }))
+  // The bundle is a plain script (chisel esm output with only side effects): registers globalThis.__lecodesServer
+  ;(0, eval)(m.code)
+  const server: LoadedServer = loadServerModules()
+  const describe = describeServer(server)
+  const notes = describe.marci ? await openDb(m.dbDir, describe.marci) : []
+  // Sessions, passwords and email codes over the project's own db, as on the runner. A code that was
+  // asked for is printed here, and DEV_CODE signs any email in without one — the developer is the
+  // only user.
+  authHost = createAuthHost({
+    db: server.dbs.find(d => d.$auth) ?? null,
+    appName: server.manifest.app?.name,
+    echoCodes: true,
+    devCode: DEV_CODE,
+    log: (level, text) => post({ t: "log", level, text }),
+  })
+  authHost.install()
+  const auth = authHost.enabled ? authHost : null
+  const onError = (id: string, e: unknown) => post({ t: "log", level: "error", text: `${id}: ${(e as Error)?.stack ?? e}` })
+  invoke = createInvoker(server, { auth, onError })
+  subscribe = createSubscribeGuard(server, { auth, onError })
+  post({ t: "loaded", describe, notes })
+}
+
+process.on("message", async (m: ToWorker) => {
+  switch (m.t) {
+    case "load":
+      try { await load(m) } catch (e) { post({ t: "loadError", message: (e as Error)?.stack ?? String(e) }) }
+      return
+    case "invoke": {
+      const result = invoke ? await invoke(m.id, m.args, m.ctx) : { ok: false as const, status: 503, message: "server not loaded" }
+      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" }
+      return post({ t: "result", req: m.req, result })
+    }
+    case "stop":
+      return quit()
+  }
+})