lecodes-cli 0.20.2 → 1.0.0

package/src/commands/{init.ts → init/index.ts}

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

@@ -1,8 +1,8 @@
 import { execFileSync } from "node:child_process"
 import { appendFileSync, chmodSync, cpSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync } from "node:fs"
 import { homedir } from "node:os"
-import { basename, delimiter, dirname, join, resolve, sep } from "node:path"
-import { c, CliError, flagBool, flagStr, log, success, warn, type Args } from "../util"
+import { basename, delimiter, dirname, join, resolve } from "node:path"
+import { CliError, bool, c, defineCommand, log, str, success, warn } from "../cli"
 
 /*
  * `lecodes install` — install this standalone build so `lecodes` is on your PATH.
@@ -17,15 +17,13 @@ import { c, CliError, flagBool, flagStr, log, success, warn, type Args } from ".
  * PATH is only edited on request (`--modify-path`); otherwise we place the files and print exactly how
  * to finish (a one-liner for this shell, a line for the rc file, or `--system` which lands in
  * /usr/local/bin and needs no PATH edit). Only meaningful for the release archive — from npm/monorepo
- * source process.execPath has no bundle beside it, so it refuses.
+ * source process.execPath has no bundle beside it, so it refuses. The registry hides the command
+ * unless the running binary IS such a bundle (src/index.ts decides).
  */
 
 const isWin = process.platform === "win32"
 const HOME = homedir()
 
-/** Display a path with the home dir collapsed to `~` (for copy-pasteable hints). */
-const tildify = (p: string): string => (p === HOME || p.startsWith(HOME + sep)) ? "~" + p.slice(HOME.length) : p
-
 const safeRealpath = (p: string): string => { try { return realpathSync(p) } catch { return resolve(p) } }
 
 /** True if `dir` is already an entry in PATH (compared by resolved path). */
@@ -37,25 +35,7 @@ const onPath = (dir: string): boolean => {
   })
 }
 
