@solidrt/cli 0.0.50 → 0.0.52

package/src/pack/docs.md

@@ -0,0 +1,18 @@
+# srt pack
+
+{{ usage pack }}
+
+Bundles, compiles to bytecode and appends the result to the runner as one
+standalone executable; `--folder` writes the flat runner + manifest +
+bundle + assets folder to `dist/pack/` instead. `--flux` packs a script for
+the bare [Flux runtime](/runtime/). Experimental.
+
+`--app` writes the app alone, without a runner: one `<entry>.srtapp` holding
+the manifest, the bytecode and the assets, which any `solidrt` runner of the
+same version runs as `solidrt <file>.srtapp`. The runner is used in place,
+so a signed runner stays signed; the file is platform-independent. This is
+how the CLI ships the [console](../console/docs.md).
+
+Set a stable `appId` in the `solidrt` key of package.json before
+distributing (it keys the app's storage folder); `pack` warns while it is
+defaulted from the package name.

package/src/{pack-folder.ts → pack/layout.ts}

@@ -1,17 +1,11 @@
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs"
 import { basename, dirname, join, resolve } from "node:path"
-import {
-  assetPathFor,
-  collectAssets,
-  loadAppIdentity,
-  projectDirFor,
-  RUNTIME_VERSION,
-  SOLIDRT_VERSION,
-  type ManifestFont,
-} from "./project"
-import { resolvePackFonts } from "./fonts"
-import { runnerGlLibs } from "./packer"
-import { isolateAssetPath } from "./bundler"
+import { assetPathFor, collectAssets, loadAppIdentity, RUNTIME_VERSION, SOLIDRT_VERSION, type ManifestFont } from "../lib/project"
+import { resolvePackFonts } from "../lib/fonts"
+import type { Mode } from "../lib/mode"
+import { runnerGlLibs } from "../lib/artifacts"
+import { fail } from "../lib/util"
+import { isolateAssetPath } from "../bundle/bundler"
 
 // The canonical flat pack folder (okf/plans/client-storage-updates.md, Pack
 // output): runner + manifest.json + bundle.bin + assets/. The manifest
@@ -20,11 +14,6 @@ import { isolateAssetPath } from "./bundler"
 // identity (org, displayName) and the complete font set with the default
 // fonts materialized under assets/fonts/.
 
-function fail(message: string): never {
-  console.error(message)
-  process.exit(1)
-}
-
 function hashHex(bytes: Uint8Array): string {
   return new Bun.CryptoHasher("sha256").update(bytes).digest("hex")
 }
@@ -41,10 +30,12 @@ export type PackFolder = {
 // `isolates` are the app's isolate bundles compiled to bytecode; they ship as
 // the manifest assets isolates/<id>.bin (the production runtime has no
 // compiler, so pack never ships isolate source).
-export function buildPackFolder(entry: string, bytecode: Buffer, isolates: { id: string; bytecode: Buffer }[]): PackFolder {
-  let identity = loadAppIdentity(entry)
-  let projectDir = projectDirFor(resolve(entry))
-  let { assets, icon } = collectAssets(entry)
+export function buildPackFolder(mode: Mode, bytecode: Buffer, isolates: { id: string; bytecode: Buffer }[]): PackFolder {
+  let identity = loadAppIdentity(mode.entry, mode.projectDir)
+  // File mode collects no assets, so the dir is only ever joined in project
+  // mode; the entry's dir stands in to keep the paths absolute.
+  let projectDir = mode.projectDir ?? dirname(mode.entry)
+  let { assets, icon } = collectAssets(mode.projectDir)
   let copies = assets.map((a) => ({ from: join(projectDir, a.path), to: a.path }))
   let files = isolates.map((i) => ({ to: isolateAssetPath(i.id, "bin"), bytes: i.bytecode }))
   for (let f of files) assets.push({ path: f.to, sha256: hashHex(f.bytes), size: f.bytes.length })
@@ -53,7 +44,7 @@ export function buildPackFolder(entry: string, bytecode: Buffer, isolates: { id:
   // defaults materialize under assets/fonts/ (a user file already at that
   // path must be the same bytes, otherwise the layout is ambiguous).
   let fonts: ManifestFont[] = []
-  for (let font of resolvePackFonts(entry)) {
+  for (let font of resolvePackFonts(mode.projectDir)) {
     if (font.isDefault) {
       let path = "assets/fonts/" + basename(font.path)
       let bytes = readFileSync(font.path)

package/src/pack/main.ts

@@ -0,0 +1,86 @@
+import { values, source } from "../lib/args"
+import { bundleFlux, bundleSolid, compileToBytecode, findFluxIsolates } from "../bundle/bundler"
+import { resolvePackFonts } from "../lib/fonts"
+import { loadAppIdentity } from "../lib/project"
+import { resolveMode } from "../lib/mode"
+import { packApp, packFlux, packSolid } from "./trailer"
+import { buildPackFolder, writePackFolder } from "./layout"
+import { requireBinary } from "../lib/util"
+import { dirname, join, resolve } from "node:path"
+
+// Windows executables need the suffix; a user-given --output may already
+// carry it.
+function exeName(outfile: string): string {
+  return process.platform === "win32" && !outfile.toLowerCase().endsWith(".exe") ? outfile + ".exe" : outfile
+}
+
+// Write the packed executable, mark it runnable, and report its size.
+async function writeExecutable(packed: Buffer, outfile: string) {
+  await Bun.write(outfile, packed)
+  if (process.platform !== "win32") {
+    Bun.spawnSync(["chmod", "+x", outfile])
+  }
+  console.log(`>> wrote ${packed.length} bytes to ${outfile}`)
+}
+
+export async function main() {
+  if (values.flux) {
+    if (values.folder || values.app) {
+      console.error("--folder and --app are for app packs; flux scripts have no folder or .srtapp output")
+      process.exit(1)
+    }
+    let outfile = exeName(values.output ?? source!.replace(/\.[jt]s$/, ""))
+    // The entry's isolate modules ride along as isolates/<id>.bin sections
+    // (module name = id, for stack attribution).
+    let isolates = []
+    for (let module of findFluxIsolates(dirname(resolve(source!)))) {
+      isolates.push({ id: module.id, bytecode: await compileToBytecode(await bundleFlux(module.path), module.id) })
+    }
+    if (isolates.length) console.log(`>> isolates: ${isolates.map((i) => i.id).join(", ")}`)
+    await writeExecutable(packFlux(await compileToBytecode(await bundleFlux(source!)), isolates), outfile)
+    process.exit()
+  }
+
+  // All solidrt outputs are the same canonical pack: manifest + bundle.bin +
+  // assets (fonts included). --folder writes it as a flat folder next to a
+  // bare runner; --app writes it alone as one .srtapp for a runner to load;
+  // the default single-file exe carries it as trailer sections.
+  let mode = resolveMode()
+  let identity = loadAppIdentity(mode.entry, mode.projectDir)
+  console.log(`>> app: ${identity.appId} (${identity.org} / ${identity.displayName})`)
+  if (identity.defaulted) {
+    console.warn('>> warning: no "solidrt.appId" in package.json; set a stable reverse-DNS id before distributing')
+  }
+  let fonts = resolvePackFonts(mode.projectDir)
+  console.log(`>> fonts: ${fonts.length ? fonts.map((f) => f.alias).join(", ") : "none"}`)
+
+  let bundled = await bundleSolid(mode)
+  let bytecode = await compileToBytecode(bundled.code)
+  let isolates = []
+  for (let i of bundled.isolates) isolates.push({ id: i.id, bytecode: await compileToBytecode(i.code, i.id) })
+  if (isolates.length) console.log(`>> isolates: ${isolates.map((i) => i.id).join(", ")}`)
+  let folder = buildPackFolder(mode, bytecode, isolates)
+
+  if (values.folder) {
+    let outDir = values.output ?? join("dist", "pack")
+    writePackFolder(outDir, requireBinary("solidrt"), bytecode, folder)
+    console.log(`>> wrote pack folder to ${resolve(outDir)}`)
+    process.exit()
+  }
+
+  if (values.app) {
+    let outfile = values.output ?? mode.entry.replace(/\.[jt]sx?$/, ".srtapp")
+    let packed = packApp(folder, bytecode)
+    await Bun.write(outfile, packed)
+    console.log(`>> wrote ${packed.length} bytes to ${outfile}`)
+    process.exit()
+  }
+
+  let outfile = values.output ?? mode.entry.replace(/\.[jt]sx?$/, "")
+  // On Windows the packed image is a PE executable; it needs a .exe name to run.
+  if (process.platform === "win32" && !outfile.toLowerCase().endsWith(".exe")) {
+    outfile += ".exe"
+  }
+  await writeExecutable(packSolid(folder, bytecode), outfile)
+  process.exit()
+}

package/src/pack/trailer.ts

@@ -0,0 +1,97 @@
+import { readFileSync } from "node:fs"
+import { runnerGlLibs } from "../lib/artifacts"
+import { requireBinary } from "../lib/util"
+import type { PackFolder } from "./layout"
+
+// Trailer magic identifying the runner an embedded payload belongs to. Must
+// match the runner-side checks: both runners parse the trailer through
+// forge/src/trailer.rs (readers: lattice/src/main.rs, flux/src/bin/fluxrt.rs).
+const MAGIC = {
+  fluxrt: Buffer.from([0x46, 0x4c, 0x55, 0x58, 0x52, 0x54, 0x88, 0x44]), // "FLUXRT\x88\x44"
+  solidrt: Buffer.from([0x53, 0x4f, 0x4c, 0x49, 0x44, 0x52, 0x54, 0x88, 0x44]), // "SOLIDRT\x88\x44"
+}
+
+// Section kinds in the trailer. Must match forge/src/trailer.rs (fluxrt only
+// consumes kind-2 file sections; solidrt consumes all three).
+const SECTION_MANIFEST = 1
+const SECTION_FILE = 2
+const SECTION_GL_LIB = 3
+
+type Section = { kind: number; bytes: Buffer; name?: string }
+
+// Append sections to the runner image: each section's bytes, then a table of
+// section entries, then [table offset u64 LE][entry count u32 LE][magic].
+// Table entry: [kind u32 LE][offset u64 LE][len u64 LE][name len u16 LE][name].
+// Offsets are absolute file offsets. The runner reads its own image at
+// startup, validates the magic, and slices the sections back out.
+function packSections(runnerBytes: Buffer, sections: Section[], magic: Buffer): Buffer {
+  let parts: Buffer[] = [runnerBytes]
+  let entries: Buffer[] = []
+  let offset = runnerBytes.length
+  for (let section of sections) {
+    parts.push(section.bytes)
+    let name = Buffer.from(section.name ?? "", "utf8")
+    let entry = Buffer.allocUnsafe(22 + name.length)
+    entry.writeUInt32LE(section.kind, 0)
+    entry.writeBigUInt64LE(BigInt(offset), 4)
+    entry.writeBigUInt64LE(BigInt(section.bytes.length), 12)
+    entry.writeUInt16LE(name.length, 20)
+    name.copy(entry, 22)
+    entries.push(entry)
+    offset += section.bytes.length
+  }
+  let tail = Buffer.allocUnsafe(12)
+  tail.writeBigUInt64LE(BigInt(offset), 0) // the table starts where the sections end
+  tail.writeUInt32LE(sections.length, 8)
+  return Buffer.concat([...parts, ...entries, tail, magic])
+}
+
+// The pack folder in section form - the canonical manifest verbatim, then
+// every manifest-listed file named by its manifest path. Bundle, fonts, and
+// identity all come from the manifest; assets are read in place via ranged
+// reads at their section offsets, so nothing is unpacked at runtime.
+function appSections(folder: PackFolder, bytecode: Buffer): Section[] {
+  return [
+    { kind: SECTION_MANIFEST, bytes: Buffer.from(folder.manifest, "utf8") },
+    { kind: SECTION_FILE, bytes: bytecode, name: "bundle.bin" },
+    ...folder.copies.map((c) => ({ kind: SECTION_FILE, bytes: readFileSync(c.from), name: c.to })),
+    ...folder.files.map((f) => ({ kind: SECTION_FILE, bytes: f.bytes, name: f.to })),
+  ]
+}
+
+// The single-file solidrt executable: the runner image plus the app sections.
+// GL libraries ride along as kind-3 sections (runtime freight, deliberately
+// outside the manifest); the runner extracts those to its cache and preloads
+// them before window setup.
+export function packSolid(folder: PackFolder, bytecode: Buffer): Buffer {
+  let runnerPath = requireBinary("solidrt")
+  let sections: Section[] = [
+    ...appSections(folder, bytecode),
+    ...runnerGlLibs(runnerPath).map((lib) => ({ kind: SECTION_GL_LIB, bytes: readFileSync(lib.path), name: lib.name })),
+  ]
+  return packSections(readFileSync(runnerPath), sections, MAGIC.solidrt)
+}
+
+// A standalone .srtapp: the app sections alone, no runner in front and no GL
+// libraries (the runner that loads it brings its own). The runner parses it
+// exactly as it parses its own image (lattice/src/main.rs, load_payload), so
+// `solidrt <file>.srtapp` runs it with the runner used in place - nothing is
+// copied or appended to, and a signed runner stays signed. The extension is
+// a convention; the magic is the contract.
+export function packApp(folder: PackFolder, bytecode: Buffer): Buffer {
+  return packSections(Buffer.alloc(0), appSections(folder, bytecode), MAGIC.solidrt)
+}
+
+// The single-file flux executable: the fluxrt runner plus the program in the
+// same section trailer packSolid uses, kind-2 file sections only -
+// "bundle.bin" is the program, each isolate module "isolates/<id>.bin".
+// Like packSolid, this assembles precompiled bytecode; the pack command
+// compiles.
+export function packFlux(bytecode: Buffer, isolates: { id: string; bytecode: Buffer }[] = []): Buffer {
+  let runnerBytes = readFileSync(requireBinary("fluxrt"))
+  let sections: Section[] = [
+    { kind: SECTION_FILE, bytes: bytecode, name: "bundle.bin" },
+    ...isolates.map((i) => ({ kind: SECTION_FILE, bytes: i.bytecode, name: `isolates/${i.id}.bin` })),
+  ]
+  return packSections(runnerBytes, sections, MAGIC.fluxrt)
+}

package/src/render/docs.md

@@ -0,0 +1,19 @@
+# srt render
+
+{{ usage render }}
+
+Replays an optional recorded script and writes frames, which is how an app
+produces video or deterministic screenshots with no display attached:
+rendering uses SDL's offscreen driver, or alloy's own EGL pbuffer where that
+driver cannot go headless.
+
+```sh
+srt run --capture session.json
+srt render --script session.json --fps 60 --duration 5
+```
+
+`--capture` records key events from connected clients to a script (pointer
+input is not captured yet). `--size` is physical output pixels: layout runs
+at exactly that size, so frames are identical on every machine. Frames land
+in the directory the command runs from; `-o <path>` picks another (or a
+path prefix for the `-NNNNNN.png` names).

package/src/render/main.ts

@@ -0,0 +1,49 @@
+import { appArgs, values } from "../lib/args"
+import { requireBinary, run } from "../lib/util"
+import { bundleSolid, writeIsolates } from "../bundle/bundler"
+import { collectAssets } from "../lib/project"
+import { resolveMode } from "../lib/mode"
+import { cpSync, mkdirSync, rmSync } from "node:fs"
+import { basename, dirname, join, resolve } from "path"
+
+export async function main() {
+  let mode = resolveMode()
+  let entry = mode.entry
+  let result = await bundleSolid(mode)
+  // The staged run dir (okf/backlog/build-output-dirs.md): bundle +
+  // isolates/ + assets/ under one root - the shape of an installed version
+  // dir, so the runtime's assets mount resolves both trees. Under the cwd's
+  // dist/ (the build root, see the bundle command). Wiped first so removed
+  // isolates and deleted assets cannot go stale; render owns this subdir
+  // and nothing else under dist/.
+  let outDir = resolve("dist", "render")
+  rmSync(outDir, { recursive: true, force: true })
+  let jsOutfile = join(outDir, basename(entry).replace(/\.[jt]sx?$/, "") + ".srt.js")
+  await Bun.write(jsOutfile, result.code)
+  writeIsolates(join(outDir, "isolates"), result.isolates)
+  // The project's assets/ tree, copied in (dotfiles filtered, like a pack)
+  // so `assets/...` resolves like it does under the dev server and in a
+  // packed app (the runtime's cwd is the data sandbox, which holds no
+  // assets). File mode collects none.
+  for (let asset of collectAssets(mode.projectDir).assets) {
+    let dest = join(outDir, asset.path)
+    mkdirSync(dirname(dest), { recursive: true })
+    cpSync(join(mode.projectDir!, asset.path), dest)
+  }
+  let runner = requireBinary("solidrt-go")
+  let playbackArgs = ["--playback"]
+  if (values.fps) playbackArgs.push("--fps", values.fps)
+  if (values.duration) playbackArgs.push("--duration", values.duration)
+  if (values.size) playbackArgs.push("--size", values.size)
+  if (values.script) playbackArgs.push("--script", resolve(values.script))
+  // Always absolute: the runtime chdirs into the app's data sandbox before
+  // frames are written, so a bare prefix would land the PNGs there.
+  playbackArgs.push("--out", resolve(values.output ?? "."))
+  playbackArgs.push("--assets", outDir)
+  playbackArgs.push(jsOutfile)
+  // The runner takes everything after the source path verbatim as the app's
+  // argument vector (flux:process argv).
+  playbackArgs.push(...appArgs)
+  let exit = await run(runner, playbackArgs)
+  process.exit(exit)
+}

package/src/server/args.ts

@@ -0,0 +1,126 @@
+// The server's command line: the interface `srt run` / `srt server` (a bun
+// launcher that spawns this process) and the console (a flux app that spawns
+// it or imports it) share, so it takes flags and never a config blob
+// (okf/done/srt-command-folders.md):
+//
+//   flux server.js [file] [--project|--file] [--port N] [--lan] [--proxy-http]
+//                  [--capture f] [--tunnel] [--stats] [--minify]
+//                  [--client N [--data-root d] [--size WxH]] [-- args]
+//
+// --client N spawns the local solidrt-go client with data slot N (`srt run`);
+// without it the server runs alone (`srt server`). Everything after a bare
+// "--" is the app's argument vector (flux:process argv on every client).
+// flux:process argv is the tail after the script, so a small parser covers
+// it: boolean flags, valued flags, one positional, the "--" tail.
+
+import { argv } from "flux:process"
+
+export type ServerArgs = {
+  /** The entry file argument, or none (the project at the cwd). */
+  entry: string | undefined
+  project: boolean
+  file: boolean
+  lan: boolean
+  proxyHttp: boolean
+  tunnel: boolean
+  stats: boolean
+  minify: boolean
+  port: number | undefined
+  capture: string | undefined
+  /** The local client's data slot, or null for no local client. */
+  client: number | null
+  dataRoot: string | undefined
+  size: string | undefined
+  appArgs: string[]
+}
+
+// A fatal usage or configuration error. flux has no exit call: an uncaught
+// error at startup ends the process with a nonzero status and the message
+// on stderr, which is what a failed launch needs.
+export function fail(message: string): never {
+  throw new Error(message)
+}
+
+function integer(name: string, raw: string, min: number, max: number): number {
+  let value = Number(raw)
+  if (!/^\d+$/.test(raw) || value < min || value > max) {
+    fail(`Invalid --${name} value "${raw}": expected an integer between ${min} and ${max}`)
+  }
+  return value
+}
+
+export function parseArgs(raw: string[] = argv): ServerArgs {
+  let sep = raw.indexOf("--")
+  let own = sep === -1 ? raw : raw.slice(0, sep)
+  let args: ServerArgs = {
+    entry: undefined,
+    project: false,
+    file: false,
+    lan: false,
+    proxyHttp: false,
+    tunnel: false,
+    stats: false,
+    minify: false,
+    port: undefined,
+    capture: undefined,
+    client: null,
+    dataRoot: undefined,
+    size: undefined,
+    appArgs: sep === -1 ? [] : raw.slice(sep + 1),
+  }
+  let value = (name: string, i: number): string => {
+    let v = own[i]
+    if (v === undefined || v.startsWith("--")) fail(`--${name} needs a value`)
+    return v
+  }
+  for (let i = 0; i < own.length; i++) {
+    let arg = own[i]!
+    if (!arg.startsWith("--")) {
+      if (args.entry !== undefined) fail(`Unexpected argument: ${arg}`)
+      args.entry = arg
+      continue
+    }
+    let name = arg.slice(2)
+    switch (name) {
+      case "project":
+        args.project = true
+        break
+      case "file":
+        args.file = true
+        break
+      case "lan":
+        args.lan = true
+        break
+      case "proxy-http":
+        args.proxyHttp = true
+        break
+      case "tunnel":
+        args.tunnel = true
+        break
+      case "stats":
+        args.stats = true
+        break
+      case "minify":
+        args.minify = true
+        break
+      case "port":
+        args.port = integer(name, value(name, ++i), 1, 65535)
+        break
+      case "capture":
+        args.capture = value(name, ++i)
+        break
+      case "client":
+        args.client = integer(name, value(name, ++i), 0, Number.MAX_SAFE_INTEGER)
+        break
+      case "data-root":
+        args.dataRoot = value(name, ++i)
+        break
+      case "size":
+        args.size = value(name, ++i)
+        break
+      default:
+        fail(`Unknown flag: ${arg}`)
+    }
+  }
+  return args
+}

package/src/server/binaries.ts

@@ -0,0 +1,47 @@
+// Where the server finds what it spawns (okf/done/srt-command-folders.md):
+//
+// - the platform binaries (solidrt-go) in SRT_PLATFORM_DIR, which srt sets to
+//   the platform package it resolved, else a checkout's SRT_HOME/dist/<triple>;
+// - srt itself, run as `bun <SRT_CLI>/bin/srt`, so the bundle and the startup
+//   typecheck run by command name (`srt bundle --json`, `srt check`): SRT_CLI
+//   is the @solidrt/cli package root (srt sets it; a checkout's is
+//   SRT_HOME/packages/cli) and SRT_BUN the bun to use (srt's own; else PATH).
+//
+// So `flux server.js` started by hand needs SRT_HOME (a built checkout) or
+// the three variables, and started by srt needs nothing.
+
+import { file } from "flux:fs"
+import { join } from "flux:path"
+import { arch, env, platform } from "flux:process"
+import { fail } from "./args"
+
+// Host platform -> dist triple, as src/artifacts.ts maps it for bun.
+const TRIPLES: Record<string, string> = {
+  "linux-x64": "linux-x64-gnu",
+  "linux-arm64": "linux-arm64-gnu",
+  "darwin-arm64": "darwin-arm64",
+  "win32-x64": "win32-x64-msvc",
+}
+
+function platformDir(): string | null {
+  if (env.SRT_PLATFORM_DIR) return env.SRT_PLATFORM_DIR
+  let triple = TRIPLES[`${platform}-${arch}`]
+  return env.SRT_HOME && triple ? join(env.SRT_HOME, "dist", triple) : null
+}
+
+/** The absolute path of a platform binary, or a failed launch. */
+export async function requireBinary(name: string): Promise<string> {
+  let dir = platformDir()
+  let path = dir ? join(dir, name + (platform === "win32" ? ".exe" : "")) : null
+  if (path && (await file(path).exists())) return path
+  fail(
+    `Could not find the ${name} binary${dir ? ` in ${dir}` : ""}. Run through srt, or set SRT_HOME to a SolidRT checkout built with make client.`,
+  )
+}
+
+/** The srt command prefix, `[bun, <cli>/bin/srt]`, for the bun-side commands. */
+export function srtCommand(): string[] {
+  let cli = env.SRT_CLI ?? (env.SRT_HOME ? join(env.SRT_HOME, "packages", "cli") : undefined)
+  if (!cli) fail("Could not find srt: set SRT_CLI to the @solidrt/cli package root, or SRT_HOME to a SolidRT checkout.")
+  return [env.SRT_BUN ?? "bun", join(cli, "bin", "srt")]
+}

package/src/server/config.ts

@@ -0,0 +1,54 @@
+// What the server resolved at startup from its flags (args.ts), its mode
+// (mode.ts) and its environment (binaries.ts), shared with the route
+// handlers through state.ts.
+
+export type ServerConfig = {
+  /** Project mode serves the project at its root; file mode serves one file. */
+  mode: "project" | "file"
+  /** The canonical project root (project mode) or file path (file mode): the
+   * registry key, and what every control response names. */
+  key: string
+  /** This server's folder under ~/.solidrt/servers/: the registry record,
+   * the remembered port, the tunnel key. */
+  serverDir: string
+  /** The app entry (absolute path) rebuilt on a reload. */
+  entry: string
+  /** Directory served by the file routes (the entry's directory). */
+  sourceDir: string
+  /** Project root whose assets/ folder the /assets/ route serves; null in
+   * file mode (no assets). */
+  projectDir: string | null
+  /** Where the bun-side commands run and the entry arguments they take
+   * (`<entry> --project` in the project root, `<entry> --file` in the
+   * entry's directory), so they resolve the same mode this server did. */
+  cwd: string
+  entryArgs: string[]
+  /** The srt command prefix (binaries.ts) the bundle and the startup
+   * typecheck run through. */
+  srt: string[]
+  /** An explicit --port; otherwise the remembered port is tried, then the
+   * first free one. */
+  port?: number
+  /** Bind every interface (and announce the LAN address); default loopback. */
+  lan: boolean
+  /** The address clients are told to reach this server on. */
+  address: string
+  proxyHttp: boolean
+  /** The session's app arguments (the tail after a bare "--"), included in
+   * every reload push as flux:process argv. */
+  args: string[]
+  /** Minify the rebuild output. */
+  minify: boolean
+  /** Enable the sqlite-backed proxy cache. */
+  cache: boolean
+  /** Build outputs and the proxy cache: the project's .srt-data, or the
+   * server folder in file mode. */
+  cacheDir: string
+  /** Destination for captured key events, or unset when off. */
+  capture?: string
+  stats: boolean
+  /** Accept ticket-paired clients through the p2p tunnel. */
+  tunnel: boolean
+  /** The local client to spawn once the port is bound, or null. */
+  client: { cmd: string; args: string[] } | null
+}