@solidrt/cli 0.0.50 → 0.0.52

package/src/lib/args.ts

@@ -0,0 +1,194 @@
+import { existsSync, statSync } from "node:fs"
+import { parseArgs } from "node:util"
+import { resolve } from "node:path"
+import { clientsRoot } from "./dev-dir"
+import { hint } from "./usage"
+
+// Everything after a bare "--" is the app's argument vector, kept out of
+// parseArgs (which would fold it into positionals) and forwarded verbatim to
+// the runner, where it becomes flux:process argv. srt's own flags may follow
+// the source file, so the separator is required.
+let rawArgs = process.argv.slice(2)
+let appArgsSep = rawArgs.indexOf("--")
+export let appArgs = appArgsSep === -1 ? [] : rawArgs.slice(appArgsSep + 1)
+
+// `srt tool <package>/<name> ...`: everything after the tool name belongs to
+// the tool (its own flags, its own usage), so only the command and the tool
+// name go through parseArgs and the rest is forwarded verbatim (tool/main.ts).
+let isTool = rawArgs[0] === "tool"
+export let toolArgs = isTool ? rawArgs.slice(2) : []
+
+// A parse failure (unknown flag, missing value) is a usage error, not a
+// crash: the parser's first sentence names it, the hint says where to look.
+function parse() {
+  try {
+    return parseArgs({
+      args: isTool ? rawArgs.slice(0, 2) : appArgsSep === -1 ? rawArgs : rawArgs.slice(0, appArgsSep),
+      options: OPTIONS,
+      allowPositionals: true,
+    })
+  } catch (e: any) {
+    hint(String(e?.message ?? e).split(". ")[0])
+  }
+}
+
+const OPTIONS = {
+    help: { type: "boolean", default: false },
+    version: { type: "boolean", default: false },
+    dev: { type: "boolean", short: "d", default: false },
+    minify: { type: "boolean", short: "m", default: false },
+    compile: { type: "boolean", default: false },
+    flux: { type: "boolean", short: "f", default: false },
+    file: { type: "boolean", default: false },
+    project: { type: "boolean", default: false },
+    lan: { type: "boolean", default: false },
+    folder: { type: "boolean", default: false },
+    app: { type: "boolean", default: false },
+    stdout: { type: "boolean", default: false },
+    json: { type: "boolean", default: false },
+    output: { type: "string", short: "o" },
+    "proxy-http": { type: "boolean", default: false },
+    fps: { type: "string" },
+    duration: { type: "string" },
+    size: { type: "string" },
+    script: { type: "string" },
+    capture: { type: "string" },
+    tunnel: { type: "boolean", default: false },
+    stats: { type: "boolean", default: false },
+    "data-root": { type: "string" },
+    client: { type: "string", short: "c" },
+    server: { type: "string" },
+    port: { type: "string" },
+    device: { type: "string" },
+    install: { type: "boolean" },
+} as const
+
+export let { values, positionals } = parse()
+
+// An explicit --port: the dev server binds it (run, server), or the caller
+// picks the server on it (client, mcp). Without it the server binds its
+// remembered port or a free one, and callers resolve by project (mode.ts,
+// registry.ts).
+function resolvePort(): number | undefined {
+  let raw = values.port
+  if (raw === undefined) return undefined
+  let port = Number(raw)
+  if (!/^\d+$/.test(raw) || port < 1 || port > 65535) {
+    console.error(`Invalid --port value "${raw}": expected a port number between 1 and 65535`)
+    process.exit(1)
+  }
+  return port
+}
+export let port = resolvePort()
+
+// Storage flags for a locally spawned client. Dev client trees live in
+// ~/.solidrt/clients/client<M>/, reached through --data-root so the client
+// runtime keeps its single pref-path default rule (see lattice/src/storage.rs
+// and okf/backlog/cli-flux-migration.md); an explicit --data-root wins.
+// Storage is per app under a tree, so two projects share client 0 without
+// colliding; only two clients of the same app need distinct slots. Roots are
+// passed absolute because the client chdirs into its app sandbox at startup.
+export function clientStorageArgs(): string[] {
+  let root = values["data-root"]
+  let args = ["--data-root", root ? resolve(root) : clientsRoot()]
+  let client = values.client ?? "0"
+  if (!/^\d+$/.test(client)) {
+    console.error(`Invalid --client value "${client}": expected a non-negative integer`)
+    process.exit(1)
+  }
+  args.push("--client", client)
+  return args
+}
+
+export let command = positionals[0]
+export let source = positionals[1]
+export let isTsx = source?.endsWith(".tsx") || source?.endsWith(".jsx")
+export let isPrebuilt = source?.endsWith(".srt.js") || source?.endsWith(".srt.bin")
+// A .srt.js also ends with .js: prebuilt wins, or the server would re-bundle
+// a prebuilt bundle as source and skip the prebuilt load path.
+export let isTs = (source?.endsWith(".ts") || source?.endsWith(".js")) && !isPrebuilt
+export let isSource = isTsx || isTs
+
+function usage(line: string): never {
+  console.error("Usage: " + line)
+  process.exit(1)
+}
+
+// Per-command argument requirements. Called once before dispatch. The app
+// commands take an optional entry: none means the project at the cwd
+// (mode.ts decides, and reports a missing or wrong entry itself).
+export function validateArgs() {
+  switch (command) {
+    case "bundle":
+      // A prebuilt .srt.js compiles to bytecode (bundle.ts); a .srt.bin
+      // already is bytecode, so there is nothing to do with it.
+      if (values.flux) {
+        if (!source || !isTs) usage("srt bundle --flux [options] <entry.[ts|js]>")
+      } else if (source && !isSource && !source.endsWith(".srt.js")) {
+        usage("srt bundle [options] [entry.[tsx|jsx|ts|js|srt.js]]")
+      }
+      break
+    case "check":
+      // An entry file, or a folder whose entries are discovered (check.ts).
+      if (source && !isSource && !(existsSync(source) && statSync(source).isDirectory())) {
+        usage("srt check [entry.[tsx|jsx|ts|js] | folder]")
+      }
+      break
+    case "demo":
+      // A number from the printed list, or the qualified name beside it.
+      if (source && !/^\d+$/.test(source) && !/^[\w.-]+\/[\w.-]+$/.test(source)) {
+        usage("srt demo [<number> | <package>/<demo>]")
+      }
+      break
+    case "render":
+      if (source && !isTsx) usage("srt render [entry.[tsx|jsx]]")
+      break
+    case "pack":
+      if (values.flux) {
+        if (!source || !isTs) usage("srt pack --flux [options] <entry.[ts|js]>")
+      } else if (source && !isSource) {
+        usage("srt pack [options] [entry.[tsx|jsx|ts|js]]")
+      }
+      break
+  }
+
+  // The commands that start a dev server; `demo` resolves its own project.
+  let serves = command === "run" || command === "server" || command === "demo"
+  // The commands that work on a project or a file (mode.ts).
+  let onApp = command === "run" || command === "server" || command === "bundle" || command === "pack" || command === "render"
+  // --folder and --app pick a pack output shape.
+  if ((values.folder || values.app) && command !== "pack") {
+    usage("srt pack --folder|--app  (--folder and --app are only valid with the pack command)")
+  }
+  if (values.folder && values.app) usage("srt pack --folder|--app  (--folder and --app exclude each other)")
+  // --install is the android command's APK install step.
+  if (values.install && command !== "android") {
+    usage("srt android --install  (--install is only valid with the android command)")
+  }
+  // --device picks the adb device `android` installs on.
+  if (values.device && command !== "android") {
+    usage("srt android --device <serial>  (--device is only valid with the android command)")
+  }
+  // --server points a standalone client at a dev server; `run` and `server`
+  // own their server side, so it is valid nowhere else.
+  if (values.server && command !== "client") {
+    usage("srt client --server <host:port>  (--server is only valid with the client command)")
+  }
+  // --json is the dev server's rebuild contract (bundle.ts).
+  if (values.json && command !== "bundle") {
+    usage("srt bundle --json  (--json is only valid with the bundle command)")
+  }
+  // --port binds the dev server (`run`, `server`) or picks one (`client`,
+  // `android`, `mcp`).
+  if (port !== undefined && !serves && command !== "client" && command !== "android" && command !== "mcp") {
+    usage("srt <run|server|demo|client|android|mcp> --port <N>  (--port is only valid with the run, server, demo, client, android and mcp commands)")
+  }
+  // --file/--project resolve a file argument in a project directory.
+  if ((values.file || values.project) && !onApp) {
+    usage("srt <run|server|bundle|pack|render> <file> [--file|--project]  (only valid with the run, server, bundle, pack and render commands)")
+  }
+  // --lan binds every interface of a server being started.
+  if (values.lan && !serves) {
+    usage("srt <run|server|demo> --lan  (--lan is only valid with the run, server and demo commands)")
+  }
+}

