lecodes-cli 0.19.0 → 0.19.2

package/src/commands/designTemplates.ts

@@ -0,0 +1,11 @@
+/* File templates `lecodes design init` scaffolds into the design folder. The strings live in
+ * lecodes-design (src/templates.ts, in the lecodes-tools repo) — the single source shared with the
+ * platform editor's "Create design" button. Imported by a RELATIVE path through the package's
+ * node_modules link (not as `lecodes-design/templates`) on purpose: the CLI build externalizes the
+ * `lecodes-design` package (it's an optional runtime install for `design serve`), but `init` must
+ * work without it — a relative import gets bundled into the binary like any local module. The link
+ * is the `link:lecodes-design` dev dependency (see the root `bun run link`). */
+
+export {
+  META_JSON, META_JSON_DESKTOP, SPEC_MD, TOKENS_TS, TABS_TS, HOME_SCREEN_TS, CLAUDE_MD, DESIGN_MACROS_DTS, README_HINT,
+} from "../../node_modules/lecodes-design/src/templates"

package/src/commands/desktop.ts

@@ -0,0 +1,122 @@
+import { CliError, c, flagBool, flagStr, log, note, type Args } from "../util"
+import { findProjectRoot } from "../manifest"
+import { buildBundle } from "./compile"
+import { assertRendererSupportsBundle, readAppConfigAt, resolveDesktopRenderer } from "./appShared"
+import { buildDesktop } from "./appDesktop"
+import {
+  DESKTOP_RENDERER_VERSION,
+  fetchDesktopManifest,
+  findMacHostExe,
+  installedDesktopVersions,
+  runDesktopApp,
+  selectedDesktopVersion,
+  semverNewer,
+  updateDesktop,
+} from "../desktopRenderer"
+
+/*
+ * `lecodes desktop` — everything about the desktop target in one place.
+ *   (no args)   status: the version renders use, what's cached, what's published
+ *   run         compile the current project and open it in a real desktop window
+ *   build       stage a portable app folder (the same command as `lecodes app build desktop`,
+ *               which stays for symmetry with the ios/android shells)
+ *   update      move the host to the newest published release (downloads it if needed)
+ * The binary cache lives in ~/.lecodes/renderer/; LECODES_DESKTOP_EXE overrides everything.
+ */
+
+/** `--scale 2` / `--scale fit` / app.json desktop.window.scale → the host's scale knob
+ *  ("system" and absent mean: let the host decide from the OS display scale). */
+export const resolveScale = (flag: string | undefined, cfg: number | "fit" | "system" | undefined): number | "fit" | undefined => {
+  const raw = flag ?? cfg
+  if (raw === undefined || raw === "system") return undefined
+  if (raw === "fit") return "fit"
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n < 0.5 || n > 4) {
+    throw new CliError(`scale must be a number 0.5..4, "fit" or "system" (got "${raw}")`)
+  }
+  return n
+}
+
+export const resolveRenderScale = (flag: string | undefined, cfg: number | undefined): number | undefined => {
+  const raw = flag ?? cfg
+  if (raw === undefined) return undefined
+  const n = Number(raw)
+  if (!Number.isFinite(n) || n < 0.25 || n > 1) throw new CliError(`render-scale must be a number 0.25..1 (got "${raw}")`)
+  return n
+}
+
+const run = async (args: Args) => {
+  // Window defaults come from app.json's desktop block (flags win); standalone projects
+  // without an app.json keep the host's built-in 1280×720.
+  let root: string
+  try { root = findProjectRoot(process.cwd()) } catch { root = process.cwd() }
+  const appCfg = readAppConfigAt(root)
+  const win = appCfg?.desktop?.window
+  // ONE renderer decision per run: it picks the host binary AND which .filamat gets staged beside
+  // the bundle. Reading the config twice is how a Vulkan exe ends up next to an OpenGL shader.
+  const renderer = resolveDesktopRenderer(root, args)
+  const { js, resources } = await buildBundle(args, undefined, { localAssets: true, desktopRenderer: renderer })
+  assertRendererSupportsBundle(renderer, js)
+  note(`Launching LeCodes Desktop${renderer === "vulkan" ? " (Vulkan)" : ""}… (close the window to return)`)
+  await runDesktopApp(js, resources, {
+    renderer,
+    width: Number(flagStr(args, "width")) || win?.width,
+    height: Number(flagStr(args, "height")) || win?.height,
+    minWidth: win?.minWidth,
+    minHeight: win?.minHeight,
+    resizable: win?.resizable,
+    title: flagStr(args, "title") ?? win?.title ?? appCfg?.name,
+    // --fullscreen forces it on; --windowed forces it off (over app.json); else the config decides.
+    fullscreen: flagBool(args, "fullscreen") ? true : flagBool(args, "windowed") ? false : win?.fullscreen,
+    scale: resolveScale(flagStr(args, "scale"), win?.scale),
+    // 3D render resolution: --render-scale wins over app.json desktop.renderScale; the cap comes
+    // from app.json only. Both are desktop-level (the machine/app), not window-level.
+    renderScale: resolveRenderScale(flagStr(args, "render-scale"), appCfg?.desktop?.renderScale),
+    maxRenderSize: appCfg?.desktop?.maxRenderSize,
+    // --fps: the host's own corner counter. A flag and not app.json on purpose — it is something you
+    // switch on while looking at a frame, not a property of the app.
+    fps: flagBool(args, "fps"),
+    // Multiplayer (docs/multiplayer-plan.md): --server [--port N] [--max-clients N] starts the host as a
+    // dedicated server; --connect ip:port joins one. Both only set Net.launch — the app calls Net.listen/connect.
+    net: flagBool(args, "server")
+      ? { role: "server", port: Number(flagStr(args, "port")) || undefined, maxClients: Number(flagStr(args, "max-clients")) || undefined }
+      : flagStr(args, "connect")
+        ? { role: "client", address: flagStr(args, "connect") }
+        : undefined,
+  })
+}
+
+const status = async () => {
+  const selected = selectedDesktopVersion()
+  const installed = installedDesktopVersions()
+  log(`renders with    ${selected}${installed.includes(selected) ? "" : c.dim("  (not downloaded yet — fetched on first render)")}`)
+  log(`CLI minimum     ${DESKTOP_RENDERER_VERSION}`)
+  log(`downloaded      ${installed.length > 0 ? installed.join(", ") : c.dim("none")}   ${c.dim("(~/.lecodes/renderer)")}`)
+  if (process.env.LECODES_DESKTOP_EXE) log(`override        LECODES_DESKTOP_EXE=${process.env.LECODES_DESKTOP_EXE}`)
+  if (process.platform === "darwin") {
+    // The cache is what runs/builds use; a hand-installed app only steps in when the manifest is unreachable.
+    const installed = findMacHostExe()
+    log(`installed       ${installed ?? c.dim("none")}   ${c.dim("(offline fallback only)")}`)
+  }
+  try {
+    const { latest } = await fetchDesktopManifest()
+    const hint = semverNewer(selected, latest) > 0
+      ? c.yellow("(newer — run `lecodes desktop update`)")
+      : latest === selected
+        ? c.dim("(up to date)")
+        : c.dim("(older than the CLI's minimum — this desktop release isn't published yet)")
+    log(`published       ${latest}   ${hint}`)
+  } catch {
+    log(`published       ${c.dim("unknown (couldn't reach the release manifest)")}`)
+  }
+}
+
+export const desktop = async (args: Args) => {
+  const sub = args._[0]
+  if (sub === undefined) return status()
+  if (sub === "run") return run(args)
+  // `buildDesktop` reads only flags, never positionals, so it takes both spellings unchanged.
+  if (sub === "build") return buildDesktop(args)
+  if (sub === "update") return updateDesktop()
+  throw new CliError(`Unknown subcommand "desktop ${sub}". Use \`lecodes desktop\` (status), \`lecodes desktop run\`, \`lecodes desktop build\` or \`lecodes desktop update\`.`)
+}

