lecodes-cli 0.20.1 → 1.0.0

package/src/compile/screenEntry.ts

@@ -1,127 +1,123 @@
-import { existsSync, readFileSync, statSync } from "node:fs"
-import { isAbsolute, join, relative, resolve } from "node:path"
-import { screenFrame } from "../designMeta"
-import { CliError, flagStr, toKey, type Args } from "../util"
-import type { CompileEntry } from "./projectCompile"
-
-/*
- * Rendering ONE screen module instead of the whole app — `lecodes render <file>` (and
- * `--desktop`). A design screen (`design/screens/login.ts`) never boots itself: it default-exports
- * a `UIScreen`, or a `(state) => UIScreen` function for its states, and the design board / snapshot
- * supply the `.open()`. This builds the same virtual entry for the normal project pipeline, so any
- * file written that way — inside design/ or not — renders with the full `lecodes render` flag set
- * (--png/--clip/--script/--device/…) against the project's real imports and assets.
- *
- * Kept in step with compile/designCompile.ts, which does the same wrapping per screen for the board.
- */
-
-/** Extensions a screen module may carry (so `render design/screens/login` works too). */
-const SCREEN_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs"]
-
-/** Where the generated entry lives — the project root, so its import specifier is the screen's
- *  own project key ("./design/screens/login"). Leading dot: never a real project file. */
-const SCREEN_ENTRY_PATH = "/.screen-entry.ts"
-
-/** The design folder a bare screen id (`lecodes render login`) is looked up in. */
-const DEFAULT_DESIGN_DIR = "design"
-
-export type ScreenTarget = {
-  /** The virtual entry module — hand it to the compiler alongside the project's own entries. */
-  entry: CompileEntry
-  /** Path of that entry, for `entryOverride`. */
-  entryPath: string
-  /** The board frame from the design folder's meta.json, when this IS a design screen. */
-  frame?: [number, number]
-  /** How the screen is named in progress notes ("design/screens/login.ts", "login@empty"). */
-  label: string
-}
-
-/** `lecodes render <file|screen-id>` — the positional a screen render is asked for by. */
-const screenArg = (args: Args): string | undefined => args._[0]
-
-/** Whether the argument names a path at all (vs a bare screen id). */
-const hasSeparator = (file: string) => file.includes("/") || file.includes("\\")
-
-/** Find the screen file: a path (with or without extension), or a bare id resolved against the
- *  design folder's screens/ (`lecodes render login`, honoring --dir). */
-const findScreenFile = (root: string, file: string, dirFlag: string | undefined): string => {
-  const candidates = [resolve(process.cwd(), file)]
-  if (!hasSeparator(file)) {
-    candidates.push(join(root, (dirFlag ?? DEFAULT_DESIGN_DIR).replace(/[/\\]+$/, ""), "screens", file))
-  }
-  for (const base of candidates) {
-    if (existsSync(base) && statSync(base).isFile()) return base
-    for (const ext of SCREEN_EXTS) if (existsSync(base + ext)) return base + ext
-  }
-  throw new CliError(
-    `No screen file at "${file}".` +
-    (hasSeparator(file) ? "" : ` Pass a path, or a screen id that exists in ${dirFlag ?? DEFAULT_DESIGN_DIR}/screens/.`))
-}
-
-/** The design folder a screen file belongs to ("<root>/design" for "/design/screens/login.ts"),
- *  or null when it isn't laid out as a design screen. */
-const designDirOf = (root: string, key: string): { dir: string, id: string } | null => {
-  const m = /^\/(.*)screens\/([^/]+)\.[^./]+$/.exec(key)
-  if (!m) return null
-  const dir = join(root, m[1])
-  return existsSync(join(dir, "meta.json")) ? { dir, id: m[2] } : null
-}
-
-/**
- * Resolve `<file>` into the virtual entry that opens its default export.
- * `state` picks the branch of a `(state) => UIScreen` screen (ignored by a value export).
- */
-const resolveScreenTarget = (
-  root: string, file: string, opts: { state?: string, dir?: string } = {},
-): ScreenTarget => {
-  const abs = findScreenFile(root, file, opts.dir)
-  const rel = relative(root, abs)
-  if (rel.startsWith("..") || isAbsolute(rel)) {
-    throw new CliError(
-      `"${file}" is outside the project (${root}) — a screen renders as part of its project, so its ` +
-      `imports and asset() files resolve from the same tree.`)
-  }
-  const key = toKey(rel)
-
-  // A file with no default export compiles to an empty render; say so here instead.
-  if (!/^\s*export\s+default\b/m.test(readFileSync(abs, "utf8"))) {
-    throw new CliError(
-      `${key.slice(1)} has no default export. A screen file ends with ` +
-      `\`export default UIScreen([...])\` — or \`export default (state) => UIScreen([...])\` for screen states.`)
-  }
-
-  // Same wrapper the design board compiles (designCompile.ts): a function export is invoked with the
-  // chosen state (a bare call uses the parameter's default = the canonical state), a value is used
-  // as-is, and either way the screen is opened so the runtime has something to render.
-  const invoke = opts.state !== undefined ? `screen(${JSON.stringify(opts.state)})` : "screen()"
-  const spec = "." + key.replace(/\.[^./]+$/, "")
-  const design = designDirOf(root, key)
-  return {
-    entryPath: SCREEN_ENTRY_PATH,
-    entry: {
-      path: SCREEN_ENTRY_PATH,
-      type: "text",
-      text: `import screen from ${JSON.stringify(spec)}\n`
-        + `const __screen = typeof screen === "function" ? ${invoke} : screen\n`
-        + `__screen.open()\n`,
-    },
-    frame: design ? screenFrame(design.dir, design.id) : undefined,
-    label: (design ? design.id : key.slice(1)) + (opts.state !== undefined ? `@${opts.state}` : ""),
-  }
-}
-
-/** Read the screen target off the CLI args, or undefined when no screen was named. Rejects the
- *  flag combinations that would fight over the entrypoint. */
-export const screenTargetFromArgs = (root: string, args: Args): ScreenTarget | undefined => {
-  const file = screenArg(args)
-  if (file === undefined) {
-    if (flagStr(args, "state") !== undefined) {
-      throw new CliError("--state picks a screen's state — name the screen file too: lecodes render <file> --state <name>")
-    }
-    return undefined
-  }
-  if (flagStr(args, "entry") !== undefined) {
-    throw new CliError("Use either a screen file or --entry, not both — each names the module to compile from.")
-  }
-  return resolveScreenTarget(root, file, { state: flagStr(args, "state"), dir: flagStr(args, "dir") })
-}
+import { existsSync, readFileSync, statSync } from "node:fs"
+import { isAbsolute, join, relative, resolve } from "node:path"
+import { screenFrame } from "../project/designMeta"
+import { CliError } from "../cli"
+import { toKey } from "../project/paths"
+import type { CompileEntry } from "./projectCompile"
+
+/*
+ * Rendering ONE screen module instead of the whole app — `lecodes render <file>` (and
+ * `--desktop`). A design screen (`design/screens/login.ts`) never boots itself: it default-exports
+ * a `UIScreen`, or a `(state) => UIScreen` function for its states, and the design board / snapshot
+ * supply the `.open()`. This builds the same virtual entry for the normal project pipeline, so any
+ * file written that way — inside design/ or not — renders with the full `lecodes render` flag set
+ * (--png/--clip/--script/--device/…) against the project's real imports and assets.
+ *
+ * Kept in step with compile/designCompile.ts, which does the same wrapping per screen for the board.
+ */
+
+/** Extensions a screen module may carry (so `render design/screens/login` works too). */
+const SCREEN_EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs"]
+
+/** Where the generated entry lives — the project root, so its import specifier is the screen's
+ *  own project key ("./design/screens/login"). Leading dot: never a real project file. */
+const SCREEN_ENTRY_PATH = "/.screen-entry.ts"
+
+/** The design folder a bare screen id (`lecodes render login`) is looked up in. */
+const DEFAULT_DESIGN_DIR = "design"
+
+export type ScreenTarget = {
+  /** The virtual entry module — hand it to the compiler alongside the project's own entries. */
+  entry: CompileEntry
+  /** Path of that entry, for `entryOverride`. */
+  entryPath: string
+  /** The board frame from the design folder's meta.json, when this IS a design screen. */
+  frame?: [number, number]
+  /** How the screen is named in progress notes ("design/screens/login.ts", "login@empty"). */
+  label: string
+}
+
+/** `lecodes render <file|screen-id>` — the positional a screen render is asked for by. */
+
+/** Whether the argument names a path at all (vs a bare screen id). */
+const hasSeparator = (file: string) => file.includes("/") || file.includes("\\")
+
+/** Find the screen file: a path (with or without extension), or a bare id resolved against the
+ *  design folder's screens/ (`lecodes render login`, honoring --dir). */
+const findScreenFile = (root: string, file: string, dirFlag: string | undefined): string => {
+  const candidates = [resolve(process.cwd(), file)]
+  if (!hasSeparator(file)) {
+    candidates.push(join(root, (dirFlag ?? DEFAULT_DESIGN_DIR).replace(/[/\\]+$/, ""), "screens", file))
+  }
+  for (const base of candidates) {
+    if (existsSync(base) && statSync(base).isFile()) return base
+    for (const ext of SCREEN_EXTS) if (existsSync(base + ext)) return base + ext
+  }
+  throw new CliError(
+    `No screen file at "${file}".` +
+    (hasSeparator(file) ? "" : ` Pass a path, or a screen id that exists in ${dirFlag ?? DEFAULT_DESIGN_DIR}/screens/.`))
+}
+
+/** The design folder a screen file belongs to ("<root>/design" for "/design/screens/login.ts"),
+ *  or null when it isn't laid out as a design screen. */
+const designDirOf = (root: string, key: string): { dir: string, id: string } | null => {
+  const m = /^\/(.*)screens\/([^/]+)\.[^./]+$/.exec(key)
+  if (!m) return null
+  const dir = join(root, m[1])
+  return existsSync(join(dir, "meta.json")) ? { dir, id: m[2] } : null
+}
+
+/**
+ * Resolve `<file>` into the virtual entry that opens its default export.
+ * `state` picks the branch of a `(state) => UIScreen` screen (ignored by a value export).
+ */
+const resolveScreenTarget = (
+  root: string, file: string, opts: { state?: string, dir?: string } = {},
+): ScreenTarget => {
+  const abs = findScreenFile(root, file, opts.dir)
+  const rel = relative(root, abs)
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new CliError(
+      `"${file}" is outside the project (${root}) — a screen renders as part of its project, so its ` +
+      `imports and asset() files resolve from the same tree.`)
+  }
+  const key = toKey(rel)
+
+  // A file with no default export compiles to an empty render; say so here instead.
+  if (!/^\s*export\s+default\b/m.test(readFileSync(abs, "utf8"))) {
+    throw new CliError(
+      `${key.slice(1)} has no default export. A screen file ends with ` +
+      `\`export default UIScreen([...])\` — or \`export default (state) => UIScreen([...])\` for screen states.`)
+  }
+
+  // Same wrapper the design board compiles (designCompile.ts): a function export is invoked with the
+  // chosen state (a bare call uses the parameter's default = the canonical state), a value is used
+  // as-is, and either way the screen is opened so the runtime has something to render.
+  const invoke = opts.state !== undefined ? `screen(${JSON.stringify(opts.state)})` : "screen()"
+  const spec = "." + key.replace(/\.[^./]+$/, "")
+  const design = designDirOf(root, key)
+  return {
+    entryPath: SCREEN_ENTRY_PATH,
+    entry: {
+      path: SCREEN_ENTRY_PATH,
+      type: "text",
+      text: `import screen from ${JSON.stringify(spec)}\n`
+        + `const __screen = typeof screen === "function" ? ${invoke} : screen\n`
+        + `__screen.open()\n`,
+    },
+    frame: design ? screenFrame(design.dir, design.id) : undefined,
+    label: (design ? design.id : key.slice(1)) + (opts.state !== undefined ? `@${opts.state}` : ""),
+  }
+}
+
+/** The screen target named on the command line (`render <file>`), or undefined when no screen was
+ *  named. Rejects the flag combinations that would fight over the entrypoint. */
+export type ScreenArgs = { file?: string, state?: string, entry?: string, dir?: string }
+export const screenTargetFrom = (root: string, a: ScreenArgs): ScreenTarget | undefined => {
+  if (a.file === undefined) {
+    if (a.state !== undefined) throw new CliError("--state picks a screen's state — name the screen file too: lecodes render <file> --state <name>")
+    return undefined
+  }
+  if (a.entry !== undefined) throw new CliError("Use either a screen file or --entry, not both — each names the module to compile from.")
+  return resolveScreenTarget(root, a.file, { state: a.state, dir: a.dir })
+}

