lecodes-cli 2.5.1 → 2.8.0

package/src/dev/projectBackend.ts

@@ -1,6 +1,6 @@
 import { rmSync } from "node:fs"
 import { join, relative } from "node:path"
-import { createChannelHub, fileResponse, isMultipart, receiveUploads, UploadError, type Upload } from "lecodes-sdk/server"
+import { callerKey, createChannelHub, createRateLimiter, fileResponse, isMultipart, RATE_LIMITS, receiveUploads, TOO_MANY_CALLS, UploadError, type Upload } from "lecodes-sdk/server"
 import { compileServer, hasServerFiles, type CompileEntry } from "../compile/projectCompile"
 import { loadPeer } from "../hosts/peerInstall"
 import { LECODES_DIR, readManifest } from "../project/manifest"
@@ -17,11 +17,22 @@ import { serve, type Served, type Socket, type SocketHandlers } from "./serve"
  *   POST <base>/api/<id>   an endpoint call, the envelope always HTTP 200 (the client reads `ok`);
  *                          multipart when it carries files
  *   GET  <base>/files/<id>/<name>   a stored file (`t.file()`): `.lecodes/files`, beside the database
- *   WS   <base>/ws         the channel socket: the SDK's hub, the one the runner serves on le.codes
+ *   WS   <base>/ws         the channel socket: the SDK's hub, the one the runner serves on le.codes —
+ *                          channels and computed subscriptions (each process that starts runs the live
+ *                          ones again: `hub.rerun`), and who is subscribed where (`watchers`, `members`)
+ *   GET  <base>/status     (from this machine only) `{ ok, root }`: whose backend this is — how the other
+ *                          commands find a running `lecodes dev` of their project (devLink.ts)
+ *   POST <base>/reset      (from this machine only) the database starts over empty (`render --fresh`)
+ *
+ * The limits are the runner's (lecodes-sdk/server rateLimit.ts): an endpoint's calls per (session, id),
+ * a session's subscriptions in the hub.
  *
  * Two users: the dev server mounts the routes under its token path (`lecodes dev`, `web dev`, the
  * browser tests), and `runBackend` listens on a port of its own for the commands that run a bundle
  * on a host this CLI starts (`desktop run`, `serve`, `render --desktop`, `test --desktop`).