package/src/commands/dev.ts

@@ -0,0 +1,214 @@
+import { existsSync, mkdirSync, readFileSync, watch, writeFileSync, type FSWatcher } from "node:fs"
+import { randomBytes } from "node:crypto"
+import { networkInterfaces } from "node:os"
+import { basename, join } from "node:path"
+import { findProjectRoot, readManifest, LECODES_DIR, type Manifest } from "../manifest"
+import { loadIgnore } from "../ignore"
+import { startDevServer } from "../dev/devServer"
+import { runDesktopDev } from "../desktopRenderer"
+import { readAppConfigAt } from "./appShared"
+import { resolveScale } from "./desktop"
+import { CliError, c, flagBool, flagStr, log, note, toKey, warnErr, type Args } from "../util"
+
+/*
+ * `lecodes dev` — run the project on a device straight from this machine, with hot reload.
+ *
+ * Starts a LAN dev server (compile + assets + reload channel), prints a QR code, and watches the
+ * working tree. The device opens the QR URL like any project URL; every save recompiles and
+ * hot-swaps the running app (`_creatorUtils.run` — fresh context, rollback on error). Device
+ * console output and errors stream back to this terminal. Fully local: no login, no le.codes
+ * backend. Custom shaders compile locally too (matc, downloaded on first use — matcTool.ts);
+ * only when matc can't be fetched do they fall back to server-compiled artifacts (push once).
+ *
+ * Works inside a cloned project or standalone in any folder with an entry .ts file.
+ * The desktop host speaks websocket since 1.0.0 (host_ws); `?t=poll` remains the fallback
+ * for older desktop builds (or any host without a websocket bridge).
+ */
+
+const DEFAULT_PORT = 4499
+const DEBOUNCE_MS = 120
+
+// Never trigger a recompile (mirrors scanLocal's skip lists + our own artifacts).
+const WATCH_SKIP_DIRS = new Set([".lecodes", ".git", "node_modules"])
+const WATCH_SKIP_FILES = new Set(["tsconfig.json", "jsconfig.json", ".gitignore", ".lecodesignore", ".DS_Store"])
+
+/*
+ * The origin a phone on the same Wi-Fi can reach, best first.
+ *
+ * `net.internal` is NOT enough on its own: in Node it only means loopback, so a WSL/Docker/Hyper-V
+ * bridge or a VPN tap counts as a normal external interface and wins whenever the OS enumerates it
+ * first. Those are host-only — the device dials them and hangs until the socket times out, which is
+ * a confusing way to learn your dev URL was never reachable. So rank instead of taking the first:
+ * de-prioritise virtual-looking adapter names, then Docker/WSL's 172.16–31 block, then plain
+ * 169.254 link-local. Ties keep OS order. Anything genuinely ambiguous (Ethernet AND Wi-Fi on
+ * different subnets, as here) is unknowable from this side — hence `lanCandidates` in the printout
+ * and `--host`.
+ */
+const VIRTUAL_IFACE = /wsl|docker|hyper-v|vethernet|virtualbox|vmware|tap|tun|zerotier|tailscale|loopback/i
+
+const lanCandidates = (): { address: string, iface: string }[] => {
+  const nets = networkInterfaces()
+  const out: { address: string, iface: string, rank: number }[] = []
+  for (const iface of Object.keys(nets)) {
+    for (const net of nets[iface] ?? []) {
+      if (net.family !== "IPv4" || net.internal) continue
+      const a = net.address
+      let rank = 0
+      if (VIRTUAL_IFACE.test(iface)) rank += 4
+      if (/^172\.(1[6-9]|2\d|3[01])\./.test(a)) rank += 2   // Docker/WSL default pools live here
+      if (a.startsWith("169.254.")) rank += 8                // link-local: no DHCP, rarely routable
+      out.push({ address: a, iface, rank })
+    }
+  }
+  return out.sort((x, y) => x.rank - y.rank).map(({ address, iface }) => ({ address, iface }))
+}
+
+/** The per-project dev token, persisted so the QR/URL stays stable across runs. */
+const loadDevToken = (root: string): string => {
+  const path = join(root, LECODES_DIR, "dev.json")
+  try {
+    const token = (JSON.parse(readFileSync(path, "utf8")) as { token?: string }).token
+    if (token && /^[a-z0-9]{8,}$/.test(token)) return token
+  } catch { /* first run */ }
+  const token = randomBytes(6).toString("hex")
+  mkdirSync(join(root, LECODES_DIR), { recursive: true })
+  writeFileSync(path, JSON.stringify({ token }, null, 2) + "\n")
+  return token
+}
+
+/** Print a scannable QR for the URL (qrcode-terminal is bundled; URL-only if it ever fails). */
+const printQr = async (url: string) => {
+  try {
+    const qrcode = (await import("qrcode-terminal")).default
+    await new Promise<void>((resolve) => qrcode.generate(url, { small: true }, (out: string) => { log(out); resolve() }))
+  } catch {
+    note("(couldn't render a QR code — open the URL below on the device)")
+  }
+}
+
+export const dev = async (args: Args) => {
+  // Inside a cloned project the server runs at its root; anywhere else it runs standalone against
+  // the current directory (no login / manifest needed) — same rule as `lecodes design`.
+  let root: string
+  let manifest: Manifest | null
+  try {
+    root = findProjectRoot(process.cwd())
+    manifest = readManifest(root)
+  } catch {
+    root = process.cwd()
+    manifest = null
+  }
+  const name = manifest?.name ?? basename(root)
+
+  // Bun's node:http can't complete a websocket upgrade (writes to the upgraded socket are dropped),
+  // so the reload push would silently never reach devices. Node is the shipped runtime.
+  if (typeof (globalThis as { Bun?: unknown }).Bun !== "undefined") {
+    warnErr("Running under Bun: the websocket reload channel doesn't work here — run `lecodes dev` with Node (or use ?t=poll on the device URL).")
+  }
+
+  const port = Number(flagStr(args, "port")) || DEFAULT_PORT
+  const candidates = lanCandidates()
+  const host = flagStr(args, "host") ?? candidates[0]?.address
+  if (!host) throw new CliError("No LAN address found — pass one with --host <ip>.")
+  // A machine with several NICs can only be disambiguated by the human: name the runners-up so a
+  // device that can't reach the printed URL is one --host away from working, not a debugging session.
+  const alternatives = candidates.filter((c) => c.address !== host)
+  const origin = `http://${host}:${port}`
+  const token = loadDevToken(root)
+
+  const server = await startDevServer({
+    root, manifest, name, origin, port, token,
+    entryOverride: flagStr(args, "entry"),
+    log: note,
+  }).catch((e: unknown) => {
+    const msg = e instanceof Error ? e.message : String(e)
+    throw new CliError(msg.includes("EADDRINUSE") ? `Port ${port} is already in use — pass --port <n>.` : msg)
+  })
+
+  note("Compiling…")
+  const first = await server.recompile()
+  if (first.ok) {
+    for (const w of first.warnings) warnErr(w)
+  } else {
+    warnErr(`Compile failed — fix it and save; devices connect once it compiles:\n${first.error}`)
+  }
+
+  // ---- watcher: debounced whole-project recompile; a successful compile broadcasts the reload ----
+  const ignore = loadIgnore(root)
+  const shouldRecompile = (file: string | null): boolean => {
+    if (file === null) return true // event without a filename — assume project content
+    const parts = file.replace(/\\/g, "/").split("/")
+    if (parts.some((p) => WATCH_SKIP_DIRS.has(p))) return false
+    if (WATCH_SKIP_FILES.has(parts[parts.length - 1])) return false
+    try {
+      const key = toKey(file)
+      if (ignore(key, false)) return false
+    } catch { return false }
+    return true
+  }
+
+  const debug = process.env.LECODES_DEV_DEBUG === "1"
+  let timer: NodeJS.Timeout | null = null
+  const onChange = (file: string | null) => {
+    if (debug) note(`[watch] event: ${file ?? "(null)"} → ${shouldRecompile(file) ? "recompile" : "skip"}`)
+    if (!shouldRecompile(file)) return
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(async () => {
+      timer = null
+      const result = await server.recompile()
+      if (!result.ok) {
+        warnErr(`Compile failed (devices keep the last good version):\n${result.error}`)
+      } else if (result.changed) {
+        const devices = server.clientCount()
+        note(`✓ v${result.v} → ${devices} device${devices === 1 ? "" : "s"}`)
+        for (const w of result.warnings) warnErr(w)
+      }
+    }, DEBOUNCE_MS)
+  }
+
+  let watcher: FSWatcher | null = null
+  try {
+    watcher = watch(root, { recursive: true }, (_type, file) => onChange(file))
+  } catch {
+    warnErr("fs.watch(recursive) unavailable on this platform — hot reload disabled (restart to pick up changes).")
+  }
+  watcher?.on("error", (e) => warnErr(`Watcher error — hot reload may have stopped (restart lecodes dev): ${e.message}`))
+
+  // ---- banner ------------------------------------------------------------------------------------
+  log("")
+  log(`${c.bold("LeCodes Dev")} — ${name}`)
+  log("")
+  if (!flagBool(args, "no-qr")) await printQr(server.url)
+  log(`Scan the QR with the LeCodes app, or open:  ${c.bold(server.url)}`)
+  note(`Older desktop builds (no websocket bridge): ${server.url}?t=poll`)
+  if (alternatives.length > 0) {
+    note(`Device can't reach it? This machine also has ${alternatives.map((a) => `${a.address} (${a.iface})`).join(", ")} — retry with --host <ip>.`)
+  }
+  if (existsSync(join(root, LECODES_DIR, "manifest.json"))) note(`Token stored in ${LECODES_DIR}/dev.json (delete it to rotate the URL).`)
+  log("")
+  log(`Watching ${root} — save a file to hot-reload. Ctrl+C to stop.`)
+
+  // --desktop: open the dev URL in the native host too (same server, same hot reload — the host
+  // speaks the websocket channel). Window config comes from app.json's desktop block. The window
+  // closing does NOT stop the server: phones stay connected, and re-running with --desktop is the
+  // reopen. Errors (host not downloadable, unsupported OS) degrade to a warning — the QR path
+  // must keep working.
+  if (flagBool(args, "desktop")) {
+    const appCfg = readAppConfigAt(root)
+    const win = appCfg?.desktop?.window
+    note("Opening LeCodes Desktop against the dev server…")
+    // scale IS forwarded (density changes how the app looks — dev should match production);
+    // fullscreen deliberately is NOT (a fullscreen dev window hides the terminal).
+    void runDesktopDev(server.url, {
+      width: win?.width, height: win?.height,
+      minWidth: win?.minWidth, minHeight: win?.minHeight,
+      resizable: win?.resizable,
+      title: win?.title ?? appCfg?.name ?? name,
+      scale: resolveScale(undefined, win?.scale),
+      fps: flagBool(args, "fps"),
+    }).then(
+      () => note("Desktop window closed — the dev server keeps running (Ctrl+C to stop)."),
+      (e: unknown) => warnErr(`Desktop host: ${e instanceof Error ? e.message : String(e)}`),
+    )
+  }
+}

