lecodes-cli 2.4.9 → 2.5.0

package/src/commands/update/index.ts

@@ -1,11 +1,11 @@
 import { spawnSync } from "node:child_process"
-import { existsSync, readdirSync } from "node:fs"
+import { existsSync, readdirSync, readFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join, resolve } from "node:path"
 import pkg from "../../../package.json"
 import { CliError, bool, c, defineCommand, log, note, readFlags, type Command } from "../../cli"
 import { OPTIONAL_PEERS, peerSource, peerVersion } from "../../hosts/peers"
-import { installPeers } from "../../hosts/peerInstall"
+import { installPeers, peerSpec } from "../../hosts/peerInstall"
 import { archiveSpec, archivedVersion } from "../../hosts/archives"
 import { commandLine, installGlobalArgv, ownManager } from "../../hosts/packageManager"
 import { updateDesktop } from "../../hosts/desktopRenderer"
@@ -18,18 +18,24 @@ import app from "../app"
  * `lecodes update` — one command that moves EVERYTHING a project depends on to its newest published
  * state, in the order the pieces depend on each other:
  *
- *   1. desktop   the LeCodes Desktop host `desktop run` / `render --desktop` use   (= `desktop update`)
- *   2. matc      Filament's material compiler for local shader compiles              (= `shaders update`)
- *   3. shaders   recompile the project's .mat files with that matc                   (= `shaders compile`)
- *   4. types     the IDE types (.lecodes/types + tsconfig) from the server            (types.ts)
- *   5. shells    ios/ + android/ pins → newest SDK release + plugin tags, re-sync     (= `app update`)
- *   6. cli       the npm installs — every installed optional peer (lecodes-headless, lecodes-design,
- *                lecodes-3d-editor, lecodes-assets, @napi-rs/canvas) and the CLI itself that is behind:
- *                peers in ~/.lecodes/peers (first-use installs, peerInstall.ts) are re-installed there
- *                — the renderer at THIS CLI's version, an editor at the newest one out that this
- *                CLI's peer range takes, the rest at npm's latest in range; global ones
- *                (`npm install -g`, the old way) via `npm install -g …@latest`; the CLI itself last
- *                (the standalone binary can't come from npm — it says so and does the peers only)
+ *   1. cli       the CLI itself, FIRST: when npm has a newer one it is installed and the rest of the run
+ *                is ITS — the same command from the same entry file, told it was handed over. Every step
+ *                below is then the new version's, the peers above all (updated last, the old CLI put back
+ *                its own ranges: lecodes-assets 0.2.1 under CLI 2.4.10, and a second `update` was needed —
+ *                2026-10-28). Already current (a `bun add -g lecodes-cli` beforehand) → nothing to do.
+ *                The standalone binary can't come from npm: it says so and goes on.
+ *   2. desktop   the LeCodes Desktop host `desktop run` / `render --desktop` use   (= `desktop update`)
+ *   3. matc      Filament's material compiler for local shader compiles              (= `shaders update`)
+ *   4. shaders   recompile the project's .mat files with that matc                   (= `shaders compile`)
+ *   5. types     the IDE types (.lecodes/types + tsconfig) from the server            (types.ts)
+ *   6. shells    ios/ + android/ pins → newest SDK release + plugin tags, re-sync     (= `app update`)
+ *   7. peers     every installed optional peer (lecodes-headless, lecodes-design, lecodes-3d-editor,
+ *                lecodes-assets, @napi-rs/canvas, …) that is behind WHAT AN INSTALL WOULD PUT THERE:
+ *                in ~/.lecodes/peers (first-use installs, peerInstall.ts) that is peerInstall's own spec
+ *                — the renderer at THIS CLI's version, an editor at the newest archive its range takes,
+ *                an npm peer at the newest version IN ITS RANGE (not npm's latest: compared with latest,
+ *                canvas and marcidb-embedded read "behind" on every run and were re-installed at the
+ *                version they had); global ones (`npm install -g`, the old way) via `…@latest`
  *
  * Every step is the existing subcommand, so nothing here can drift from what the individual
  * commands do; this only sequences them and keeps going when one fails (the summary says which).
@@ -86,6 +92,45 @@ const semverNewer = (a: string, b: string): number => {
   return 0
 }
 
