lecodes-cli 2.2.11 → 2.2.14

package/src/cli/args.ts

@@ -3,7 +3,10 @@
  *   --key value   --key=value   --flag   -k value   -k     positionals anywhere
  * A token that starts with "-" followed by a digit (or ".5") is a negative NUMBER (or a vector
  * starting with one: `--look-at -0.15,1,2`), never the next flag. A repeated flag keeps the LAST
- * value (list-valued flags take commas). `--` ends flag parsing.
+ * value (list-valued flags take commas). `--` ends flag parsing. A flag the command declares as
+ * BOOLEAN never takes the next token as its value (`lecodes test --lite login` is the flag and
+ * the positional "login" — it used to read "login" as the flag's value, run every test headless
+ * and say nothing); only an explicit `true` / `false` after it, or `--flag=false`, is its value.
  */
 
 export type RawFlags = Record<string, string | boolean>
@@ -12,7 +15,7 @@ export type Parsed = { positional: string[], flags: RawFlags }
 const isNegativeNumber = (s: string): boolean => /^-(\d|\.\d)/.test(s)
 const isValue = (s: string): boolean => !s.startsWith("-") || isNegativeNumber(s)
 
-export const parseArgv = (argv: string[]): Parsed => {
+export const parseArgv = (argv: string[], booleans: ReadonlySet<string> = new Set()): Parsed => {
   const out: Parsed = { positional: [], flags: {} }
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i]
@@ -25,7 +28,11 @@ export const parseArgv = (argv: string[]): Parsed => {
     }
     const key = arg.slice(long ? 2 : 1)
     const next = argv[i + 1]
-    if (next !== undefined && isValue(next)) { out.flags[key] = next; i++ }
+    if (booleans.has(key)) {
+      if (next === "true" || next === "false") { out.flags[key] = next; i++ }
+      else out.flags[key] = true
+    }
+    else if (next !== undefined && isValue(next)) { out.flags[key] = next; i++ }
     else out.flags[key] = true
   }
   return out

package/src/cli/command.ts

