lecodes-cli 0.20.2 → 2.0.0

package/src/commands/compile.ts

@@ -1,23 +1,22 @@
 import { writeFileSync } from "node:fs"
 import { basename, resolve } from "node:path"
-import { getProject } from "../api"
-import { loadConfig, requireApiUrl, requireToken } from "../config"
-import { findProjectRoot, readManifest, type Manifest } from "../manifest"
+import { getProject } from "../platform/api"
+import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
 import { collectEntries } from "../compile/collect"
 import { collectLocalEntries } from "../compile/collectLocal"
-import { ambiguousEntryWarning, compileProject, type CompileEntry } from "../compile/projectCompile"
+import { ambiguousEntryWarning, compileProject, localAssetNames, type CompileEntry } from "../compile/projectCompile"
 import { applyProjectFonts } from "../compile/fonts"
 import { applyLocalShaders, desktopShaderPlatform, type StagedShader } from "../compile/shaders"
-import type { DesktopRenderer } from "../desktopRenderer"
+import type { DesktopRenderer } from "../hosts/desktopRenderer"
 import { applyAppAssetIcons } from "../compile/assetIcons"
-import { buildGlobMatcher } from "../ignore"
-import { readAppConfigAt } from "./appShared"
-import { flagBool, flagStr, isNullSink, note, warnErr, type Args } from "../util"
+import { buildGlobMatcher } from "../project/ignore"
+import { readAppConfigAt } from "./app/shared"
+import { defineCommand, isNullSink, note, warnErr } from "../cli"
+import { bundleFlags, bundleOptions, outFlag, session, type BundleOptions } from "./shared"
 
 /*
- * `lecodes compile` — compile the local project into one JS bundle (same pipeline as the server)
- * and print it to stdout (pipeable), or write it with -o/--out. Diagnostics go to stderr.
- * `lecodes preview` is the legacy alias for this command (see `previewLegacy` below).
+ * `lecodes compile` — the local project as one JS bundle (the server's pipeline), printed to stdout
+ * or written with -o. Diagnostics go to stderr, so `lecodes compile > app.js` stays clean.
  *
  * Two modes, picked automatically:
  *   - Server-backed project (a cloned/created one with .lecodes/manifest.json): code/.svg/scene
@@ -34,14 +33,14 @@ import { flagBool, flagStr, isNullSink, note, warnErr, type Args } from "../util
  * `lecodes render` has. `--remote-assets` (or an explicit `--public-url`) opts back into server
  * URLs; app.json `resources.remote` matches stay URLs either way (they stream in the built app too).
  *
- * A third mode exists for `lecodes app sync` only (the `shell` parameter): compile for a native
- * shell that ships its assets inside the app. Resources resolve locally (`id:` + fetchLocal) in
- * BOTH project modes, fonts vendor into assets/fonts/ (never CDN — text must render offline,
- * before any network), and resources matching `shell.remotePatterns` keep their server URL for
- * streaming. Returns every resource entry so the caller can copy the bundled ones into the shell.
+ * A third mode exists for `lecodes app sync` only (`compileShell`): compile for a native shell that
+ * ships its assets inside the app. Resources resolve locally (`id:` + fetchLocal) in BOTH project
+ * modes, fonts vendor into assets/fonts/ (never CDN — text must render offline, before any
+ * network), and resources matching `shell.remotePatterns` keep their server URL for streaming.
+ * Returns every resource entry so the caller can copy the bundled ones into the shell.
  */
 