+/** A version test for the range forms peer specs take (^x.y.z, ~x.y.z, >=x.y.z, x.y.z, *, latest); null for
+ *  any other form — the caller falls back to npm's latest. */
+const rangeTest = (range: string): ((v: string) => boolean) | null => {
+  const r = range.trim()
+  if (r === "" || r === "*" || r === "latest") return () => true
+  const m = /^(\^|~|>=)?(\d+)\.(\d+)\.(\d+)$/.exec(r)
+  if (!m) return null
+  const [ a, b, p ] = [ Number(m[2]), Number(m[3]), Number(m[4]) ]
+  const low = `${a}.${b}.${p}`
+  if (!m[1]) return (v) => v === low
+  if (m[1] === ">=") return (v) => semverNewer(v, low) >= 0
+  const below = m[1] === "~" ? `${a}.${b + 1}.0` : a > 0 ? `${a + 1}.0.0` : b > 0 ? `0.${b + 1}.0` : `0.0.${p + 1}`
+  return (v) => semverNewer(v, low) >= 0 && semverNewer(v, below) < 0
+}
+
+/** The newest release of an npm package inside a range — what an install of `name@range` resolves to; null
+ *  when npm is unreachable or the range is of another form. */
+const npmNewestIn = async (name: string, range: string): Promise<string | null> => {
+  const accepts = rangeTest(range)
+  if (!accepts) return null
+  try {
+    const res = await fetch(`${NPM}/${name.replace("/", "%2f")}`, { headers: { accept: "application/vnd.npm.install-v1+json" }, signal: AbortSignal.timeout(6000) })
+    if (!res.ok) return null
+    const json = await res.json() as { versions?: Record<string, unknown> }
+    return Object.keys(json.versions ?? {}).filter((v) => /^\d+\.\d+\.\d+$/.test(v) && accepts(v)).sort(semverNewer).at(-1) ?? null
+  } catch {
+    return null
+  }
+}
+
+/** The version of the lecodes-cli package an entry file belongs to (`<pkg>/dist/index.js`), or null. */
+const cliVersionAt = (entry: string): string | null => {
+  try {
+    return (JSON.parse(readFileSync(join(dirname(entry), "..", "package.json"), "utf8")) as { name?: string, version?: string }).version ?? null
+  } catch {
+    return null
+  }
+}
+
 /** Running straight from the repo checkout (src/commands/update/index.ts), not a built dist/binary. */
 const FROM_SOURCE = /[\\/]src[\\/]commands[\\/]/.test(import.meta.url)
 /** The standalone release build: the bundle + chisel sit next to the executable (same test as index.ts). */
@@ -95,15 +140,16 @@ 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 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.",
+  description: "In dependency order: this CLI first (when npm has a newer one it is installed with the package manager the CLI came by — `npm install -g`, or `bun add -g` for a CLI installed with bun — and the rest of the run is the new version's), 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 every installed optional peer (lecodes-headless, lecodes-design, lecodes-3d-editor, lecodes-assets, …) that is behind what this CLI installs: its own version for the renderer, the newest version in its range for the rest.\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)"),
-    check: bool("npm step: report what's behind, install nothing"),
-    "no-cli": bool("skip the npm step (offline)"),
+    check: bool("npm steps: report what's behind, install nothing"),
+    "no-cli": bool("skip the npm steps — the CLI and its peers (offline)"),
+    yes: bool("answer yes to every install prompt (the global --yes / -y; LECODES_YES=1)"),
   },
