lecodes-cli 2.3.0 → 2.4.0

package/src/commands/app/shared.ts

@@ -100,14 +100,21 @@ export interface AppConfig {
     /** 3D buffer cap in px, e.g. [1920, 1080]: on a bigger window/monitor the 3D renders at most
      *  this size (aspect kept) — the per-machine answer to "fullscreen on a 4K display is slow". */
     maxRenderSize?: [number, number],
-    /** Frame-rate CAP for the host's render loop: `"display"` (default — follow the screen's refresh
-     *  rate, 120 on a ProMotion Mac) or a number, meaning "at most this many fps" (the screen's
-     *  maximum still wins when it is lower — vsync is the real ceiling, so this can never be a
-     *  target above it). For an app that wants to spend less: a UI-heavy app on a laptop, a game
-     *  whose feel is tuned for 60. `desktop run` forwards it as CREATOR_FRAME_RATE (a set env wins);
-     *  a built .app's host reads it from the staged app.json. Honoured by the macOS host
-     *  (2026-09-09); the Windows/Linux host is vsync-locked and ignores it for now. */
+    /** Frame-rate CAP the host starts with: a number = "at most this many fps", `0` or `"display"`
+     *  (the default) = no cap — the display's own rate, or, with vsync off, as fast as the host
+     *  renders. The app changes it at runtime with `device.setFrameRate()`; this is the value in
+     *  force before the bundle runs. For an app that wants to spend less: a UI-heavy app on a
+     *  laptop, a game whose feel is tuned for 60. `desktop run` / `dev --desktop` forward it as
+     *  CREATOR_FRAME_RATE (a set env wins); a built folder's host reads it from the staged app.json.
+     *  Headless render/test ignore it (their frames are app-time steps). */
     frameRate?: number | "display",
+    /** Vertical sync the host starts with (default true). `false` presents without waiting for the
+     *  display's refresh: the lowest input latency, tearing possible — and with no `frameRate` cap
+     *  the loop renders as fast as it can, so set one unless you are measuring. The app switches it
+     *  at runtime with `device.setVsync()`. Forwarded as CREATOR_VSYNC (a set env wins), read from
+     *  the staged app.json by a built folder's host. Windows (GL: the swap interval; Vulkan: the
+     *  immediate present mode); the macOS and Linux hosts ignore it for now. */
+    vsync?: boolean,
     /** The mouse button acts as a finger: a left click-drag scrolls + flings like touch (the wheel
      *  always scrolls, clicks are unaffected; a button inside a scrollable then gets the touch-style
      *  press feedback delay). For testing the touch experience without a touchscreen, or an app

package/src/commands/desktop.ts

@@ -93,8 +93,9 @@ const run = defineCommand({
       // from app.json only. Both are desktop-level (the machine/app), not window-level.
       renderScale: resolveRenderScale(flags["render-scale"], appCfg?.desktop?.renderScale),
       maxRenderSize: appCfg?.desktop?.maxRenderSize,
-      // Frame-rate cap (app.json only — like renderScale it is a property of the app, not of a run).
+      // Frame-rate cap + vsync (app.json only — like renderScale they are properties of the app, not of a run).
       frameRate: appCfg?.desktop?.frameRate,
+      vsync: appCfg?.desktop?.vsync,
       mouseEmulateTouch: appCfg?.desktop?.mouseEmulateTouch,
       virtualKeyboard: appCfg?.desktop?.virtualKeyboard,
       // --fps: the host's own corner counter. A flag and not app.json on purpose — it is something you

package/src/commands/dev.ts

@@ -300,6 +300,7 @@ export default defineCommand({
         scale: resolveScale(undefined, win?.scale),
         // The frame-rate cap is forwarded too: it changes how the game FEELS, and dev should match production.
         frameRate: appCfg?.desktop?.frameRate,
+        vsync: appCfg?.desktop?.vsync,
         fps: flags.fps,
       }).then(
         () => note("Desktop window closed — the dev server keeps running (Ctrl+C to stop)."),

package/src/commands/init/index.ts

@@ -1,195 +1,195 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs"
-import { basename, dirname, join, resolve } from "node:path"
-import { LECODES_DIR } from "../../project/manifest"
-import { materializeTypesLocal, writeTsconfig } from "../../project/types"
-import { DEFAULT_IGNORE_FILE, ensureGitignore } from "../../project/ignore"
-import { appClaudeMd, CLAUDE_SETTINGS, STARTER_FLOW } from "./templates"
-import { bool, c, defineCommand, log, note, success, warnErr } from "../../cli"
-
-/*
- * `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("Taps: 0").style({ color: "#9fb0d0", fontSize: 22, marginTop: 18 })
-
-const button = UIButton(UIText("Tap me").style({ color: "#ffffff", fontSize: 22 }))
-  .style({
-    backgroundColor: "#4f7cff",
-    borderRadius: 14,
-    paddingVertical: 16,
-    paddingHorizontal: 40,
-    marginTop: 24,
-    alignItems: "center",
-    justifyContent: "center",
-    $hovered: { backgroundColor: "#6b91ff" }, // the mouse over it (desktop); $pressed is the press
-  })
-  .named("tap") // names make elements targetable in tests/*.flow.json (see CLAUDE.md)
-  .onClick(() => {
-    count++
-    counter.text = "Taps: " + count
-  })
-
-const screen = UIScreen(
-  UIColumn(UIText("Hello, LeCodes").style({ color: "#ffffff", fontSize: 32 }), button, counter)
-    .style({ backgroundColor: "#2b3550", borderRadius: 24, padding: 40, alignItems: "center" }),
-)
-  .style({ backgroundColor: "#1e2230", alignItems: "center", justifyContent: "center", padding: 40 })
-  .named("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 default defineCommand({
-  name: "init",
-  summary: "Scaffold a new LOCAL project (no login, no server)",
-  usage: "[dir]",
-  description: "Writes a starter main.ts, a CLAUDE.md + a passing flow test (the headless render / test loop), the IDE types + tsconfig, and a .lecodesignore. Run it with `lecodes dev` or `lecodes compile`. Idempotent: existing files are kept.",
-  flags: { desktop: bool("also write an app.json declaring the desktop target (window size; `dev --desktop`, `desktop run` and headless render / test pick it up)") },
-  examples: ["lecodes init myapp", "lecodes init --desktop"],
-  run: ({ args, flags }) => init(args[0], flags.desktop),
-})
-
-const init = (dir: string | undefined, forDesktop: boolean): void => {
-  const dirArg = (dir ?? ".").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++
-  }
-
-  // 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`)
-  }
-}
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { LECODES_DIR } from "../../project/manifest"
+import { materializeTypesLocal, writeTsconfig } from "../../project/types"
+import { DEFAULT_IGNORE_FILE, ensureGitignore } from "../../project/ignore"
+import { appClaudeMd, CLAUDE_SETTINGS, STARTER_FLOW } from "./templates"
+import { bool, c, defineCommand, log, note, success, warnErr } from "../../cli"
+
+/*
+ * `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("Taps: 0").style({ color: "#9fb0d0", fontSize: 22, marginTop: 18 })
+
+const button = UIButton(UIText("Tap me").style({ color: "#ffffff", fontSize: 22 }))
+  .style({
+    backgroundColor: "#4f7cff",
+    borderRadius: 14,
+    paddingVertical: 16,
+    paddingHorizontal: 40,
+    marginTop: 24,
+    alignItems: "center",
+    justifyContent: "center",
+    $hovered: { backgroundColor: "#6b91ff" }, // the mouse over it (desktop); $pressed is the press
+  })
+  .named("tap") // names make elements targetable in tests/*.flow.json (see CLAUDE.md)
+  .onClick(() => {
+    count++
+    counter.text = "Taps: " + count
+  })
+
+const screen = UIScreen(
+  UIColumn(UIText("Hello, LeCodes").style({ color: "#ffffff", fontSize: 32 }), button, counter)
+    .style({ backgroundColor: "#2b3550", borderRadius: 24, padding: 40, alignItems: "center" }),
+)
+  .style({ backgroundColor: "#1e2230", alignItems: "center", justifyContent: "center", padding: 40 })
+  .named("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 default defineCommand({
+  name: "init",
+  summary: "Scaffold a new LOCAL project (no login, no server)",
+  usage: "[dir]",
+  description: "Writes a starter main.ts, a CLAUDE.md + a passing flow test (the headless render / test loop), the IDE types + tsconfig, and a .lecodesignore. Run it with `lecodes dev` or `lecodes compile`. Idempotent: existing files are kept.",
+  flags: { desktop: bool("also write an app.json declaring the desktop target (window size; `dev --desktop`, `desktop run` and headless render / test pick it up)") },
+  examples: ["lecodes init myapp", "lecodes init --desktop"],
+  run: ({ args, flags }) => init(args[0], flags.desktop),
+})
+
+const init = (dir: string | undefined, forDesktop: boolean): void => {
+  const dirArg = (dir ?? ".").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++
+  }
+
+  // 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`)
+  }
+}

package/src/commands/shared.ts

@@ -1,79 +1,79 @@
-import { basename } from "node:path"
-import { bool, str, type FlagValues } from "../cli"
-import { loadConfig, requireApiUrl, requireToken } from "../platform/config"
-import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
-
-/*
- * What several commands share: the flag groups (spread into a command's `flags:`) and the
- * "where am I / who am I" lookups every platform command starts with.
- */
-
-// ---- flag groups -----------------------------------------------------------------------------
-
-/** How the project is compiled — `compile`, `dev`, `render`, `test`, `desktop run`, `app sync` … */
-export const bundleFlags = {
-  entry: str("compile from this entry instead of the detected one", { value: "<path>" }),
-  "public-url": str("resolve assets from this URL prefix (default: the API origin / the working tree)", { value: "<url>" }),
-  "remote-assets": bool("desktop hosts: load asset() resources from the server instead of the working tree"),
-  "no-header": bool("omit the metadata header"),
-  "no-minify": bool("keep the bundle readable (no compress / mangle)"),
-  "no-sourcemap": bool("don't generate / inline the source map"),
-}
-
-/** `-o` for commands whose result is a file. */
-export const outFlag = { out: str("write to this file instead of stdout", { alias: "o", value: "<file>" }) }
-
-/** The compiler's view of the bundle flags (see compile.ts `buildBundle`). */
-export type BundleOptions = {
-  entry?: string
-  publicUrl?: string
-  remoteAssets?: boolean
-  header?: boolean
-  minify?: boolean
-  sourcemap?: boolean
-}
-
-export const bundleOptions = (flags: FlagValues<typeof bundleFlags>): BundleOptions => ({
-  entry: flags.entry,
-  publicUrl: flags["public-url"],
-  remoteAssets: flags["remote-assets"],
-  header: !flags["no-header"],
-  // Both default on; `false` only when the flag is present, so the SDK's own defaults stand.
-  minify: flags["no-minify"] ? false : undefined,
-  sourcemap: flags["no-sourcemap"] ? false : undefined,
-})
-
-// ---- where / who -----------------------------------------------------------------------------
-
-export type Session = { apiUrl: string, token: string }
-
-/** The logged-in session (api origin + token) or a "run `lecodes login`" error. */
-export const session = (): Session => {
-  const config = loadConfig()
-  return { apiUrl: requireApiUrl(config), token: requireToken(config) }
-}
-
-export type LinkedProject = Session & { root: string, manifest: Manifest }
-
-/** A server-backed checkout: the project root (found upward from the cwd), its manifest and the session. */
-export const linkedProject = (): LinkedProject => {
-  const root = findProjectRoot(process.cwd())
-  return { root, manifest: readManifest(root), ...session() }
-}
-
-export type LocalProject = { root: string, manifest: Manifest | null, name: string }
-
-/** Any project: a linked checkout, else the current folder standing alone (no login needed). */
-export const localProject = (): LocalProject => {
-  try {
-    const root = findProjectRoot(process.cwd())
-    const manifest = readManifest(root)
-    return { root, manifest, name: manifest.name }
-  } catch {
-    const root = process.cwd()
-    return { root, manifest: null, name: basename(root) }
-  }
-}
-
-/** A folder name for a project: lower-case, dashes, never empty. */
-export const slugOf = (name: string): string => name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project"
+import { basename } from "node:path"
+import { bool, str, type FlagValues } from "../cli"
+import { loadConfig, requireApiUrl, requireToken } from "../platform/config"
+import { findProjectRoot, readManifest, type Manifest } from "../project/manifest"
+
+/*
+ * What several commands share: the flag groups (spread into a command's `flags:`) and the
+ * "where am I / who am I" lookups every platform command starts with.
+ */
+
+// ---- flag groups -----------------------------------------------------------------------------
+
+/** How the project is compiled — `compile`, `dev`, `render`, `test`, `desktop run`, `app sync` … */
+export const bundleFlags = {
+  entry: str("compile from this entry instead of the detected one", { value: "<path>" }),
+  "public-url": str("resolve assets from this URL prefix (default: the API origin / the working tree)", { value: "<url>" }),
+  "remote-assets": bool("desktop hosts: load asset() resources from the server instead of the working tree"),
+  "no-header": bool("omit the metadata header"),
+  "no-minify": bool("keep the bundle readable (no compress / mangle)"),
+  "no-sourcemap": bool("don't generate / inline the source map"),
+}
+
+/** `-o` for commands whose result is a file. */
+export const outFlag = { out: str("write to this file instead of stdout", { alias: "o", value: "<file>" }) }
+
+/** The compiler's view of the bundle flags (see compile.ts `buildBundle`). */
+export type BundleOptions = {
+  entry?: string
+  publicUrl?: string
+  remoteAssets?: boolean
+  header?: boolean
+  minify?: boolean
+  sourcemap?: boolean
+}
+
+export const bundleOptions = (flags: FlagValues<typeof bundleFlags>): BundleOptions => ({
+  entry: flags.entry,
+  publicUrl: flags["public-url"],
+  remoteAssets: flags["remote-assets"],
+  header: !flags["no-header"],
+  // Both default on; `false` only when the flag is present, so the SDK's own defaults stand.
+  minify: flags["no-minify"] ? false : undefined,
+  sourcemap: flags["no-sourcemap"] ? false : undefined,
+})
+
+// ---- where / who -----------------------------------------------------------------------------
+
+export type Session = { apiUrl: string, token: string }
+
+/** The logged-in session (api origin + token) or a "run `lecodes login`" error. */
+export const session = (): Session => {
+  const config = loadConfig()
+  return { apiUrl: requireApiUrl(config), token: requireToken(config) }
+}
+
+export type LinkedProject = Session & { root: string, manifest: Manifest }
+
+/** A server-backed checkout: the project root (found upward from the cwd), its manifest and the session. */
+export const linkedProject = (): LinkedProject => {
+  const root = findProjectRoot(process.cwd())
+  return { root, manifest: readManifest(root), ...session() }
+}
+
+export type LocalProject = { root: string, manifest: Manifest | null, name: string }
+
+/** Any project: a linked checkout, else the current folder standing alone (no login needed). */
+export const localProject = (): LocalProject => {
+  try {
+    const root = findProjectRoot(process.cwd())
+    const manifest = readManifest(root)
+    return { root, manifest, name: manifest.name }
+  } catch {
+    const root = process.cwd()
+    return { root, manifest: null, name: basename(root) }
+  }
+}
+
+/** A folder name for a project: lower-case, dashes, never empty. */
+export const slugOf = (name: string): string => name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project"