lecodes-cli 0.20.2 → 1.0.0

package/src/commands/{types.ts → update/types.ts}

@@ -1,54 +1,63 @@
 import { resolve } from "node:path"
-import { getTypes } from "../api"
-import { DEFAULT_API, loadConfig, normalizeApiUrl } from "../config"
-import { findProjectRoot, LECODES_DIR } from "../manifest"
+import { getTypes } from "../../platform/api"
+import { DEFAULT_API, loadConfig, normalizeApiUrl } from "../../platform/config"
+import { findProjectRoot, LECODES_DIR } from "../../project/manifest"
 import {
   bundleHash, readLocalTypeBundle, readProjectTypeBundle, writeTsconfig, writeTypeBundle,
   type TypeBundle,
-} from "../types"
-import { CliError, c, flagBool, flagStr, log, note, success, warn, type Args } from "../util"
+} from "../../project/types"
+import { CliError, c, log, note, success, warn } from "../../cli"
 
 /*
- * The types step of `lecodes update` (formerly `lecodes types [dir]`) — re-materialize the IDE type surface (<root>/.lecodes/types/ + tsconfig).
+ * The types step of `lecodes update` (formerly `lecodes types [dir]`) — re-materialize the IDE type
+ * surface (<root>/.lecodes/types/ + tsconfig).
  *
  * Every project gets these types once, at scaffold time: `clone`/`create`/`pull` fetch them from
  * GET /api/types (the deployed runtime's surface), while `init` and `design` — which run with no
  * server and no login — write the bundle vendored into the CLI at publish time. Neither source
- * refreshes on its own, so a local project's types age with the CLI binary that made it. This
- * command is the refresh: server by default (newest SDK the platform actually runs), `--local` for
- * the CLI's own copy, `--check` to only report drift (non-zero exit when stale).
+ * refreshes on its own, so a local project's types age with the CLI binary that made it. This step
+ * is the refresh: server by default (newest SDK the platform actually runs), `local` for the CLI's
+ * own copy, `check` to only report drift (a CliError when stale).
  *
  * IDE-only: the compiler reads the SDK sources vendored in runtime/sdk, never .lecodes/types. When
- * the two sources disagree the command says so — types promising APIs this CLI can't compile is
+ * the two sources disagree the step says so — types promising APIs this CLI can't compile is
  * exactly the confusing case worth naming out loud.
  */
 
+export type RefreshTypesOptions = {
+  /** The project folder (default: the project root above the cwd, else the cwd). */
+  dir?: string
+  /** The bundle vendored in this CLI instead of the server's. */
+  local: boolean
+  /** Only report drift — write nothing, throw when stale. */
+  check: boolean
+  /** API origin for the server bundle (default: the configured one). */
+  api?: string
+}
+
 const label = (bundle: TypeBundle) => `${Object.keys(bundle).length} file(s)`
 