package/src/{artifacts.ts → lib/artifacts.ts}

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module"
 import { existsSync } from "node:fs"
-import { resolve, dirname } from "node:path"
+import { resolve, dirname, join } from "node:path"
 import process from "node:process"
 
 let require = createRequire(import.meta.url)
@@ -46,6 +46,32 @@ export function resolveBinary(name: string) {
   return null
 }
 
+// The GL libraries the runner needs next to it (or, single-file, embedded as
+// kind-3 trailer sections it extracts at boot): ANGLE's libraries on Windows
+// and macOS, nothing on platforms with a system GL. Order matters and the
+// runner preloads in section order: libGLESv2 must load before libEGL so
+// libEGL's import of it resolves against the already-loaded module instead
+// of a directory search.
+const GL_LIB_NAMES: Partial<Record<NodeJS.Platform, string[]>> = {
+  win32: ["libGLESv2.dll", "libEGL.dll"],
+  darwin: ["libGLESv2.dylib", "libEGL.dylib"],
+}
+
+// The GL libraries shipped next to the runner binary, resolved to their paths.
+// Missing files are fatal: a pack without them cannot create a window.
+export function runnerGlLibs(runnerPath: string): Array<{ name: string; path: string }> {
+  let names = GL_LIB_NAMES[process.platform] ?? []
+  let dir = dirname(runnerPath)
+  return names.map((name) => {
+    let path = join(dir, name)
+    if (!existsSync(path)) {
+      console.error(`Could not find ${name} next to the runner (${dir}); the packed app needs it to create a GL context.`)
+      process.exit(1)
+    }
+    return { name, path }
+  })
+}
+
 // The Android client APK is host-independent (it bundles native .so for the
 // device, not the host), so it lives under dist/android/<abi>/ rather than the
 // host triple map. arm64-v8a (a fat APK: arm64-v8a + the x86_64 emulator) and