package/src/compile/shaders.ts

@@ -8,9 +8,9 @@ import {
   matcArgs, MATC_PLATFORMS, TARGET_MATRIX_GENERATION,
   type AnyMatcPlatform, type AnyShaderPlatform,
 } from "lecodes-sdk/compile"
-import { resolveMatcExe, resolveMatcExeCached } from "../matcTool"
-import { LECODES_DIR } from "../manifest"
-import { CliError } from "../util"
+import { resolveMatcExe, resolveMatcExeCached } from "../hosts/matcTool"
+import { LECODES_DIR } from "../project/manifest"
+import { CliError } from "../cli"
 import type { CompileEntry } from "./projectCompile"
 
 /*

package/src/dev/androidDev.ts

@@ -1,7 +1,7 @@
 import { existsSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 import { spawnSync } from "node:child_process"
-import { CliError, note, warnErr } from "../util"
+import { CliError, note, warnErr } from "../cli"
 
 /*
  * `lecodes dev --android` — open the dev URL in the LeCodes app on the connected phone, through adb.

package/src/dev/devServer.ts

@@ -1,8 +1,8 @@
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
 import { createReadStream, statSync } from "node:fs"
 import { join } from "node:path"
-import type { Manifest } from "../manifest"
-import { resolveLocalPath } from "../localFiles"
+import type { Manifest } from "../project/manifest"
+import { resolveLocalPath } from "../project/localFiles"
 import { collectLocalEntries } from "../compile/collectLocal"
 import { applyLocalShaders, isShaderArtifactName, shadersCacheDir } from "../compile/shaders"
 import { ambiguousEntryWarning, compileProject } from "../compile/projectCompile"
@@ -10,7 +10,7 @@ import { applyProjectFonts } from "../compile/fonts"
 import { applyAppAssetIcons } from "../compile/assetIcons"
 import { renderDevScreen, renderPrelude } from "./clientTemplates"
 import { upgradeWebSocket, type WsConnection } from "./wsServer"
-import { toKey } from "../util"
+import { toKey } from "../project/paths"
 import { makeStackDemangler } from "../compile/nativeStack"
 
 /*

package/src/dev/webRunner.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs"
 import { createRequire } from "node:module"
 import { dirname, join } from "node:path"
-import { distRoot } from "../distRoot"
+import { distRoot } from "../hosts/distRoot"
 
 /**
  * Where the browser runner for `lecodes dev --web` lives: viewer-lite's built `dist-embed`

package/src/{cmgenTool.ts → hosts/cmgenTool.ts}

@@ -2,7 +2,7 @@ import { existsSync, readdirSync } from "node:fs"
 import { homedir } from "node:os"
 import { join, resolve } from "node:path"
 import { downloadReleaseArchive, fetchReleaseProduct, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
-import { CliError, note } from "./util"
+import { CliError, note } from "../cli"
 
 /*
  * Filament's cmgen (environment tool) — the tool behind `lecodes assets sky`, which turns an

package/src/{desktopRenderer.ts → hosts/desktopRenderer.ts}

@@ -3,8 +3,8 @@ import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFile
 import { homedir, tmpdir } from "node:os"
 import { delimiter, join, resolve } from "node:path"
 import { cachedArtifactSha, downloadReleaseArchive, fetchReleaseProduct, semverNewer, type ManifestVersion } from "./releases"
-import { CliError, note, warnErr } from "./util"
-import { makeStackDemangler } from "./compile/nativeStack"
+import { CliError, note, warnErr } from "../cli"
+import { makeStackDemangler } from "../compile/nativeStack"
 
 /*
  * The NATIVE renderer behind `lecodes render --desktop`: the LeCodes Desktop host (tgfx UI + Filament
@@ -38,9 +38,10 @@ export const DESKTOP_RENDERER_VERSION = "1.1.0"
 export { semverNewer }
 
 /** Which desktop host to run. "gl" is the default everywhere; "vulkan" is a separate Windows binary
- *  (Filament + tgfx on one VkDevice), NOT a runtime switch — it has its own artifact, its own
- *  shaders, and a smaller feature set (no 2D engine, no native-view plugins). Chosen per project via
- *  app.json `desktop.renderer`, or per run via `--renderer` / LECODES_DESKTOP_RENDERER. */
+ *  (Filament + tgfx + creator-2d on one VkDevice), NOT a runtime switch — it has its own artifact, its
+ *  own shaders, and a smaller feature set (no native-view plugins; the 2D engine joined it 2026-09-08,
+ *  i.e. desktop releases after 1.4.1). Chosen per project via app.json `desktop.renderer`, or per run via `--renderer` /
+ *  LECODES_DESKTOP_RENDERER. */
 export type DesktopRenderer = "gl" | "vulkan"
 
 export const DESKTOP_RENDERER_MIN_VERSION: Record<DesktopRenderer, string> = { gl: "0.0.0", vulkan: "1.4.0" }