-export const install = async (args: Args): Promise<void> => {
-  const bundle = dirname(process.execPath)
-  const exeName = basename(process.execPath)               // "lecodes" | "lecodes.exe"
-  const chiselName = isWin ? "chisel.exe" : "chisel"
-
-  // Guard: this must be the packaged standalone bundle (chisel + runtime/ sit next to the binary).
-  // From npm / the monorepo, process.execPath is the bun/node binary and has no companions.
-  if (!existsSync(join(bundle, "runtime")) || !existsSync(join(bundle, chiselName))) {
-    throw new CliError(
-      "`lecodes install` only works from the packaged release build (the archive containing lecodes + " +
-      "chisel + runtime/). You appear to be running from source or an npm install — install globally " +
-      "with your package manager there instead.",
-    )
-  }
-
-  const companions = [exeName, chiselName, "runtime", "README.txt"].filter(f => existsSync(join(bundle, f)))
-  if (isWin) return installWindows(args, bundle, companions)
-  return installUnix(args, bundle, companions)
-}
+type InstallOptions = { modifyPath: boolean, system: boolean, dir?: string, bin?: string }
 
 /** Copy the bundle's companion files into `target` (skipping the copy when target IS the bundle). */
 const copyBundle = (bundle: string, target: string, companions: string[]): void => {
@@ -79,29 +59,6 @@ const permError = (e: unknown, dir: string, system: boolean): CliError => {
   return new CliError(`Install failed: ${e instanceof Error ? e.message : String(e)}`)
 }
 
-const installUnix = (args: Args, bundle: string, companions: string[]): void => {
-  const system = flagBool(args, "system")
-  const libDir = resolve(flagStr(args, "dir") ?? (system ? "/usr/local/lib/lecodes-cli" : join(HOME, ".local", "lib", "lecodes-cli")))
-  const binDir = resolve(flagStr(args, "bin") ?? (system ? "/usr/local/bin" : join(HOME, ".local", "bin")))
-  const link = join(binDir, "lecodes")
-
-  try {
-    copyBundle(bundle, libDir, companions)
-    chmodSync(join(libDir, "lecodes"), 0o755)
-    chmodSync(join(libDir, "chisel"), 0o755)
-  } catch (e) { throw permError(e, libDir, system) }
-
-  try {
-    mkdirSync(binDir, { recursive: true })
-    rmSync(link, { force: true })                            // replace a previous symlink/file
-    symlinkSync(join(libDir, "lecodes"), link)
-  } catch (e) { throw permError(e, binDir, system) }
-
-  success(`Installed to ${c.bold(libDir)}`)
-  log(`  ${c.dim(link + " → " + join(libDir, "lecodes"))}`)
-  finishPathUnix(args, binDir)
-}
-
 /** The shell startup file to persist PATH into, picked from $SHELL (bash/zsh handled; else ~/.profile,
  *  which login shells read). Returns the absolute path and a ~-collapsed display name. */
 const shellRc = (): { file: string, name: string } => {
@@ -127,12 +84,12 @@ const appendPathToShellRc = (binDir: string): string | null => {
 }
 
 /** Put `binDir` on PATH: verify (already there), or `--modify-path` (edit the rc), or print how. */
-const finishPathUnix = (args: Args, binDir: string): void => {
+const finishPathUnix = (modifyPath: boolean, binDir: string): void => {
   if (onPath(binDir)) {
     log(`  Run ${c.bold("lecodes --version")} in a new shell to verify.`)
     return
   }
-  if (flagBool(args, "modify-path")) {
+  if (modifyPath) {
     const rc = appendPathToShellRc(binDir)
     if (rc) {
       success(`Added ${c.bold(binDir)} to PATH in ${rc}.`)
@@ -151,8 +108,46 @@ const finishPathUnix = (args: Args, binDir: string): void => {
   log(`  • or install system-wide (no PATH edit): ${c.bold("sudo lecodes install --system")}`)
 }
 
-const installWindows = (args: Args, bundle: string, companions: string[]): void => {
-  const target = resolve(flagStr(args, "dir") ?? join(process.env.LOCALAPPDATA ?? join(HOME, "AppData", "Local"), "Programs", "lecodes-cli"))
+const installUnix = (opts: InstallOptions, bundle: string, companions: string[]): void => {
+  const { system } = opts
+  const libDir = resolve(opts.dir ?? (system ? "/usr/local/lib/lecodes-cli" : join(HOME, ".local", "lib", "lecodes-cli")))
+  const binDir = resolve(opts.bin ?? (system ? "/usr/local/bin" : join(HOME, ".local", "bin")))
+  const link = join(binDir, "lecodes")
+
+  try {
+    copyBundle(bundle, libDir, companions)
+    chmodSync(join(libDir, "lecodes"), 0o755)
+    chmodSync(join(libDir, "chisel"), 0o755)
+  } catch (e) { throw permError(e, libDir, system) }
+
+  try {
+    mkdirSync(binDir, { recursive: true })
+    rmSync(link, { force: true })                            // replace a previous symlink/file
+    symlinkSync(join(libDir, "lecodes"), link)
+  } catch (e) { throw permError(e, binDir, system) }
+
+  success(`Installed to ${c.bold(libDir)}`)
+  log(`  ${c.dim(link + " → " + join(libDir, "lecodes"))}`)
+  finishPathUnix(opts.modifyPath, binDir)
+}
+
+/** Append `dir` to the current user's Path via the .NET env API (PowerShell). Unlike `setx` this never
+ *  truncates a long Path. The dir is passed through an env var to avoid any quoting/injection. */
+const addToUserPathWindows = (dir: string): boolean => {
+  const script =
+    "$d = $env:LECODES_INSTALL_DIR;" +
+    "$p = [Environment]::GetEnvironmentVariable('Path','User'); if (-not $p) { $p = '' };" +
+    "$parts = @($p.Split(';') | Where-Object { $_ -ne '' });" +
+    "if ($parts -notcontains $d) { [Environment]::SetEnvironmentVariable('Path', (@($parts + $d) -join ';'), 'User') }"
+  try {
+    execFileSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", script],
+      { stdio: "ignore", env: { ...process.env, LECODES_INSTALL_DIR: dir } })
+    return true
+  } catch { return false }
+}
+
+const installWindows = (opts: InstallOptions, bundle: string, companions: string[]): void => {
+  const target = resolve(opts.dir ?? join(process.env.LOCALAPPDATA ?? join(HOME, "AppData", "Local"), "Programs", "lecodes-cli"))
 
   try {
     copyBundle(bundle, target, companions)
@@ -167,7 +162,7 @@ const installWindows = (args: Args, bundle: string, companions: string[]): void
     log(`  Already on PATH — run ${c.bold("lecodes --version")} in a new terminal.`)
     return
   }
-  if (flagBool(args, "modify-path")) {
+  if (opts.modifyPath) {
     if (addToUserPathWindows(target)) {
       success(`Added ${c.bold(target)} to your user PATH.`)
       log(`  ${c.yellow("Open a NEW terminal")} for it to take effect, then run ${c.bold("lecodes --version")}.`)
@@ -182,17 +177,35 @@ const installWindows = (args: Args, bundle: string, companions: string[]): void
   log(`  • or add the folder manually via System → Environment Variables.`)
 }
 
-/** Append `dir` to the current user's Path via the .NET env API (PowerShell). Unlike `setx` this never
- *  truncates a long Path. The dir is passed through an env var to avoid any quoting/injection. */
-const addToUserPathWindows = (dir: string): boolean => {
-  const script =
-    "$d = $env:LECODES_INSTALL_DIR;" +
-    "$p = [Environment]::GetEnvironmentVariable('Path','User'); if (-not $p) { $p = '' };" +
-    "$parts = @($p.Split(';') | Where-Object { $_ -ne '' });" +
-    "if ($parts -notcontains $d) { [Environment]::SetEnvironmentVariable('Path', (@($parts + $d) -join ';'), 'User') }"
-  try {
-    execFileSync("powershell", ["-NoProfile", "-NonInteractive", "-Command", script],
-      { stdio: "ignore", env: { ...process.env, LECODES_INSTALL_DIR: dir } })
-    return true
-  } catch { return false }
-}
+export default defineCommand({
+  name: "install",
+  summary: "Install this standalone build so `lecodes` is on your PATH",
+  description: "Copies the bundle (lecodes + chisel + runtime/) to a library folder and exposes the binary: a symlink in ~/.local/bin on Linux/macOS, the install folder itself on PATH on Windows. PATH is only edited with --modify-path; otherwise the command prints how to finish. Only works from the packaged release archive.",
+  flags: {
+    "modify-path": bool("also add it to PATH (edits your shell rc / user PATH)"),
+    system: bool("install for all users (Linux/macOS; needs sudo)"),
+    dir: str("override the install/library folder", { value: "<path>" }),
+    bin: str("override the symlink folder (Linux/macOS)", { value: "<path>" }),
+  },
+  examples: ["lecodes install --modify-path", "sudo lecodes install --system"],
+  run: ({ flags }) => {
+    const bundle = dirname(process.execPath)
+    const exeName = basename(process.execPath)               // "lecodes" | "lecodes.exe"
+    const chiselName = isWin ? "chisel.exe" : "chisel"
+
+    // Guard: this must be the packaged standalone bundle (chisel + runtime/ sit next to the binary).
+    // From npm / the monorepo, process.execPath is the bun/node binary and has no companions.
+    if (!existsSync(join(bundle, "runtime")) || !existsSync(join(bundle, chiselName))) {
+      throw new CliError(
+        "`lecodes install` only works from the packaged release build (the archive containing lecodes + " +
+        "chisel + runtime/). You appear to be running from source or an npm install — install globally " +
+        "with your package manager there instead.",
+      )
+    }
+
+    const companions = [exeName, chiselName, "runtime", "README.txt"].filter(f => existsSync(join(bundle, f)))
+    const opts: InstallOptions = { modifyPath: flags["modify-path"], system: flags.system, dir: flags.dir, bin: flags.bin }
+    if (isWin) return installWindows(opts, bundle, companions)
+    return installUnix(opts, bundle, companions)
+  },
+})