@@ -105,6 +105,13 @@ export const readFlags = <F extends Flags>(spec: F, raw: RawFlags, path: string[
   return out as FlagValues<F>
 }
 
+/** The names (and aliases) of a spec's boolean flags: what the argv grammar must not read a value for. */
+export const booleanFlagNames = (spec: Flags): Set<string> => {
+  const names = new Set<string>()
+  for (const [name, s] of Object.entries(spec)) if (s.type === "boolean") { names.add(name); if (s.alias) names.add(s.alias) }
+  return names
+}
+
 /** Flags on the line that no spec names — reported as a warning by the runner. */
 export const unknownFlags = (spec: Flags, raw: RawFlags): string[] => {
   const known = new Set<string>()

package/src/cli/run.ts

@@ -1,3 +1,4 @@
+import { booleanFlagNames } from "./command"
 import { parseArgv } from "./args"
 import { readFlags, unknownFlags, type Command, type Context } from "./command"
 import { CliError, UsageError } from "./errors"
@@ -82,8 +83,8 @@ export const runCli = async (cli: Cli, argv: string[]): Promise<void> => {
     return
   }
 
-  const parsed = parseArgv(rest)
   const spec = node.flags ?? {}
+  const parsed = parseArgv(rest, booleanFlagNames(spec))
   if (!node.passthrough) {
     const unknown = unknownFlags(spec, parsed.flags)
     if (unknown.length) warnErr(`${unknown.map(f => `--${f}`).join(", ")}: not an option of \`lecodes ${path.join(" ")}\` (see --help)`)

package/src/commands/app/android.ts

@@ -10,7 +10,7 @@ import { upsertDotEnv } from "../../project/env"
 import {
   type AppConfig, ANDROID_SDK_VARIANTS, type AndroidSdkVariant, VERSION_RE, androidSdkArtifact, androidVariantEngines,
   childEnv, cmpVersion, ensureShellIgnored, fetchLatestSdkVersion,
-  projectRoot, readJson, resolvePlugin, resolveSdkVersion, resolveVariant, runTool, sdkSatisfies, slugify,
+  projectRoot, readAppConfigAt, readJson, resolvePlugin, resolveSdkVersion, resolveVariant, runTool, sdkSatisfies, slugify,
   writeJson, type LockEntry, resolveUpdateUrl, urlSchemeOf,
 } from "./shared"
 import { loadIconMaster, restampManifestIcon, writeAndroidIcons } from "./icon"
@@ -104,7 +104,7 @@ export const initAndroid = async (opts: AndroidInitOptions) => {
     throw new CliError("android/ already exists — run `lecodes app sync` to update it.")
   }
 
-  const existing = readJson<AppConfig>(join(root, "app.json")) ?? {}
+  const existing = readAppConfigAt(root) ?? {}
 
   const variant = opts.variant ?? existing.android?.variant ?? "auto"
   if (variant !== "auto" && !ANDROID_SDK_VARIANTS.includes(variant as AndroidSdkVariant)) {
@@ -249,7 +249,7 @@ export const syncAndroid = async (root: string, config: AppConfig, prior: SyncAr
     throw new CliError(`app.json android.variant must be "auto" or one of ${ANDROID_SDK_VARIANTS.join(", ")} (got "${requestedVariant}").`)
   }
   // vulkan is full's engines on another backend: the coverage check runs as full, the artifact is its own.
-  const { variant: covered, detected } = resolveVariant(
+  const { variant: covered, why } = resolveVariant(
     requestedVariant === "auto" ? "auto" : androidVariantEngines(requestedVariant as AndroidSdkVariant), bundleJs, "android.variant")
   const variant: AndroidSdkVariant = requestedVariant === "vulkan" ? "vulkan" : covered
   let sdkArtifact = androidSdkArtifact(variant, sdkVersion)
@@ -257,10 +257,7 @@ export const syncAndroid = async (root: string, config: AppConfig, prior: SyncAr
     warn(`lecodes-android-sdk ${sdkVersion} predates the variant matrix (${ANDROID_SDK_VARIANTS_MIN}) — linking the full lecodes-sdk AAR; run \`lecodes app update\` to pick up variant builds.`)
     sdkArtifact = "lecodes-sdk"
   }
-  const WHY: Record<string, string> = {
-    full: "3D + 2D engines in use", "3d": "3D in use, no 2D", "2d": "2D in use, no 3D", core: "no 3D/2D engine use detected",
-  }
-  log(`${c.green("variant")}   ${variant} → ${sdkArtifact}${requestedVariant === "auto" ? c.dim(`  (auto: ${WHY[detected]})`) : c.dim("  (forced by android.variant)")}`)
+  log(`${c.green("variant")}   ${variant} → ${sdkArtifact}${requestedVariant === "auto" ? c.dim(`  (auto: ${why})`) : c.dim("  (forced by android.variant)")}`)
 
   // ---- plugins: vendor sources as Gradle modules, generate their build files, pin the lock ----
   const lockPath = join(root, "plugins.lock.json")
@@ -532,7 +529,7 @@ const androidBuildFlags = {
 /** `lecodes app build android` — sync, Gradle, then the artifacts copied under dist/. */
 const buildAndroid = async (flags: FlagValues<typeof androidBuildFlags>): Promise<void> => {
   const root = projectRoot()
-  const config = readJson<AppConfig>(join(root, "app.json"))
+  const config = readAppConfigAt(root)
   const androidDir = join(root, "android")
   if (!config?.android || !existsSync(androidDir)) {
     throw new CliError("No Android shell here — run `lecodes app init android` first.")
@@ -779,7 +776,7 @@ const writeSigningConfig = (root: string, config: AppConfig, storeFile: string,
   }
 
   const configPath = join(root, "app.json")
-  const fresh = readJson<AppConfig>(configPath) ?? config
+  const fresh = readAppConfigAt(root) ?? config
   fresh.android = { ...(fresh.android ?? {}), signing: { storeFile: envPath, keyAlias: alias } }
   writeJson(configPath, fresh)
   log(`${c.green("written")}   app.json  (android.signing — metadata only, no passwords)`)
@@ -799,7 +796,7 @@ const PLAY_APP_SIGNING_NOTE = "With Play App Signing (default for new Play apps)
 /** Every keystore subcommand starts from the project + its app.json (which may not exist yet). */
 const keystoreProject = (): { root: string, config: AppConfig } => {
   const root = projectRoot()
-  return { root, config: readJson<AppConfig>(join(root, "app.json")) ?? {} }
+  return { root, config: readAppConfigAt(root) ?? {} }
 }
 
 const passwordFlag = { password: str("keystore password (else asked on the terminal)", { value: "<pw>" }) }

package/src/commands/app/desktop.ts

@@ -5,7 +5,7 @@ import { buildBundle } from "../compile"
 import { resolveDesktopExe, selectedDesktopVersion } from "../../hosts/desktopRenderer"
 import { CliError, bool, c, defineCommand, log, note, num, str, success, warn, type FlagValues } from "../../cli"
 import { bundleFlags, bundleOptions } from "../shared"
-import { desktopPluginLibraries, projectRoot, readJson, resolveDesktopRenderer, writeJson, type AppConfig } from "./shared"
+import { desktopPluginLibraries, projectRoot, readAppConfigAt, readJson, resolveDesktopRenderer, writeJson, type AppConfig } from "./shared"
 import { loadIconMaster } from "./icon"
 import { buildMacApp, macHostProvidedNames } from "./desktopMac"
 
@@ -41,7 +41,7 @@ export interface DesktopInitOptions { name?: string, fullscreen?: boolean }
  *  `lecodes init --desktop` for existing projects). Purely additive; re-running keeps edits. */
 export const initDesktop = async (opts: DesktopInitOptions): Promise<void> => {
   const root = projectRoot()
-  const existing = readJson<AppConfig>(join(root, "app.json")) ?? {}
+  const existing = readAppConfigAt(root) ?? {}
   const name = opts.name ?? existing.name ?? basename(root)
   const window = {
     width: 1280, height: 800, minWidth: 640, minHeight: 480,
@@ -82,7 +82,7 @@ const desktopBuildFlags = {
 
 const buildDesktop = async (flags: FlagValues<typeof desktopBuildFlags>): Promise<void> => {
   const root = projectRoot()
-  const config = readJson<AppConfig>(join(root, "app.json")) ?? {}
+  const config = readAppConfigAt(root) ?? {}
   const name = (config.name ?? basename(root)).trim() || "app"
   const slug = flags.slug ?? cleanFileName(name)
   const out = resolve(root, flags.out ?? join(root, "dist", slug))

package/src/commands/app/index.ts

@@ -13,7 +13,7 @@ import {
 } from "./templates/ios"
 import {
   FIRST_PARTY_PLUGINS, SDK_VARIANTS, cmpVersion, ensureShellIgnored,
-  fetchLatestSdkVersion, isLocalPluginSpec, latestPluginTag, projectRoot, readJson, resolvePlugin, resolveSdkVersion, sdkSatisfies,
+  fetchLatestSdkVersion, isLocalPluginSpec, latestPluginTag, projectRoot, readAppConfigAt, readJson, resolvePlugin, resolveSdkVersion, sdkSatisfies,
   resolveVariant, runTool, slugify, writeJson, VERSION_RE, type AppConfig, type LockEntry, resolveUpdateUrl, urlSchemeOf,
 } from "./shared"
 import {
@@ -111,7 +111,7 @@ const initIos = async (opts: IosInitOptions): Promise<void> => {
     throw new CliError("ios/ already exists — run `lecodes app sync` to update it.")
   }
 
-  const existing = readJson<AppConfig>(join(root, "app.json")) ?? {}
+  const existing = readAppConfigAt(root) ?? {}
   const variant = opts.variant ?? existing.ios?.variant ?? "auto"
   if (variant !== "auto" && !SDK_VARIANTS.includes(variant as SdkVariant)) {
     throw new CliError(`--variant must be auto, ${SDK_VARIANTS.join(", ")} (got "${variant}")`)
@@ -216,7 +216,7 @@ const init = defineCommand({
  *  the byte-identical output. `app update` and `app build ios` run it too. */
 export const runSync = async (platformArg?: string): Promise<void> => {
   const root = projectRoot()
-  const config = readJson<AppConfig>(join(root, "app.json"))
+  const config = readAppConfigAt(root)
   const platform = mobilePlatform(platformArg)
   const { hasIos, hasAndroid } = shellsOf(root, config)
   if (platform === "ios" && !hasIos) throw new CliError(NO_IOS_SHELL)
@@ -312,11 +312,8 @@ const syncIos = async (root: string, config: AppConfig): Promise<SyncArtifacts>
 
   // ---- variant: the smallest SDK product covering what the bundle uses (or the forced one) ----
   const bundleJs = readFileSync(join(resourcesDir, "app.js"), "utf8")
-  const { variant, detected } = resolveVariant(requestedVariant, bundleJs)
-  const WHY: Record<SdkVariant, string> = {
-    core: "UI only", "2d": "uses the 2D engine", "3d": "uses the 3D engine", full: "uses the 3D + 2D engines",
-  }
-  log(`${c.green("variant")}   ${variant}${requestedVariant === "auto" ? ` (auto: ${WHY[detected]})` : " (forced by ios.variant)"}`)
+  const { variant, why } = resolveVariant(requestedVariant, bundleJs)
+  log(`${c.green("variant")}   ${variant}${requestedVariant === "auto" ? ` (auto: ${why})` : " (forced by ios.variant)"}`)
   const sdkWhy = sdkPin === "latest" ? "latest" : config.ios.sdk ? "pinned by ios.sdk" : "from the shell — set ios.sdk or run `lecodes app update`"
   log(`${c.green("sdk")}       lecodes-ios-sdk ${sdkVersion}${c.dim(`  (${sdkWhy})`)}`)
 
@@ -449,7 +446,7 @@ const sync = defineCommand({
 const pluginConfig = (): { root: string, configPath: string, config: AppConfig & { plugins: Record<string, string> } } => {
   const root = projectRoot()
   const configPath = join(root, "app.json")
-  const config = readJson<AppConfig>(configPath)
+  const config = readAppConfigAt(root)
   if (!config) throw new CliError("No app.json here — run `lecodes app init <ios|android>` first.")
   config.plugins ??= {}
   return { root, configPath, config: config as AppConfig & { plugins: Record<string, string> } }
@@ -572,7 +569,7 @@ export interface AppUpdateOptions { platform?: string, sdk?: string, check?: boo
  *  `lecodes update` runs it as its shells step. */
 export const runAppUpdate = async (opts: AppUpdateOptions = {}): Promise<void> => {
   const root = projectRoot()
-  const config = readJson<AppConfig>(join(root, "app.json"))
+  const config = readAppConfigAt(root)
   const platform = mobilePlatform(opts.platform)
   const { hasIos, hasAndroid } = shellsOf(root, config)
   if (platform === "ios" && !hasIos) throw new CliError(NO_IOS_SHELL)
@@ -756,7 +753,7 @@ const doctor = defineCommand({
   examples: ["lecodes app doctor"],
   run: async () => {
     const root = projectRoot()
-    const config = readJson<AppConfig>(join(root, "app.json"))
+    const config = readAppConfigAt(root)
     const { hasIos, hasAndroid } = shellsOf(root, config)
     if (!hasIos && !hasAndroid) throw new CliError(NO_IOS_SHELL)
     let failed = 0
@@ -805,7 +802,7 @@ const exportOptionsPlist = (method: string, teamId: string, destination?: "uploa
 
 const requireShell = (): { root: string, config: AppConfig } => {
   const root = projectRoot()
-  const config = readJson<AppConfig>(join(root, "app.json"))
+  const config = readAppConfigAt(root)
   if (!config?.ios || !existsSync(join(root, "ios"))) throw new CliError(NO_IOS_SHELL)
   return { root, config }
 }
@@ -905,7 +902,7 @@ const iosUpload = defineCommand({
 
     // A successful upload consumes this build number — bump for the next one.
     const configPath = join(root, "app.json")
-    const fresh = readJson<AppConfig>(configPath)!
+    const fresh = readAppConfigAt(root)!
     fresh.ios!.buildNumber = (fresh.ios!.buildNumber ?? 1) + 1
     writeJson(configPath, fresh)
     success(`Uploaded build ${(fresh.ios!.buildNumber ?? 2) - 1} — check App Store Connect / TestFlight once processing finishes.`)

package/src/commands/app/shared.ts

@@ -7,6 +7,7 @@ import { loadConfig, requireApiUrl } from "../../platform/config"
 import { DEFAULT_IGNORE_FILE } from "../../project/ignore"
 import { CliError, c, log, note, warn } from "../../cli"
 import { pascal, readManifest as readPluginManifest, type IosPackage, type PluginManifest as PluginManifest2 } from "../../plugin/manifest"
+import { pluginSpecsOf } from "lecodes-sdk/compile"
 
 /** The 2.x manifest (plugin/manifest.ts), plus the desktop branch the desktop flow reads: a
  *  PREBUILT shared library per OS/arch behind the C ABI in hosts/desktop/plugin-sdk — another
@@ -71,7 +72,7 @@ export interface AppConfig {
    *  `variant`: SDK artifact — "auto" (default: sync picks the smallest one covering the engines
    *  the compiled bundle actually uses) or core|2d|3d|full to force one, like ios.variant
    *  (needs lecodes-android-sdk >= 1.3.0 — older releases ship only the full AAR); "vulkan" = full
-   *  on Filament's Vulkan backend, arm64 only, never auto-picked (lecodes-android-sdk >= 2.1.0).
+   *  on Filament's Vulkan backend, arm64 only, never auto-picked (lecodes-android-sdk >= 2.2.11).
    *  `signing`: keystore METADATA only (written by `lecodes app keystore create|use`) — the
    *  path + passwords live in the project .env as LECODES_ANDROID_* (or android/
    *  keystore.properties for Studio-only builds), never in app.json.
@@ -216,8 +217,13 @@ export const urlSchemeOf = (config: Pick<AppConfig, "urlScheme"> | null | undefi
 /** app.json wherever a command needs the project-level desktop/window config. Tolerant of a
  *  missing or broken file — standalone projects (no app.json) must keep working everywhere
  *  this is consulted. */
-export const readAppConfigAt = (root: string): AppConfig | null =>
-  readJson<AppConfig>(join(root, "app.json"))
+export const readAppConfigAt = (root: string): AppConfig | null => {
+  const config = readJson<AppConfig & { plugins?: unknown }>(join(root, "app.json"))
+  // `"plugins"` is read in either shape (`["camera"]` or `{ "camera": "*" }`, the SDK's rule):
+  // every command below works on id → spec, and a list read as "no plugins" vendored nothing.
+  if (config && "plugins" in config) config.plugins = pluginSpecsOf(config.plugins)
+  return config as AppConfig | null
+}
 
 /** The desktop host's own built-in fallback, mirrored where the CLI must fill a missing side. */
 export const DESKTOP_DEFAULT_WINDOW = { width: 1280, height: 720 }
@@ -361,36 +367,56 @@ export const ensureShellIgnored = (root: string, dir: string) => {
 export const SDK_VARIANTS = ["core", "2d", "3d", "full"] as const
 type SdkVariantShared = (typeof SDK_VARIANTS)[number]
 
+export type EngineUse = { gl: boolean, g2: boolean, physics: boolean, net: boolean, nav: boolean, audio: boolean }
+
 /** Engine signals from a compiled bundle's header — the same lines buildHeader emits.
  *  No `// gl: disable` line → the 3D engine is used (eagerly, or lazily via `gl: defer`);
- *  `// 2d: enable` → the 2D engine is used. */
-export const detectEngines = (bundleJs: string): { gl: boolean, g2: boolean } => {
+ *  `// 2d: enable` → the 2D engine is used; `// physics|net|nav|audio: enable` → that part of the
+ *  game stack is called (a bundle older than those lines reads as using none). */
+export const detectEngines = (bundleJs: string): EngineUse => {
   const lines: string[] = []
   for (const line of bundleJs.split("\n")) {
     if (!line.startsWith("//")) break
     lines.push(line)
   }
   const header = lines.join("\n")
-  return { gl: !/^\/\/ gl: disable$/m.test(header), g2: /^\/\/ 2d: enable$/m.test(header) }
+  const on = (name: string) => new RegExp(`^// ${name}: enable$`, "m").test(header)
+  return { gl: !/^\/\/ gl: disable$/m.test(header), g2: on("2d"), physics: on("physics"), net: on("net"), nav: on("nav"), audio: on("audio") }
 }
 
+/** What each variant carries, the switch tables of hosts/apple/build-apple.sh and
+ *  hosts/android/build-android.ps1: `3d` = Filament alone (no Jolt, net, nav; on iOS no game
+ *  audio); `2d` / `core` = no Filament, no Jolt, net or nav (game audio stays on iOS; Android
+ *  links it in no variant). */
+const VARIANT_LACKS: Record<SdkVariantShared, (keyof EngineUse)[]> = {
+  full: [],
+  "3d": ["g2", "physics", "net", "nav", "audio"],
+  "2d": ["gl", "physics", "net", "nav"],
+  core: ["gl", "g2", "physics", "net", "nav"],
+}
+const ENGINE_WORDS: Record<keyof EngineUse, string> = { gl: "3D", g2: "2D", physics: "physics", net: "multiplayer", nav: "navigation", audio: "game audio" }
+
+/** The engines of `uses` the variant does not carry, in words ("3D + physics"). */
+const lacks = (variant: SdkVariantShared, uses: EngineUse): string[] =>
+  VARIANT_LACKS[variant].filter((e) => uses[e]).map((e) => ENGINE_WORDS[e])
+
 /** The SDK product for a shell: the smallest variant covering the engines the compiled bundle
  *  actually uses, unless <configKey> (ios.variant / android.variant) forces one — then warn when
  *  the forced product can't run the project (missing engine = those scenes silently no-op on
- *  device). */
-export const resolveVariant = (requested: string, bundleJs: string, configKey = "ios.variant"): { variant: SdkVariantShared, detected: SdkVariantShared } => {
+ *  device, Physics.configure throws). `why` says what the auto pick rests on. */
+export const resolveVariant = (requested: string, bundleJs: string, configKey = "ios.variant"): { variant: SdkVariantShared, detected: SdkVariantShared, why: string } => {
   const uses = detectEngines(bundleJs)
-  const detected: SdkVariantShared = uses.gl && uses.g2 ? "full" : uses.gl ? "3d" : uses.g2 ? "2d" : "core"
-  if (requested === "auto") return { variant: detected, detected }
+  // The smallest variant that lacks nothing the bundle uses (SDK_VARIANTS is ordered by size).
+  const detected = SDK_VARIANTS.find((v) => lacks(v, uses).length === 0) ?? "full"
+  const inUse = (Object.keys(ENGINE_WORDS) as (keyof EngineUse)[]).filter((e) => uses[e]).map((e) => ENGINE_WORDS[e])
+  const why = inUse.length > 0 ? `uses ${inUse.join(" + ")}` : "UI only, no engine use detected"
+  if (requested === "auto") return { variant: detected, detected, why }
   const variant = requested as SdkVariantShared
-  const missing = [
-    uses.gl && variant !== "3d" && variant !== "full" ? "3D" : null,
-    uses.g2 && variant !== "2d" && variant !== "full" ? "2D" : null,
-  ].filter(Boolean)
+  const missing = lacks(variant, uses)
   if (missing.length > 0) {
-    warn(`project uses the ${missing.join(" + ")} engine but ${configKey} forces "${variant}" — those scenes won't run on device; remove ${configKey} to auto-select "${detected}".`)
+    warn(`project uses ${missing.join(" + ")} but ${configKey} forces "${variant}", which has no such engine — that part won't run on device; remove ${configKey} to auto-select "${detected}".`)
   }
-  return { variant, detected }
+  return { variant, detected, why }
 }
 
 /* ------------------------------ Android: the vulkan variant ------------------------------ */
@@ -403,7 +429,7 @@ export const ANDROID_SDK_VARIANTS = [...SDK_VARIANTS, "vulkan"] as const
 export type AndroidSdkVariant = (typeof ANDROID_SDK_VARIANTS)[number]
 
 /** First lecodes-android-sdk release whose GitHub release carries lecodes-sdk-vulkan. */
-export const ANDROID_SDK_VULKAN_MIN = "2.1.0"
+export const ANDROID_SDK_VULKAN_MIN = "2.2.11"
 
 /** Release-asset / ivy artifact name of an Android variant — full keeps the historic plain name so
  *  pre-variant pins and shells keep resolving. vulkan refuses a release that has no such asset: Gradle

package/src/commands/app/templates/android.ts

@@ -286,7 +286,7 @@ engines the bundle uses and cannot see those, so a project using \`Physics\`,
 
 \`android.variant: "vulkan"\` links \`lecodes-sdk-vulkan\`: the full engine set with Filament on
 Vulkan (OpenGL ES where the device has no Vulkan 1.1), \`arm64-v8a\` only — for 3D games. Never
-auto-selected; needs lecodes-android-sdk >= 2.1.0.
+auto-selected; needs lecodes-android-sdk >= 2.2.11.
 
 ## App-local native code
 

package/src/commands/index.ts

@@ -16,8 +16,10 @@ import login from "./login"
 import navmesh from "./navmesh"
 import plugin from "./plugin"
 import pn from "./pn"
+import publish from "./publish"
 import pull from "./pull"
 import push from "./push"
+import releases from "./releases"
 import render from "./render"
 import scene from "./scene"
 import serve from "./serve"
@@ -33,7 +35,7 @@ import web from "./web"
  * here, in the group it belongs to (CONTRIBUTING.md). Order within a group is the help's order.
  */
 export const commandGroups = (opts: { install: boolean }): Group[] => [
-  { title: "Project", commands: [init, create, clone, link, status, diff, pull, push, login] },
+  { title: "Project", commands: [init, create, clone, link, status, diff, pull, push, publish, releases, login] },
   { title: "Run & test", commands: [
     dev,
     web,

package/src/commands/init/templates.ts

@@ -32,7 +32,7 @@ lecodes render --desktop --view iso --png iso.png   # 3D: inspection camera fitt
                                   # { "view": "iso", "screenshot": "iso.png" } then { "view": "off" }
 lecodes render --desktop --script <file>  # the same scenario on the NATIVE host (real GPU, the
                                   # real hit-test): the same steps, targets and expects as
-                                  # headless (only expect.audio / the json output are headless-only)
+                                  # headless (only expect.audio / expect.toast / the json output are headless-only)
 lecodes render --sim --script <file>      # the WINDOWLESS native host (lecodes-server): the real
                                   # engines, no GPU, no pixels, no UI hit-test — expect.log /
                                   # expect.paint only; runs on CI and beside an open desktop window
@@ -78,11 +78,12 @@ Three hosts run the same file, at a fixed 16 ms clock on all of them:
 |---|---|---|---|---|
 | headless | (none) | Bun: the runtime + UI renderer + a recording 3D core (no GPU) | names or \`{ x, y }\` | all |
 | sim | \`--sim\` | the windowless native server: real engines, no pixels, no UI | \`{ x, y }\`, straight to the scene | \`log\`, \`paint\` |
-| desktop | \`--desktop\` | the hidden desktop window: pixels, GL materials, the real hit-test | names or \`{ x, y }\` | all but \`audio\` |
+| desktop | \`--desktop\` | the hidden desktop window: pixels, GL materials, the real hit-test | names or \`{ x, y }\` | all but \`audio\` / \`toast\` |
 
 One flow file, the same verdict on headless and desktop: names resolve the same way (\`name\` →
 exact text → substring → placeholder), every step runs (\`hover\`, \`type\`, \`fill\`, \`scroll\`,
-\`clip\` included) and the semantic expects read the same tree. Only \`expect.audio\` and the
+\`clip\` included) and the semantic expects read the same tree. Only \`expect.audio\`,
+\`expect.toast\` (the last \`toast()\` message — a toast is not in the tree) and the
 \`json\` output are the headless renderer's. On the desktop \`type\` taps the input and types into
 it (appends); the sim has no UI, so it takes coordinates and \`expect.log\` / \`expect.paint\` only.
 

package/src/commands/publish.ts

@@ -0,0 +1,38 @@
+import { bool, defineCommand, str } from "../cli"
+import { publishProject } from "../platform/api"
+import { diffLocal, hasChanges, scanProject } from "../project/localFiles"
+import { runPush } from "./push"
+import { qrUrl, reportRelease, withSchemaConfirm } from "./releases"
+import { linkedProject } from "./shared"
+
+/*
+ * `lecodes publish` — the editor's Publish button (docs/plans/publishing-plan.md). Local changes go
+ * up first as one checkpoint (the push, message "Release" unless -m); then the platform builds the
+ * head, deploys its server to production and makes the build the current release — unless the head
+ * is the current release already (its checkpoint, or a build to the same bytes): then nothing is
+ * made and the answer is `unchanged` ("Nothing changed — 1.2.4 is current", exit 0); --force makes
+ * one all the same (a new SDK on the build service). A schema change
+ * that deletes production data is the one question (withSchemaConfirm). `push --publish` is the
+ * same in one /sync call.
+ */
+export default defineCommand({
+  name: "publish",
+  summary: "Release the project: push local changes, build, make it the live version",
+  description: "The editor's Publish button. Local changes are pushed first as a checkpoint (\"Release\", or -m). The platform builds the project, deploys its server to production and makes the build the current release at https://<handle>.le.codes — what the viewers and the store run. A project that builds to what is live already makes no release: \"Nothing changed — <version> is current\" (--force releases it all the same). A schema change that deletes production data is shown and asked about; without a terminal it needs --allow-destructive. `lecodes releases` lists the releases, `lecodes releases use <version>` rolls back.",
+  flags: {
+    message: str("checkpoint message when there are local changes (default \"Release\")", { alias: "m", value: "<text>" }),
+    force: bool("rebuild even when nothing changed — a new SDK on the build service"),
+    "allow-destructive": bool("apply a schema change that deletes production data without asking"),
+  },
+  examples: ["lecodes publish", 'lecodes publish -m "Checkout v2"', "lecodes publish --force", "lecodes publish --allow-destructive"],
+  run: async ({ flags }) => {
+    const { root, manifest, apiUrl, token } = linkedProject()
+    if (hasChanges(diffLocal(manifest, scanProject(root, manifest)))) await runPush({ message: flags.message || "Release" })
+
+    const release = await withSchemaConfirm(
+      allowDestructive => publishProject(apiUrl, token, manifest.uuid, { allowDestructive, force: flags.force }),
+      { allowDestructive: flags["allow-destructive"], retry: flags.force ? "lecodes publish --force" : "lecodes publish" },
+    )
+    if (release) reportRelease(release, qrUrl(apiUrl, manifest.uuid))
+  },
+})

package/src/commands/push.ts

@@ -1,11 +1,12 @@
 import { readFileSync } from "node:fs"
 import { basename } from "node:path"
 import { CliError, bool, c, confirm, defineCommand, info, log, prompt, str, success, warn } from "../cli"
-import { getCommits, getProject, publishProject, sync, uploadBlob, type Project, type SyncFileInput, type SyncFolderInput } from "../platform/api"
+import { getCommits, getProject, publishProject, sync, uploadBlob, type Project, type SyncFileInput, type SyncFolderInput, type SyncResponse } from "../platform/api"
 import { computeServerDiff } from "../platform/serverDiff"
 import { classifyKind, diffLocal, hasChanges, isTextKind, scanProject } from "../project/localFiles"
 import { writeManifest, type FileKind, type Manifest, type ManifestFile } from "../project/manifest"
 import { buildPaths } from "../project/materialize"
+import { qrUrl, reportRelease, withSchemaConfirm } from "./releases"
 import { linkedProject } from "./shared"
 
 /*
@@ -13,8 +14,10 @@ import { linkedProject } from "./shared"
  * then POST /sync (atomic set-tree + one checkpoint). Identity is carried via assetId so renames /
  * moves keep their history; unchanged binaries are referenced by id and never re-uploaded.
  *
- * With --publish the push also deploys the project (compile → live bundle) in the same /sync call,
- * so the changes go live atomically. On a clean tree, --publish just deploys the current state.
+ * With --publish the push also releases the project (build → the current release) in the same /sync
+ * call, so the changes go live atomically. On a clean tree, --publish is `lecodes publish`.
+ * --force-publish is --publish that releases even a head the live release was made of
+ * (`lecodes publish --force`; --force itself is the push's overwrite of the server).
  *
  * It also carries the design board's queued comment writes — replies and resolutions Claude or the
  * developer wrote locally. They go AFTER the design, deliberately: a reply saying "fixed" that
@@ -24,29 +27,39 @@ import { linkedProject } from "./shared"
 
 export const pushFlags = {
   message: str("checkpoint message (asked for when omitted)", { alias: "m", value: "<text>" }),
-  publish: bool("also deploy the project live (compile) with the push"),
+  publish: bool("also release the project with the push (= `lecodes publish`)"),
+  // (not --force: that one is the push's own, overwriting the server)
+  "force-publish": bool("--publish, and release even when nothing changed — a new SDK on the build service (= `lecodes publish --force`)"),
   force: bool("push even if the server moved on (shows + confirms which server files get overwritten)"),
   yes: bool("skip the --force overwrite confirmation", { alias: "y" }),
 }
 
-export type PushOptions = { message?: string, publish?: boolean, force?: boolean, yes?: boolean }
+export type PushOptions = { message?: string, publish?: boolean, "force-publish"?: boolean, force?: boolean, yes?: boolean }
 
 export default defineCommand({
   name: "push",
   summary: "Push local changes as one new checkpoint",
   flags: pushFlags,
-  examples: ['lecodes push -m "Tweak the menu"', "lecodes push --publish"],
+  examples: ['lecodes push -m "Tweak the menu"', "lecodes push --publish", "lecodes push --force-publish"],
   run: ({ flags }) => runPush(flags),
 })
 
 /** The push itself — `lecodes link --push` runs it too. */
 export const runPush = async (opts: PushOptions): Promise<void> => {
   const { root, manifest, apiUrl, token } = linkedProject()
-  const publish = !!opts.publish
+  const forcePublish = !!opts["force-publish"]
+  const publish = !!opts.publish || forcePublish
   const scan = scanProject(root, manifest)
   const diff = diffLocal(manifest, scan)
   if (!hasChanges(diff)) {
-    if (publish) { await publishProject(apiUrl, token, manifest.uuid); success("No file changes — published the current project state.") }
+    if (publish) {
+      info(c.dim("Working tree clean — publishing the project as it is."))
+      const release = await withSchemaConfirm(
+        allowDestructive => publishProject(apiUrl, token, manifest.uuid, { allowDestructive, force: forcePublish }),
+        { allowDestructive: false, retry: "lecodes publish" },
+      )
+      if (release) reportRelease(release, qrUrl(apiUrl, manifest.uuid))
+    }
     else info(c.dim("Working tree clean — nothing to push."))
     // Still flush: a queued answer must not be stuck behind "no files changed", which is exactly the
     // state you're in after resolving a comment about something you already pushed.
@@ -110,10 +123,10 @@ export const runPush = async (opts: PushOptions): Promise<void> => {
   const folders: SyncFolderInput[] = scan.dirs.map(path => ({ path }))
 
   if (uploaded > 0) info(c.dim(`Uploaded ${uploaded} binary file${uploaded === 1 ? "" : "s"}.`))
-  const res = await sync(apiUrl, token, manifest.uuid, { message, files, folders, publish })
+  const res = await sync(apiUrl, token, manifest.uuid, { message, files, folders, publish, ...(forcePublish ? { force: true } : {}) })
   if (!res.created) {
     info(c.dim("Server reported no changes."))
-    if (publish) reportPublish(res)
+    if (publish) reportPublish(res, qrUrl(apiUrl, manifest.uuid))
     return
   }
 
@@ -130,7 +143,7 @@ export const runPush = async (opts: PushOptions): Promise<void> => {
     diff.deleted.length - diff.moves.size && `${diff.deleted.length - diff.moves.size} deleted`,
   ].filter(Boolean).join(", ")
   success(`Pushed checkpoint${res.seq ? ` #${res.seq}` : ""}${counts ? ` (${counts})` : ""}: ${message}`)
-  if (publish) reportPublish(res)
+  if (publish) reportPublish(res, qrUrl(apiUrl, manifest.uuid))
   await flushComments()
 }
 
@@ -160,8 +173,8 @@ const serverPathDrift = (project: Project, manifest: Manifest): string | null =>
   return parts.length ? parts.join("; ") : null
 }
 
-/** Report the outcome of a --publish deploy bundled with the push (best-effort on the server). */
-const reportPublish = (res: { published?: boolean, publishError?: string }): void => {
-  if (res.published) success("Published — the project is now live.")
-  else warn(`Push landed, but publish failed: ${res.publishError ?? "unknown error"}`)
+/** Report the outcome of a --publish release bundled with the push (best-effort on the server). */
+const reportPublish = (res: SyncResponse, qr: string): void => {
+  if (res.published && res.release) reportRelease(res.release, qr)
+  else warn(`Push landed, but publish failed: ${res.publishError ?? "unknown error"} — \`lecodes publish\` tries again.`)
 }