lecodes-cli 0.19.0 → 0.20.0

package/src/peers.ts

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+
+/* Optional peer packages a user installs separately — `npm install -g …`, matching how the CLI
+ * itself is installed. A bare specifier resolves upward from the importing FILE, so a global CLI
+ * only ever sees globally installed peers: a project-local `-D` install is invisible to it, and
+ * under `npx` neither works (pass every peer as its own `-p`). `--version` reports each one's
+ * installed version so a stale/mismatched copy — the usual cause of "needs X" errors or silent
+ * render failures like a design screen coming back empty — is visible at a glance. The probe is an
+ * export subpath that resolves to a real file in BOTH the published package and the workspace
+ * source, so version reporting works whether the CLI runs from npm or straight from the monorepo. */
+export const OPTIONAL_PEERS: [name: string, probe: string][] = [
+  ["lecodes-renderer", "lecodes-renderer/headless"],
+  ["lecodes-design", "lecodes-design/server"],
+  ["lecodes-3d-editor", "lecodes-3d-editor/server"],
+  ["lecodes-assets", "lecodes-assets/cli"],
+]
+
+/** Installed version of an optional peer, or null when it isn't installed. Resolves the probe
+ *  subpath, then walks up to the nearest package.json that actually names the package (skipping any
+ *  nested ones). Never throws — a standalone binary with no node_modules reports every peer absent. */
+export const peerVersion = (name: string, probe: string): string | null => {
+  try {
+    const require = createRequire(import.meta.url)
+    let dir = dirname(require.resolve(probe))
+    for (let depth = 0; depth < 16; depth++) {
+      const manifest = join(dir, "package.json")
+      if (existsSync(manifest)) {
+        const parsed = JSON.parse(readFileSync(manifest, "utf8")) as { name?: string, version?: string }
+        if (parsed.name === name) return parsed.version ?? "unknown"
+      }
+      const parent = dirname(dir)
+      if (parent === dir) break
+      dir = parent
+    }
+  } catch { /* not installed, or not resolvable (e.g. the standalone binary) */ }
+  return null
+}
+

package/src/project.ts