package/src/commands/diff.ts

@@ -0,0 +1,59 @@
+import { getProject } from "../api"
+import { loadConfig, requireApiUrl, requireToken } from "../config"
+import { findProjectRoot, readManifest } from "../manifest"
+import { scanProject } from "../localFiles"
+import { computeServerDiff, type ServerDiffEntry } from "../serverDiff"
+import { unifiedDiff } from "../textDiff"
+import { c, info, log, flagBool, toKey, type Args } from "../util"
+
+/*
+ * `lecodes diff [path…]` — compare the local working tree against the project's CURRENT server state
+ * and print a unified diff. The "+" side is local, the "-" side is the server, so it answers "what
+ * would my push change?" — including any edits made on the server (e.g. in the web editor) since you
+ * cloned. The headline use is conflict resolution before `push --force`.
+ *
+ *   --name-only   list changed paths + status instead of full diffs
+ *   [path…]       limit to these files / folders
+ */
+export const diff = async (args: Args) => {
+  const root = findProjectRoot(process.cwd())
+  const manifest = readManifest(root)
+  const config = loadConfig()
+  const apiUrl = requireApiUrl(config)
+  const token = requireToken(config)
+
+  info(c.dim("Comparing with the server…"))
+  const project = await getProject(apiUrl, token, manifest.uuid)
+  const scan = scanProject(root, manifest)
+  let entries = computeServerDiff(project, scan)
+
+  // Optional path filter (a file, or a folder prefix).
+  if (args._.length > 0) {
+    const keys = args._.map(toKey)
+    entries = entries.filter(e => keys.some(k => e.path === k || e.path.startsWith(k + "/")))
+  }
+
+  if (entries.length === 0) {
+    info(c.dim("No differences between local and server."))
+    return
+  }
+
+  if (flagBool(args, "name-only")) {
+    for (const e of entries) log(statusLabel(e) + e.path + (e.binary ? c.dim(" (binary)") : ""))
+    return
+  }
+
+  for (const e of entries) {
+    if (e.binary) {
+      log(statusLabel(e) + e.path + c.dim(" (binary — content not shown)"))
+      continue
+    }
+    const d = unifiedDiff(e.serverText ?? "", e.localText ?? "", `server${e.path}`, `local${e.path}`)
+    if (d) log("\n" + d)
+  }
+}
+
+const statusLabel = (e: ServerDiffEntry): string =>
+  e.status === "added" ? c.green("  added    ")
+    : e.status === "removed" ? c.red("  removed  ")
+    : c.yellow("  modified ")

