@solidrt/cli 0.0.51 → 0.0.53

package/src/init/scaffold/AGENTS.md

@@ -0,0 +1,100 @@
+# SolidRT app - agent notes
+
+This project uses SolidRT: a custom SolidJS renderer that paints through a Rust
+runtime. No DOM, no HTML, no CSS cascade. If you are an AI assistant, read this
+whole file before writing or editing code here - it is short on purpose. The
+depth lives in the topic files listed under "Read before you", one of which you
+should open whenever the work matches its trigger.
+
+## Levels: core, and extensions on top
+
+- @solidrt/core is the low-level foundation: host intrinsics (`<window>`,
+  `<view>`, `<text>`, the detached `d-*` drawing primitives) with flat props
+  that feed the layout and paint engine directly. An app can be written
+  entirely at this level. d-* elements go under anything; laid-out elements
+  only under laid-out parents (a `<view>` inside a `<d-view>` throws), so a
+  component's doc comment says which kind it renders.
+- Extensions build on core. The first-party ones are @solidrt/components
+  (UI components), @solidrt/2d (2D graphics) and @solidrt/3d (3D graphics).
+  None is privileged - an extension is just functions returning core JSX,
+  and an app can use a third-party one or grow its own.
+
+Match the level the code you are editing already uses. package.json shows
+the choice this app made: only the extensions listed there are installed -
+do not add one for a change core covers.
+
+Convention: every @solidrt package describes itself in
+node_modules/@solidrt/<name>/AGENTS.md, carries its prose in docs/, and
+ships working code in examples/. AGENTS.md is the reference for the package;
+open it before using anything from the package, and read the extensions'
+files only when they are installed.
+
+## Read before you
+
+The authoritative references ship inside the installed packages. Open the one
+that matches the work; do not work from memory of what a web framework does.
+
+- write any reactive code (signals, effects, control flow) ->
+  node_modules/solid-js/CHEATSHEET.md - the SolidJS 2.0 model
+- touch elements, props, events, gestures or text ->
+  node_modules/@solidrt/core/AGENTS.md, and
+  node_modules/@solidrt/core/src/types.d.ts + jsx-runtime.d.ts (source of truth)
+- style a screen: a background, a gradient, a shadow, an effect, vector art,
+  a chart -> node_modules/@solidrt/core/agents/painting.md
+- write per-frame code, an animation, or anything writing properties in a
+  loop -> node_modules/@solidrt/core/agents/performance.md
+- use an installed extension (UI components, 2D, 3D) ->
+  node_modules/@solidrt/<name>/AGENTS.md and its examples/
+- debug a running app, or drive it over MCP to verify a change ->
+  node_modules/@solidrt/cli/agents/debugging.md
+- add an asset or font, set the app's identity, or build for distribution ->
+  node_modules/@solidrt/cli/agents/assets.md
+- run, bundle, typecheck or render headlessly ->
+  node_modules/@solidrt/cli/AGENTS.md
+- copy a working pattern -> node_modules/@solidrt/core/examples/ (see its
+  README.md index)
+
+<!-- Claude Code auto-imports these; other tools read the paths above. -->
+@./node_modules/solid-js/CHEATSHEET.md
+@./node_modules/@solidrt/core/AGENTS.md
+<!-- components:begin -->
+@./node_modules/@solidrt/components/AGENTS.md
+<!-- components:end -->
+<!-- 2d:begin -->
+@./node_modules/@solidrt/2d/AGENTS.md
+<!-- 2d:end -->
+<!-- 3d:begin -->
+@./node_modules/@solidrt/3d/AGENTS.md
+<!-- 3d:end -->
+@./node_modules/@solidrt/cli/AGENTS.md
+
+## The three traps that cost the most (this is not React/DOM)
+
+Each package's AGENTS.md carries its own trap list; these three are
+platform-wide and bite in every app:
+
+1. Reading a signal/prop/store at the top level of a component body (not
+   inside JSX, a `createMemo`, or an effect's compute phase) reads it
+   untracked - it silently freezes at the initial value. `createEffect` is
+   two-argument here: `(compute, apply)`; the Solid 1.x single-arg form does
+   not track.
+2. Writing a signal or store from inside an owned scope - a component body,
+   a `createMemo`, an effect's compute phase - throws
+   `REACTIVE_WRITE_IN_OWNED_SCOPE` in dev. Move the write into an event
+   handler, an effect's apply phase, `onSettled`, or an `untrack` block; opt
+   in with `createSignal(v, { ownedWrite: true })` for internal state.
+3. An element-valued prop (children, a content/icon slot) builds a fresh
+   native subtree on EVERY read, and an uninserted subtree is never freed -
+   a permanent memory leak, not wasted work. Read such props exactly once,
+   where they mount; inspect them through the `children()` helper.
+
+## Run / verify
+
+- FIRST check whether a dev server and a client are already running and
+  build against those; do not start a second `srt run` when one is up.
+- The dev loop (reload, logs, snapshots, the holds on reload-on-save and on
+  the user's input), typechecking, headless rendering and the MCP tools:
+  node_modules/@solidrt/cli/AGENTS.md and its agents/debugging.md. Read it
+  before the first reload. The `.mcp.json` here is Claude Code's convention;
+  if your client lists no `solidrt` tools, debugging.md has the entry to add
+  to its own config.

package/src/init/scaffold/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "solidrt-app",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "srt run",
+    "pack": "srt pack -o out",
+    "server": "srt server",
+    "client": "srt client",
+    "android": "srt android"
+  },
+  "dependencies": {
+    "@solidrt/core": "0.0.53",
+    "@solidrt/components": "0.0.53",
+    "@solidrt/2d": "0.0.53",
+    "@solidrt/3d": "0.0.53"
+  },
+  "devDependencies": {
+    "@solidrt/cli": "0.0.53",
+    "@solidrt/flux-types": "0.0.53",
+    "typescript": "^7"
+  }
+}

package/{scaffold → src/init/scaffold}/templates/components/index.tsx

@@ -1,7 +1,6 @@
 // Components template: built with the @solidrt/components framework.
-import { render, createLinearGradient } from "@solidrt/core"
+import { render, createLinearGradient, Logo } from "@solidrt/core"
 import { Window, SafeArea, View, Text } from "@solidrt/components"
-import { Icon } from "./icon"
 
 function App() {
   let backgroundColor = createLinearGradient(0, 0, 1, 1, [
@@ -13,7 +12,7 @@ function App() {
     <Window title="The Solid Runtime" style={{ backgroundColor }}>
       <SafeArea>
         <View layout={{ flex: 1, gap: 20, alignItems: "center", justifyContent: "center" }}>
-          <Icon />
+          <Logo size={300} animation="loop" />
           <Text layout={{ fontSize: 40 }} style={{ color: "#ccc" }}>
             The Solid Runtime
           </Text>

package/{scaffold → src/init/scaffold}/templates/default/index.tsx

@@ -1,5 +1,4 @@
-import { render, createLinearGradient, safeArea } from "@solidrt/core"
-import { Icon } from "./icon"
+import { render, createLinearGradient, safeArea, Logo } from "@solidrt/core"
 
 function App() {
   let backgroundColor = createLinearGradient(0, 0, 1, 1, [
@@ -18,7 +17,7 @@ function App() {
         paddingTop={safeArea().top}
         paddingBottom={safeArea().bottom}
       >
-        <Icon />
+        <Logo size={300} animation="loop" />
         <text fontSize={40} color="#ccc">The Solid Runtime</text>
       </view>
     </window>

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)
+}