@@ -0,0 +1,61 @@
+import { dirname, join } from "node:path"
+import { mkdirSync, writeFileSync } from "node:fs"
+import { downloadBlob, type Project, type ProjectAsset } from "./api"
+import type { FileKind, ManifestFile } from "./manifest"
+import { sha256 } from "./util"
+
+/* Writes a project's asset tree to disk and returns the path -> { id, type, sha } map for the
+ * manifest. Shared by clone and pull. */
+
+const kindOf = (type: ProjectAsset["type"]): FileKind => (type === "file" ? "resource" : type as FileKind)
+
+const absOf = (root: string, key: string) => join(root, ...key.replace(/^\//, "").split("/"))
+
+/** Build each asset's posix path key ("/a/b.ts"). Assets arrive parents-first. */
+export const buildPaths = (assets: ProjectAsset[]): Map<number, string> => {
+  const pathById = new Map<number, string>()
+  for (const asset of assets) {
+    const parent = asset.parentId !== null ? pathById.get(asset.parentId) : undefined
+    pathById.set(asset.id, `${parent ?? ""}/${asset.name}`)
+  }
+  return pathById
+}
+
+/** Write all assets to disk; returns the manifest file map (folders are created but not tracked). */
+export const materializeAssets = async (
+  root: string, project: Project, apiUrl: string, token: string,
+  onProgress?: (done: number, total: number, path: string) => void,
+): Promise<Record<string, ManifestFile>> => {
+  const pathById = buildPaths(project.assets)
+  const files: Record<string, ManifestFile> = {}
+
+  const total = project.assets.filter(a => a.type !== "folder").length
+  let done = 0
+
+  for (const asset of project.assets) {
+    const key = pathById.get(asset.id)!
+    const abs = absOf(root, key)
+
+    if (asset.type === "folder") {
+      mkdirSync(abs, { recursive: true })
+      continue
+    }
+
+    mkdirSync(dirname(abs), { recursive: true })
+    let sha: string
+    if (asset.type === "file") {
+      if (!asset.file?.src) continue
+      const bytes = await downloadBlob(apiUrl, asset.file.src)
+      writeFileSync(abs, bytes)
+      sha = sha256(bytes)
+    } else {
+      const text = asset.text ?? ""
+      writeFileSync(abs, text)
+      sha = sha256(text)
+    }
+    files[key] = { id: asset.id, type: kindOf(asset.type), sha }
+    onProgress?.(++done, total, key)
+  }
+
+  return files
+}

package/src/projectEnv.ts

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+
+/*
+ * Project `.env` — the CLI's LECODES_* / CREATOR_* knobs kept next to app.json instead of in the
+ * shell's environment. Loaded once at startup, before any command runs, from the nearest project
+ * root above the cwd (a dir with app.json or .lecodes/); nothing is loaded outside a project.
+ *
+ * Rules, all chosen so a .env can never surprise:
+ *   - the REAL environment wins: a key already set in the shell is never overridden — the same
+ *     precedence every command already documents (flag > env > app.json);
+ *   - only LECODES_* and CREATOR_* keys are taken. A .env is a per-project config file for THIS
+ *     tool, not a way to rewrite PATH or HOME for the child processes it spawns;
+ *   - a value starting with ./ or ../ is resolved against the .env's own directory, so a project
+ *     can point LECODES_DESKTOP_EXE at a host build checked out next to it and still work from any
+ *     subdirectory; a leading ~/ is the home dir;
+ *   - the file is never pushed (ignore.ts BUILTIN_PATTERNS) — LECODES_TOKEN and the Android
+ *     keystore passwords are exactly what ends up in it.
+ * Syntax: KEY=value per line, `export KEY=value` accepted, # comments, single or double quotes
+ * (\n, \t and \" unescape inside double quotes only), blank lines ignored.
+ */
+
+const KEY_RE = /^(LECODES|CREATOR)_[A-Z0-9_]+$/
+
+/** Parse .env text into key → value. Pure; unknown/odd lines are skipped, never fatal. */
+export const parseDotEnv = (text: string): Record<string, string> => {
+  const out: Record<string, string> = {}
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim()
+    if (!line || line.startsWith("#")) continue
+    const m = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line)
+    if (!m) continue
+    const key = m[1]
+    let value = m[2]
+    if (value.startsWith('"')) {
+      const end = value.indexOf('"', 1)
+      value = (end < 0 ? value.slice(1) : value.slice(1, end))
+        .replace(/\\n/g, "\n").replace(/\\t/g, "\t").replace(/\\"/g, '"').replace(/\\\\/g, "\\")
+    } else if (value.startsWith("'")) {
+      const end = value.indexOf("'", 1)
+      value = end < 0 ? value.slice(1) : value.slice(1, end)
+    } else {
+      // Unquoted: an inline ` # comment` ends the value.
+      const hash = value.search(/\s#/)
+      value = (hash >= 0 ? value.slice(0, hash) : value).trim()
+    }
+    out[key] = value
+  }
+  return out
+}
+
+/** The values a .env contributes to the environment: prefix-filtered, paths resolved against
+ *  `dir`, and nothing that `env` already has. Pure — the file/process plumbing is in loadProjectEnv. */
+export const applyDotEnv = (
+  parsed: Record<string, string>, dir: string, env: Record<string, string | undefined>,
+): Record<string, string> => {
+  const out: Record<string, string> = {}
+  for (const [key, raw] of Object.entries(parsed)) {
+    if (!KEY_RE.test(key) || env[key] !== undefined) continue
+    let value = raw
+    if (value.startsWith("./") || value.startsWith("../")) value = resolve(dir, value)
+    else if (value === "~" || value.startsWith("~/")) value = join(homedir(), value.slice(1))
+    out[key] = value
+  }
+  return out
+}
+
+/** The nearest project root at or above `start`: the first dir with app.json or .lecodes/. */
+export const findEnvRoot = (start: string): string | null => {
+  let dir = resolve(start)
+  while (true) {
+    if (existsSync(join(dir, "app.json")) || existsSync(join(dir, ".lecodes"))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** Load `<project>/.env` into process.env (see the rules above). Returns the keys it set, for
+ *  diagnostics. Never throws — a broken .env is skipped, not a reason the CLI can't run. */
+export const loadProjectEnv = (cwd = process.cwd()): string[] => {
+  try {
+    const root = findEnvRoot(cwd)
+    if (!root) return []
+    const file = join(root, ".env")
+    if (!existsSync(file)) return []
+    const added = applyDotEnv(parseDotEnv(readFileSync(file, "utf8")), root, process.env)
+    for (const [k, v] of Object.entries(added)) process.env[k] = v
+    return Object.keys(added)
+  } catch {
+    return []
+  }
+}

package/src/qrcode-terminal.d.ts

@@ -0,0 +1,9 @@
+// qrcode-terminal ships no types — the minimal surface the dev command uses.
+declare module "qrcode-terminal" {
+  type QrOptions = { small?: boolean }
+  const qrcode: {
+    generate(text: string, options: QrOptions, callback: (output: string) => void): void
+    generate(text: string, callback?: (output: string) => void): void
+  }
+  export default qrcode
+}

package/src/releases.ts

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { spawnSync } from "node:child_process"
+import { CliError } from "./util"
+
+/*
+ * The S3 release channel the CLI downloads native tools from: the manifest scripts/release/*
+ * publishes (releases/versions.json) + the sha256-verified archive download. Consumers:
+ *   - desktopRenderer.ts  the LeCodes Desktop host behind `render --desktop` (product "desktop")
+ *   - matcTool.ts         Filament's matc for local shader compile (product "matc")
+ */
+
+// Straight off the S3 bucket, NOT the CDN: the manifest must never be stale (an updater reading
+// a cached copy would miss fresh releases), and a ~2 KB JSON doesn't need one. The artifact URLs
+// INSIDE it are whatever publish.ts baked (RELEASES_PUBLIC_BASE) — immutable, so caching is fine there.
+const MANIFEST_URL = "https://storage.yandexcloud.net/le-codes/releases/versions.json"
+
+export type ManifestFile = { url: string, size: number, sha256: string }
+
+/** Written inside every downloaded cache dir: WHICH artifact it holds. A cache dir is named after
+ *  the release VERSION, but a version can be republished — the macOS desktop host shipped twice as
+ *  1.3.2 — and then the name alone says nothing about the contents. Recording the sha256 is what
+ *  lets `update` tell "already have it" from "same number, different build". */
+const ARTIFACT_STAMP = ".lecodes-artifact.json"
+
+/** The sha256 of the artifact a cache dir was filled from; null for a dir predating the stamp
+ *  (treat as unknown — i.e. re-download, since its contents can't be vouched for). */
+export const cachedArtifactSha = (dir: string): string | null => {
+  try {
+    return (JSON.parse(readFileSync(join(dir, ARTIFACT_STAMP), "utf8")) as { sha256?: string }).sha256 ?? null
+  } catch {
+    return null
+  }
+}
+export type ManifestVersion = { version: string, files: Record<string, ManifestFile> }
+type Manifest = { products?: Record<string, { latest: string, versions: ManifestVersion[] }> }
+
+/** Positive when b is a newer semver than a (the manifest publisher's ordering, mirrored). */
+export const semverNewer = (a: string, b: string): number => {
+  const pa = a.split(/[.-]/).map(Number), pb = b.split(/[.-]/).map(Number)
+  for (let i = 0; i < 3; i++) if ((pb[i] ?? 0) !== (pa[i] ?? 0)) return (pb[i] ?? 0) - (pa[i] ?? 0)
+  return 0
+}
+
+/** One product from the release manifest (always fetched fresh — see MANIFEST_URL). */
+export const fetchReleaseProduct = async (
+  product: string, label: string,
+): Promise<{ latest: string, versions: ManifestVersion[] }> => {
+  let manifest: Manifest
+  try {
+    const res = await fetch(MANIFEST_URL)
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    manifest = (await res.json()) as Manifest
+  } catch (e) {
+    throw new CliError(`Can't fetch the release manifest (${MANIFEST_URL}): ${e instanceof Error ? e.message : String(e)}`)
+  }
+  const entry = manifest.products?.[product]
+  if (!entry) throw new CliError(`The release manifest has no ${label} product.`)
+  return entry
+}
+
+/**
+ * Download a manifest artifact, verify its sha256, extract it, and move it into `dest` — staged
+ * through a temp sibling so a killed download never leaves a half-cache that later resolves as
+ * valid. `validate` inspects the extracted stage and returns an error string when the archive
+ * doesn't contain what the caller expects (null = good). A concurrent download winning the final
+ * rename is fine as long as `dest` then validates.
+ */
+export const downloadReleaseArchive = async (
+  file: ManifestFile,
+  opts: {
+    cacheRoot: string, dest: string, validate: (dir: string) => string | null,
+    /** Unpack `archive` into `stage` (default: tar — which reads .zip/.tar.gz everywhere it runs).
+     *  The macOS desktop host publishes as a DMG, which tar can't open; desktopRenderer passes an
+     *  hdiutil-based extractor for it. */
+    extract?: (archive: string, stage: string) => void,
+  },
+): Promise<void> => {
+  let bytes: Buffer
+  try {
+    const res = await fetch(file.url)
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    bytes = Buffer.from(await res.arrayBuffer())
+  } catch (e) {
+    throw new CliError(`Download failed (${file.url}): ${e instanceof Error ? e.message : String(e)}`)
+  }
+  const sha = createHash("sha256").update(bytes).digest("hex")
+  if (sha !== file.sha256) throw new CliError(`Downloaded archive is corrupt (sha256 mismatch) — try again.`)
+
+  // Extract into a temp sibling, then rename into place. `tar` handles .zip too on Windows 10+ (bsdtar).
+  mkdirSync(opts.cacheRoot, { recursive: true })
+  const stage = mkdtempSync(join(opts.cacheRoot, "dl-"))
+  try {
+    const archiveName = file.url.split("/").pop() ?? "archive"
+    const archive = join(stage, archiveName)
+    writeFileSync(archive, bytes)
+    if (opts.extract) {
+      opts.extract(archive, stage)
+    } else {
+      // On Windows use the SYSTEM tar (bsdtar, Windows 10+) by absolute path — it's the one that
+      // extracts .zip too, and a Git Bash PATH would otherwise resolve GNU tar, which can't read
+      // zip AND parses the `:` in `C:\…` as a remote-host separator. Relative path + cwd keeps the
+      // argv drive-letter-free for the GNU-tar fallback (PATH) on other setups.
+      const winTar = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "tar.exe")
+      const tarExe = process.platform === "win32" && existsSync(winTar) ? winTar : "tar"
+      const tar = spawnSync(tarExe, ["-xf", archiveName], { cwd: stage, stdio: ["ignore", "ignore", "pipe"] })
+      if (tar.status !== 0) throw new CliError(`Couldn't extract the archive: ${tar.stderr?.toString() ?? "tar failed"}`)
+    }
+    rmSync(archive)
+    const bad = opts.validate(stage)
+    if (bad) throw new CliError(bad)
+    // Stamp before the rename, so a cache dir can never exist without saying what it holds.
+    writeFileSync(join(stage, ARTIFACT_STAMP), JSON.stringify({ sha256: file.sha256, url: file.url }, null, 2))
+    try {
+      renameSync(stage, opts.dest)
+    } catch {
+      let destBad: string | null
+      try { destBad = opts.validate(opts.dest) } catch { destBad = "missing" }
+      if (destBad) throw new CliError(`Couldn't move the download into ${opts.dest}.`) // a concurrent download won the race → fine
+    }
+  } finally {
+    rmSync(stage, { recursive: true, force: true })
+  }
+}

package/src/serverDiff.ts

@@ -0,0 +1,78 @@
+import { readFileSync } from "node:fs"
+import type { Project, ProjectAsset } from "./api"
+import type { LocalScan } from "./localFiles"
+import { classifyKind, isTextKind } from "./localFiles"
+import { buildPaths } from "./project"
+import { basename } from "node:path"
+
+/*
+ * Compares the local working tree against the project's current server state — the basis for
+ * `lecodes diff` and the `push --force` overwrite preview. Status is local-relative:
+ *   added    — present locally, absent on the server (a `push` would create it)
+ *   removed  — present on the server, absent locally (a `push` would delete it)
+ *   modified — present on both with differing content (a `push` would overwrite the server copy)
+ *
+ * Text content (text/shader/scene assets) is compared exactly and carried for a line diff. Binary
+ * assets are compared by size only — true server-side binary changes aren't detected (noted to the
+ * user), but local binary edits and presence differences are.
+ */
+
+export type ServerDiffStatus = "added" | "removed" | "modified"
+
+export type ServerDiffEntry = {
+  path: string
+  status: ServerDiffStatus
+  binary: boolean
+  /** For text entries: the server-side text (the diff's "old" side); "" when absent on the server. */
+  serverText?: string
+  /** For text entries: the local text (the diff's "new" side); "" when absent locally. */
+  localText?: string
+}
+
+const isTextAsset = (t: ProjectAsset["type"]) => t === "text" || t === "shader" || t === "scene"
+
+/** Diff the local scan against the server `project`. Sorted by path. */
+export const computeServerDiff = (project: Project, scan: LocalScan): ServerDiffEntry[] => {
+  const pathById = buildPaths(project.assets)
+  const serverByPath = new Map<string, ProjectAsset>()
+  for (const asset of project.assets) {
+    if (asset.type === "folder") continue
+    serverByPath.set(pathById.get(asset.id)!, asset)
+  }
+  const localByPath = new Map(scan.files.map(f => [f.path, f]))
+
+  const entries: ServerDiffEntry[] = []
+  const paths = new Set<string>([...serverByPath.keys(), ...localByPath.keys()])
+
+  for (const path of [...paths].sort()) {
+    const server = serverByPath.get(path)
+    const local = localByPath.get(path)
+
+    if (local && !server) {
+      const text = isTextKind(classifyKind(basename(path)))
+      entries.push({ path, status: "added", binary: !text, serverText: "", localText: text ? readFileSync(local.absPath, "utf8") : undefined })
+      continue
+    }
+    if (server && !local) {
+      const text = isTextAsset(server.type)
+      entries.push({ path, status: "removed", binary: !text, serverText: text ? (server.text ?? "") : undefined, localText: "" })
+      continue
+    }
+    // present on both
+    if (server && local) {
+      if (isTextAsset(server.type)) {
+        const serverText = server.text ?? ""
+        const localText = readFileSync(local.absPath, "utf8")
+        if (serverText !== localText) entries.push({ path, status: "modified", binary: false, serverText, localText })
+      } else {
+        // Binary: compare by size when the server reports one; otherwise can't tell → skip quietly.
+        const serverSize = server.file?.size
+        const localSize = Buffer.byteLength(readFileSync(local.absPath))
+        if (serverSize !== undefined && serverSize !== localSize) {
+          entries.push({ path, status: "modified", binary: true })
+        }
+      }
+    }
+  }
+  return entries
+}

package/src/textDiff.ts

@@ -0,0 +1,103 @@
+import { c } from "./util"
+
+/* A small line-level unified diff (LCS-based) for `lecodes diff`. Good enough for source files;
+ * for very large inputs it bails out to a one-line summary to avoid O(n·m) blow-up. */
+
+const MAX_LINES = 4000
+
+type Op = { tag: " " | "-" | "+", line: string }
+
+/** Longest-common-subsequence over lines → a sequence of context/-/+ ops. */
+const lcsDiff = (a: string[], b: string[]): Op[] => {
+  const n = a.length, m = b.length
+  // dp[i][j] = LCS length of a[i:], b[j:]
+  const dp: number[][] = Array.from({ length: n + 1 }, () => new Array<number>(m + 1).fill(0))
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1])
+    }
+  }
+  const ops: Op[] = []
+  let i = 0, j = 0
+  while (i < n && j < m) {
+    if (a[i] === b[j]) { ops.push({ tag: " ", line: a[i] }); i++; j++ }
+    else if (dp[i + 1][j] >= dp[i][j + 1]) { ops.push({ tag: "-", line: a[i] }); i++ }
+    else { ops.push({ tag: "+", line: b[j] }); j++ }
+  }
+  while (i < n) ops.push({ tag: "-", line: a[i++] })
+  while (j < m) ops.push({ tag: "+", line: b[j++] })
+  return ops
+}
+
+const splitLines = (text: string): string[] => {
+  if (text === "") return []
+  const lines = text.split("\n")
+  if (lines[lines.length - 1] === "") lines.pop() // trailing newline isn't a line
+  return lines
+}
+
+/**
+ * Produce a colored unified diff of `oldText` → `newText`. Returns "" when there's no difference.
+ * `oldLabel`/`newLabel` head the `--- ` / `+++ ` lines.
+ */
+export const unifiedDiff = (
+  oldText: string, newText: string, oldLabel: string, newLabel: string, context = 3,
+): string => {
+  if (oldText === newText) return ""
+  const a = splitLines(oldText)
+  const b = splitLines(newText)
+  if (a.length + b.length > MAX_LINES) {
+    return c.dim(`  (large file — ${a.length} → ${b.length} lines, diff omitted)`)
+  }
+
+  const ops = lcsDiff(a, b)
+
+  // Group ops into hunks, keeping `context` unchanged lines around each run of changes.
+  type Hunk = { aStart: number, bStart: number, lines: Op[] }
+  const hunks: Hunk[] = []
+  let aLine = 0, bLine = 0 // 1-based counters advanced as we walk ops
+  let cur: Hunk | null = null
+  let trailingContext = 0
+
+  for (let k = 0; k < ops.length; k++) {
+    const op = ops[k]
+    const isChange = op.tag !== " "
+    if (isChange) {
+      if (!cur) {
+        // open a hunk, back-filling up to `context` preceding context lines
+        const back: Op[] = []
+        let bi = k - 1
+        while (bi >= 0 && ops[bi].tag === " " && back.length < context) { back.unshift(ops[bi]); bi-- }
+        cur = { aStart: aLine - back.length, bStart: bLine - back.length, lines: [...back] }
+      }
+      cur.lines.push(op)
+      trailingContext = 0
+    } else if (cur) {
+      cur.lines.push(op)
+      if (++trailingContext >= context * 2) {
+        // enough trailing context → close the hunk, dropping the surplus tail context
+        cur.lines.length -= trailingContext - context
+        hunks.push(cur); cur = null; trailingContext = 0
+      }
+    }
+    if (op.tag !== "+") aLine++
+    if (op.tag !== "-") bLine++
+  }
+  if (cur) {
+    if (trailingContext > context) cur.lines.length -= trailingContext - context
+    hunks.push(cur)
+  }
+
+  const out: string[] = [c.bold(`--- ${oldLabel}`), c.bold(`+++ ${newLabel}`)]
+  for (const h of hunks) {
+    const aCount = h.lines.filter(o => o.tag !== "+").length
+    const bCount = h.lines.filter(o => o.tag !== "-").length
+    out.push(c.cyan(`@@ -${h.aStart + 1},${aCount} +${h.bStart + 1},${bCount} @@`))
+    for (const o of h.lines) {
+      if (o.tag === "+") out.push(c.green("+" + o.line))
+      else if (o.tag === "-") out.push(c.red("-" + o.line))
+      else out.push(c.dim(" " + o.line))
+    }
+  }
+  return out.join("\n")
+}

