lecodes-cli 0.20.2 → 1.0.0

package/src/commands/{appShared.ts → app/shared.ts}

@@ -2,14 +2,14 @@ import { execFileSync } from "node:child_process"
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
 import { dirname, join, resolve } from "node:path"
-import { findProjectRoot } from "../manifest"
-import { DEFAULT_IGNORE_FILE } from "../ignore"
-import { CliError, c, flagStr, log, note, warn, type Args } from "../util"
+import { findProjectRoot } from "../../project/manifest"
+import { DEFAULT_IGNORE_FILE } from "../../project/ignore"
+import { CliError, c, log, note, warn } from "../../cli"
 
-/* Shared plumbing for the `lecodes app` platform arms (app.ts = iOS + dispatch,
- * appAndroid.ts = Android). Everything here moved verbatim out of app.ts when the Android
- * arm landed — behavior for iOS is unchanged; the SDK helpers just grew a repo parameter
- * (lecodes-ios-sdk vs lecodes-android-sdk) and resolvePlugin a platform one. */
+/* Shared plumbing for the `lecodes app` platform arms (index.ts = iOS + the command tree,
+ * android.ts = Android, desktop.ts = the portable desktop build) and for every other command that
+ * reads app.json (the desktop window, the renderer, native plugin libraries). The SDK helpers take
+ * a repo parameter (lecodes-ios-sdk vs lecodes-android-sdk) and resolvePlugin a platform one. */
 
 /** First-party plugin registry: id → GitHub repo holding plugins/<id>/. Third-party plugins
  *  use a `github:owner/repo[@tag]` spec in app.json instead (manifest at the repo root). */