package/src/{desktopScript.ts → hosts/desktopScript.ts}

@@ -1,5 +1,5 @@
 import { resolve } from "node:path"
-import { CliError } from "./util"
+import { CliError } from "../cli"
 
 /*
  * `lecodes render --desktop --script`: the same JSON scenario a headless run takes, driven through

package/src/{distRoot.ts → hosts/distRoot.ts}

@@ -5,16 +5,20 @@ import { fileURLToPath } from "node:url"
 /* Root of the CLI's on-disk companion files (runtime/ with the vendored SDK source + type bundle).
  *
  * Two distribution shapes:
- *  - npm package / monorepo dev: this module lives in dist/ (or src/), companions at ../runtime —
- *    resolve relative to import.meta.url as before.
+ *  - npm package: the bundle is dist/index.js, companions at ../runtime.
+ *  - monorepo dev: this module runs from src/hosts/, so the package root is two levels up. The
+ *    package.json marker matters here — runtime/ is gitignored and absent until vendor-runtime runs,
+ *    and callers also resolve siblings from the root (../projects, ../creator-gl).
  *  - standalone binary (`bun build --compile`, see scripts/build-bin.ts): import.meta.url points into
  *    the virtual bunfs archive which does NOT exist on disk, so the companions ship in the release
  *    archive NEXT TO the executable and are resolved via process.execPath. */
 export const distRoot = (() => {
+  const here = dirname(fileURLToPath(import.meta.url))
   const candidates = [
-    join(dirname(fileURLToPath(import.meta.url)), ".."), // package root (dist/.. or src/..)
-    dirname(process.execPath),                           // standalone binary: next to the exe
+    join(here, ".."),           // npm package: dist/..
+    join(here, "..", ".."),     // monorepo dev: src/hosts/../..
+    dirname(process.execPath),  // standalone binary: next to the exe
   ]
-  for (const c of candidates) if (existsSync(join(c, "runtime"))) return c
+  for (const c of candidates) if (existsSync(join(c, "runtime")) || existsSync(join(c, "package.json"))) return c
   return candidates[0]
 })()