-export const types = async (args: Args) => {
-  const dirArg = args._[0]
-  const root = dirArg ? resolve(dirArg) : (() => {
+export const refreshTypes = async (opts: RefreshTypesOptions): Promise<void> => {
+  const root = opts.dir ? resolve(opts.dir) : (() => {
     try { return findProjectRoot(process.cwd()) } catch { return process.cwd() }
   })()
 
-  const useLocal = flagBool(args, "local")
-  const checkOnly = flagBool(args, "check")
   const local = readLocalTypeBundle()
 
   // ---- pick the source ----
   let bundle: TypeBundle | null = null
   let source = ""
-  if (useLocal) {
+  if (opts.local) {
     if (!local) throw new CliError("This CLI ships no vendored type bundle — drop --local to fetch them from the server.")
     bundle = local
     source = "the CLI's bundled SDK"
   } else {
-    const apiUrl = normalizeApiUrl(flagStr(args, "api") ?? loadConfig().apiUrl ?? DEFAULT_API)
+    const apiUrl = normalizeApiUrl(opts.api ?? loadConfig().apiUrl ?? DEFAULT_API)
     try {
       bundle = await getTypes(apiUrl)
       source = apiUrl
     } catch (e) {
-      if (!local || checkOnly) throw e
+      if (!local || opts.check) throw e
       warn(`${(e as Error).message}`)
       bundle = local
       source = "the CLI's bundled SDK (server unreachable)"
@@ -56,10 +65,10 @@ export const types = async (args: Args) => {
   }
   log(`${c.green("source")}    ${source} — ${label(bundle)}`)
 
-  // ---- report drift, write unless --check ----
+  // ---- report drift, write unless check ----
   const onDisk = readProjectTypeBundle(root)
   const same = bundleHash(onDisk) === bundleHash(bundle)
-  if (checkOnly) {
+  if (opts.check) {
     if (Object.keys(onDisk).length === 0) throw new CliError(`No types in ${LECODES_DIR}/types/ — run \`lecodes update\`.`)
     if (!same) throw new CliError(`Types are out of date (${label(onDisk)} on disk) — run \`lecodes update\`.`)
     success(`Types are up to date (${label(onDisk)}).`)
@@ -77,11 +86,11 @@ export const types = async (args: Args) => {
 
   // The compiler uses the SDK vendored in this CLI, not these declarations — worth saying when the
   // server's surface is a different one, since that gap shows up as "autocompletes but won't build".
-  if (!useLocal && local && bundleHash(local) !== bundleHash(bundle)) {
+  if (!opts.local && local && bundleHash(local) !== bundleHash(bundle)) {
     warn("The server's SDK surface differs from the one this CLI compiles with — if something autocompletes but fails to compile, update the CLI (`npm install -g lecodes-cli@latest`) or re-run with --local.")
   }
 
   log("")
   success(stats.added + stats.updated + stats.removed > 0 ? "Types synced." : "Types already current.")
-  if (!dirArg) note("Reload the TypeScript server in your editor to pick them up.")
+  if (!opts.dir) note("Reload the TypeScript server in your editor to pick them up.")
 }

package/src/compile/collect.ts

@@ -1,10 +1,10 @@
 import { readFileSync } from "node:fs"
 import { basename } from "node:path"
-import type { Project } from "../api"
-import type { Manifest } from "../manifest"
-import { classifyKind, scanLocal } from "../localFiles"
-import { loadIgnore } from "../ignore"
-import { buildPaths } from "../project"
+import type { Project } from "../platform/api"
+import type { Manifest } from "../project/manifest"
+import { classifyKind, scanLocal } from "../project/localFiles"
+import { loadIgnore } from "../project/ignore"
+import { buildPaths } from "../project/materialize"
 import type { CompileEntry } from "./projectCompile"
 
 /*

package/src/compile/collectLocal.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from "node:fs"
 import { basename } from "node:path"
-import type { Manifest } from "../manifest"
-import { classifyKind, scanLocal } from "../localFiles"
-import { loadIgnore } from "../ignore"
+import type { Manifest } from "../project/manifest"
+import { classifyKind, scanLocal } from "../project/localFiles"
+import { loadIgnore } from "../project/ignore"
 import type { CompileEntry } from "./projectCompile"
 
 /*

package/src/compile/designCompile.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from "node:fs"
 import { basename } from "node:path"
-import type { Manifest } from "../manifest"
-import { classifyKind, scanLocal } from "../localFiles"
-import { loadIgnore } from "../ignore"
+import type { Manifest } from "../project/manifest"
+import { classifyKind, scanLocal } from "../project/localFiles"
+import { loadIgnore } from "../project/ignore"
 import { compileProject, type CompileEntry } from "./projectCompile"
 import { applyAssetIcons } from "./assetIcons"
 import { applyProjectFonts } from "./fonts"

package/src/compile/headlessBundle.ts

@@ -1,129 +1,133 @@
-import { getProject } from "../api"
-import { loadConfig, requireApiUrl, requireToken } from "../config"
-import { findProjectRoot, readManifest, type Manifest } from "../manifest"
-import { collectEntries } from "./collect"
-import { collectLocalEntries } from "./collectLocal"
-import { ambiguousEntryWarning, compileProject } from "./projectCompile"
-import { applyProjectFonts } from "./fonts"
-import { applyAppAssetIcons } from "./assetIcons"
-import type { ScreenTarget } from "./screenEntry"
-import { flagBool, flagStr, note, type Args } from "../util"
-
-/*
- * Compile the project into the iife bundle the headless renderer runs — shared by `lecodes render`
- * and `lecodes test`. Two modes, picked automatically (same split as `lecodes compile`):
- *   - Server-backed project (.lecodes/manifest.json): entries resolve from local files + the
- *     project's server metadata (needs login).
- *   - Local project (from `lecodes init` — no manifest): compiles straight from the working tree,
- *     no login.
- * In both, resource assets default to LOCAL disk reads: each asset('./x.png') URL becomes
- * `lecodesfile://<abs-path>` which the renderer reads off disk — unpushed/edited files render with
- * no network. `--remote-assets` / an explicit `--public-url` switch to server URLs instead
- * (server-backed projects only; then data needs --wait-network).
- */
-
-// URL scheme emitted for a local project's resources so the renderer reads them off disk. Must match
-// lecodes-renderer's LOCAL_ASSET_SCHEME (headless/runProject.ts).
-export const LOCAL_ASSET_SCHEME = "lecodesfile://"
-
-export type HeadlessBundle = {
-  js: string
-  /** The project root the bundle was compiled from. */
-  root: string
-  /** Non-fatal compile-time notices (missing URLs, engine hints) — print via warnErr. */
-  warnings: string[]
-  /** Whether asset URLs resolve from the local disk (`lecodesfile://`). */
-  useLocalAssets: boolean
-}
-
-/** Compile the local project for a headless run (honors --entry / --public-url / --remote-assets). */
-export const compileHeadlessBundle = async (args: Args, opts: { screen?: ScreenTarget } = {}): Promise<HeadlessBundle> => {
-  let root: string
-  let manifest: Manifest | null
-  try {
-    root = findProjectRoot(process.cwd())
-    manifest = readManifest(root)
-  } catch {
-    root = process.cwd()
-    manifest = null
-  }
-
-  const publicUrlFlag = flagStr(args, "public-url")
-  // A local (server-less) project has no remote asset URLs — it always reads from disk.
-  const useLocalAssets = manifest ? (!publicUrlFlag && !flagBool(args, "remote-assets")) : true
-
-  let entries
-  let warnings: string[]
-  let name: string
-  let publicUrl: string
-
-  if (manifest) {
-    const config = loadConfig()
-    const apiUrl = requireApiUrl(config)
-    const token = requireToken(config)
-
-    note("Resolving project assets…")
-    const project = await getProject(apiUrl, token, manifest.uuid)
-    ;({ entries, warnings } = collectEntries(root, manifest, project))
-    name = manifest.name
-    publicUrl = useLocalAssets ? LOCAL_ASSET_SCHEME : (publicUrlFlag ?? apiUrl)
-    // In local mode the "push it so its URL resolves" notices are moot (we read from disk).
-    if (useLocalAssets) warnings = warnings.filter((w) => !w.includes("No server URL"))
-  } else {
-    ;({ entries, warnings } = collectLocalEntries(root, null, ""))
-    name = root.split(/[\\/]/).pop() ?? "project"
-    publicUrl = LOCAL_ASSET_SCHEME
-    if (flagBool(args, "remote-assets") || publicUrlFlag) {
-      warnings.push("This is a local project (no server) — assets always load from the working tree.")
-    }
-  }
-
-  // Local assets (default): resolve each resource (asset('./x.png')) from the working tree instead of
-  // the server, so unpushed / edited images show up with no --wait-network. Each resource's URL becomes
-  // `lecodesfile://<abs-path>`, which the renderer reads off disk.
-  const compileEntries = useLocalAssets
-    ? entries.map((e) => (e.type === "resource" && e.absPath)
-      ? { ...e, fileSrc: encodeURIComponent(e.absPath) }
-      : e)
-    : [...entries]
-  // Rendering one screen: the generated entry that imports it and calls .open() (see screenEntry.ts).
-  if (opts.screen) compileEntries.push(opts.screen.entry)
-
-  // font() macro: vendor registry faces into assets/fonts/ so headless renders read them off disk
-  // (lecodesfile://); with --remote-assets they stay CDN URLs like every other remote resource.
-  await applyProjectFonts(compileEntries, useLocalAssets
-    ? {
-        mode: "vendor", root, vendorDir: root, vendorPrefix: "",
-        makeResourceEntry: (path, absPath) => ({ path, type: "resource", fileSrc: encodeURIComponent(absPath), absPath }),
-      }
-    : { mode: "cdn", root })
-
-  // assetIcon() macro: resolve from the user-level cache (~/.lecodes/cache/icons) and inline, so
-  // headless renders stay deterministic and offline after the first fetch (like local assets).
-  await applyAppAssetIcons(compileEntries)
-
-  note("Compiling…")
-  const entryFlag = opts.screen?.entryPath ?? flagStr(args, "entry")
-  if (!entryFlag) {
-    const ambiguous = ambiguousEntryWarning(compileEntries)
-    if (ambiguous) warnings.push(ambiguous)
-  }
-  const js = await compileProject({
-    entries: compileEntries,
-    name,
-    publicUrl,
-    entryOverride: entryFlag,
-    header: false,
-    format: "iife",
-  })
-  if (js.includes("_creator.createScene") || js.includes("_creator.createEntity")) {
-    warnings.push("3D project: the scene graph is captured as `scene3d` in the JSON output; 3D isn't rasterized into PNGs.")
-  }
-  // With --remote-assets, 2D textures come from the network; without --wait-network they resolve empty
-  // and sprites render as flat placeholders. Local assets (default) load from disk, so no hint needed.
-  if (js.includes("_creator2d") && !useLocalAssets && !flagBool(args, "wait-network")) {
-    warnings.push("2D scene detected: sprite textures load over the network — add --wait-network to include them (else sprites render as flat placeholders).")
-  }
-
-  return { js, root, warnings, useLocalAssets }
-}
+import { getProject } from "../platform/api"
+import { loadConfig, requireApiUrl, requireToken } from "../platform/config"
+import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
+import { collectEntries } from "./collect"
+import { collectLocalEntries } from "./collectLocal"
+import { ambiguousEntryWarning, compileProject } from "./projectCompile"
+import { applyProjectFonts } from "./fonts"
+import { applyAppAssetIcons } from "./assetIcons"
+import type { ScreenTarget } from "./screenEntry"
+import { note } from "../cli"
+
+/*
+ * Compile the project into the iife bundle the headless renderer runs — shared by `lecodes render`
+ * and `lecodes test`. Two modes, picked automatically (same split as `lecodes compile`):
+ *   - Server-backed project (.lecodes/manifest.json): entries resolve from local files + the
+ *     project's server metadata (needs login).
+ *   - Local project (from `lecodes init` — no manifest): compiles straight from the working tree,
+ *     no login.
+ * In both, resource assets default to LOCAL disk reads: each asset('./x.png') URL becomes
+ * `lecodesfile://<abs-path>` which the renderer reads off disk — unpushed/edited files render with
+ * no network. `--remote-assets` / an explicit `--public-url` switch to server URLs instead
+ * (server-backed projects only; then data needs --wait-network).
+ */
+
+// URL scheme emitted for a local project's resources so the renderer reads them off disk. Must match
+// lecodes-renderer's LOCAL_ASSET_SCHEME (headless/runProject.ts).
+export const LOCAL_ASSET_SCHEME = "lecodesfile://"
+
+export type HeadlessBundle = {
+  js: string
+  /** The project root the bundle was compiled from. */
+  root: string
+  /** Non-fatal compile-time notices (missing URLs, engine hints) — print via warnErr. */
+  warnings: string[]
+  /** Whether asset URLs resolve from the local disk (`lecodesfile://`). */
+  useLocalAssets: boolean
+}
+
+/** What a headless compile honours: `--entry` / `--public-url` / `--remote-assets` / `--wait-network`,
+ *  and the screen module a `render <file>` named. */
+export type HeadlessOptions = { entry?: string, publicUrl?: string, remoteAssets?: boolean, waitNetwork?: boolean, screen?: ScreenTarget }
+
+/** Compile the local project for a headless run. */
+export const compileHeadlessBundle = async (opts: HeadlessOptions = {}): Promise<HeadlessBundle> => {
+  let root: string
+  let manifest: Manifest | null
+  try {
+    root = findProjectRoot(process.cwd())
+    manifest = readManifest(root)
+  } catch {
+    root = process.cwd()
+    manifest = null
+  }
+
+  const publicUrlFlag = opts.publicUrl
+  // A local (server-less) project has no remote asset URLs — it always reads from disk.
+  const useLocalAssets = manifest ? (!publicUrlFlag && !opts.remoteAssets) : true
+
+  let entries
+  let warnings: string[]
+  let name: string
+  let publicUrl: string
+
+  if (manifest) {
+    const config = loadConfig()
+    const apiUrl = requireApiUrl(config)
+    const token = requireToken(config)
+
+    note("Resolving project assets…")
+    const project = await getProject(apiUrl, token, manifest.uuid)
+    ;({ entries, warnings } = collectEntries(root, manifest, project))
+    name = manifest.name
+    publicUrl = useLocalAssets ? LOCAL_ASSET_SCHEME : (publicUrlFlag ?? apiUrl)
+    // In local mode the "push it so its URL resolves" notices are moot (we read from disk).
+    if (useLocalAssets) warnings = warnings.filter((w) => !w.includes("No server URL"))
+  } else {
+    ;({ entries, warnings } = collectLocalEntries(root, null, ""))
+    name = root.split(/[\\/]/).pop() ?? "project"
+    publicUrl = LOCAL_ASSET_SCHEME
+    if (opts.remoteAssets || publicUrlFlag) {
+      warnings.push("This is a local project (no server) — assets always load from the working tree.")
+    }
+  }
+
+  // Local assets (default): resolve each resource (asset('./x.png')) from the working tree instead of
+  // the server, so unpushed / edited images show up with no --wait-network. Each resource's URL becomes
+  // `lecodesfile://<abs-path>`, which the renderer reads off disk.
+  const compileEntries = useLocalAssets
+    ? entries.map((e) => (e.type === "resource" && e.absPath)
+      ? { ...e, fileSrc: encodeURIComponent(e.absPath) }
+      : e)
+    : [...entries]
+  // Rendering one screen: the generated entry that imports it and calls .open() (see screenEntry.ts).
+  if (opts.screen) compileEntries.push(opts.screen.entry)
+
+  // font() macro: vendor registry faces into assets/fonts/ so headless renders read them off disk
+  // (lecodesfile://); with --remote-assets they stay CDN URLs like every other remote resource.
+  await applyProjectFonts(compileEntries, useLocalAssets
+    ? {
+        mode: "vendor", root, vendorDir: root, vendorPrefix: "",
+        makeResourceEntry: (path, absPath) => ({ path, type: "resource", fileSrc: encodeURIComponent(absPath), absPath }),
+      }
+    : { mode: "cdn", root })
+
+  // assetIcon() macro: resolve from the user-level cache (~/.lecodes/cache/icons) and inline, so
+  // headless renders stay deterministic and offline after the first fetch (like local assets).
+  await applyAppAssetIcons(compileEntries)
+
+  note("Compiling…")
+  const entryFlag = opts.screen?.entryPath ?? opts.entry
+  if (!entryFlag) {
+    const ambiguous = ambiguousEntryWarning(compileEntries)
+    if (ambiguous) warnings.push(ambiguous)
+  }
+  const js = await compileProject({
+    entries: compileEntries,
+    name,
+    publicUrl,
+    entryOverride: entryFlag,
+    header: false,
+    format: "iife",
+  })
+  if (js.includes("_creator.createScene") || js.includes("_creator.createEntity")) {
+    warnings.push("3D project: the scene graph is captured as `scene3d` in the JSON output; 3D isn't rasterized into PNGs.")
+  }
+  // With --remote-assets, 2D textures come from the network; without --wait-network they resolve empty
+  // and sprites render as flat placeholders. Local assets (default) load from disk, so no hint needed.
+  if (js.includes("_creator2d") && !useLocalAssets && !opts.waitNetwork) {
+    warnings.push("2D scene detected: sprite textures load over the network — add --wait-network to include them (else sprites render as flat placeholders).")
+  }
+
+  return { js, root, warnings, useLocalAssets }
+}

package/src/compile/projectCompile.ts

@@ -1,8 +1,8 @@
 import { existsSync } from "node:fs"
 import { createRequire } from "node:module"
 import { dirname, join } from "node:path"
-import type { FileKind } from "../manifest"
-import { distRoot } from "../distRoot"
+import type { FileKind } from "../project/manifest"
+import { distRoot } from "../hosts/distRoot"
 import { compileProject as sdkCompileProject, detectEntry, scanModulesChisel, ENTRY_CONVENTION } from "lecodes-sdk/compile"
 
 // Every project compiles through the SDK's one import-free compiler, which bundles with chisel (the

package/src/compile/sceneCompile.ts

@@ -1,11 +1,11 @@
 import { createHash } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
-import type { Manifest } from "../manifest"
-import { scanLocal } from "../localFiles"
-import { loadIgnore } from "../ignore"
-import { distRoot } from "../distRoot"
-import { CliError, warnErr } from "../util"
+import type { Manifest } from "../project/manifest"
+import { scanLocal } from "../project/localFiles"
+import { loadIgnore } from "../project/ignore"
+import { distRoot } from "../hosts/distRoot"
+import { CliError, warnErr } from "../cli"
 import { compileProject, type CompileEntry } from "./projectCompile"
 import { applyLocalShaders, shadersCacheDir } from "./shaders"
 
@@ -55,7 +55,7 @@ export const compileSceneEditor = async (opts: {
   scenePath: string
 }): Promise<{ js: string | null, error?: string }> => {
   const { root, scenePath } = opts
-  const { loadSceneHarness, sceneEditorEntries, SCENE_ENTRY_PATH } = await import("lecodes-sdk/compile")
+  const { loadSceneHarness, sceneEditorEntries, sceneImportsOf, SCENE_ENTRY_PATH } = await import("lecodes-sdk/compile")
 
   const entries: CompileEntry[] = []
   const scan = scanLocal(root, { ignore: loadIgnore(root), tracked: new Set(Object.keys(opts.manifest?.files ?? {})) })
@@ -96,10 +96,12 @@ export const compileSceneEditor = async (opts: {
   }
 
   const scene = scenePath.startsWith("./") ? scenePath : "./" + rel(scenePath)
-  if (!entries.some((e) => e.path === scene && e.type === "text")) {
+  const sceneEntry = entries.find((e) => e.path === scene && e.type === "text")
+  if (!sceneEntry) {
     return { js: null, error: `Scene file not found: ${scene}` }
   }
-  entries.push(...sceneEditorEntries(scene, resolveHarness(loadSceneHarness), entries.map((e) => e.path)))
+  const paths = entries.map((e) => e.path)
+  entries.push(...sceneEditorEntries(scene, resolveHarness(loadSceneHarness), paths, sceneImportsOf(sceneEntry.text ?? "", scene, paths)))
 
   try {
     const js = await compileProject({