lecodes-cli 0.19.0 → 0.20.0

package/src/commands/clone.ts

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, readdirSync } from "node:fs"
+import { resolve } from "node:path"
+import { getCommits, getProject } from "../api"
+import { loadConfig, requireApiUrl, requireToken } from "../config"
+import { writeManifest } from "../manifest"
+import { materializeAssets } from "../project"
+import { materializeTypes, writeTsconfig } from "../types"
+import { ensureGitignore, writeDefaultIgnore } from "../ignore"
+import { CliError, c, info, success, progress, endProgress, flagBool, type Args } from "../util"
+
+/* `lecodes clone <uuid|url> [dir]` — download a project's files + types into a new folder. */
+
+/**
+ * Accept a bare uuid or a project link and pull out the uuid. Handles editor links
+ * (https://le.codes/app/projects/<uuid>) and viewer links (.../view/<uuid>), with any
+ * query/hash or trailing slash; falls back to the last path segment.
+ */
+export const parseUuid = (input: string): string => {
+  if (!input) throw new CliError("Usage: lecodes clone <project-uuid|url> [directory]")
+  if (!input.includes("/")) return input
+  const clean = input.split(/[?#]/)[0].replace(/\/+$/, "")
+  const match = clean.match(/\/(?:projects|view)\/([^/]+)/)
+  return match ? match[1] : clean.slice(clean.lastIndexOf("/") + 1)
+}
+
+const slug = (name: string) => name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project"
+
+export const clone = async (args: Args) => {
+  const config = loadConfig()
+  const apiUrl = requireApiUrl(config)
+  const token = requireToken(config)
+
+  const uuid = parseUuid(args._[0])
+  const project = await getProject(apiUrl, token, uuid)
+
+  const dir = args._[1] ?? slug(project.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(`Fetching project ${c.bold(project.name)}…`))
+  const files = await materializeAssets(root, project, apiUrl, token, progress)
+  endProgress()
+
+  if (!flagBool(args, "no-types")) {
+    info(c.dim("Fetching type definitions…"))
+    await materializeTypes(root, apiUrl)
+    writeTsconfig(root)
+  }
+  writeDefaultIgnore(root)
+  ensureGitignore(root)   // .lecodes/ is per-checkout state — keep it out of the project's git repo
+
+  const commits = await getCommits(apiUrl, token, uuid)
+  writeManifest(root, { uuid, apiUrl, name: project.name, baseHeadId: commits.headId, files })
+
+  success(`Cloned ${c.bold(project.name)} into ${c.bold(dir)}/ (${Object.keys(files).length} files)`)
+  info(c.dim(`  cd ${dir} — edit, then \`lecodes push -m "your message"\``))
+}

package/src/commands/compile.ts

@@ -0,0 +1,253 @@
+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 { collectEntries } from "../compile/collect"
+import { collectLocalEntries } from "../compile/collectLocal"
+import { ambiguousEntryWarning, compileProject, type CompileEntry } from "../compile/projectCompile"
+import { applyProjectFonts } from "../compile/fonts"
+import { applyLocalShaders, desktopShaderPlatform, type StagedShader } from "../compile/shaders"
+import type { DesktopRenderer } from "../desktopRenderer"
+import { applyAppAssetIcons } from "../compile/assetIcons"
+import { buildGlobMatcher } from "../ignore"
+import { readAppConfigAt } from "./appShared"
+import { flagBool, flagStr, isNullSink, note, warnErr, type Args } from "../util"
+
+/*
+ * `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).
+ *
+ * Two modes, picked automatically:
+ *   - Server-backed project (a cloned/created one with .lecodes/manifest.json): code/.svg/scene
+ *     content comes from local files (fresh); binary & shader URLs are resolved from the project's
+ *     server metadata. Local-only / locally-changed assets are flagged.
+ *   - Local project (from `lecodes init` — no manifest): compile straight from the working tree,
+ *     no login. `asset()` resources resolve via the host's fetchLocal (the desktop reads the file
+ *     by name), so the bundle runs on LeCodes Desktop with the assets sitting next to it. Pass
+ *     `--public-url <url>` to resolve assets from a URL prefix instead.
+ *
+ * Desktop-host callers (`desktop run`, `render --desktop`, `test --desktop`) pass `localAssets`:
+ * in BOTH project modes `asset()` resources then resolve from the working tree (fetchLocal, the
+ * files are staged next to app.js), so an edited-but-unpushed image shows up — the same default
+ * `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.
+ */
+
+/** One project resource as the shell compile resolved it (returned to `lecodes app sync`). */
+export type BundleResource = {
+  /** Root-relative project path. */
+  path: string
+  /** The runtime lookup name — the basename the bundle passes to fetchLocal / `// preload:`. */
+  name: string
+  /** Local file to copy from (always set for resources found in the working tree). */
+  absPath?: string
+  /** True → left as a server URL (matched app.json resources.remote); not shipped in the app. */
+  remote: boolean
+  /** A locally compiled shader artifact (.filamat), not a project file: it must ship next to the
+   *  bundle (the host loads it by name via fetchLocal) but it is not `asset()`-referenced, so the
+   *  bundle's fetchLocal-literal scan can't see it. */
+  shader?: boolean
+}
+
+/** 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). */
+export type BuildBundleOptions = {
+  /** Resolve resources from the working tree by default (`--remote-assets` / `--public-url` opt out). */
+  localAssets?: boolean
+  /** Compile the project's .mat shaders locally and stage the artifacts next to the bundle
+   *  (fetchLocal). On by default for a non-shell local-asset compile; `app build desktop` opts in
+   *  explicitly because it builds a fetchLocal host THROUGH the shell path. */
+  localShaders?: boolean
+  /** 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. */
+  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`). */
+  entryOverride?: string
+}
+
+const compileImpl = async (args: Args, shell?: ShellCompile): Promise<BundleResource[]> => {
+  const { js, resources } = await buildBundle(args, shell)
+
+  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")
+  }
+  return resources
+}
+
+export const buildBundle = async (args: Args, shell?: ShellCompile, opts: BuildBundleOptions = {}): Promise<BuiltBundle> => {
+  let root: string
+  let manifest: Manifest | null
+  try {
+    root = findProjectRoot(process.cwd())
+    manifest = readManifest(root)
+  } catch {
+    root = process.cwd()
+    manifest = null
+  }
+
+  let entries: CompileEntry[]
+  let warnings: string[]
+  let name: string
+  let publicUrl: string
+  let localAssets = false
+
+  if (manifest) {
+    const config = loadConfig()
+    const apiUrl = requireApiUrl(config)
+    const token = requireToken(config)
+
+    const publicUrlFlag = flagStr(args, "public-url")
+    // 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"))
+
+    note("Resolving project assets…")
+    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
+
+    // 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.
+    const remotePatterns = shell?.remotePatterns ?? (localAssets ? readAppConfigAt(root)?.resources?.remote ?? [] : [])
+    if (localAssets && remotePatterns.length > 0) {
+      const isRemote = buildGlobMatcher(remotePatterns)
+      for (const e of entries) {
+        if (e.type !== "resource" || !isRemote(e.path)) continue
+        if (!e.fileSrc) { warnErr(`${e.path} matches resources.remote but has no server URL yet — ${shell ? "bundling it (push, then re-sync)" : "reading it from the working tree"}.`); continue }
+        e.remote = true
+      }
+    }
+  } else {
+    // 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.")
+    }
+    // localShaders: a local-asset compile compiles the .mat files itself below, so the
+    // "push the project once" degradation notice would be wrong.
+    ;({ entries, warnings } = collectLocalEntries(root, null, "", { localShaders: localAssets && (opts.localShaders ?? !shell) }))
+    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.")
+    }
+  }
+
+  // Custom shaders (.mat) for a host with no asset server: compile them locally (matc) and stage
+  // the artifacts next to the bundle, so the desktop host loads them through fetchLocal like the
+  // built-in materials. Shell compiles (`app sync ios|android`) keep the URL form for now — the
+  // fetchLocal path there is unverified on device. Failure degrades to a warning and the entries
+  // keep whatever they had (server URLs, or empty for a local project).
+  let stagedShaders: StagedShader[] = []
+  if (localAssets && (opts.localShaders ?? !shell)) {
+    // 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 local = await applyLocalShaders(entries, { root, local: true, platforms })
+    warnings.push(...local.warnings)
+    stagedShaders = local.artifacts
+  }
+
+  // font() macro: a server-backed URL compile bakes CDN registry URLs; a local-asset or shell one
+  // 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 fontsHeader = await applyProjectFonts(entries, (manifest && !localAssets)
+    ? { mode: "cdn", root, publicUrl }
+    : {
+        mode: "vendor", root, vendorDir: root, vendorPrefix: "", publicUrl: shell ? "" : publicUrl,
+        makeResourceEntry: (path, absPath) => ({ path, type: "resource", fileSrc: encodeURI(path), absPath }),
+      })
+
+  // assetIcon() macro: icons resolve from the user-level cache (~/.lecodes/cache/icons), fetching
+  // misses from the registry, and inline into the bundle as SvgSource — never written into the
+  // project. The returned pack list becomes the `// icons:` attribution header.
+  if (opts.extraEntries) entries.push(...opts.extraEntries)
+  const iconsHeader = await applyAppAssetIcons(entries)
+
+  note("Compiling…")
+  const entryFlag = opts.entryOverride ?? flagStr(args, "entry")
+  if (!entryFlag) {
+    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,
+  })
+
+  for (const w of warnings) warnErr(w)
+
+  // Resource inventory for shell/render callers (includes faces the font pass vendored into 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,
+    }))
+  // 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 })
+  }
+  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

@@ -0,0 +1,59 @@
+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"
+
+const STARTER = `// Welcome to le.codes — no imports needed, the whole SDK is available as globals.
+const scene = new Scene2D({ background: '#10131a' })
+scene.open()
+
+setLoop((dt) => {
+  // your per-frame logic — dt is seconds since the previous frame
+})
+`
+
+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`))
+}