@@ -53,11 +53,14 @@ 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).
-   *  `signing`: keystore METADATA only — the store/key passwords live in android/
-   *  keystore.properties (gitignored) or LECODES_ANDROID_* env vars, never in app.json. */
+   *  `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.
+   *  `minify`: R8 on release builds (default true; sync restamps the values in app/build.gradle.kts). */
   android?: {
     applicationId?: string, versionCode?: number, sdk?: string, variant?: string,
     signing?: { storeFile?: string, keyAlias?: string },
+    minify?: boolean,
   }
   /** Desktop host (packages/desktop). `window` sizes are LOGICAL units — the host multiplies by
    *  the display scale. `entry` picks a per-target entry file (default: the detected project
@@ -67,8 +70,8 @@ export interface AppConfig {
     window?: DesktopWindowConfig,
     /** Which desktop host binary to run: "gl" (default) or "vulkan" (Windows only, host >= 1.4.0).
      *  A BUILD/DEV-TIME host selection, not a runtime switch — the two are separate binaries with
-     *  their own shaders and different features (the Vulkan one has no 2D engine and no native-view
-     *  plugins). Overridable per run with `--renderer` / LECODES_DESKTOP_RENDERER. */
+     *  their own shaders and different features (the Vulkan one has no native-view plugins).
+     *  Overridable per run with `--renderer` / LECODES_DESKTOP_RENDERER. */
     renderer?: "gl" | "vulkan",
     /** 3D buffer scale vs the window (0.25–1, host ≥1.4.0). The UI always renders at native
      *  pixels; only the 3D scene is rendered smaller and upscaled by the compositor. Multiplies
@@ -88,7 +91,7 @@ export interface AppConfig {
      *  a built folder's host reads it from the staged app.json. Headless render/test ignore it. */
     virtualKeyboard?: boolean | DesktopVirtualKeyboard,
     /** The macOS .app build (`lecodes app build desktop` on a Mac) — identity + signing +
-     *  notarization. See appDesktopMac.ts for the whole story. */
+     *  notarization. See desktopMac.ts for the whole story. */
     macos?: MacDesktopConfig,
   }
 }
@@ -181,13 +184,14 @@ export const readAppConfigAt = (root: string): AppConfig | null =>
 export const DESKTOP_DEFAULT_WINDOW = { width: 1280, height: 720 }
 
 /**
- * The renderer for this run: `--renderer` > LECODES_DESKTOP_RENDERER > app.json `desktop.renderer`
- * > "gl". Resolve it ONCE per command and pass the result to both `resolveDesktopExe` and the
- * shader staging — two independent reads of the config is how a build ends up with a Vulkan exe
- * next to an OpenGL .filamat, which fails at the first material with a Filament abort.
+ * The renderer for this run: the `--renderer` flag > LECODES_DESKTOP_RENDERER > app.json
+ * `desktop.renderer` > "gl". Resolve it ONCE per command and pass the result to both
+ * `resolveDesktopExe` and the shader staging — two independent reads of the config is how a build
+ * ends up with a Vulkan exe next to an OpenGL .filamat, which fails at the first material with a
+ * Filament abort.
  */
-export const resolveDesktopRenderer = (root: string, args?: Args): "gl" | "vulkan" => {
-  const raw = (args ? flagStr(args, "renderer") : undefined)
+export const resolveDesktopRenderer = (root: string, renderer?: string): "gl" | "vulkan" => {
+  const raw = renderer
     ?? process.env.LECODES_DESKTOP_RENDERER
     ?? readAppConfigAt(root)?.desktop?.renderer
   if (raw === undefined) return "gl"
@@ -303,10 +307,16 @@ export const git = (cwd: string, ...args: string[]): string =>
 
 export const slugify = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "app"
 
+/** The environment for a child process. Spelled out on every spawn on purpose: Bun hands an
+ *  inherited child the environment SNAPSHOT taken at startup, so anything the project .env
+ *  contributed (projectEnv.ts — keystore passwords, CREATOR_* tracing) would never arrive. */
+export const childEnv = (extra: Record<string, string> = {}): Record<string, string | undefined> =>
+  ({ ...process.env, ...extra })
+
 /** Run a tool, capturing output; on failure surface the tail (xcodebuild/gradle logs are huge). */
 export const runTool = (cwd: string, cmd: string, args: string[]): string => {
   try {
-    return execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 128 * 1024 * 1024 })
+    return execFileSync(cmd, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 128 * 1024 * 1024, env: childEnv() })
   } catch (e) {
     const err = e as { stdout?: string, stderr?: string }
     const tail = ((err.stdout ?? "") + "\n" + (err.stderr ?? "")).split("\n").filter(l => l.trim()).slice(-25).join("\n")
@@ -329,7 +339,7 @@ export const ensureShellIgnored = (root: string, dir: string) => {
 /* ----------------------------------- SDK variants ----------------------------------- */
 
 // Both native SDKs ship the same variant matrix (full / 3d / 2d / core), so the detection and
-// resolution logic is shared between the iOS (app.ts) and Android (appAndroid.ts) syncs.
+// resolution logic is shared between the iOS (index.ts) and Android (android.ts) syncs.
 export const SDK_VARIANTS = ["core", "2d", "3d", "full"] as const
 type SdkVariantShared = (typeof SDK_VARIANTS)[number]
 
@@ -346,25 +356,6 @@ export const detectEngines = (bundleJs: string): { gl: boolean, g2: boolean } =>
   return { gl: !/^\/\/ gl: disable$/m.test(header), g2: /^\/\/ 2d: enable$/m.test(header) }
 }
 
-/**
- * Refuse a Vulkan desktop build for a project that uses the 2D engine. The Vulkan host is built with
- * CREATOR_PKG_2D=OFF (creator-2d is sokol-on-GL, with no Vulkan twin), so those scenes don't render
- * — a blank window at runtime with nothing in the log to explain it. Fail at build time instead,
- * where the fix ("use the default renderer") is one line away.
- *
- * Detection is the same `// 2d: enable` bundle header `lecodes app sync` picks its SDK variant from,
- * so it can't drift from what the engine actually needs.
- */
-export const assertRendererSupportsBundle = (renderer: "gl" | "vulkan", bundleJs: string): void => {
-  if (renderer !== "vulkan") return
-  if (!detectEngines(bundleJs).g2) return
-  throw new CliError(
-    "This project uses the 2D engine, which the Vulkan desktop host doesn't include " +
-    "(creator-2d renders through OpenGL and has no Vulkan path yet).\n" +
-    "  Build with the default renderer: drop `desktop.renderer` from app.json, or pass `--renderer gl`.",
-  )
-}
-
 /** 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

package/src/commands/{appTemplatesAndroid.ts → app/templates/android.ts}

@@ -1,5 +1,5 @@
 /* Templates for `lecodes app init android` / `lecodes app sync` — the Android mirror of
- * appTemplates.ts, distilled from the LetaryCreatorViewer host (lecodes-android :app). The
+ * ios.ts, distilled from the LetaryCreatorViewer host (lecodes-android :app). The
  * same three ownership tiers: app/ is USER-owned after generation (init writes once, sync
  * never touches it — except app/src/main/assets/, the Resources/ analog, and values-only
  * versionName/versionCode restamps in app/build.gradle.kts); settings/root gradle files,
@@ -234,16 +234,17 @@ export const ANDROID_README = `# Android shell
 Generated by \`lecodes app init android\`. Daily workflow:
 
 \`\`\`
-lecodes app sync            # embed the compiled bundle + plugins into this shell
-lecodes app open android    # open in Android Studio
-lecodes app build android   # signed release APK + AAB (gradlew assembleRelease bundleRelease)
+lecodes app sync                 # embed the compiled bundle + plugins into this shell
+lecodes app open android         # open in Android Studio
+lecodes app keystore create      # once: the release signing key (or \`keystore use <file>\`)
+lecodes app build android        # signed release .apk + .aab → ../dist/
 \`\`\`
 
 ## Ownership
 
 | Path | Owner |
 | --- | --- |
-| \`app/\` (sources, manifest, res, build.gradle.kts) | **Yours** after init — sync never rewrites them (it only restamps \`versionName\`/\`versionCode\` values, manages \`// lecodes:plugin\`-tagged lines in the plugins block, and — when \`app.json\` sets \`"icon"\` — the icon files below) |
+| \`app/\` (sources, manifest, res, build.gradle.kts, proguard-rules.pro) | **Yours** after init — sync never rewrites them (it only restamps the \`versionName\`/\`versionCode\` and \`isMinifyEnabled\`/\`isShrinkResources\` values, manages \`// lecodes:plugin\`-tagged lines in the plugins block, and — when \`app.json\` sets \`"icon"\` — the icon files below) |
 | \`app/src/main/assets/\` | CLI-owned — wiped and regenerated by every sync (the compiled \`app.js\` + its \`// preload:\` assets) |
 | \`res/mipmap-*/ic_launcher*\`, \`res/values/lecodes_icon.xml\` | CLI-owned **only when** \`app.json\` sets \`"icon"\` — regenerated by every sync (plus a value-only \`android:icon\` restamp in the manifest); without the key sync never touches icons |
 | \`settings.gradle.kts\`, \`build.gradle.kts\` (root), \`gradle.properties\`, \`lecodes-runtime/\`, \`plugins/\` | CLI-owned — regenerated by every sync |
@@ -280,17 +281,42 @@ dependencies they need to \`app/build.gradle.kts\` — that file is yours.
 
 ## Release signing
 
-Create \`android/keystore.properties\` (gitignored):
+The key lives in the project's \`.env\` (next to \`app.json\`; the CLI loads it for every command
+and never pushes it):
 
 \`\`\`
-storeFile=release.keystore
-storePassword=…
-keyAlias=…
-keyPassword=…
+LECODES_ANDROID_KEYSTORE_FILE=./android/release.keystore    # ./ = the project root; ~/ and absolute paths work too
+LECODES_ANDROID_KEYSTORE_PASSWORD=…
+LECODES_ANDROID_KEY_ALIAS=upload
+LECODES_ANDROID_KEY_PASSWORD=…
 \`\`\`
 
-or export \`LECODES_ANDROID_KEYSTORE_FILE\` / \`LECODES_ANDROID_KEYSTORE_PASSWORD\` /
-\`LECODES_ANDROID_KEY_ALIAS\` / \`LECODES_ANDROID_KEY_PASSWORD\`. Never put passwords in app.json.
+\`lecodes app keystore create\` makes a new key and writes those lines; \`lecodes app keystore use
+<file>\` attaches an existing one (a keystore outside the project is just a path); \`lecodes app
+keystore info\` prints the SHA-1 / SHA-256 fingerprints the Play Console, Firebase and Google
+Sign-In ask for. The same four names work as real environment variables (CI). Building from
+Android Studio without the CLI? \`android/keystore.properties\` (gitignored, \`storeFile\` /
+\`storePassword\` / \`keyAlias\` / \`keyPassword\`) is still honoured and wins over the env.
+Never put passwords in app.json — \`android.signing\` there is metadata only.
+
+With Play App Signing (the default for new Play apps) this key is the UPLOAD key — Google holds
+the app signing key and a lost upload key can be reset through Play support. Without it, losing
+the keystore means the app can never be updated. Back it up either way.
+
+## Building
+
+\`lecodes app build android\` syncs, runs \`gradlew assembleRelease bundleRelease\` and copies the
+results to \`../dist/<name>-<version>-<versionCode>.apk|.aab\` (\`-o <dir>\` elsewhere). A release
+without a signing key is refused (\`--allow-unsigned\` for a throwaway build); \`--configuration
+Debug\` signs with the debug keystore. \`--apk\` / \`--aab\` pick one artifact.
+
+Release builds run R8 (\`isMinifyEnabled\` + \`isShrinkResources\`): the SDK AAR ships the keep
+rules its JNI bindings need, plugins ship theirs, \`app/proguard-rules.pro\` is for your own
+classes. \`app.json\` \`"android": { "minify": false }\` turns it off (sync restamps the values).
+R8 only touches the dex — the engine's native libraries and \`app.js\` are not shrunk.
+
+\`abiFilters\` in \`app/build.gradle.kts\` keeps the package to the two ABIs the SDK ships
+(arm64-v8a, armeabi-v7a).
 
 ## Icons
 
@@ -314,11 +340,11 @@ the init-time placeholder.
 
 /* ---------------------------- USER-owned (written once) ---------------------------- */
 
-export const appBuildGradleTemplate = ({ applicationId, version, versionCode }: AndroidShellIdentity): string => `import java.util.Properties
+export const appBuildGradleTemplate = ({ applicationId, version, versionCode }: AndroidShellIdentity, minify = true): string => `import java.util.Properties
 
 // Generated by \`lecodes app init\` — yours to edit. \`lecodes app sync\` only restamps the
-// versionName/versionCode VALUES and manages \`// lecodes:plugin\`-tagged lines in the plugins
-// block below; everything else is left alone.
+// versionName/versionCode and isMinifyEnabled/isShrinkResources VALUES and manages
+// \`// lecodes:plugin\`-tagged lines in the plugins block below; everything else is left alone.
 plugins {
     id("com.android.application")
     id("org.jetbrains.kotlin.android")
@@ -342,6 +368,9 @@ android {
         targetSdk = ${TARGET_SDK}
         versionCode = ${versionCode}
         versionName = "${version}"
+        // The LeCodes SDK ships arm64-v8a + armeabi-v7a natives. A transitive dependency adds a
+        // lone x86_64 library, which would make the package claim an ABI the engine can't load on.
+        ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a") }
     }
 
     val storeFilePath = signing("storeFile", "LECODES_ANDROID_KEYSTORE_FILE")
@@ -356,7 +385,12 @@ android {
 
     buildTypes {
         release {
-            isMinifyEnabled = false
+            // R8 (shrink + optimize + obfuscate). The SDK AAR carries the keep rules its JNI
+            // bindings need; app-local rules go in proguard-rules.pro. app.json
+            // android.minify: false turns it off (sync restamps these two values).
+            isMinifyEnabled = ${minify}
+            isShrinkResources = ${minify}
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
             signingConfig = signingConfigs.findByName("release")
         }
     }
@@ -378,6 +412,18 @@ dependencies {
 }
 `
 