-/** One project resource as the shell compile resolved it (returned to `lecodes app sync`). */
+/** One project resource as the compile resolved it (returned to `lecodes app sync`). */
 export type BundleResource = {
   /** Root-relative project path. */
   path: string
@@ -60,14 +59,6 @@ export type BundleResource = {
 /** Shell-compile options (see the mode note above) — only `lecodes app sync` passes this. */
 export type ShellCompile = { remotePatterns: string[] }
 
-/** The `lecodes compile` command. */
-export const compile = async (args: Args): Promise<void> => { await compileImpl(args) }
-
-/** `lecodes app sync`'s entry: shell mode (see above), returning the resource inventory. */
-export const compileShell = (args: Args, shell: ShellCompile): Promise<BundleResource[]> => compileImpl(args, shell)
-
-/** The compiled project without any output handling — `lecodes render --desktop` runs this bundle in
- *  the native desktop host, copying the local-asset resources next to it (fetchLocal by basename). */
 export type BuiltBundle = { js: string, resources: BundleResource[] }
 
 /** Extra knobs for the desktop-host callers (see the mode note above). */
@@ -81,32 +72,46 @@ export type BuildBundleOptions = {
   /** The desktop renderer this bundle is being built FOR, when the caller knows (it stages or spawns
    *  the very exe that will run it). Narrows the shader compile + staging to the one artifact that
    *  host asks for, instead of shipping every native variant. Leave unset when the target is unknown
-   *  — a generic `preview --local` bundle can be carried anywhere. */
+   *  — a generic bundle can be carried anywhere. */
   desktopRenderer?: DesktopRenderer
   /** Synthetic in-memory entries added to the project's own (a virtual entry module, say — see
    *  `lecodes lightmap bake`). Paths use the entry convention ("/.name.ts" at the root). */
   extraEntries?: CompileEntry[]
-  /** Compile from this entry instead of the detected one / `--entry` (pairs with `extraEntries`). */
+  /** Compile from this entry instead of the detected one / `entry` (pairs with `extraEntries`). */
   entryOverride?: string
+  /** Shell mode (`lecodes app sync`) — see above. */
+  shell?: ShellCompile
 }
 
-const compileImpl = async (args: Args, shell?: ShellCompile): Promise<BundleResource[]> => {
-  const { js, resources } = await buildBundle(args, shell)
+export default defineCommand({
+  name: "compile",
+  summary: "Compile the local project to one JS bundle (stdout, or -o <file>)",
+  description: "Works on a cloned / created project (binary asset URLs resolved from the server) or a local `init` project (no login — asset() resources resolve on the host via fetchLocal, so the bundle is self-contained for LeCodes Desktop). Diagnostics go to stderr; the bundle is the only thing on stdout.",
+  aliases: ["preview"],
+  flags: { ...outFlag, ...bundleFlags },
+  examples: ["lecodes compile -o app.js", "lecodes compile --no-minify > app.js"],
+  run: async ({ flags }) => {
+    const { js } = await buildBundle(bundleOptions(flags))
+    writeBundle(js, flags.out)
+  },
+})
+
+/** Print or write a bundle (`-o /dev/null` discards it). */
+export const writeBundle = (js: string, out: string | undefined): void => {
+  if (out && isNullSink(out)) note(`Discarded output (${out})`)
+  else if (out) { writeFileSync(resolve(out), js); note(`Wrote ${out} (${js.length} bytes)`) }
+  else { process.stdout.write(js); if (!js.endsWith("\n")) process.stdout.write("\n") }
+}
 
-  const out = flagStr(args, "o", "out")
-  if (out && isNullSink(out)) {
-    note(`Discarded output (${out})`)
-  } else if (out) {
-    writeFileSync(resolve(out), js)
-    note(`Wrote ${out} (${js.length} bytes)`)
-  } else {
-    process.stdout.write(js)
-    if (!js.endsWith("\n")) process.stdout.write("\n")
-  }
+/** `lecodes app sync`'s entry: shell mode (see above), the bundle written to `out`, the resource inventory returned. */
+export const compileShell = async (out: string, shell: ShellCompile): Promise<BundleResource[]> => {
+  const { js, resources } = await buildBundle({}, { shell })
+  writeBundle(js, out)
   return resources
 }
 
-export const buildBundle = async (args: Args, shell?: ShellCompile, opts: BuildBundleOptions = {}): Promise<BuiltBundle> => {
+export const buildBundle = async (bundle: BundleOptions, opts: BuildBundleOptions = {}): Promise<BuiltBundle> => {
+  const shell = opts.shell
   let root: string
   let manifest: Manifest | null
   try {
@@ -124,21 +129,19 @@ export const buildBundle = async (args: Args, shell?: ShellCompile, opts: BuildB
   let localAssets = false
 
   if (manifest) {
-    const config = loadConfig()
-    const apiUrl = requireApiUrl(config)
-    const token = requireToken(config)
-
-    const publicUrlFlag = flagStr(args, "public-url")
+    const { apiUrl, token } = session()
     // Shell compiles always bundle; a desktop-host run reads the tree unless told to use the server.
-    localAssets = !!shell || (!!opts.localAssets && publicUrlFlag === undefined && !flagBool(args, "remote-assets"))
+    localAssets = !!shell || (!!opts.localAssets && bundle.publicUrl === undefined && !bundle.remoteAssets)
 
     note("Resolving project assets…")
+    const tResolve = performance.now()
     const project = await getProject(apiUrl, token, manifest.uuid)
     // Local-asset compiles use URL-less resources as-is instead of degrading, so skip that warning
     // there (an unpushed resources.remote match still warns below).
     ;({ entries, warnings } = collectEntries(root, manifest, project, { warnMissingUrl: !localAssets }))
     name = manifest.name
-    publicUrl = publicUrlFlag ?? apiUrl
+    publicUrl = bundle.publicUrl ?? apiUrl
+    note(`Resolved ${entries.length} entries in ${((performance.now() - tResolve) / 1000).toFixed(1)} s`)
 
     // Local-asset compile: everything resolves from the tree except the resources.remote matches,
     // which keep their server URL — and can't without one, so an unpushed match falls back to local.
@@ -155,20 +158,17 @@ export const buildBundle = async (args: Args, shell?: ShellCompile, opts: BuildB
     // Local project (no server): compile from the tree. Without an explicit --public-url the assets
     // resolve locally (host fetchLocal) so the bundle is self-contained for LeCodes Desktop.
     // fileSrc stays a path (assetBase "") — compileProject prefixes publicUrl exactly once, same as
-    // the server/dev conventions. (Passing publicUrl as assetBase too used to double the prefix.)
-    const publicUrlFlag = flagStr(args, "public-url")
-    localAssets = shell ? true : publicUrlFlag === undefined
-    publicUrl = publicUrlFlag ?? ""
-    if (opts.localAssets && flagBool(args, "remote-assets")) {
-      warnErr("This is a local project (no server) — assets always load from the working tree.")
-    }
+    // the server/dev conventions.
+    localAssets = shell ? true : bundle.publicUrl === undefined
+    publicUrl = bundle.publicUrl ?? ""
+    if (opts.localAssets && bundle.remoteAssets) warnErr("This is a local project (no server) — assets always load from the working tree.")
     // localShaders: a local-asset compile compiles the .mat files itself below, so the
     // "push the project once" degradation notice would be wrong.
+    const tEntries = performance.now()
     ;({ entries, warnings } = collectLocalEntries(root, null, "", { localShaders: localAssets && (opts.localShaders ?? !shell) }))
+    note(`Collected ${entries.length} entries in ${((performance.now() - tEntries) / 1000).toFixed(1)} s`)
     name = basename(root)
-    if (shell && shell.remotePatterns.length > 0) {
-      warnErr("resources.remote needs a server-backed project (a streamed asset needs a server URL) — bundling everything.")
-    }
+    if (shell && shell.remotePatterns.length > 0) warnErr("resources.remote needs a server-backed project (a streamed asset needs a server URL) — bundling everything.")
   }
 
   // Custom shaders (.mat) for a host with no asset server: compile them locally (matc) and stage
@@ -181,9 +181,7 @@ export const buildBundle = async (args: Args, shell?: ShellCompile, opts: BuildB
     // A caller that knows its target host (every desktop path) narrows this to the single artifact
     // that host will fetch; otherwise every native variant is compiled and staged, since the
     // runtime picks by `_creator.backend` and the bundle could be carried anywhere.
-    const platforms = opts.desktopRenderer
-      ? [desktopShaderPlatform(process.platform, opts.desktopRenderer)]
-      : undefined
+    const platforms = opts.desktopRenderer ? [desktopShaderPlatform(process.platform, opts.desktopRenderer)] : undefined
     const local = await applyLocalShaders(entries, { root, local: true, platforms })
     warnings.push(...local.warnings)
     stagedShaders = local.artifacts
@@ -193,6 +191,7 @@ export const buildBundle = async (args: Args, shell?: ShellCompile, opts: BuildB
   // vendors faces into assets/fonts/ so the bundle stays self-contained (fetchLocal / --public-url).
   // Shell compiles pass publicUrl "" here so the `// fonts:` header carries no face URLs — the
   // host must register faces from the bundle, never wait on the network before first paint.
+  const tPrep = performance.now()
   const fontsHeader = await applyProjectFonts(entries, (manifest && !localAssets)
     ? { mode: "cdn", root, publicUrl }
     : {
@@ -205,49 +204,37 @@ export const buildBundle = async (args: Args, shell?: ShellCompile, opts: BuildB
   // project. The returned pack list becomes the `// icons:` attribution header.
   if (opts.extraEntries) entries.push(...opts.extraEntries)
   const iconsHeader = await applyAppAssetIcons(entries)
+  note(`Prepared shaders, fonts and icons in ${((performance.now() - tPrep) / 1000).toFixed(1)} s`)
 
   note("Compiling…")
-  const entryFlag = opts.entryOverride ?? flagStr(args, "entry")
-  if (!entryFlag) {
+  const tCompile = performance.now()
+  const entryOverride = opts.entryOverride ?? bundle.entry
+  if (!entryOverride) {
     const ambiguous = ambiguousEntryWarning(entries)
     if (ambiguous) warnErr(ambiguous)
   }
   const js = await compileProject({
-    entries,
-    name,
-    publicUrl,
-    entryOverride: entryFlag,
-    header: !flagBool(args, "no-header"),
-    localAssets,
-    fontsHeader,
-    iconsHeader,
-    // Both default on; `false` only when the flag is present, so the SDK's own defaults stand.
-    minify: flagBool(args, "no-minify") ? false : undefined,
-    sourcemap: flagBool(args, "no-sourcemap", "no-source-map") ? false : undefined,
+    entries, name, publicUrl, entryOverride,
+    header: bundle.header ?? true,
+    localAssets, fontsHeader, iconsHeader,
+    minify: bundle.minify,
+    sourcemap: bundle.sourcemap,
+    onWarning: (w) => warnings.push(w),
   })
+  note(`Compiled in ${((performance.now() - tCompile) / 1000).toFixed(1)} s (${(js.length / 1024).toFixed(0)} KB)`)
 
   for (const w of warnings) warnErr(w)
 
   // Resource inventory for shell/render callers (includes faces the font pass vendored into entries).
+  // The NAME is what the bundle passes to fetchLocal, so it has to come from where the bundle got
+  // it: a basename two project files share is disambiguated there, and a caller that re-derived the
+  // basename here would stage both packs' SM_Sign_01.glb onto one file again.
+  const localNames = localAssetNames(entries)
   const resources: BundleResource[] = entries
     .filter((e) => e.type === "resource")
-    .map((e) => ({
-      path: e.path.replace(/^\//, ""),
-      name: e.path.split(/[\\/]/).pop() ?? e.path,
-      absPath: e.absPath,
-      remote: !!e.remote,
-    }))
+    .map((e) => ({ path: e.path.replace(/^\//, ""), name: localNames.get(e.path) ?? e.path.split(/[\\/]/).pop() ?? e.path, absPath: e.absPath, remote: !!e.remote }))
   // Compiled shader artifacts ship the same way (copied next to app.js, loaded by name), flagged
   // so the desktop packager keeps them — they have no asset() reference for its scan to match.
-  for (const artifact of stagedShaders) {
-    resources.push({ path: artifact.name, name: artifact.name, absPath: artifact.absPath, remote: false, shader: true })
-  }
+  for (const artifact of stagedShaders) resources.push({ path: artifact.name, name: artifact.name, absPath: artifact.absPath, remote: false, shader: true })
   return { js, resources }
 }
-
-/** `lecodes preview` — the command's former name, kept working for existing scripts. The deprecation
- *  goes to stderr, so a piped `lecodes preview > app.js` still yields a clean bundle. */
-export const previewLegacy = async (args: Args) => {
-  warnErr("'lecodes preview' is now 'lecodes compile' — the old name still works.")
-  await compile(args)
-}

package/src/commands/create.ts

@@ -1,18 +1,16 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs"
 import { join, resolve } from "node:path"
-import { createProject, getCommits } from "../api"
-import { loadConfig, requireApiUrl, requireToken } from "../config"
-import { writeManifest } from "../manifest"
-import { materializeTypes, writeTsconfig } from "../types"
-import { writeDefaultIgnore } from "../ignore"
-import { appClaudeMd, CLAUDE_SETTINGS } from "./projectTemplates"
-import { CliError, c, flagStr, info, success, type Args } from "../util"
-
-/* `lecodes create <name> [dir]` — create a brand-new project on the server, then scaffold a local
- * folder for it: the current type definitions (fetched from the server, so IntelliSense matches the
- * deployed runtime), a tsconfig, an ignore file, and an import-free starter. Edit, then `lecodes push`. */
-
-const slug = (name: string) => name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project"
+import { CliError, UsageError, c, defineCommand, info, str, success } from "../cli"
+import { createProject, getCommits } from "../platform/api"
+import { writeDefaultIgnore } from "../project/ignore"
+import { writeManifest } from "../project/manifest"
+import { materializeTypes, writeTsconfig } from "../project/types"
+import { appClaudeMd, CLAUDE_SETTINGS } from "./init/templates"
+import { session, slugOf } from "./shared"
+
+/* `lecodes create <name> [dir]` — a brand-new project on the server plus a local folder for it:
+ * the server's type definitions (IntelliSense matches the deployed runtime), a tsconfig, an ignore
+ * file and an import-free starter. Edit, then `lecodes push`. */
 
 const STARTER = `// Welcome to le.codes — no imports needed, the whole SDK is available as globals.
 const scene = new Scene2D({ background: '#10131a' })
@@ -23,37 +21,38 @@ setLoop((dt) => {
 })
 `
 
-export const create = async (args: Args) => {
-  const config = loadConfig()
-  const apiUrl = requireApiUrl(config)
-  const token = requireToken(config)
-
-  const name = args._[0]
-  if (!name) throw new CliError("Usage: lecodes create <name> [directory]")
-
-  const dir = args._[1] ?? slug(name)
-  const root = resolve(dir)
-  if (existsSync(root) && readdirSync(root).length > 0) {
-    throw new CliError(`Directory "${dir}" already exists and is not empty.`)
-  }
-  mkdirSync(root, { recursive: true })
-
-  info(c.dim(`Creating project ${c.bold(name)}…`))
-  const { uuid } = await createProject(apiUrl, token, name, flagStr(args, "team"))
-
-  info(c.dim("Fetching type definitions…"))
-  await materializeTypes(root, apiUrl)
-  writeTsconfig(root)
-  writeDefaultIgnore(root)
-  writeFileSync(join(root, "main.ts"), STARTER)
-  writeFileSync(join(root, "CLAUDE.md"), appClaudeMd(name))
-  mkdirSync(join(root, ".claude"), { recursive: true })
-  writeFileSync(join(root, ".claude", "settings.json"), CLAUDE_SETTINGS)
-
-  // A fresh project's tree is empty on the server; the local main.ts is a pending add for the first push.
-  const commits = await getCommits(apiUrl, token, uuid)
-  writeManifest(root, { uuid, apiUrl, name, baseHeadId: commits.headId, files: {} })
-
-  success(`Created ${c.bold(name)} in ${c.bold(dir)}/`)
-  info(c.dim(`  cd ${dir} — edit main.ts, then \`lecodes push -m "first commit"\` to save it`))
-}
+export default defineCommand({
+  name: "create",
+  summary: "Create a new project on the server and scaffold it locally",
+  usage: "<name> [dir]",
+  flags: { team: str("create it inside a team", { value: "<uuid>" }) },
+  run: async ({ args, flags }) => {
+    const { apiUrl, token } = session()
+    const name = args[0]
+    if (!name) throw new UsageError("a project name is required")
+
+    const dir = args[1] ?? slugOf(name)
+    const root = resolve(dir)
+    if (existsSync(root) && readdirSync(root).length > 0) throw new CliError(`Directory "${dir}" already exists and is not empty.`)
+    mkdirSync(root, { recursive: true })
+
+    info(c.dim(`Creating project ${c.bold(name)}…`))
+    const { uuid } = await createProject(apiUrl, token, name, flags.team)
+
+    info(c.dim("Fetching type definitions…"))
+    await materializeTypes(root, apiUrl)
+    writeTsconfig(root)
+    writeDefaultIgnore(root)
+    writeFileSync(join(root, "main.ts"), STARTER)
+    writeFileSync(join(root, "CLAUDE.md"), appClaudeMd(name))
+    mkdirSync(join(root, ".claude"), { recursive: true })
+    writeFileSync(join(root, ".claude", "settings.json"), CLAUDE_SETTINGS)
+
+    // A fresh project's tree is empty on the server; the local main.ts is a pending add for the first push.
+    const commits = await getCommits(apiUrl, token, uuid)
+    writeManifest(root, { uuid, apiUrl, name, baseHeadId: commits.headId, files: {} })
+
+    success(`Created ${c.bold(name)} in ${c.bold(dir)}/`)
+    info(c.dim(`  cd ${dir} — edit main.ts, then \`lecodes push -m "first commit"\` to save it`))
+  },
+})