@solidrt/cli 0.0.50 → 0.0.52

package/src/{bundler.ts → bundle/bundler.ts}

@@ -4,13 +4,15 @@ import ts from "@babel/preset-typescript"
 import remapping from "@jridgewell/remapping"
 import solid from "babel-preset-solid"
 import { type BunPlugin, type BuildArtifact } from "bun"
-import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
 import { dirname, join, relative, resolve as resolvePath, sep } from "node:path"
-import { values, source } from "./args"
-import { state, print, requireBinary } from "./util"
-import { buildManifest, manifestAssetFor } from "./project"
+import { values } from "../lib/args"
+import type { Mode } from "../lib/mode"
+import { requireBinary } from "../lib/util"
+import type { BundleOutput } from "../types/bundle"
+import { buildManifest, manifestAssetFor, type ManifestAsset } from "../lib/project"
 
-// Babel plugin: rewrite `import data from "./x" with { type: "binary" }` into an
+// Babel plugin: rewrite `import data from "../x" with { type: "binary" }` into an
 // inline Uint8Array of the file's bytes, and `with { type: "text" }` into an
 // inline string of its UTF-8 contents. The import attribute is invisible to
 // Bun's bundler and its plugins in this Bun version, so we handle it here in the
@@ -21,8 +23,10 @@ import { buildManifest, manifestAssetFor } from "./project"
 // attribute-free path later. Both attributes work on any extension, so shader
 // and other text sources inline by attribute the same way bytes do; `.svg` is
 // additionally text-loaded without an attribute (see Bun's `loader` below).