package/src/{matcTool.ts → hosts/matcTool.ts}

@@ -2,7 +2,7 @@ import { existsSync, readdirSync } from "node:fs"
 import { homedir } from "node:os"
 import { join, resolve } from "node:path"
 import { downloadReleaseArchive, fetchReleaseProduct, newestForPlatform, semverNewer, type ManifestFile, type ManifestVersion } from "./releases"
-import { CliError, note } from "./util"
+import { CliError, note } from "../cli"
 
 /*
  * Filament's matc (material compiler) — the tool behind LOCAL shader compile: `lecodes dev`

package/src/{peerInstall.ts → hosts/peerInstall.ts}

@@ -2,9 +2,9 @@ import { spawnSync } from "node:child_process"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 import { pathToFileURL } from "node:url"
-import pkg from "../package.json"
+import pkg from "../../package.json"
 import { peerDirInPrefix, peersDir, peerVersionGlobal } from "./peers"
-import { CliError, c, confirm, log, note } from "./util"
+import { CliError, c, confirm, log, note } from "../cli"
 
 /*
  * Peers install themselves on first use. `lecodes render` on a machine with only the CLI asks once,

package/src/{releases.ts → hosts/releases.ts}

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto"
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 import { spawnSync } from "node:child_process"
-import { CliError } from "./util"
+import { CliError } from "../cli"
 
 /*
  * The S3 release channel the CLI downloads native tools from: the manifest scripts/release/*