+ *
+ * While a `lecodes dev` of the project runs, it holds the database: the other commands talk to it
+ * instead (`devRunBackend`, the dev server's `forwardedBackend` — devLink.ts finds it).
  */
 
 export type ServerBundle = Awaited<ReturnType<typeof compileServer>>
@@ -35,18 +46,20 @@ export type ProjectBackendOptions = {
   command: string
 }
 
-export type ProjectBackend = {
+export type ProjectBackend<B = ServerBundle> = {
   /** The server bundle of these entries; null when the project has no server files. */
-  compile: (entries: CompileEntry[]) => Promise<ServerBundle | null>
+  compile: (entries: CompileEntry[]) => Promise<B | null>
   /** Run this bundle from now on (null = the project has no server side any more: stop). Rejects
    *  when it does not load; resolves to what to tell the developer. */
-  run: (bundle: ServerBundle | null) => Promise<string[]>
+  run: (bundle: B | null) => Promise<string[]>
   /** A request under the backend's base; `route` is the path after it ("/api/<id>"). */
   handle: (req: Request, route: string, ip: string | undefined) => Promise<Response>
   /** The channel socket (`<base>/ws`). */
   socket: (req: Request, ip: string | undefined) => (conn: Socket) => SocketHandlers
-  /** Start again on an EMPTY database (a test's case). */
+  /** Start again on an EMPTY database (a test's case), on the machine's clock. */
   reset: () => Promise<void>
+  /** The server's clock reads `offsetMs` ahead of the machine's (a test's case clock; sdk/server `setServerClock`). */
+  setClock: (offsetMs: number) => void
   /** Resolves once the database is closed. */
   close: () => Promise<void>
 }
@@ -59,6 +72,24 @@ const CORS = {
 }
 const bearerOf = (req: Request): string | null => /^Bearer\s+(.+)$/i.exec(req.headers.get("authorization") ?? "")?.[1]?.trim() ?? null
 const BODY_LIMIT = 8 * 1024 * 1024
+/** How long a request that came before the first compile waits for it (see `known` below). */
+const FIRST_RUN_WAIT_MS = 30_000
+
+/** A peer on this machine: the admin routes answer it alone, and the `x-forwarded-*` of a dev server that
+ *  forwards to this one (`forwardedBackend`) are believed from it alone. */
+export const isLoopback = (ip: string | undefined): boolean =>
+  !!ip && (ip === "::1" || ip.startsWith("127.") || ip.startsWith("::ffff:127."))
+
+/** Where a request came in: its own origin, or — from a dev server of this machine that forwards to this
+ *  one — the origin the device used there (a stored file's url must be one the device reaches). */
+const originOf = (req: Request, ip: string | undefined): string => {
+  const host = req.headers.get("x-forwarded-host")
+  if (host && isLoopback(ip)) return `${req.headers.get("x-forwarded-proto") === "https" ? "https" : "http"}://${host}`
+  return new URL(req.url).origin
+}
+/** The caller's address: a forwarding dev server's word for it, from this machine only. */
+const ipOf = (req: Request, ip: string | undefined): string | undefined =>
+  (isLoopback(ip) ? req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() : undefined) || ip
 
 export const createProjectBackend = (options: ProjectBackendOptions): ProjectBackend => {
   const { root, log } = options
@@ -66,13 +97,27 @@ export const createProjectBackend = (options: ProjectBackendOptions): ProjectBac
   const filesDir = filesDirOf(dbDir)
   let backend: LocalBackend | null = null
   let running: string | null = null
+  /** the server's clock offset (`setClock`): a backend started again keeps it */
+  let clock = 0
+  // Before the first `run` nobody knows yet whether the project has a backend: a device that reconnects to a
+  // dev server still compiling (a restart of `lecodes dev`) is answered once it knows — a "no server files" then
+  // would be a refusal the device keeps. Bounded: a first compile that fails answers after FIRST_RUN_WAIT_MS.
+  let ran = false
+  let firstRan!: () => void
+  const firstRun = new Promise<void>((r) => { firstRan = r })
+  const known = (): Promise<void> => ran ? Promise.resolve() : Promise.race([firstRun, new Promise<void>((r) => { setTimeout(r, FIRST_RUN_WAIT_MS).unref?.() })])
 
   // The channel socket is the SDK's hub — the one the runner serves too.
   const hub = createChannelHub<Socket>({
     send: (conn, frame) => conn.send(frame),
-    subscribe: (_scope, ch, args, ctx) => backend
-      ? backend.subscribe(ch, args, ctx)
-      : Promise.resolve({ ok: false as const, status: 404, message: "The project has no server files" }),
+    subscribe: async (_scope, ch, args, ctx, sub) => {
+      await known()
+      return backend
+        ? backend.subscribe(ch, args, ctx, sub)
+        : { ok: false as const, status: 404, message: "The project has no server files" }
+    },
+    unsubscribe: (_scope, sub) => backend?.unsubscribe(sub),
+    presenceChanged: (_scope, id, key) => backend?.presenceChanged(id, key),
   })
   const sockets = new Set<Socket>()
   // `pushChannel.send` reaches the platform's sender through the developer's own login when the checkout is linked —
@@ -80,9 +125,59 @@ export const createProjectBackend = (options: ProjectBackendOptions): ProjectBac
   const push = (() => {
     try { const { apiUrl, token } = session(); return { apiUrl, token, uuid: readManifest(root).uuid } } catch { return null }
   })()
-  const start = () => startLocalBackend({ root, dbDir, log, push, onPublish: (ch, group, data) => hub.publish("", ch, group, data) })
+  const start = () => {
+    const b = startLocalBackend({
+      root, dbDir, log, push,
+      onPublish: (ch, group, data) => hub.publish("", ch, group, data),
+      onStart: () => { void hub.rerun("") },
+      presence: (id, key) => hub.presence("", id, key),
+    })
+    if (clock !== 0) b.setClock(clock)
+    return b
+  }
 
   const envelope = (body: unknown) => new Response(JSON.stringify(body), { status: 200, headers: { "content-type": "application/json", "cache-control": "no-store", ...CORS } })
+  /** an endpoint's calls by one caller: the runner's limits */
+  const calls = createRateLimiter(RATE_LIMITS.call)
+
+  const reset = async () => {
+    clock = 0
+    if (!backend || running === null) return
+    await backend.close()
+    rmSync(dbDir, { recursive: true, force: true })
+    rmSync(filesDir, { recursive: true, force: true })
+    backend = start()
+    await backend.deploy(running, readAppEnv(root))
+  }
+
+  const runBundle = async (bundle: ServerBundle | null): Promise<string[]> => {
+    if (!bundle) {
+      await backend?.close()
+      backend = null
+      running = null
+      return []
+    }
+    // the embedded database is a peer, installed the first time a project defines models
+    if (Object.keys(bundle.manifest.modules).length && /\bdefineDb\s*\(/.test(bundle.code)) {
+      await loadPeer("marcidb-embedded", undefined, { for: `${options.command} (the project's database)` })
+      // …and so is the codec of its pictures, the first time a model has a t.image() field
+      if (/\bimage\s*\(/.test(bundle.code)) await loadPeer("sharp", undefined, { for: `${options.command} (the project's t.image() fields)` })
+    }
+    backend ??= start()
+    // the project's keys come from its .env, read on every run: a changed key is a deploy by itself
+    const env = readAppEnv(root)
+    const deployed = await backend.deploy(bundle.code, env)
+    running = bundle.code
+    if (!deployed.changed) return []
+    const d = deployed.describe
+    const models = Object.keys(d.models).length
+    const count = (n: number, what: string) => `${n} ${what}${n === 1 ? "" : "s"}`
+    const keys = Object.keys(env).sort()
+    // a computed is an endpoint too (its one-shot call): counted apart
+    const computeds = d.computeds.length
+    log(`server: ${count(d.endpoints.length - computeds, "endpoint")}, ${computeds} computed, ${count(d.channels.length, "channel")}${models ? `, ${count(models, "model")} (database in ${relative(root, dbDir).replace(/\\/g, "/")})` : ""}${keys.length ? `, env ${keys.join(", ")} (.env)` : ""}`)
+    return deployed.notes.map((n) => `server: ${n}`)
+  }
 
   return {
     compile: async (entries) => {
@@ -91,39 +186,27 @@ export const createProjectBackend = (options: ProjectBackendOptions): ProjectBac
       const app = readAppConfigAt(root)
       return compileServer({ entries, root, app: app ? { name: app.name } : undefined })
     },
-    run: async (bundle) => {
-      if (!bundle) {
-        await backend?.close()
-        backend = null
-        running = null
-        return []
-      }
-      // the embedded database is a peer, installed the first time a project defines models
-      if (Object.keys(bundle.manifest.modules).length && /\bdefineDb\s*\(/.test(bundle.code)) {
-        await loadPeer("marcidb-embedded", undefined, { for: `${options.command} (the project's database)` })
-        // …and so is the codec of its pictures, the first time a model has a t.image() field
-        if (/\bimage\s*\(/.test(bundle.code)) await loadPeer("sharp", undefined, { for: `${options.command} (the project's t.image() fields)` })
-      }
-      backend ??= start()
-      // the project's keys come from its .env, read on every run: a changed key is a deploy by itself
-      const env = readAppEnv(root)
-      const deployed = await backend.deploy(bundle.code, env)
-      running = bundle.code
-      if (!deployed.changed) return []
-      const d = deployed.describe
-      const models = Object.keys(d.models).length
-      const count = (n: number, what: string) => `${n} ${what}${n === 1 ? "" : "s"}`
-      const keys = Object.keys(env).sort()
-      log(`server: ${count(d.endpoints.length, "endpoint")}, ${count(d.channels.length, "channel")}${models ? `, ${count(models, "model")} (database in ${relative(root, dbDir).replace(/\\/g, "/")})` : ""}${keys.length ? `, env ${keys.join(", ")} (.env)` : ""}`)
-      return deployed.notes.map((n) => `server: ${n}`)
-    },
+    run: (bundle) => runBundle(bundle).finally(() => { ran = true; firstRan() }),
     handle: async (req, route, ip) => {
       if (req.method === "OPTIONS") return new Response(null, { status: 204, headers: CORS })
       if (route.startsWith("/files/") && (req.method === "GET" || req.method === "HEAD")) {
         return fileResponse(filesDir, route.slice("/files/".length), req, { "access-control-allow-origin": "*" })
       }
+      // the admin routes: the other commands of this machine (devLink.ts)
+      if (route === "/status" || route === "/reset") {
+        if (!isLoopback(ip)) return envelope({ ok: false, status: 403, message: "from this machine only" })
+        if (route === "/status" && req.method === "GET") return envelope({ ok: true, root, running: running !== null })
+        if (route === "/reset" && req.method === "POST") {
+          await reset()
+          log("server: the database was emptied (a run asked for a fresh one: render --fresh, call --reset)")
+          return envelope({ ok: true })
+        }
+      }
       const id = route.startsWith("/api/") ? decodeURIComponent(route.slice("/api/".length)) : ""
       if (!id || req.method !== "POST") return envelope({ ok: false, status: 404, message: "not an endpoint call" })
+      const caller = ipOf(req, ip)
+      if (!calls.take(`${callerKey(bearerOf(req), caller)}|${id}`)) return envelope(TOO_MANY_CALLS)
+      await known()
       if (!backend) return envelope({ ok: false, status: 404, message: "The project has no server files" })
       let args: unknown
       let uploads: Upload[] = []
@@ -143,25 +226,24 @@ export const createProjectBackend = (options: ProjectBackendOptions): ProjectBac
       if (!Array.isArray(args)) return envelope({ ok: false, status: 400, message: "body must be {\"args\":[…]}" })
       // a stored file's url starts where this very request found the backend (a phone's address of this machine, a tunnel)
       const url = new URL(req.url)
-      const filesBase = url.origin + url.pathname.slice(0, url.pathname.length - route.length)
-      return envelope(await backend.invoke(id, args, { headers: Object.fromEntries(req.headers), ip, sessionToken: bearerOf(req) ?? undefined, uploads, filesBase }))
+      const filesBase = originOf(req, ip) + url.pathname.slice(0, url.pathname.length - route.length)
+      return envelope(await backend.invoke(id, args, { headers: Object.fromEntries(req.headers), ip: caller, sessionToken: bearerOf(req) ?? undefined, uploads, filesBase }))
     },
     socket: (req, ip) => (conn) => {
-      const c = hub.connect(conn, { ip, session: bearerOf(req) })
+      // a stored file's url, in what a computed answers: where this socket found the backend
+      const url = new URL(req.url)
+      const c = hub.connect(conn, { ip: ipOf(req, ip), session: bearerOf(req), filesBase: originOf(req, ip) + url.pathname.replace(/\/ws$/, "") })
       sockets.add(conn)
       return {
         onMessage: (raw) => { void c.message(raw) },
         onClose: () => { sockets.delete(conn); c.close() },
       }
     },
-    reset: async () => {
-      if (!backend || running === null) return
-      await backend.close()
-      rmSync(dbDir, { recursive: true, force: true })
-      rmSync(filesDir, { recursive: true, force: true })
-      backend = start()
-      await backend.deploy(running, readAppEnv(root))
+    setClock: (offsetMs) => {
+      clock = offsetMs
+      backend?.setClock(offsetMs)
     },
+    reset,
     close: async () => {
       for (const conn of [...sockets]) conn.close()
       await backend?.close()
@@ -170,15 +252,109 @@ export const createProjectBackend = (options: ProjectBackendOptions): ProjectBac
   }
 }
 
+// ───────────────────────── the backend another dev server of this machine runs ─────────────────────────
+
+/**
+ * The backend of a dev server whose project's backend ANOTHER dev server of this machine runs (a `web dev`
+ * started beside a `lecodes dev` — devLink.ts finds it): its routes are forwarded there — calls, stored files,
+ * the channel socket — with the origin and the address the device used (`x-forwarded-*`, believed from this
+ * machine only), so what the owner answers (a stored file's url) is one the device reaches. Nothing runs
+ * here: the owner compiles and runs the server files itself, on every save.
+ */
+export const forwardedBackend = (target: string, log: (msg: string) => void): ProjectBackend<true> => {
+  const sockets = new Set<Socket>()
+  let silent = false
+  const unreachable = (e: unknown) => {
+    if (!silent) log(`[server:error] this project's backend runs in another dev server (${target}), which does not answer: ${(e as Error)?.message ?? e} — start it again, or restart this one to run the backend here`)
+    silent = true
+  }
+  const forwarded = (req: Request, ip: string | undefined): Record<string, string> => {
+    const url = new URL(req.url)
+    return {
+      "x-forwarded-host": req.headers.get("host") ?? url.host,
+      "x-forwarded-proto": url.protocol === "https:" ? "https" : "http",
+      ...(ip ? { "x-forwarded-for": ip } : {}),
+    }
+  }
+  return {
+    compile: async (entries) => (hasServerFiles(entries) ? true : null),
+    run: async () => [],
+    handle: async (req, route, ip) => {
+      // the owner answers its admin routes to this machine — and so does this one, never on a device's behalf
+      if ((route === "/status" || route === "/reset") && !isLoopback(ip)) return new Response(JSON.stringify({ ok: false, status: 403, message: "from this machine only" }), { status: 200, headers: { "content-type": "application/json", ...CORS } })
+      const headers = new Headers(req.headers)
+      for (const h of ["host", "connection", "content-length", "x-forwarded-host", "x-forwarded-proto", "x-forwarded-for"]) headers.delete(h)
+      for (const [k, v] of Object.entries(forwarded(req, ip))) headers.set(k, v)
+      const bodyless = req.method === "GET" || req.method === "HEAD" || req.method === "OPTIONS"
+      try {
+        const res = await fetch(target + route + new URL(req.url).search, {
+          method: req.method, headers, redirect: "manual",
+          ...(bodyless ? {} : { body: req.body, duplex: "half" }),
+        } as RequestInit)
+        silent = false
+        // the body is passed on as it came (fetch already undid any transfer coding)
+        const out = new Headers(res.headers)
+        for (const h of ["content-encoding", "content-length", "transfer-encoding", "connection"]) out.delete(h)
+        return new Response(res.body, { status: res.status, headers: out })
+      } catch (e) {
+        unreachable(e)
+        return new Response(JSON.stringify({ ok: false, status: 503, message: "The project's backend (another lecodes dev on this machine) does not answer" }), { status: 200, headers: { "content-type": "application/json", ...CORS } })
+      }
+    },
+    socket: (req, ip) => (conn) => {
+      // a client socket is Bun's or Node's (22 on): an older Node has none
+      if (typeof WebSocket === "undefined") {
+        unreachable(new Error("forwarding the channel socket needs Bun or Node 22+ — run this server's backend here (stop the other dev server) or update Node"))
+        conn.close()
+        return { onMessage: () => {}, onClose: () => {} }
+      }
+      const auth = req.headers.get("authorization")
+      // Bun's and Node's WebSocket take headers beside the protocols (not the browser's)
+      const Ws = WebSocket as unknown as new (url: string, init: { headers: Record<string, string> }) => WebSocket
+      const up = new Ws(target.replace(/^http/, "ws") + "/ws", { headers: { ...forwarded(req, ip), ...(auth ? { authorization: auth } : {}) } })
+      const queue: string[] = []
+      let open = false
+      let ended = false
+      const end = () => {
+        if (ended) return
+        ended = true
+        sockets.delete(conn)
+        try { up.close() } catch { /* not open yet */ }
+        conn.close()
+      }
+      up.addEventListener("open", () => { open = true; silent = false; for (const m of queue.splice(0)) up.send(m) })
+      up.addEventListener("message", (ev) => { conn.send(typeof ev.data === "string" ? ev.data : new TextDecoder().decode(ev.data as ArrayBuffer)) })
+      up.addEventListener("close", end)
+      up.addEventListener("error", (e) => { if (!open) unreachable(new Error("the socket did not open")); void e; end() })
+      sockets.add(conn)
+      return {
+        onMessage: (raw) => { if (open) up.send(raw); else queue.push(raw) },
+        onClose: () => { ended = true; sockets.delete(conn); try { up.close() } catch { /* already going */ } },
+      }
+    },
+    // the owner's database and clock: never this server's to change
+    reset: async () => {},
+    setClock: () => {},
+    close: async () => { for (const conn of [...sockets]) conn.close() },
+  }
+}
+
 // ───────────────────────────── a backend for one run of a bundle ─────────────────────────────
 
 export type RunBackend = {
   /** Called by the compile, once it has the project's entries: the backend is started when there
    *  are server files, and its url — what the app's stubs call — is the answer. */
   start: (entries: CompileEntry[], onWarning: (w: string) => void) => Promise<string | undefined>
-  /** Start again on an empty database. */
+  /** Start again on an empty database, on the machine's clock. */
   reset: () => Promise<void>
+  /** The server's clock reads `offsetMs` ahead of the machine's — a test's case clock (`lecodes test`: a flow's
+   *  `clock` and `wait` steps move the server with the apps). */
+  setClock: (offsetMs: number) => void
   close: () => Promise<void>
+  /** Set when this run talks to a running `lecodes dev` of the project (devLink.ts `devRunBackend`): its backend
+   *  is the one the developer's devices use, on the machine's clock — a run on it keeps real time
+   *  (`setClock` refuses) and never empties it unasked. */
+  dev?: { port: number, url: string }
 }
 
 /** A port that stays the same for a project from run to run: the app keeps its session under the
@@ -194,10 +370,11 @@ const stablePort = (root: string): number => {
  * 127.0.0.1. `test`: a database of its own (`.lecodes/test-db`, emptied by `reset`) and any free
  * port — a test never touches what `lecodes dev` and `desktop run` keep in `.lecodes/db`.
  */
-export const runBackend = (options: { root: string, command: string, log: (msg: string) => void, test?: boolean }): RunBackend => {
+export const runBackend = (options: { root: string, command: string, log: (msg: string) => void, test?: boolean, keepTestDb?: boolean }): RunBackend => {
   const { root } = options
   const dbDir = join(root, LECODES_DIR, options.test ? "test-db" : "db")
-  if (options.test) { rmSync(dbDir, { recursive: true, force: true }); rmSync(filesDirOf(dbDir), { recursive: true, force: true }) }
+  // `keepTestDb`: the test database as the last run left it (`lecodes call`; `lecodes test` empties it)
+  if (options.test && !options.keepTestDb) { rmSync(dbDir, { recursive: true, force: true }); rmSync(filesDirOf(dbDir), { recursive: true, force: true }) }
   const backend = createProjectBackend({ root, dbDir, log: options.log, command: options.command })
   let server: Served | null = null
 
@@ -222,6 +399,7 @@ export const runBackend = (options: { root: string, command: string, log: (msg:
       return `http://127.0.0.1:${server.port}/server`
     },
     reset: () => backend.reset(),
+    setClock: (offsetMs) => backend.setClock(offsetMs),
     close: async () => {
       server?.close()
       server = null

package/src/hosts/desktopRenderer.ts

@@ -1,5 +1,5 @@
 import { execFileSync, spawn, spawnSync } from "node:child_process"
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, linkSync } from "node:fs"
+import { constants as fsConstants, copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, linkSync } from "node:fs"
 import { homedir, tmpdir } from "node:os"
 import { delimiter, join, resolve } from "node:path"
 import { cachedArtifactSha, downloadReleaseArchive, fetchReleaseProduct, macPlatformKey, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
@@ -573,8 +573,14 @@ const stageBundle = (js: string, resources: { name: string, absPath?: string }[]
     const st = statSync(r.absPath)
     if (!st.isFile()) continue
     const dst = join(runDir, r.name)
+    // NEVER ONTO AN EXISTING FILE: what is already there may be a hard link to another project file, and a copy
+    // over it rewrites that file IN THE PROJECT (a case-only name clash on Windows did that to a GLB, 2026-11-04).
+    // The copy is the fallback for a link across volumes, and it refuses to replace anything.
     try { linkSync(r.absPath, dst) }
-    catch { copyFileSync(r.absPath, dst); copied++ }
+    catch (e) {
+      if ((e as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`two resources stage as ${r.name} (names that differ only in case?): ${r.absPath}`)
+      copyFileSync(r.absPath, dst, fsConstants.COPYFILE_EXCL); copied++
+    }
     files++
     bytes += st.size
   }

package/src/hosts/liteRunner.ts

@@ -150,6 +150,7 @@ export const startLiteSession = async (options: { root: string, manifest: Manife
   const server: DevServer = await startDevServer({
     root: options.root, manifest: options.manifest, name: options.name, lite: options.lite, web: options.web,
     origin: `http://127.0.0.1:${port}`, bind: "127.0.0.1", port, token: "test", entryOverride: options.entry, dbDir,
+    ambiguousEntry: "error",
   })
   const compiled = await server.recompile()
   if (!compiled.ok) { server.close(); throw new CliError(`Compile failed:\n${compiled.error}`) }

package/src/plugin/generate.ts

@@ -52,8 +52,10 @@ export const findPlugins = (path: string): PluginDir[] => {
     .filter(p => statSync(p.dir).isDirectory() && isPluginDir(p.dir))
 }
 
-/** The CLI carries no TypeScript: a contract is read with the one its author has — the plugin's own
- *  (looked up from its directory upwards), else whatever the CLI's install can see. */
+/** A contract is read with the `typescript` package (5.x: 6 is ESM-only and `require` gets a stub
+ *  without `createSourceFile`): the plugin's own (looked up from its directory upwards), else the
+ *  one next to the CLI's install — a dependency of lecodes-cli after 2.4.9, so a bun / npm install
+ *  of the CLI brings it; the standalone binaries carry none and read the plugin's. */
 export const loadTypescript = (dir: string): typeof tsModule => {
   for (const from of [join(dir, "package.json"), import.meta.url]) {
     try {
@@ -62,7 +64,7 @@ export const loadTypescript = (dir: string): typeof tsModule => {
       if (ts?.createSourceFile) return ts
     } catch { /* the next place */ }
   }
-  throw new CliError(`Reading a contract needs TypeScript — add it to the plugin's repo: npm install --save-dev typescript`)
+  throw new CliError(`Reading a contract needs the typescript package 5.x — next to the CLI (bun add -g "typescript@^5.8.3" for a bun-installed lecodes-cli) or in the plugin's repo (npm install --save-dev "typescript@^5.8.3"); TypeScript 6 is not read`)
 }
 
 export type Generated = { file: string, text: string }