+/** app/proguard-rules.pro — user-owned R8 rules for app-local code. The SDK's own keep rules
+ *  (its JNI-bound classes) ride inside the AAR as consumer rules, and plugin modules ship theirs
+ *  through consumerProguardFiles, so this file starts empty. */
+export const APP_PROGUARD_RULES = `# R8 rules for app-local code (yours — \`lecodes app sync\` never touches this file).
+#
+# The LeCodes SDK keeps its own JNI-bound classes through the consumer rules inside the AAR, and
+# plugin modules bring their own. Add rules here only for classes YOUR Kotlin registers with the
+# engine by name (engine.registerCallback / registerService / registerView) or reaches through
+# reflection, e.g.
+#   -keep class com.example.myapp.MyBridge { *; }
+`
+
 export const appManifestTemplate = (): string => `<?xml version="1.0" encoding="utf-8"?>
 <!-- Generated by \`lecodes app init\` — yours to edit. Sync leaves it alone, except that with
      app.json "icon" set it restamps the android:icon VALUE to the generated @mipmap set.
@@ -404,18 +450,6 @@ export const appManifestTemplate = (): string => `<?xml version="1.0" encoding="
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
-
-            <!-- le.codes/qr deep links (QR scans, notification taps). Editable — remove if the
-                 app should not claim them. -->
-            <intent-filter android:autoVerify="true">
-                <action android:name="android.intent.action.VIEW" />
-                <category android:name="android.intent.category.DEFAULT" />
-                <category android:name="android.intent.category.BROWSABLE" />
-                <data android:scheme="https" />
-                <data android:scheme="http" />
-                <data android:host="le.codes" />
-                <data android:pathPrefix="/qr" />
-            </intent-filter>
         </activity>
     </application>
 