@@ -57,6 +83,20 @@ export let ANDROID_PKG_MAP: Record<string, string> = {
   "armeabi-v7a": "@solidrt/android-armeabi-v7a",
 }
 
+// The client version the project expects on an `abi` device: the version of
+// its @solidrt/android-<abi> dev dependency (the release action pins it to the
+// runtime version). Null when the package is not installed.
+export function androidPackageVersion(abi: string): string | null {
+  let pkg = ANDROID_PKG_MAP[abi]
+  if (!pkg) return null
+  try {
+    let version = require(`${pkg}/package.json`).version
+    return typeof version === "string" ? version : null
+  } catch {
+    return null
+  }
+}
+
 export function resolveApk(abi: string = DEFAULT_ANDROID_ABI) {
   // 1. SRT_HOME: contributor checkout, where `make dist-android` stages the APK
   //    under dist/android/<abi>/.

package/src/{dev-dir.ts → lib/dev-dir.ts}

@@ -6,20 +6,22 @@ import { join } from "node:path"
 const DEV_DIR_NAME = ".solidrt"
 
 // All dev-tooling state lives in one home dotdir, one rule on every platform
-// (okf/backlog/parallel-dev-servers.md): servers/<port>/ holds a dev server's
-// identity (tunnel.key) and its registry record (live.json), clients/ is the
-// data root srt passes for every locally spawned client, so dev client trees
-// land in clients/client<M>/. Deleting the dir resets every bit of dev state.
+// (okf/backlog/cli-flux-migration.md): servers/<key hash>/ holds a dev
+// server's registry record (live.json, written by the server itself, which
+// also names the folder: server/registry.ts), its remembered port and its
+// tunnel key; clients/ is the data root for every locally spawned client,
+// so dev client trees land in clients/client<M>/. Deleting the dir resets
+// every bit of dev state.
 export function devDir(...parts: string[]): string {
   return join(homedir(), DEV_DIR_NAME, ...parts)
 }
 
-/** `servers/<port>/` under the dev dir - a dev server's identity and registry record, keyed by port. */
-export function serverDir(port: number): string {
-  return devDir("servers", String(port))
+/** `servers/` under the dev dir: one folder per server key. */
+export function serversRoot(): string {
+  return devDir("servers")
 }
 
 /** `clients/` under the dev dir - the --data-root for locally spawned dev clients. */
 export function clientsRoot(): string {
   return devDir("clients")
-}
+}

package/src/{fonts.ts → lib/fonts.ts}

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync } from "node:fs"
+import { existsSync } from "node:fs"
 import { resolve } from "node:path"