-function inlineImport({ types: t }: { types: any }) {
-  return {
+// Inlined files leave no trace in the module graph, so the plugin records
+// each one in `inputs` (see `BundleOutput.inputs`).
+function inlineImport(inputs: Set<string>) {
+  return ({ types: t }: { types: any }) => ({
     visitor: {
       ImportDeclaration(path: any, pluginState: any) {
         let attrs = path.node.attributes ?? path.node.assertions
@@ -32,12 +36,13 @@ function inlineImport({ types: t }: { types: any }) {
         let def = path.node.specifiers.find((s: any) => s.type === "ImportDefaultSpecifier")
         if (!def) {
           throw path.buildCodeFrameError(
-            `A ${kind} import needs a default import: import data from "./file" with { type: "${kind}" }`,
+            `A ${kind} import needs a default import: import data from "../file" with { type: "${kind}" }`,
           )
         }
 
         let importer = pluginState.file.opts.filename as string
         let abs = resolvePath(dirname(importer), path.node.source.value)
+        inputs.add(abs)
 
         // text: var <local> = "<contents>"
         // binary: var <local> = Uint8Array.from(atob("<b64>"), c => c.charCodeAt(0))
@@ -56,7 +61,7 @@ function inlineImport({ types: t }: { types: any }) {
         path.replaceWith(t.variableDeclaration("var", [t.variableDeclarator(t.identifier(def.local.name), expr)]))
       },
     },
-  }
+  })
 }
 
 // Concatenate only the JS outputs (entry point plus any code-split chunks) of a
@@ -84,25 +89,27 @@ async function codeFromOutputs(outputs: BuildArtifact[]): Promise<string> {
 // collected there, keyed by absolute path, for sourcemap composition later.
 // `isolateEntry` is the one "use isolate" module this build may load (its own
 // entry); loading any other one means a by-value import of an isolate module,
-// which is a build error (see isolate modules below).
-function solidPlugin(babelMaps?: Map<string, object>, isolateEntry?: string): BunPlugin {
+// which is a build error (see isolate modules below). Every file the plugin
+// loads or inlines is recorded in `inputs`.
+function solidPlugin(inputs: Set<string>, babelMaps?: Map<string, object>, isolateEntry?: string): BunPlugin {
   return {
     name: "bun-plugin-solid",
     setup: (build) => {
       build.onLoad({ filter: /\.(js|ts)x?$/ }, async (args) => {
         if (!/\.(js|ts)x$/.test(args.path) && args.path.includes("node_modules")) return
+        inputs.add(args.path)
         let file = Bun.file(args.path)
         let code = await file.text()
         if (args.path !== isolateEntry && hasIsolateDirective(code)) {
           throw new Error(
-            `${args.path} is a "use isolate" module: import its types only (import type * as W from "./...") and call it through isolate() from flux:isolate`,
+            `${args.path} is a "use isolate" module: import its types only (import type * as W from "../...") and call it through isolate() from flux:isolate`,
           )
         }
         let transforms = await transformAsync(code, {
           filename: args.path,
           sourceMaps: !!babelMaps,
           presets: [[solid, { moduleName: "@solidrt/core", generate: "universal" }], [ts]],
-          plugins: [jsx, inlineImport],
+          plugins: [jsx, inlineImport(inputs)],
         })
         if (babelMaps && transforms?.map) babelMaps.set(args.path, transforms.map)
         return { contents: transforms?.code ?? "", loader: "js" }
@@ -129,26 +136,39 @@ export function hasIsolateDirective(code: string): boolean {
 
 let SKIP_DIRS = new Set(["node_modules", "dist"])
 
-export type IsolateModule = { id: string; path: string }
-
-/** Every "use isolate" module under `root`, in id order. */
-export function findIsolateModules(root: string): IsolateModule[] {
-  let out: IsolateModule[] = []
+/**
+ * Depth-first files under `root`, visited as (absolute path, forward-slash
+ * path relative to root). Dotfiles and `skipDirs` are skipped; a missing
+ * root visits nothing.
+ */
+export function walkFiles(root: string, visit: (abs: string, rel: string) => void, skipDirs?: Set<string>) {
+  if (!existsSync(root)) return
   let walk = (dir: string) => {
     for (let entry of readdirSync(dir, { withFileTypes: true })) {
-      if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue
+      if (entry.name.startsWith(".") || skipDirs?.has(entry.name)) continue
       let abs = join(dir, entry.name)
-      if (entry.isDirectory()) {
-        walk(abs)
-      } else if (entry.isFile() && /\.(js|ts)x?$/.test(entry.name) && !entry.name.endsWith(".d.ts")) {
-        if (hasIsolateDirective(readFileSync(abs, "utf8"))) {
-          let id = relative(root, abs).split(sep).join("/").replace(/\.(js|ts)x?$/, "")
-          out.push({ id, path: abs })
-        }
-      }
+      if (entry.isDirectory()) walk(abs)
+      else if (entry.isFile()) visit(abs, relative(root, abs).split(sep).join("/"))
     }
   }
   walk(root)
+}
+
+export type IsolateModule = { id: string; path: string }
+
+/** Every "use isolate" module under `root`, in id order. */
+export function findIsolateModules(root: string): IsolateModule[] {
+  let out: IsolateModule[] = []
+  walkFiles(
+    root,
+    (abs, rel) => {
+      if (!/\.(js|ts)x?$/.test(rel) || rel.endsWith(".d.ts")) return
+      if (hasIsolateDirective(readFileSync(abs, "utf8"))) {
+        out.push({ id: rel.replace(/\.(js|ts)x?$/, ""), path: abs })
+      }
+    },
+    SKIP_DIRS,
+  )
   out.sort((a, b) => (a.id < b.id ? -1 : 1))
   return out
 }
@@ -158,20 +178,28 @@ export function isolateAssetPath(id: string, ext: "js" | "bin"): string {
   return `isolates/${id}.${ext}`
 }
 
-export type BundleOptions = { entry: string; devBase?: string; dev: boolean; minify: boolean }
+// `project` is the project root (mode.ts decides it, never a search), or
+// null for a file on its own: no assets in the manifest and no isolate
+// modules (isolates are a project feature).
+export type BundleOptions = { entry: string; dev: boolean; minify: boolean; project: string | null }
+
+// The `srt bundle --json` stdout contract doubles as the in-process result.
+export type BundleResult = BundleOutput
 
-export type BundleResult = {
-  code: string
-  /** Composed sourcemap JSON (bundle -> original .tsx sources), dev builds only. */
-  map: string | null
-  /** Version manifest JSON for this bundle; clients install pushes under its hash. */
-  manifest: string
-  /** The app's isolate bundles, one per "use isolate" module, in id order. */
-  isolates: { id: string; code: string }[]
+/**
+ * The bundle's sourcemaps keyed by the module name stack frames cite ("main"
+ * for the app, the isolate id for each isolate), for the server's log remap.
+ * Null when the build carries no maps (production builds).
+ */
+export function bundleMaps(result: BundleResult): Record<string, string> | null {
+  let maps: Record<string, string> = {}
+  if (result.map) maps.main = result.map
+  for (let i of result.isolates) if (i.map) maps[i.id] = i.map
+  return Object.keys(maps).length ? maps : null
 }
 
 // The pure bundle: every input is explicit, so it runs identically in the srt
-// (Bun) process and in the standalone bundle-cli subprocess the dev server
+// (Bun) process and in the `srt bundle --json` subprocess the dev server
 // spawns. It never touches the ambient args/state singletons and never prints
 // progress (callers own that), so its stdout stays clean for subprocess use.
 export async function bundleWith(opts: BundleOptions): Promise<BundleResult | null> {
@@ -185,12 +213,15 @@ export async function bundleWith(opts: BundleOptions): Promise<BundleResult | nu
     "import.meta.env.DEV": opts.dev ? "true" : "false",
     "process.env.NODE_ENV": opts.dev ? '"development"' : '"production"',
   }
-  if (opts.devBase) define.__SRT_DEV_BASE__ = opts.devBase
 
   // One Bun.build per entry: the app, then each isolate module as its own
   // self-contained bundle (splitting is off, so a helper both import gets
-  // duplicated rather than shared). Only the app's build gets a composed
-  // sourcemap for now.
+  // duplicated rather than shared). In dev every build gets a composed
+  // sourcemap, keyed downstream by its module name.
+  // Every file the bundle depends on (BundleOutput.inputs): what the plugin
+  // loaded or inlined, plus every module in the build's sourcemap, which is
+  // where dependency code (node_modules, workspace packages) shows up.
+  let inputs = new Set<string>()
   let build = async (entry: string, babelMaps?: Map<string, object>, isolateEntry?: string) => {
     let result = null
     try {
@@ -203,7 +234,7 @@ export async function bundleWith(opts: BundleOptions): Promise<BundleResult | nu
         define,
         loader: { ".svg": "text" },
         sourcemap: babelMaps ? "external" : "none",
-        plugins: [solidPlugin(babelMaps, isolateEntry)],
+        plugins: [solidPlugin(inputs, babelMaps, isolateEntry)],
       })
     } catch (e) {
       console.error("[cli] compile error:\n", e)
@@ -213,6 +244,7 @@ export async function bundleWith(opts: BundleOptions): Promise<BundleResult | nu
       for (let msg of result.logs) console.error(msg)
       return null
     }
+    for (let source of await mapSources(result.outputs)) inputs.add(source)
     return result
   }
 
@@ -221,26 +253,56 @@ export async function bundleWith(opts: BundleOptions): Promise<BundleResult | nu
   if (!main) return null
   let code = await codeFromOutputs(main.outputs)
 
-  let isolates: { id: string; code: string }[] = []
-  for (let module of findIsolateModules(dirname(resolvePath(opts.entry)))) {
-    let result = await build(module.path, undefined, module.path)
+  let isolates: { id: string; code: string; map: string | null }[] = []
+  let modules = opts.project === null ? [] : findIsolateModules(dirname(resolvePath(opts.entry)))
+  for (let module of modules) {
+    let moduleMaps = opts.dev ? new Map<string, object>() : undefined
+    let result = await build(module.path, moduleMaps, module.path)
     if (!result) return null
-    isolates.push({ id: module.id, code: await codeFromOutputs(result.outputs) })
+    isolates.push({
+      id: module.id,
+      code: await codeFromOutputs(result.outputs),
+      map: await composeMap(result.outputs, moduleMaps),
+    })
+  }
+
+  // The project files the manifest and the build read: package.json (app
+  // identity, icon, fonts) and tsconfig.json (resolution, JSX).
+  if (opts.project !== null) {
+    for (let name of ["package.json", "tsconfig.json"]) {
+      let abs = join(opts.project, name)
+      if (existsSync(abs)) inputs.add(abs)
+    }
   }
 
-  let extra = isolates.map((i) => manifestAssetFor(isolateAssetPath(i.id, "js"), Buffer.from(i.code, "utf8")))
   return {
     code,
     map: await composeMap(main.outputs, babelMaps),
-    manifest: buildManifest(code, opts.entry, extra),
+    manifest: buildManifest(code, opts.entry, isolateManifestAssets(isolates), opts.project),
     isolates,
+    inputs: [...inputs].sort(),
   }
 }
 
-// Write dev isolate bundles where the dev server serves /isolates/ from
-// (<project>/.srt-data/isolates/<id>.js), so clients can fetch the manifest
-// assets the bundle lists. Stale files from removed modules stay behind
-// unlisted, which is harmless.
+// The source files a build's sourcemap cites, as absolute paths (Bun writes
+// them cwd-relative). Empty for a build without a map.
+async function mapSources(outputs: BuildArtifact[]): Promise<string[]> {
+  let out: string[] = []
+  for (let o of outputs) {
+    if ((o.kind !== "entry-point" && o.kind !== "chunk") || !o.sourcemap) continue
+    let map = JSON.parse(await o.sourcemap.text())
+    for (let source of map.sources ?? []) out.push(resolvePath(source))
+  }
+  return out
+}
+
+/** The manifest assets for a set of isolate bundles (dev form: isolates/<id>.js). */
+export function isolateManifestAssets(isolates: { id: string; code: string }[]): ManifestAsset[] {
+  return isolates.map((i) => manifestAssetFor(isolateAssetPath(i.id, "js"), Buffer.from(i.code, "utf8")))
+}
+
+// Write isolate bundles as `<dir>/<id>.js`, the shape the manifest lists and
+// a prebuilt bundle's sibling isolates/ dir carries.
 export function writeIsolates(dir: string, isolates: { id: string; code: string }[]) {
   for (let i of isolates) {
     let file = join(dir, `${i.id}.js`)
@@ -271,30 +333,52 @@ async function composeMap(outputs: BuildArtifact[], babelMaps?: Map<string, obje
   return composed.toString()
 }
 
-export async function bundle(entry = source) {
-  let devBase = state.serverUrl ?? undefined
-  let dev = !!devBase || values.dev
+// The one-shot commands' bundle (bundle, pack, render): production unless
+// --dev, on what the cwd and the argument decide (mode.ts).
+export async function bundle(mode: Mode) {
+  let dev = values.dev
   // Keep stdout clean when the bundle itself is written to stdout.
-  if (!values.stdout) print(`[cli] Bundling (${dev ? "development" : "production"})`)
-  let result = await bundleWith({ entry: entry!, devBase, dev, minify: values.minify })
-  // With a server running, its /isolates/ route serves what we write here.
-  if (result && devBase) writeIsolates(devIsolatesDir(state.projectDir), result.isolates)
-  return result
+  if (!values.stdout) console.log(`[cli] Bundling (${dev ? "development" : "production"})`)
+  return bundleWith({ entry: mode.entry, dev, minify: values.minify, project: mode.projectDir })
 }
 
-/** Where a project's dev isolate bundles are written and served from. */
-export function devIsolatesDir(projectDir: string): string {
-  return join(projectDir, ".srt-data", "isolates")
+// A flux entry's isolate modules: everything under its isolates/ dir, id =
+// the path relative to that dir without extension. Standalone flux resolves
+// isolates by location, not directive - module <id> is
+// <entry dir>/isolates/<id>.bin or .js - so this is the discovery for
+// bundling and packing flux scripts (which also lets a worker be .ts, unlike
+// running from source).
+export function findFluxIsolates(entryDir: string): IsolateModule[] {
+  let out: IsolateModule[] = []
+  walkFiles(join(entryDir, "isolates"), (abs, rel) => {
+    if (/\.[jt]s$/.test(rel) && !rel.endsWith(".d.ts")) {
+      out.push({ id: rel.replace(/\.[jt]s$/, ""), path: abs })
+    }
+  })
+  out.sort((a, b) => (a.id < b.id ? -1 : 1))
+  return out
 }
 
-export async function bundleTo(outfile: string) {
-  let result = await bundle()
-  if (!result) {
-    console.error("Build failed")
-    process.exit(1)
-  }
-  await Bun.write(outfile, result.code)
-  return result
+// A bundle cannot carry its isolate bundles inside itself, so they travel in
+// the isolates/ dir next to it: `<dir>/isolates/<id>.js` (or `.bin`,
+// compiled) beside the bundle file - the shape the flux runtime and an
+// installed version dir resolve. Writes are confined to bundle-owned output
+// dirs (the ensureOutDir rule in the bundle command); loads read the dir
+// from wherever the bundle sits.
+export function bundleIsolatesDir(bundlePath: string): string {
+  return join(dirname(bundlePath), "isolates")
+}
+
+/** A prebuilt bundle's isolate bundles, read back from its sibling dir; no dir means none. */
+export function readPrebuiltIsolates(bundlePath: string): { id: string; code: string }[] {
+  let out: { id: string; code: string }[] = []
+  walkFiles(bundleIsolatesDir(resolvePath(bundlePath)), (abs, rel) => {
+    if (rel.endsWith(".js")) {
+      out.push({ id: rel.replace(/\.js$/, ""), code: readFileSync(abs, "utf8") })
+    }
+  })
+  out.sort((a, b) => (a.id < b.id ? -1 : 1))
+  return out
 }
 
 // Bundle for the bare Flux runtime: no Solid plugin, flux: modules stay external.
@@ -314,9 +398,10 @@ export async function bundleFlux(entry: string): Promise<string> {
   return codeFromOutputs(result.outputs)
 }
 
-// Bundle for the SolidRT runtime via the standard Solid-aware bundler.
-export async function bundleSolid(): Promise<BundleResult> {
-  let result = await bundle()
+// Bundle for the SolidRT runtime via the standard Solid-aware bundler, or
+// exit the command on a failed build.
+export async function bundleSolid(mode: Mode): Promise<BundleResult> {
+  let result = await bundle(mode)
   if (!result) {
     console.error("Build failed")
     process.exit(1)
@@ -324,10 +409,12 @@ export async function bundleSolid(): Promise<BundleResult> {
   return result
 }
 
-// Compile JS source to QuickJS bytecode via the fluxc binary.
-export async function compileToBytecode(jsCode: string): Promise<Buffer> {
+// Compile JS source to QuickJS bytecode via the fluxc binary. `moduleName` is
+// what stack frames cite at runtime: "main" for the entry, the isolate id for
+// an isolate bundle.
+export async function compileToBytecode(jsCode: string, moduleName = "main"): Promise<Buffer> {
   let compiler = requireBinary("fluxc")
-  let proc = Bun.spawn([compiler], {
+  let proc = Bun.spawn([compiler, moduleName], {
     stdin: new Blob([jsCode]),
     stdout: "pipe",
     stderr: "inherit",

package/src/bundle/docs.md

@@ -0,0 +1,12 @@
+# srt bundle
+
+{{ usage bundle }}
+
+Writes `dist/bundle/` (or `--output <dir>`): `<name>.srt.js` plus the app's
+isolate modules as `isolates/<id>.js`, or bytecode with `--compile`. Move
+the dir, not the bare file: a bundle loaded without its isolates/ dir loses
+them.
+
+`--flux` targets the bare [Flux runtime](/runtime/) instead of a SolidRT
+app, for scripts and servers with no UI. `--json` is the dev server's
+rebuild contract, one JSON object on stdout.

package/src/bundle/main.ts

@@ -0,0 +1,203 @@
+import { values, source, isPrebuilt } from "../lib/args"
+import {
+  bundleFlux,
+  bundleSolid,
+  bundleWith,
+  compileToBytecode,
+  findFluxIsolates,
+  isolateManifestAssets,
+  readPrebuiltIsolates,
+  walkFiles,
+  writeIsolates,
+} from "./bundler"
+import { resolveMode } from "../lib/mode"
+import { buildManifest } from "../lib/project"
+import type { BundleOutput } from "../types/bundle"
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+
+// Write to stdout and resolve only once the whole payload is flushed.
+// process.stdout.write to a pipe is async and applies backpressure; the
+// callback fires after every byte is drained, so it is safe to exit after.
+function writeStdout(data: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    process.stdout.write(data, (err) => (err ? reject(err) : resolve()))
+  })
+}
+
+// The bundle output dir (okf/backlog/build-output-dirs.md): the bundle flow's
+// subdir of the build root, or an explicit --output dir. The build root is
+// the cwd: a project command runs in its root (mode.ts), and a file on its
+// own builds where it is run from. Only reused when it is empty or already a
+// bundle output (a *.srt.* or *.flux.* bundle at top level) - the
+// writePackFolder rule - so it never writes into an unrelated directory.
+function ensureOutDir(defaultDir = join("dist", "bundle")): string {
+  let outDir = values.output ?? defaultDir
+  let existing = existsSync(outDir) ? readdirSync(outDir) : null
+  if (existing && existing.length > 0 && !existing.some((name) => /\.(srt|flux)\.(js|bin)$/.test(name))) {
+    console.error(`${resolve(outDir)} exists and is not a bundle output; choose another --output`)
+    process.exit(1)
+  }
+  mkdirSync(outDir, { recursive: true })
+  return outDir
+}
+
+// Clear one form's files from the output's isolates/ dir before rewriting it,
+// so removed modules cannot go stale. The dir is shared by a bundle's .js and
+// .bin forms, so only the form being rewritten is cleared - a --compile must
+// not delete the .js set the .js bundle pairs with, nor the reverse.
+function clearIsolates(dir: string, ext: ".js" | ".bin") {
+  walkFiles(dir, (abs) => {
+    if (abs.endsWith(ext)) rmSync(abs)
+  })
+}
+
+// Compile one isolate bundle to `<dir>/<id>.bin` (module name = its id, for
+// stack attribution).
+async function writeIsolateBytecode(dir: string, isolate: { id: string; code: string }) {
+  let outfile = join(dir, isolate.id + ".bin")
+  mkdirSync(dirname(outfile), { recursive: true })
+  await Bun.write(outfile, await compileToBytecode(isolate.code, isolate.id))
+}
+
+// Compile JS to a bytecode file and report its size.
+async function writeBytecode(jsCode: string, outfile: string) {
+  let bytecode = await compileToBytecode(jsCode)
+  await Bun.write(outfile, bytecode)
+  let binSize = (await Bun.file(outfile).stat()).size
+  console.log(`>> wrote ${binSize} bytes to ${outfile}`)
+}
+
+export async function main() {
+  if (values.flux) {
+    let entry = resolve(source!)
+    let name = basename(entry).replace(/\.[jt]s$/, "")
+    let jsCode = await bundleFlux(entry)
+    // Standalone flux resolves isolates by location, not directive: module
+    // <id> is <entry dir>/isolates/<id>.js. Bundling keeps that shape - every
+    // module under the entry's isolates/ dir is built bare like the entry
+    // (which also lets a worker be .ts, unlike running from source) and lands
+    // as isolates/<id>.js next to the bundle.
+    let isolateModules = findFluxIsolates(dirname(entry))
+
+    if (values.stdout) {
+      if (isolateModules.length) {
+        console.error("[cli] Warning: this script has isolate modules; --stdout carries only the main bundle")
+      }
+      await writeStdout(jsCode)
+      process.exit()
+    }
+    let outDir = ensureOutDir()
+    if (values.compile) {
+      await writeBytecode(jsCode, join(outDir, name + ".flux.bin"))
+    } else {
+      let outfile = join(outDir, name + ".flux.js")
+      await Bun.write(outfile, jsCode)
+      console.log(`>> wrote ${jsCode.length} bytes to ${outfile}`)
+    }
+    // Isolates follow the main bundle's form: source beside a .flux.js,
+    // bytecode beside a .flux.bin (the flux resolver reads .bin first).
+    let isolatesDir = join(outDir, "isolates")
+    if (values.compile) {
+      clearIsolates(isolatesDir, ".bin")
+      for (let module of isolateModules) {
+        await writeIsolateBytecode(isolatesDir, { id: module.id, code: await bundleFlux(module.path) })
+      }
+    } else {
+      clearIsolates(isolatesDir, ".js")
+      for (let module of isolateModules) {
+        let file = join(isolatesDir, module.id + ".js")
+        mkdirSync(dirname(file), { recursive: true })
+        await Bun.write(file, await bundleFlux(module.path))
+      }
+    }
+    process.exit()
+  }
+
+  // --json: the dev server's rebuild (server/rebuild.ts spawns it in the
+  // project root or the entry's directory with the entry and --project or
+  // --file, so the mode resolves the same). One BundleOutput object on
+  // stdout (types/bundle.d.ts), diagnostics on stderr, exit 1 with an empty
+  // stdout on a build failure. A prebuilt .srt.js is read as-is with its
+  // sibling isolate bundles.
+  if (values.json) {
+    let mode = resolveMode()
+    let result: BundleOutput | null
+    if (mode.entry.endsWith(".srt.js")) {
+      let code = await Bun.file(mode.entry).text()
+      let isolates = readPrebuiltIsolates(mode.entry).map((i) => ({ ...i, map: null }))
+      result = {
+        code,
+        map: null,
+        manifest: buildManifest(code, mode.entry, isolateManifestAssets(isolates), mode.projectDir),
+        isolates,
+        inputs: [mode.entry],
+      }
+    } else {
+      result = await bundleWith({
+        entry: mode.entry,
+        project: mode.projectDir,
+        dev: values.dev,
+        minify: values.minify,
+      })
+    }
+    if (!result) process.exit(1)
+    await writeStdout(JSON.stringify(result))
+    process.exit()
+  }
+
+  // A prebuilt .srt.js (validateArgs admits no other prebuilt form) is
+  // compiled to bytecode: the only step left, so --compile is implied. The
+  // output lands in the bundle's own dir unless --output says otherwise; its
+  // isolate bundles compile along into the output's isolates/ (the ids match,
+  // the extension picks the form).
+  if (isPrebuilt) {
+    let jsFile = resolve(source!)
+    if (!existsSync(jsFile)) {
+      console.error(`Entry not found: ${source}`)
+      process.exit(1)
+    }
+    let outDir = ensureOutDir(dirname(jsFile))
+    await writeBytecode(await Bun.file(jsFile).text(), join(outDir, basename(jsFile).replace(/\.js$/, ".bin")))
+    let isolatesDir = join(outDir, "isolates")
+    clearIsolates(isolatesDir, ".bin")
+    for (let isolate of readPrebuiltIsolates(jsFile)) {
+      await writeIsolateBytecode(isolatesDir, isolate)
+    }
+    process.exit()
+  }
+
+  let mode = resolveMode()
+  let entry = mode.entry
+  let name = basename(entry).replace(/\.[jt]sx?$/, "")
+
+  if (values.stdout) {
+    let result = await bundleSolid(mode)
+    if (result.isolates.length) {
+      console.error("[cli] Warning: this app has isolate modules; --stdout carries only the main bundle")
+    }
+    await writeStdout(result.code)
+    process.exit()
+  }
+
+  let outDir = ensureOutDir()
+  let isolatesDir = join(outDir, "isolates")
+
+  if (values.compile) {
+    let result = await bundleSolid(mode)
+    await writeBytecode(result.code, join(outDir, name + ".srt.bin"))
+    clearIsolates(isolatesDir, ".bin")
+    for (let isolate of result.isolates) {
+      await writeIsolateBytecode(isolatesDir, isolate)
+    }
+    process.exit()
+  }
+
+  let result = await bundleSolid(mode)
+  let jsOutfile = join(outDir, name + ".srt.js")
+  await Bun.write(jsOutfile, result.code)
+  clearIsolates(isolatesDir, ".js")
+  writeIsolates(isolatesDir, result.isolates)
+  console.log(`>> wrote ${result.code.length} bytes to ${jsOutfile}`)
+  process.exit()
+}

package/src/check/docs.md

@@ -0,0 +1,10 @@
+# srt check
+
+{{ usage check }}
+
+The gate worth wiring into CI: it builds and typechecks the app without
+producing build output. With a folder it covers every entry under it
+(`src/index.tsx`, `examples/*`, and in a monorepo every example app,
+package example and package demo), so one call at the repo root answers
+"did I break any example" before pushing. The dev server runs the same check once at
+startup, without gating on it.