package/src/commands/{appTemplatesGradlew.ts → app/templates/gradlew.ts}

@@ -1,5 +1,5 @@
 /* Gradle wrapper launcher scripts, verbatim from the gradle/gradle v8.13.0 tag (the same
- * pinned source as the wrapper jar download in appAndroid.ts). JSON-escaped mechanically —
+ * pinned source as the wrapper jar download in ../android.ts). JSON-escaped mechanically —
  * regenerate from the tag rather than editing. gradlew must be written with LF and
  * gradlew.bat with CRLF (initAndroid handles the conversion); both are version-agnostic
  * launchers that read gradle/wrapper/gradle-wrapper.properties for the real distribution. */

package/src/commands/{appTemplates.ts → app/templates/ios.ts}

@@ -1,4 +1,4 @@
-import { swiftPackageName, type IosPackage } from "./appShared"
+import { swiftPackageName, type IosPackage } from "../shared"
 
 /* Templates for `lecodes app init ios` / `lecodes app sync` — distilled 1:1 from the
  * hand-built, device-verified reference shell (docs/xcode-app-plan.md). Three ownership

package/src/commands/assets.ts

@@ -1,24 +1,26 @@
-import { type Args } from "../util"
-import { resolveCmgenExe } from "../cmgenTool"
-import { loadPeer } from "../peerInstall"
+import { defineCommand } from "../cli"
+import { resolveCmgenExe } from "../hosts/cmgenTool"
+import { loadPeer } from "../hosts/peerInstall"
 
 /*
- * `lecodes assets <convert|probe|doctor|sky> …` — the LeCodes asset pipeline (packages/lecodes-assets):
- * FBX → GLB (ufbx wasm + glTF-Transform), `--clips` merged by bone name, textures embedded, GLB
- * doctor (bone cap / texture normalize / KTX2). The package is an optional peer (like the design
- * board and the renderer); its own argv parser handles the sub-command flags, so the raw argv is
- * forwarded untouched (`assets` gets `_raw` from main). See docs/animation-plan.md §2.9.
+ * `lecodes assets …` — the asset pipeline (packages/lecodes-assets): FBX → GLB, the GLB doctor,
+ * retargeting, Unity packs, skies. The package is an optional peer with its OWN argv parser and
+ * help, so the argv is forwarded untouched (`passthrough`) — `lecodes assets --help` is theirs.
  */