package/src/commands/init.ts

@@ -0,0 +1,191 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { LECODES_DIR } from "../manifest"
+import { materializeTypesLocal, writeTsconfig } from "../types"
+import { DEFAULT_IGNORE_FILE, ensureGitignore } from "../ignore"
+import { appClaudeMd, CLAUDE_SETTINGS, STARTER_FLOW } from "./projectTemplates"
+import { c, flagBool, log, note, success, warnErr, type Args } from "../util"
+
+/*
+ * `lecodes init [dir]` — scaffold a brand-new LOCAL project: no account, no login, no server.
+ *
+ * Writes a starter entry, a CLAUDE.md (the headless render/test workflow for AI assistants) with
+ * a passing starter flow test, the SDK's import-free type surface + a tsconfig (so VS Code gives
+ * full IntelliSense offline), and a `.lecodesignore`. The result runs immediately with `lecodes dev`
+ * (hot reload on a device) and compiles with `lecodes compile -o app.js` (a self-contained bundle
+ * for LeCodes Desktop). It's the offline counterpart to `lecodes create`, which makes a project on
+ * the server; a local project needs no manifest — `dev`/`compile` compile straight from the tree.
+ *
+ * Idempotent: existing files are kept (never clobbered), so it's safe to re-run or run in a folder
+ * that already has content. Only the generated tsconfig + `.lecodes/types/` are rewritten each run.
+ */
+
+const STARTER = `// Welcome to LeCodes — the whole SDK is available as globals, no imports needed.
+// Run it live on a device with \`lecodes dev\`, or bundle it with \`lecodes compile -o app.js\`.
+
+let count = 0
+
+const counter = UIText({ color: "#9fb0d0", fontSize: 22, marginTop: 18 }, "Taps: 0")
+
+const button = UIButton(
+  {
+    backgroundColor: "#4f7cff",
+    borderRadius: 14,
+    paddingVertical: 16,
+    paddingHorizontal: 40,
+    marginTop: 24,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  [UIText({ color: "#ffffff", fontSize: 22 }, "Tap me")],
+)
+  .style({ name: "tap" }) // names make elements targetable in tests/*.flow.json (see CLAUDE.md)
+  .onClick(() => {
+    count++
+    counter.text = "Taps: " + count
+  })
+
+const screen = UIScreen(
+  { backgroundColor: "#1e2230", alignItems: "center", justifyContent: "center", padding: 40 },
+  [
+    UIColumn(
+      { backgroundColor: "#2b3550", borderRadius: 24, padding: 40, alignItems: "center" },
+      [UIText({ color: "#ffffff", fontSize: 32 }, "Hello, LeCodes"), button, counter],
+    ),
+  ],
+).style({ name: "home" }) // the screen root's name is what tests' \`expect: { screen: … }\` reads
+
+screen.open()
+`
+
+/** `--desktop`: declare the desktop target up front. Window sizes are logical units (the host
+ *  scales for HiDPI); `dev --desktop` / `desktop run` / `render --desktop` all read this, and a
+ *  desktop-only app.json makes headless render/test default to the window size too. */
+const appJsonDesktop = (name: string) => JSON.stringify({
+  name,
+  desktop: {
+    window: { width: 1280, height: 800, minWidth: 640, minHeight: 480 },
+  },
+}, null, 2) + "\n"
+
+const readmeTemplate = (name: string) => `# ${name}
+
+A LeCodes app. The whole SDK is available as globals (\`UIScreen\`, \`UIText\`, \`Scene2D\`, …) —
+no imports needed. \`main.ts\` is the entry point.
+
+## Run it
+
+\`\`\`
+lecodes dev                  # live on your phone: scan the QR with the LeCodes app, hot reload
+lecodes compile -o app.js    # bundle to a single self-contained JS file
+\`\`\`
+
+## Test it (no device needed)
+
+\`\`\`
+lecodes render --png shot.png    # headless screenshot of the running app
+lecodes test                     # run tests/*.flow.json — the starter ships with a passing one
+\`\`\`
+
+Scenario format + conventions: see [CLAUDE.md](./CLAUDE.md) (written for AI assistants, useful
+for humans too).
+
+## Put it on the platform
+
+This project is local-only. To give it a home on le.codes (web editor, sharing, OTA updates):
+
+\`\`\`
+lecodes login                    # once per machine
+lecodes link                     # create a project from this folder and connect it
+lecodes push -m "initial"        # upload it as the first checkpoint (--publish to go live)
+\`\`\`
+
+Already made the project in the web editor? \`lecodes link --project <uuid>\` adopts it — it
+shows what your next push would change there before connecting anything.
+
+## Go native
+
+\`\`\`
+lecodes app init ios         # generate a native Xcode shell in ios/
+lecodes app sync             # embed the compiled bundle + plugins into it
+lecodes app open             # open it in Xcode, build & run
+\`\`\`
+
+## Layout
+
+- \`main.ts\` — the app's entry point. Add more .ts files freely and import them from
+  \`main.ts\`; a file named \`main.ts\` is always the entry.
+- \`tests/\` — headless flow tests (\`lecodes test\`); failing steps dump the frame to
+  \`tests/.artifacts/\`
+- \`CLAUDE.md\` — guidance for AI assistants (the headless feedback loop + testability conventions)
+- \`assets/\` — images/fonts the app references (created on demand)
+- \`tsconfig.json\` + \`.lecodes/types/\` — generated IDE types (rewritten by the CLI; don't edit).
+  They come from the SDK bundled in the CLI; \`lecodes update\` refreshes them from the platform.
+- \`.lecodes/\` is gitignored — per-checkout state (those types + \`manifest.json\`, this machine's
+  sync cursor once linked). After a fresh git clone: \`lecodes update\`, then
+  \`lecodes link --project <uuid>\` to re-attach.
+- \`.lecodesignore\` — files a future \`lecodes push\` would skip
+
+Full command list: \`lecodes --help\`.
+`
+
+export const init = async (args: Args) => {
+  const dirArg = (args._[0] ?? ".").replace(/[/\\]+$/, "") || "."
+  const root = resolve(dirArg)
+  const name = basename(root)
+
+  mkdirSync(root, { recursive: true })
+
+  let created = 0
+  const write = (rel: string, content: string) => {
+    const abs = join(root, rel)
+    if (existsSync(abs)) { note(`kept      ${rel}`); return }
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, content)
+    log(`${c.green("created")}   ${rel}`)
+    created++
+  }
+
+  const forDesktop = flagBool(args, "desktop")
+
+  // Starter entry — a root file named main.ts is always the detected entrypoint.
+  write("main.ts", STARTER)
+  write("README.md", readmeTemplate(name))
+  // --desktop: an app.json declaring the desktop target (window config in logical units).
+  if (forDesktop) write("app.json", appJsonDesktop(name))
+  // AI-assistant guidance + a passing flow test: the headless loop is discoverable from day one.
+  write("CLAUDE.md", appClaudeMd(name))
+  write(".claude/settings.json", CLAUDE_SETTINGS)
+  write("tests/counter.flow.json", STARTER_FLOW)
+  // Keep local render/preview outputs (screenshot.png, shots/) out of any future push.
+  write(".lecodesignore", DEFAULT_IGNORE_FILE)
+  // .lecodes/ is per-checkout state (generated types + the push cursor) — keep it out of git.
+  const gi = ensureGitignore(root)
+  if (gi === "created") { log(`${c.green("created")}   .gitignore`); created++ }
+  else if (gi === "updated") log(`${c.green("updated")}   .gitignore  ${c.dim("(+ .lecodes/)")}`)
+  else note("kept      .gitignore")
+
+  // IDE types: the SDK's import-free global surface + a tsconfig, so VS Code resolves UIScreen,
+  // Scene2D, setLoop, … with no server. Regenerated every run to pick up CLI upgrades.
+  const wroteTypes = materializeTypesLocal(root)
+  writeTsconfig(root)
+  log(`${c.green("written")}   tsconfig.json${wroteTypes ? ` + ${LECODES_DIR}/types/` : ""}  (IDE types)`)
+  if (!wroteTypes) {
+    warnErr("Bundled SDK types not found — tsconfig written, but globals may show unresolved until the CLI is rebuilt with vendored types.")
+  }
+
+  log("")
+  success(created
+    ? `Local project ${c.bold(name)} ready${dirArg === "." ? "" : ` in ${c.bold(dirArg)}/`}.`
+    : `Project ${c.bold(name)} already initialized.`)
+  const cd = dirArg === "." ? "" : `cd ${dirArg} && `
+  if (forDesktop) {
+    log(`  ${c.bold(cd + "lecodes dev --desktop")}      run it in a desktop window with hot reload`)
+    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (desktop-sized)`)
+    log(`  ${c.bold(cd + "lecodes desktop run")}        open the compiled app in the desktop host`)
+  } else {
+    log(`  ${c.bold(cd + "lecodes dev")}                run it on a device with hot reload`)
+    log(`  ${c.bold(cd + "lecodes test")}               run the flow tests headless (no device)`)
+    log(`  ${c.bold(cd + "lecodes compile -o app.js")}  bundle it for LeCodes Desktop`)
+  }
+}