-import { findProjectPackage } from "./project"
+import { loadProject } from "./project"
+import { fail } from "./util"
 
 // The fonts `srt pack` appends to a solidrt binary (see
 // okf/plans/packaged-fonts.md). By default the three Noto role defaults;
@@ -30,46 +31,31 @@ let DEFAULT_FONTS: Record<string, string> = {
 function defaultFontsDir(): string | null {
   let candidates: string[] = []
   if (process.env.SRT_HOME) candidates.push(resolve(process.env.SRT_HOME, "alloy/assets/fonts"))
-  candidates.push(resolve(import.meta.dir, "../fonts"))
-  candidates.push(resolve(import.meta.dir, "../../../alloy/assets/fonts"))
+  candidates.push(resolve(import.meta.dir, "../../fonts"))
+  candidates.push(resolve(import.meta.dir, "../../../../alloy/assets/fonts"))
   for (let dir of candidates) {
     if (existsSync(resolve(dir, "NotoSans.ttf"))) return dir
   }
   return null
 }
 
-function findProjectConfig(sourcePath: string): { dir: string; fonts: unknown } | null {
-  let project = findProjectPackage(sourcePath)
-  return project && { dir: project.dir, fonts: project.pkg.solidrt?.fonts }
-}
-
-function fail(message: string): never {
-  console.error(message)
-  process.exit(1)
-}
-
 // Resolve the font set for a pack as file paths: role defaults merged with the
-// project's `solidrt.fonts` map. Order is roles first (sans, serif, mono),
+// project's `solidrt.fonts` map (shape-checked by loadProject; file mode has
+// no project, so defaults only). Order is roles first (sans, serif, mono),
 // then added aliases in config order.
-export function resolvePackFonts(sourcePath: string): ResolvedFont[] {
-  let config = findProjectConfig(sourcePath)
-  let overrides = config?.fonts ?? {}
-  if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) {
-    fail('The "solidrt.fonts" key in package.json must be a map of alias to font file path (or false)')
-  }
+export function resolvePackFonts(projectDir: string | null): ResolvedFont[] {
+  let project = loadProject(projectDir)
+  let overrides = project?.config.fonts ?? {}
 
-  // alias -> path relative to the config dir, or null for a role default.
+  // alias -> path relative to the project dir, or null for a role default.
   let selected = new Map<string, string | null>()
   for (let role of Object.keys(DEFAULT_FONTS)) selected.set(role, null)
   for (let [alias, value] of Object.entries(overrides)) {
     if (value === false) {
       if (!(alias in DEFAULT_FONTS)) fail(`"solidrt.fonts": "${alias}": false drops a default, but "${alias}" is not one of ${Object.keys(DEFAULT_FONTS).join("/")}`)
       selected.delete(alias)
-    } else if (typeof value === "string") {
-      if (Buffer.byteLength(alias, "utf8") > 255) fail(`"solidrt.fonts": alias "${alias}" is too long (max 255 bytes)`)
-      selected.set(alias, resolve(config!.dir, value))
     } else {
-      fail(`"solidrt.fonts": "${alias}" must be a font file path or false, got ${JSON.stringify(value)}`)
+      selected.set(alias, resolve(project!.dir, value))
     }
   }
 

package/src/lib/mode.ts

@@ -0,0 +1,77 @@
+// What a command works on (run, server, bundle, pack, render), decided by
+// the cwd and the argument and never by searching upward
+// (okf/backlog/cli-flux-migration.md):
+//
+//   cwd has package.json   argument   mode
+//   yes                    none       project (entry = solidrt.entry, default src/index.tsx)
+//   no                     none       error
+//   no                     file       file
+//   yes                    file       error, unless --project (project at cwd,
+//                                     entry overridden) or --file (ignore the project)
+//
+// Project mode hangs assets, fonts, identity, isolates and build outputs off
+// the project root; file mode has none of those, the file stands alone. The
+// key (the canonical project root, or the canonical file path) is what the
+// dev server registry and every control response name.
+
+import { existsSync, realpathSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { values, source, isSource, isPrebuilt } from "./args"
+import { loadProject } from "./project"
+import { fail } from "./util"
+
+export type Mode =
+  | { mode: "project"; key: string; projectDir: string; entry: string }
+  | { mode: "file"; key: string; projectDir: null; entry: string }
+
+const DEFAULT_ENTRY = "src/index.tsx"
+
+function canonical(path: string): string {
+  try {
+    return realpathSync.native(path)
+  } catch {
+    return resolve(path)
+  }
+}
+
+export function resolveMode(): Mode {
+  let cwd = process.cwd()
+  let pkgPath = resolve(cwd, "package.json")
+  let hasPkg = existsSync(pkgPath)
+
+  if (source !== undefined && !isSource && !(isPrebuilt && source.endsWith(".srt.js"))) {
+    fail(`Not an app entry: ${source} (expected .tsx, .jsx, .ts, .js or .srt.js)`)
+  }
+  if (source !== undefined && !existsSync(source)) fail(`Entry not found: ${source}`)
+  if (values.file && values.project) fail("--file and --project exclude each other")
+
+  if (source === undefined) {
+    if (values.file || values.project) fail("--file and --project need an entry file")
+    if (!hasPkg) fail(`No package.json in ${cwd}. Run from the project root, or pass a file to use on its own.`)
+    let declared = loadProject(cwd)!.config.entry
+    let entry = resolve(cwd, declared ?? DEFAULT_ENTRY)
+    if (!existsSync(entry)) {
+      fail(`Entry not found: ${entry}${declared ? "" : ' (set "solidrt": { "entry": ... } in package.json)'}`)
+    }
+    let key = canonical(cwd)
+    return { mode: "project", key, projectDir: key, entry }
+  }
+
+  let entry = canonical(source)
+  if (hasPkg && !values.file && !values.project) {
+    fail(
+      `${cwd} is a project (it has a package.json) and ${source} is a file: pass --project to use the project with this entry, or --file to use the file on its own.`,
+    )
+  }
+  if (hasPkg && values.project) {
+    let key = canonical(cwd)
+    return { mode: "project", key, projectDir: key, entry }
+  }
+  if (!hasPkg && values.project) fail(`--project needs a package.json in ${cwd}`)
+  return { mode: "file", key: entry, projectDir: null, entry }
+}
+
+/** The directory the file routes serve: the entry's directory. */
+export function sourceDirOf(mode: Mode): string {
+  return dirname(mode.entry)
+}