-export const assets = async (args: Args & { _raw?: string[] }) => {
-  const mod = await loadPeer<typeof import("lecodes-assets/cli")>("lecodes-assets", "cli", { for: "lecodes assets" })
-  const raw = args._raw ?? args._
-  // `sky` shells out to filament's cmgen, which the asset package deliberately never downloads
-  // itself (it stays network-free and usable standalone). The CLI owns release artifacts, so it
-  // resolves the binary — cache or first-use download — and hands it over through the env var the
-  // package already honours. An explicit LECODES_CMGEN wins, so a local filament build still rules.
-  if (raw[0] === "sky" && !process.env.LECODES_CMGEN) {
-    process.env.LECODES_CMGEN = await resolveCmgenExe()
-  }
-  const code = await mod.runAssetsCli(raw)
-  if (code !== 0) process.exitCode = code
-}
+export default defineCommand({
+  name: "assets",
+  summary: "The asset pipeline: convert / probe / doctor / retarget / unpack / scene / sky / terrain-pack …",
+  usage: "<command> [args…]",
+  passthrough: true,
+  examples: ["lecodes assets convert hero.fbx --clips anims/*.fbx -o hero.glb", "lecodes assets doctor hero.glb --fix --ktx2", "lecodes assets --help"],
+  run: async ({ argv }) => {
+    const mod = await loadPeer<typeof import("lecodes-assets/cli")>("lecodes-assets", "cli", { for: "lecodes assets" })
+    // `sky` shells out to filament's cmgen, which the asset package deliberately never downloads
+    // itself (it stays network-free and usable standalone). The CLI owns release artifacts, so it
+    // resolves the binary — cache or first-use download — and hands it over through the env var the
+    // package already honours. An explicit LECODES_CMGEN wins, so a local filament build still rules.
+    if (argv[0] === "sky" && !process.env.LECODES_CMGEN) process.env.LECODES_CMGEN = await resolveCmgenExe()
+    const code = await mod.runAssetsCli(argv)
+    if (code !== 0) process.exitCode = code
+  },
+})

package/src/commands/clone.ts

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