package/src/util.ts

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto"
+import { createInterface } from "node:readline"
+import { sanitizeAssetName } from "lecodes-sdk/compile/assetName"
+
+/* Small dependency-free helpers shared across commands: colored logging, prompts, hashing,
+ * posix-path normalization and a minimal argv parser. */
+
+const useColor = process.stdout.isTTY && process.env.NO_COLOR === undefined
+const paint = (code: string, s: string) => useColor ? `\x1b[${code}m${s}\x1b[0m` : s
+export const c = {
+  bold: (s: string) => paint("1", s),
+  dim: (s: string) => paint("2", s),
+  red: (s: string) => paint("31", s),
+  green: (s: string) => paint("32", s),
+  yellow: (s: string) => paint("33", s),
+  cyan: (s: string) => paint("36", s),
+}
+
+export const log = (msg = ""): void => { process.stdout.write(msg + "\n") }
+export const info = (msg: string) => log(msg)
+export const success = (msg: string) => log(c.green("✓ ") + msg)
+export const warn = (msg: string) => log(c.yellow("! ") + msg)
+
+// stderr variants — for commands that write a result (JS, data) to stdout, so diagnostics never
+// pollute the piped output.
+export const logErr = (msg = "") => process.stderr.write(msg + "\n")
+export const note = (msg: string) => logErr(c.dim(msg))
+export const warnErr = (msg: string) => logErr(c.yellow("! ") + msg)
+
+/** Keep a label short, dropping characters from the FRONT (paths matter most at the end). */
+const ellipsize = (s: string, max: number) => s.length <= max ? s : "…" + s.slice(s.length - max + 1)
+
+/** A single, in-place-updating progress line (TTY only; a no-op when piped). */
+export const progress = (done: number, total: number, label = "") => {
+  if (!process.stdout.isTTY) return
+  const pct = total > 0 ? Math.round((done / total) * 100) : 100
+  process.stdout.clearLine(0)
+  process.stdout.cursorTo(0)
+  process.stdout.write(`  ${c.cyan(`${pct}`.padStart(3) + "%")} ${c.dim(`(${done}/${total})`)} ${c.dim(ellipsize(label, 48))}`)
+}
+
+/** Finish a progress line with a newline so later output starts cleanly. */
+export const endProgress = () => { if (process.stdout.isTTY) process.stdout.write("\n") }
+
+/** A user-facing error: index.ts prints its message without a stack trace and exits non-zero. */
+export class CliError extends Error {
+  /** HTTP status, when the failure came from the API. Lets a caller tell "already gone" (404) from
+   *  "refused" (403) — deleting something the server no longer has is a success, not an error. */
+  status?: number
+  constructor(message: string, status?: number) {
+    super(message)
+    this.status = status
+  }
+}
+
+// Output targets that mean "discard" — so `-o /dev/null` (or Windows NUL) doesn't create a real file.
+const NULL_SINKS = new Set(["/dev/null", "nul", "//./nul"])
+/** True if an `--out` value is a null device, i.e. the output should be thrown away, not written. */
+export const isNullSink = (path: string): boolean =>
+  NULL_SINKS.has(path.trim().replace(/\\/g, "/").toLowerCase())
+
+export const sha256 = (data: string | Uint8Array): string =>
+  createHash("sha256").update(data).digest("hex")
+
+/** Normalize any path to a leading-slash, forward-slash, "." / ".." free key (e.g. "/a/b.ts").
+ *  Each segment gets the platform's canonical spelling (sdk/compile/assetName) — macOS hands out
+ *  decomposed names ("й" as и + U+0306) from readdir, which would otherwise key a file differently
+ *  than the same name typed in an import or stored on the server. */
+export const toKey = (path: string): string => {
+  const parts = path.replace(/\\/g, "/").split("/").map(p => p.trim()).filter(p => p && p !== ".")
+  if (parts.some(p => p === "..")) throw new CliError(`Unsafe path: ${path}`)
+  const names = parts.map(p => sanitizeAssetName(p))
+  if (names.some(name => !name)) throw new CliError(`Wrong path: ${path}`)
+  return "/" + names.join("/")
+}
+
+export const prompt = (question: string, fallback?: string): Promise<string> =>
+  new Promise(resolve => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    const suffix = fallback ? c.dim(` (${fallback})`) : ""
+    rl.question(`${question}${suffix}: `, answer => {
+      rl.close()
+      resolve(answer.trim() || fallback || "")
+    })
+  })
+
+/** Prompt without echoing the input (for passwords / token paste). */
+export const promptHidden = (question: string): Promise<string> =>
+  new Promise(resolve => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true })
+    rl.question(`${question}: `, answer => {
+      rl.close()
+      process.stdout.write("\n")
+      resolve(answer.trim())
+    })
+    // Mute everything written after the prompt line was emitted (the keystroke echoes).
+    ;(rl as unknown as { _writeToOutput: (s: string) => void })._writeToOutput = () => {}
+  })
+
+export const confirm = async (question: string, fallback = false): Promise<boolean> => {
+  const answer = (await prompt(`${question} ${fallback ? "[Y/n]" : "[y/N]"}`)).toLowerCase()
+  if (!answer) return fallback
+  return answer === "y" || answer === "yes"
+}
+
+export type Args = { _: string[], flags: Record<string, string | boolean> }
+
+/** Parse argv into positionals + flags. Supports `--key value`, `--key=value`, `--bool`, `-m msg`. */
+// `--look-at -0.15,1,2` / `--scale -1`: a token that starts with "-" followed by a digit (or ".5")
+// is a negative NUMBER (or a vector starting with one), not the next flag.
+const isNegativeNumber = (s: string): boolean => /^-(\d|\.\d)/.test(s)
+const isValue = (s: string): boolean => !s.startsWith("-") || isNegativeNumber(s)
+
+export const parseArgs = (argv: string[]): Args => {
+  const out: Args = { _: [], flags: {} }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=")
+      if (eq >= 0) { out.flags[arg.slice(2, eq)] = arg.slice(eq + 1); continue }
+      const key = arg.slice(2)
+      const next = argv[i + 1]
+      if (next !== undefined && isValue(next)) { out.flags[key] = next; i++ }
+      else out.flags[key] = true
+    } else if (arg.startsWith("-") && arg.length > 1 && !isNegativeNumber(arg)) {
+      const key = arg.slice(1)
+      const next = argv[i + 1]
+      if (next !== undefined && isValue(next)) { out.flags[key] = next; i++ }
+      else out.flags[key] = true
+    } else {
+      out._.push(arg)
+    }
+  }
+  return out
+}
+
+export const flagStr = (args: Args, ...keys: string[]): string | undefined => {
+  for (const key of keys) {
+    const v = args.flags[key]
+    if (typeof v === "string") return v
+  }
+  return undefined
+}
+
+export const flagBool = (args: Args, ...keys: string[]): boolean =>
+  keys.some(key => args.flags[key] === true || args.flags[key] === "true")