-  examples: ["lecodes update", "lecodes update --check", "lecodes update --local --no-shells"],
-  run: async ({ flags }) => {
+  examples: ["lecodes update", "lecodes update --check", "lecodes update --yes", "lecodes update --local --no-shells"],
+  run: async ({ flags, argv }) => {
     const steps: Step[] = []
     const heading = (name: string, what: string) => log(`\n${c.bold(name)}  ${c.dim(what)}`)
     const run = async (name: string, what: string, fn: () => Promise<Outcome | [Outcome, string]>) => {
@@ -122,35 +168,82 @@ export default defineCommand({
 
     const root = findProjectDir(process.cwd())
 
-    // 1. desktop host
+    // 1. this CLI, first (see the header). LECODES_UPDATE_RESUMED is the hand-over: the CLI before this one
+    // installed it and ran this command again — "<from> → <to>", for the summary.
+    const resumed = process.env.LECODES_UPDATE_RESUMED
+    let handover = null as string | null   // set inside the step's closure, read after it
+    if (resumed) {
+      delete process.env.LECODES_UPDATE_RESUMED
+      heading("cli", "lecodes-cli itself")
+      log(`  lecodes-cli        ${resumed}`)
+      steps.push({ name: "cli", outcome: "updated", detail: `lecodes-cli ${resumed}` })
+    } else {
+      await run("cli", "lecodes-cli itself — first, so every step after it is the new version's", async () => {
+        if (flags["no-cli"]) return ["skipped", "--no-cli"]
+        if (FROM_SOURCE) return ["skipped", "running from the repo checkout — the CLI and its peers are the repo's own"]
+        const latest = await npmLatest("lecodes-cli")
+        if (!latest) return ["skipped", "npm unreachable"]
+        if (semverNewer(latest, pkg.version) <= 0) { log(`  lecodes-cli        ${pkg.version}   ${c.dim("(up to date)")}`); return "ok" }
+        log(`  lecodes-cli        ${pkg.version}   ${c.yellow("→ " + latest)}`)
+        if (flags.check) return ["updated", `${pkg.version} → ${latest} behind — run: lecodes update (the peers below are compared with this CLI's ranges, not ${latest}'s)`]
+        if (STANDALONE) return ["skipped", `this is the standalone build — ${latest} comes as the release archive, not through npm`]
+        // with the manager this CLI was installed by: another one's global dir is another copy
+        const tool = ownManager()
+        const install = installGlobalArgv(tool, [`lecodes-cli@${latest}`])
+        log("  " + c.dim("$") + " " + commandLine(tool, install))
+        const r = spawnSync(tool, install, { 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, install.slice(0, 2)) + " exited with " + (r.status ?? "a signal"))
+        // The new CLI is the same entry file now — unless the install landed in another copy than the one
+        // running (another prefix, another manager): then the rest stays this version's, and says so.
+        const now = cliVersionAt(process.argv[1] ?? "")
+        if (now !== latest) {
+          note(`the install put ${latest} where this CLI does not run from (${process.argv[1]} is ${now ?? "unreadable"}) — the rest of this run is ${pkg.version}'s; run \`lecodes update\` again`)
+          return ["updated", `${pkg.version} → ${latest} (another copy — run lecodes update again)`]
+        }
+        handover = `${pkg.version} → ${latest}`
+        return ["updated", handover]
+      })
+    }
+    if (handover) {
+      // the rest of the run is the new version's: the same command, the same flags, from the same entry file —
+      // never `lecodes` off PATH, which may name another install
+      log(c.dim(`\n  the rest of this update runs in lecodes-cli ${handover.split(" → ")[1]}`))
+      const r = spawnSync(process.execPath, [process.argv[1]!, "update", ...argv], { stdio: "inherit", env: { ...process.env, LECODES_UPDATE_RESUMED: handover } })
+      if (r.error || r.status === null) throw new CliError(`the new lecodes-cli could not run: ${r.error?.message ?? "a signal"} — run \`lecodes update\` again`)
+      process.exitCode = r.status
+      return
+    }
+
+    // 2. desktop host
     await run("desktop", "LeCodes Desktop host (desktop run / render --desktop)", async () => {
       if (process.env.LECODES_DESKTOP_EXE) return ["skipped", `LECODES_DESKTOP_EXE=${process.env.LECODES_DESKTOP_EXE} (a local build; \`lecodes desktop update\` refreshes the cache anyway)`]
       await updateDesktop()
       return "ok"
     })
 
-    // 2. matc
+    // 3. matc
     await run("matc", "Filament material compiler for local shader compiles", async () => {
       if (process.env.LECODES_MATC) return ["skipped", `LECODES_MATC=${process.env.LECODES_MATC} (a local matc)`]
       await updateMatc()
       return "ok"
     })
 
-    // 3. shaders (project)
+    // 4. shaders (project)
     await run("shaders", "recompile the project's .mat shaders with the current matc", async () => {
       if (!root) return ["skipped", "not inside a project"]
       await compileShaders()
       return "ok"
     })
 
-    // 4. types (project)
+    // 5. types (project)
     await run("types", flags.local ? "IDE types from the SDK bundled in this CLI" : "IDE types from the server", async () => {
       if (!root) return ["skipped", "not inside a project"]
       await refreshTypes({ local: flags.local, check: false })
       return "ok"
     })
 
-    // 5. native shells (project)
+    // 6. native shells (project)
     await run("shells", "ios/ + android/ pins → newest SDK release + plugin tags, then re-sync", async () => {
       if (!root) return ["skipped", "not inside a project"]
       if (flags["no-shells"]) return ["skipped", "--no-shells"]
@@ -160,37 +253,42 @@ export default defineCommand({
       return "ok"
     })
 
-    // 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.
-    await run("cli", "lecodes-cli + its optional peers (global npm installs)", async () => {
+    // 7. the optional peers — the CLI's prefix (~/.lecodes/peers, filled on first use) or global installs.
+    // Each installed one is compared with what an install would PUT where it lives, never with npm's latest
+    // alone: in the prefix that is peerInstall's own spec (the renderer at THIS CLI's version — compiler and
+    // headless host are one ABI set —, an editor's archive, an npm peer's newest release in its range), so the
+    // report and the install cannot disagree; a global install (`npm install -g`, the old way) moves to npm's
+    // latest, as it was put there. Peers that are NOT installed stay that way: optional, installing one is a choice.
+    await run("peers", "the CLI's optional peers (~/.lecodes/peers, or global installs)", async () => {
       if (flags["no-cli"]) return ["skipped", "--no-cli"]
       if (FROM_SOURCE) return ["skipped", "running from the repo checkout — the CLI and its peers are the repo's own"]
-      // Where each peer lives decides how it moves: the CLI's own prefix (~/.lecodes/peers, filled on
-      // first use) is re-installed by peerInstall — the renderer there tracks THIS CLI's version, not
-      // npm's latest, because compiler and headless host are one ABI set; a global install
-      // (`npm install -g`, the old way) moves through npm like before.
-      const rows: { name: string, installed: string | null, latest: string | null, where: "global" | "prefix" | null }[] = []
+      type Row = { name: string, installed: string | null, target: string | null, latest: string | null, range: string | null, where: "global" | "prefix" | null }
+      const rows: Row[] = []
       for (const [name, probe] of OPTIONAL_PEERS) {
         const where = peerSource(name, probe)
         const installed = peerVersion(name, probe)
-        // an archived peer (the headless host, the editors) has no "latest" of a registry: the
-        // version this CLI installs is the one to have
-        const latest = !installed ? null
-          : await archivedVersion(name) ?? await npmLatest(name)
-        rows.push({ name, installed, latest, where })
+        if (!installed) { rows.push({ name, installed, target: null, latest: null, range: null, where }); continue }
+        // an archived peer (the headless host, the editors) has no "latest" of a registry: the version this CLI
+        // installs is the one to have
+        const archived = await archivedVersion(name)
+        if (archived) { rows.push({ name, installed, target: archived, latest: archived, range: null, where }); continue }
+        const latest = await npmLatest(name)
+        if (where !== "prefix") { rows.push({ name, installed, target: latest, latest, range: null, where }); continue }
+        const spec = await peerSpec(name)   // `name@range` — what installPeers below would install
+        const range = spec.lastIndexOf("@") > 0 ? spec.slice(spec.lastIndexOf("@") + 1) : "latest"
+        rows.push({ name, installed, target: await npmNewestIn(name, range) ?? latest, latest, range, where })
       }
-      rows.push({ name: "lecodes-cli", installed: pkg.version, latest: await npmLatest("lecodes-cli"), where: "global" })
-      if (rows.every((r) => r.latest === null)) return ["skipped", "npm unreachable"]
-      const behind = rows.filter((r) => r.installed && r.latest && semverNewer(r.latest, r.installed) > 0)
+      const known = rows.filter((r) => r.installed)
+      if (known.length > 0 && known.every((r) => r.target === null)) return ["skipped", "npm unreachable"]
+      const behind = known.filter((r) => r.target && semverNewer(r.target, r.installed!) > 0)
       for (const r of rows) {
         const state = !r.installed ? c.dim("not installed (optional — installed on first use)")
-          : !r.latest ? c.dim("(npm: unknown)")
-          : behind.includes(r) ? c.yellow("→ " + r.latest)
+          : !r.target ? c.dim("(npm: unknown)")
+          : behind.includes(r) ? c.yellow("→ " + r.target)
           : c.dim("(up to date)")
-        log("  " + r.name.padEnd(18) + " " + (r.installed ?? "").padEnd(8) + " " + (r.where === "prefix" ? c.dim("peers ") : "") + state)
+        // a newer release out of the range this CLI installs: current for this CLI — said, so it is no mystery
+        const outside = r.range && r.latest && r.target && semverNewer(r.latest, r.target) > 0 ? c.dim(`  ${r.latest} is out, outside ${r.range}`) : ""
+        log("  " + r.name.padEnd(18) + " " + (r.installed ?? "").padEnd(8) + " " + (r.where === "prefix" ? c.dim("peers ") : "") + state + outside)
       }
       if (behind.length === 0) return "ok"
       const prefixBehind = behind.filter((r) => r.where === "prefix")
@@ -198,28 +296,20 @@ export default defineCommand({
       if (flags.check) {
         return ["updated", behind.length + " behind — run: lecodes update" + (globalSpecs.length ? "  (global: " + commandLine(ownManager(), installGlobalArgv(ownManager(), globalSpecs)) + ")" : "")]
       }
-      const done: string[] = []
-      if (prefixBehind.length) {
-        await installPeers(prefixBehind.map((r) => r.name), "lecodes update", { yes: true })
-        done.push(...prefixBehind.map((r) => r.name))
-      }
-      if (STANDALONE && globalSpecs.some((s) => s.startsWith("lecodes-cli@"))) {
-        note("this is the standalone build — the CLI updates by re-installing the release archive, not through npm; peers still go through npm")
-      }
-      const toInstall = STANDALONE ? globalSpecs.filter((s) => !s.startsWith("lecodes-cli@")) : globalSpecs
-      if (toInstall.length) {
+      // an npm peer at the exact version reported (the range alone leaves a locked one where it is); an archive's
+      // spec is its versioned url already
+      const at = Object.fromEntries(prefixBehind.filter((r) => r.range !== null).map((r) => [ r.name, r.target! ]))
+      if (prefixBehind.length) await installPeers(prefixBehind.map((r) => r.name), "lecodes update", { yes: true, at })
+      if (globalSpecs.length) {
         // 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 })
+        const install = installGlobalArgv(tool, globalSpecs)
+        log("  " + c.dim("$") + " " + commandLine(tool, install))
+        const r = spawnSync(tool, install, { 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 (r.status !== 0) throw new CliError(commandLine(tool, install.slice(0, 2)) + " exited with " + (r.status ?? "a signal"))
       }
-      if (done.length === 0) return ["skipped", "only the standalone CLI itself is behind — download the release"]
-      const cliToo = done.includes("lecodes-cli")
-      return ["updated", done.join(", ") + " → latest" + (cliToo ? " (the new CLI runs from your next command)" : "")]
+      return ["updated", behind.map((r) => `${r.name} ${r.installed} → ${r.target}`).join(", ")]
     })
 
     // Summary — one line per step so a scrolled-away failure can't hide.

package/src/compile/designCompile.ts

@@ -1,3 +1,4 @@
+import { readAppEnv } from "../project/env"
 import { readFileSync } from "node:fs"
 import type { Manifest } from "../project/manifest"
 import { scanLocal } from "../project/localFiles"
@@ -95,6 +96,7 @@ export const compileDesignScreen = async (opts: {
   return compileProject({
     entries,
     name: opts.name,
+    env: readAppEnv(root),
     publicUrl: opts.assets === "disk" ? LOCAL_ASSET_SCHEME : "/project",
     entryOverride: entryPath,
     header: false,

package/src/compile/headlessBundle.ts

@@ -1,3 +1,4 @@
+import { readAppEnv } from "../project/env"
 import { getProject } from "../platform/api"
 import { loadConfig, requireApiUrl, requireToken } from "../platform/config"
 import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
@@ -123,6 +124,7 @@ export const compileHeadlessBundle = async (opts: HeadlessOptions = {}): Promise
     name,
     publicUrl,
     serverUrl,
+    env: readAppEnv(root),
     entryOverride: entryFlag,
     header: false,
     format: "iife",

package/src/compile/projectCompile.ts

@@ -7,7 +7,7 @@ import { installPeers } from "../hosts/peerInstall"
 import { peerDirInPrefix } from "../hosts/peers"
 import {
   compileProjectWithMap as sdkCompileProjectWithMap, compileServerBundle, detectEntry, inlineSourceMapComment, isServerPath, scanModulesChisel,
-  localAssetNames, ENTRY_CONVENTION, type BundleBake, type CompileServerOptions,
+  localAssetNames, ENTRY_CONVENTION, findEnvLeaks, EnvLeakError, type BundleBake, type CompileServerOptions,
 } from "lecodes-sdk/compile"
 
 // Every project compiles through the SDK's one import-free compiler, which bundles with chisel (the
@@ -95,6 +95,10 @@ export type CompileOptions = {
   /** 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
+  /** The project's keys (`readAppEnv(root)` — its .env): the `PUBLIC_*` ones are baked in as `env.PUBLIC_*`,
+   *  and the bundle is searched for every other value — a secret pasted into app code fails the compile
+   *  (`EnvLeakError`). Absent = no keys. */
+  env?: Record<string, string>
 }
 
 /** A warning when auto-detection has several import-graph roots and no main.ts to settle it —
@@ -136,7 +140,14 @@ export const compileProjectBundle = async (opts: CompileOptions): Promise<{ js:
     editor: opts.editor,
     onWarning: opts.onWarning,
     serverUrl: opts.serverUrl,
+    env: opts.env,
   })
+  // a secret's VALUE in the bundle — pasted into app code or an asset — is what `env` cannot prevent, and this is
+  // where the values are known (the project's .env)
+  if (opts.env) {
+    const leaked = findEnvLeaks(code, opts.env)
+    if (leaked.length) throw new EnvLeakError(leaked, "the app bundle")
+  }
   return { js: map ? `${code}\n${inlineSourceMapComment(map)}` : code, bakes }
 }
 

package/src/compile/sceneCompile.ts

@@ -1,3 +1,4 @@
+import { readAppEnv } from "../project/env"
 import { createHash } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
@@ -93,7 +94,7 @@ export const compileSceneEditor = async (opts: {
   try {
     const js = await compileProject({
       entries, name: opts.name, publicUrl: "", entryOverride: SCENE_ENTRY_PATH,
-      header: false, format: "iife", minify: false, editor: true,
+      header: false, format: "iife", minify: false, editor: true, env: readAppEnv(root),
     })
     return { js }
   } catch (e: any) {

package/src/dev/backendWorker.ts

@@ -5,7 +5,7 @@ import { join } from "node:path"
 import { format } from "node:util"
 import {
   createAuthHost, createFilesHost, createInvoker, createPushHost, createSubscribeGuard, describeServer, loadServerModules, runSeed,
-  setChannelPublisher, setDbTransport, type AuthHost, type Heic, type LoadedServer, type PushRelay, type Sharp,
+  setChannelPublisher, setDbTransport, setEnv, type AuthHost, type Heic, type LoadedServer, type PushRelay, type Sharp,
 } from "lecodes-sdk/server"
 import { loadPeer } from "../hosts/peerInstall"
 import { ApiError, sendPush } from "../platform/api"
@@ -116,11 +116,16 @@ 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 project's keys (its .env), before any module-level code can read one
+  setEnv(m.env)
   // 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, m.filesDir, describe.marci) : []
+  // the keys the code reads and .env does not have: said now, not at the first failed call
+  const missing = describe.env.filter(name => !(name in m.env))
+  if (missing.length) notes.push(`env: ${missing.join(", ")} not set — add ${missing.length === 1 ? "it" : "them"} to the project's .env (NAME=value); a call that reads one fails until then`)
   // 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.

package/src/dev/devServer.ts

@@ -1,3 +1,4 @@
+import { readAppEnv } from "../project/env"
 import { createHash } from "node:crypto"
 import { createReadStream, readFileSync, statSync } from "node:fs"
 import { join } from "node:path"
@@ -199,7 +200,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
       }
       const onWarning = (w: string) => { warnings.push(w) }
       const serverBundle = await backend.compile(entries)
-      const js = await compileProject({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader, iconsHeader, onWarning, serverUrl: serverBundle ? serverUrl : undefined })
+      const js = await compileProject({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader, iconsHeader, onWarning, serverUrl: serverBundle ? serverUrl : undefined, env: readAppEnv(root) })
       // the page's own halves, before anything is told to reload: one that does not build fails the
       // compile, the page keeps the last good ones
       const halvesChanged = lite ? await buildHalves() : false

package/src/dev/localBackend.ts

@@ -25,7 +25,7 @@ export type LogLevel = "log" | "info" | "warn" | "error" | "debug"
 type Ctx = Omit<RequestContext, "id">
 
 export type ToWorker =
-  | { t: "load", code: string, dbDir: string, filesDir: string, root: string, push: PushSender | null }
+  | { t: "load", code: string, dbDir: string, filesDir: string, root: string, push: PushSender | null, env: Record<string, string> }
   | { t: "invoke", req: number, id: string, args: unknown[], ctx: Ctx }
   | { t: "subscribe", req: number, ch: string, args: unknown[], ctx: Ctx }
   | { t: "stop" }
@@ -57,8 +57,9 @@ export type LocalBackendOptions = {
 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>
+  /** Run this bundle from now on, with these keys (`env.NAME` in the bundle — the project's .env).
+   *  A changed key alone is a deploy too. Rejects with the reason when it does not load. */
+  deploy: (code: string, env: Record<string, string>) => Promise<DeployResult>
   invoke: (id: string, args: unknown[], ctx: Ctx) => Promise<InvokeResult>
   /** A channel subscription: its hooks → the subscriber's group (the envelope's `result`). */
   subscribe: (ch: string, args: unknown[], ctx: Ctx) => Promise<InvokeResult>
@@ -92,8 +93,13 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
   const filesDir = options.filesDir ?? filesDirOf(dbDir)
 
   let live: Live | null = null
-  /** The bundle that is deployed — what a crashed or timed-out process is started from again. */
+  /** The bundle that is deployed — what a crashed or timed-out process is started from again — and its keys. */
   let code: string | null = null
+  let env: Record<string, string> = {}
+  const sameEnv = (a: Record<string, string>, b: Record<string, string>) => {
+    const ka = Object.keys(a).sort(), kb = Object.keys(b).sort()
+    return ka.length === kb.length && ka.every((k, i) => k === kb[i] && a[k] === b[k])
+  }
   let starting: Promise<Live> | null = null
   let chain: Promise<unknown> = Promise.resolve()
   let nextReq = 1
@@ -107,7 +113,7 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
     l.pending.clear()
   }
 
-  const start = (bundle: string): Promise<{ live: Live, notes: string[] }> => new Promise((resolve, reject) => {
+  const start = (bundle: string, keys: Record<string, 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
@@ -152,7 +158,7 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
         if (!closed) log(`[server:error] the server process exited (${status ?? "killed"}) — it starts again with the next call`)
       }
     })
-    child.send({ t: "load", code: bundle, dbDir, filesDir, root: options.root, push: options.push ?? null } satisfies ToWorker)
+    child.send({ t: "load", code: bundle, dbDir, filesDir, root: options.root, push: options.push ?? null, env: keys } satisfies ToWorker)
   })
 
   const stop = async (l: Live) => {
@@ -169,7 +175,7 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
   const ensure = async (): Promise<Live | null> => {
     await chain.catch(() => {})
     if (live || code === null || closed) return live
-    starting ??= start(code).then((r) => { live = r.live; return r.live }).finally(() => { starting = null })
+    starting ??= start(code, env).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 }
   }
 
@@ -192,25 +198,26 @@ export const startLocalBackend = (options: LocalBackendOptions): LocalBackend =>
     })
   }
 
-  const deployNow = async (bundle: string): Promise<DeployResult> => {
-    if (bundle === code && live) return { changed: false, describe: live.describe, notes: [] }
-    const before = code
+  const deployNow = async (bundle: string, keys: Record<string, string>): Promise<DeployResult> => {
+    if (bundle === code && sameEnv(keys, env) && live) return { changed: false, describe: live.describe, notes: [] }
+    const before = code, beforeEnv = env
     if (live) await stop(live)
     try {
-      const next = await start(bundle)
+      const next = await start(bundle, keys)
       live = next.live
       code = bundle
+      env = keys
       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 }, () => {})
+      if (before !== null) await start(before, beforeEnv).then((r) => { live = r.live }, () => {})
       throw e
     }
   }
 
   return {
-    deploy: (bundle) => {
-      const run = chain.catch(() => {}).then(() => deployNow(bundle))
+    deploy: (bundle, keys) => {
+      const run = chain.catch(() => {}).then(() => deployNow(bundle, keys))
       chain = run
       return run
     },

package/src/dev/projectBackend.ts

@@ -4,6 +4,7 @@ import { createChannelHub, fileResponse, isMultipart, receiveUploads, UploadErro
 import { compileServer, hasServerFiles, type CompileEntry } from "../compile/projectCompile"
 import { loadPeer } from "../hosts/peerInstall"
 import { LECODES_DIR, readManifest } from "../project/manifest"
+import { readAppEnv } from "../project/env"
 import { session } from "../commands/shared"
 import { readAppConfigAt } from "../commands/app/shared"
 import { filesDirOf, startLocalBackend, type LocalBackend } from "./localBackend"
@@ -104,13 +105,16 @@ export const createProjectBackend = (options: ProjectBackendOptions): ProjectBac
         if (/\bimage\s*\(/.test(bundle.code)) await loadPeer("sharp", undefined, { for: `${options.command} (the project's t.image() fields)` })
       }
       backend ??= start()
-      const deployed = await backend.deploy(bundle.code)
+      // 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"}`
-      log(`server: ${count(d.endpoints.length, "endpoint")}, ${count(d.channels.length, "channel")}${models ? `, ${count(models, "model")} (database in ${relative(root, dbDir).replace(/\\/g, "/")})` : ""}`)
+      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}`)
     },
     handle: async (req, route, ip) => {
@@ -156,7 +160,7 @@ export const createProjectBackend = (options: ProjectBackendOptions): ProjectBac
       rmSync(dbDir, { recursive: true, force: true })
       rmSync(filesDir, { recursive: true, force: true })
       backend = start()
-      await backend.deploy(running)
+      await backend.deploy(running, readAppEnv(root))
     },
     close: async () => {
       for (const conn of [...sockets]) conn.close()

package/src/dev/watchProject.ts

@@ -21,6 +21,8 @@ export const watchProject = (root: string, onChange: () => void, log: { warn(mes
   const counts = (file: string | null): boolean => {
     if (file === null) return true   // an event without a name: assume the project's content
     const parts = file.replace(/\\/g, "/").split("/")
+    // the project's .env is never pushed (ignored), but the backend reads its keys: a save is a deploy
+    if (parts.length === 1 && parts[0] === ".env") return true
     if (parts.some((p) => SKIP_DIRS.has(p))) return false
     if (SKIP_FILES.has(parts[parts.length - 1]!)) return false
     try {

package/src/hosts/desktopRenderer.ts

@@ -517,8 +517,12 @@ const netArgs = (net: DesktopWindowOpts["net"]): string[] => {
 
 export type DesktopRenderOptions = {
   /** Called per output chunk; returning true ends the run early (the host is killed, the
-   *  outcome is a success with the output so far — a bake that printed its done marker). */
+   *  outcome is a success with the output so far — a bake that printed its done marker). The text
+   *  handed over starts at the last line break seen before the chunk, so a marker line a pipe chunk
+   *  cut in two still matches whole. */
   stopOnLine?: (chunk: string) => boolean
+  /** Called per output chunk as it arrives, the same text as stopOnLine's (a wall clock over the host's marker lines). */
+  onChunk?: (chunk: string) => void
   /** Which host binary to run (see DesktopRenderer). Must match the renderer the bundle's shaders
    *  were staged for — resolve it once per command and pass the same value to both. */
   renderer?: DesktopRenderer
@@ -703,11 +707,15 @@ export const runDesktopRender = async (
       // live only with --logs. The error tail is the last 80 chunks.
       const chunks: string[] = []
       let stopped = false
+      let partial = ""   // the unterminated last line of the previous chunk (stdout and stderr share it: markers are single lines)
       const sink = (d: unknown) => {
         const text = String(d)
         chunks.push(text)
         if (opts.logs) process.stderr.write(demangle(text))
-        if (!stopped && opts.stopOnLine?.(text)) { stopped = true; child.kill() }
+        const lines = partial + text
+        partial = lines.slice(lines.lastIndexOf("\n") + 1)
+        opts.onChunk?.(lines)
+        if (!stopped && opts.stopOnLine?.(lines)) { stopped = true; child.kill() }
       }
       child.stdout.on("data", sink)
       child.stderr.on("data", sink)