lecodes-cli 0.1.2 → 0.1.5

package/README.md

@@ -35,7 +35,7 @@ lecodes preview > app.js            # compile the local project to JS
 | `pull` | Overwrite local files with the project's current remote state. `--force` to discard local edits. |
 | `push` | Push all local changes as **one** new checkpoint. `-m`/`--message` for the message, `--force` to override the "server moved on" guard. |
 | `preview` | Compile the local project to a single JS bundle, printed to **stdout** (pipeable). `-o`/`--out <file>` to write a file, `--entry <path>` to override the entrypoint, `--no-header` to omit the metadata header, `--public-url <url>` for the asset URL prefix. Diagnostics go to stderr. |
-| `render` | Render the local **UI** project. By default emits a semantic JSON description (great for AI/automated checks) to stdout or `-o`/`--out <file>`; `--png [file]` rasterizes a PNG (default `screenshot.png`, `--scale <n>` for DPR). `--width`/`--height` set the viewport (default 390×844). Requires the optional `lecodes-render` package (`npm i -D lecodes-render`); PNG also needs `@napi-rs/canvas`. 3D scenes aren't rendered. |
+| `render` | Render the local **UI** project. By default emits a semantic JSON description (great for AI/automated checks) to stdout or `-o`/`--out <file>`; `--png [file]` rasterizes a PNG (default `screenshot.png`, `--scale <n>` for DPR). `--width`/`--height` set the viewport (default 390×844). Requires the optional `lecodes-renderer` package (`npm i -D lecodes-renderer`); PNG also needs `@napi-rs/canvas`. 3D scenes aren't rendered. |
 
 ## How it works
 

package/dist/index.js

@@ -2,8 +2,13 @@
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// src/index.ts
+import { readFileSync as readFileSync8 } from "node:fs";
+import { dirname as dirname5, join as join9 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
 // src/commands/clone.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync5, readdirSync } from "node:fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync5, readdirSync } from "node:fs";
 import { resolve } from "node:path";
 
 // src/util.ts
@@ -23,6 +28,7 @@ var log = (msg = "") => process.stdout.write(msg + `
 `);
 var info = (msg) => log(msg);
 var success = (msg) => log(c.green("✓ ") + msg);
+var warn = (msg) => log(c.yellow("! ") + msg);
 var logErr = (msg = "") => process.stderr.write(msg + `
 `);
 var note = (msg) => logErr(c.dim(msg));
@@ -44,6 +50,8 @@ var endProgress = () => {
 
 class CliError extends Error {
 }
+var NULL_SINKS = new Set(["/dev/null", "nul", "//./nul"]);
+var isNullSink = (path) => NULL_SINKS.has(path.trim().replace(/\\/g, "/").toLowerCase());
 var sha256 = (data) => createHash("sha256").update(data).digest("hex");
 var toKey = (path) => {
   const parts = path.replace(/\\/g, "/").split("/").map((p) => p.trim()).filter((p) => p && p !== ".");
@@ -59,6 +67,12 @@ var prompt = (question, fallback) => new Promise((resolve) => {
     resolve(answer.trim() || fallback || "");
   });
 });
+var confirm = async (question, fallback = false) => {
+  const answer = (await prompt(`${question} ${fallback ? "[Y/n]" : "[y/N]"}`)).toLowerCase();
+  if (!answer)
+    return fallback;
+  return answer === "y" || answer === "yes";
+};
 var parseArgs = (argv) => {
   const out = { _: [], flags: {} };
   for (let i = 0;i < argv.length; i++) {
@@ -154,6 +168,7 @@ var uploadBlob = (apiUrl, token, uuid, name, bytes) => {
   return apiRequest(apiUrl, `/projects/${uuid}/blobs`, { token, body: form });
 };
 var sync = (apiUrl, token, uuid, payload) => apiRequest(apiUrl, `/projects/${uuid}/sync`, { token, body: payload });
+var publishProject = (apiUrl, token, uuid) => apiRequest(apiUrl, `/projects/${uuid}/publish`, { token, body: {} });
 var downloadBlob = async (apiUrl, src) => {
   const resp = await fetch(`${apiUrl}${src}`);
   if (!resp.ok)
@@ -328,6 +343,96 @@ var writeTsconfig = (root) => {
   writeFileSync4(join4(root, "tsconfig.json"), JSON.stringify(TSCONFIG, null, 2));
 };
 
+// src/ignore.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync5 } from "node:fs";
+import { join as join5 } from "node:path";
+var BUILTIN_PATTERNS = ["node_modules/", ".git/", "_*", "*.log", ".DS_Store"];
+var DEFAULT_IGNORE_FILE = `# Files matched here are NOT pushed to LeCodes.
+# Only untracked files are affected — assets already in the project stay tracked
+# even if they match a pattern. Built-in defaults (node_modules, _*, *.log) always apply.
+
+# Render / preview outputs
+screenshot.png
+shots/
+*.png
+
+# Local notes & dumps (uncomment to ignore)
+# *.json
+# notes.md
+`;
+var translate = (glob) => {
+  let re = "";
+  for (let i = 0;i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "*") {
+      if (glob[i + 1] === "*") {
+        re += ".*";
+        i++;
+        if (glob[i + 1] === "/")
+          i++;
+      } else
+        re += "[^/]*";
+    } else if (ch === "?")
+      re += "[^/]";
+    else if (ch === "/")
+      re += "/";
+    else if ("\\^$.|+()[]{}".includes(ch))
+      re += "\\" + ch;
+    else
+      re += ch;
+  }
+  return re;
+};
+var compile = (raw) => {
+  let p = raw.trim();
+  if (!p || p.startsWith("#"))
+    return null;
+  let negate = false;
+  if (p.startsWith("!")) {
+    negate = true;
+    p = p.slice(1);
+  }
+  let dirOnly = false;
+  if (p.endsWith("/")) {
+    dirOnly = true;
+    p = p.slice(0, -1);
+  }
+  const anchored = p.startsWith("/") || p.includes("/");
+  if (p.startsWith("/"))
+    p = p.slice(1);
+  if (!p)
+    return null;
+  const body = translate(p);
+  const re = anchored ? new RegExp("^/" + body + "(/.*)?$") : new RegExp("(^|/)" + body + "(/.*)?$");
+  return { re, negate, dirOnly };
+};
+var buildMatcher = (rules) => (key, isDir) => {
+  let ignored = false;
+  for (const r of rules) {
+    if (r.dirOnly && !isDir)
+      continue;
+    if (r.re.test(key))
+      ignored = !r.negate;
+  }
+  return ignored;
+};
+var loadIgnore = (root) => {
+  const lines = [...BUILTIN_PATTERNS];
+  const file = join5(root, ".lecodesignore");
+  if (existsSync2(file)) {
+    try {
+      lines.push(...readFileSync3(file, "utf8").split(/\r?\n/));
+    } catch {}
+  }
+  const rules = lines.map(compile).filter((r) => r !== null);
+  return buildMatcher(rules);
+};
+var writeDefaultIgnore = (root) => {
+  const file = join5(root, ".lecodesignore");
+  if (!existsSync2(file))
+    writeFileSync5(file, DEFAULT_IGNORE_FILE);
+};
+
 // src/commands/clone.ts
 var parseUuid = (input) => {
   if (!input)
@@ -347,7 +452,7 @@ var clone = async (args) => {
   const project = await getProject(apiUrl, token, uuid);
   const dir = args._[1] ?? slug(project.name);
   const root = resolve(dir);
-  if (existsSync2(root) && readdirSync(root).length > 0) {
+  if (existsSync3(root) && readdirSync(root).length > 0) {
     throw new CliError(`Directory "${dir}" already exists and is not empty.`);
   }
   mkdirSync5(root, { recursive: true });
@@ -359,12 +464,310 @@ var clone = async (args) => {
     await materializeTypes(root, apiUrl);
     writeTsconfig(root);
   }
+  writeDefaultIgnore(root);
   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"\``));
 };
 
+// src/localFiles.ts
+import { readdirSync as readdirSync2, readFileSync as readFileSync4 } from "node:fs";
+import { join as join6, relative } from "node:path";
+var SKIP_DIRS = new Set([".lecodes", ".git", "node_modules"]);
+var SKIP_FILES = new Set(["tsconfig.json", "jsconfig.json", ".gitignore", ".lecodesignore", ".DS_Store"]);
+var TEXT_EXTS = new Set([
+  "ts",
+  "tsx",
+  "js",
+  "jsx",
+  "mjs",
+  "cjs",
+  "json",
+  "svg",
+  "glsl",
+  "vert",
+  "frag",
+  "txt",
+  "md",
+  "css",
+  "html",
+  "xml",
+  "yml",
+  "yaml",
+  "csv"
+]);
+var ext = (name) => {
+  const i = name.lastIndexOf(".");
+  return i < 0 ? "" : name.slice(i + 1).toLowerCase();
+};
+var classifyKind = (name) => {
+  const e = ext(name);
+  if (e === "mat")
+    return "shader";
+  if (e === "scene")
+    return "scene";
+  return TEXT_EXTS.has(e) ? "text" : "resource";
+};
+var isTextKind = (kind) => kind !== "resource";
+var scanLocal = (root, opts = {}) => {
+  const { ignore, tracked } = opts;
+  const files = [];
+  const dirs = [];
+  const ignored = [];
+  const isTracked = (key) => tracked?.has(key) ?? false;
+  const hasTrackedUnder = (key) => {
+    if (!tracked)
+      return false;
+    const prefix = key + "/";
+    for (const t of tracked)
+      if (t.startsWith(prefix))
+        return true;
+    return false;
+  };
+  const walk = (dir, parentIgnored) => {
+    for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+      const abs = join6(dir, entry.name);
+      const key = toKey(relative(root, abs));
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name))
+          continue;
+        const dirIgnored = parentIgnored || !!ignore && ignore(key, true);
+        if (dirIgnored && !isTracked(key) && !hasTrackedUnder(key)) {
+          ignored.push(key + "/");
+          continue;
+        }
+        dirs.push(key);
+        walk(abs, dirIgnored);
+      } else if (entry.isFile()) {
+        if (SKIP_FILES.has(entry.name))
+          continue;
+        const fileIgnored = parentIgnored || !!ignore && ignore(key, false);
+        if (fileIgnored && !isTracked(key)) {
+          ignored.push(key);
+          continue;
+        }
+        files.push({ path: key, absPath: abs, sha: sha256(readFileSync4(abs)) });
+      }
+    }
+  };
+  walk(root, false);
+  return { files, dirs, ignored };
+};
+var scanProject = (root, manifest) => scanLocal(root, { ignore: loadIgnore(root), tracked: new Set(Object.keys(manifest.files)) });
+var diffLocal = (manifest, scan) => {
+  const added = [];
+  const modified = [];
+  const localByPath = new Map(scan.files.map((f) => [f.path, f]));
+  for (const file of scan.files) {
+    const known = manifest.files[file.path];
+    if (!known)
+      added.push(file);
+    else if (known.sha !== file.sha)
+      modified.push(file);
+  }
+  const deleted = Object.keys(manifest.files).filter((path) => !localByPath.has(path));
+  const moves = new Map;
+  const claimed = new Set;
+  for (const file of added) {
+    const from = deleted.find((path) => !claimed.has(path) && manifest.files[path].sha === file.sha);
+    if (from) {
+      moves.set(file.path, from);
+      claimed.add(from);
+    }
+  }
+  return { added, modified, deleted, moves };
+};
+var hasChanges = (diff) => diff.added.length + diff.modified.length + diff.deleted.length > 0;
+
+// src/serverDiff.ts
+import { readFileSync as readFileSync5 } from "node:fs";
+import { basename } from "node:path";
+var isTextAsset = (t) => t === "text" || t === "shader" || t === "scene";
+var computeServerDiff = (project, scan) => {
+  const pathById = buildPaths(project.assets);
+  const serverByPath = new Map;
+  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 = [];
+  const paths = new Set([...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 ? readFileSync5(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;
+    }
+    if (server && local) {
+      if (isTextAsset(server.type)) {
+        const serverText = server.text ?? "";
+        const localText = readFileSync5(local.absPath, "utf8");
+        if (serverText !== localText)
+          entries.push({ path, status: "modified", binary: false, serverText, localText });
+      } else {
+        const serverSize = server.file?.size;
+        const localSize = Buffer.byteLength(readFileSync5(local.absPath));
+        if (serverSize !== undefined && serverSize !== localSize) {
+          entries.push({ path, status: "modified", binary: true });
+        }
+      }
+    }
+  }
+  return entries;
+};
+
+// src/textDiff.ts
+var MAX_LINES = 4000;
+var lcsDiff = (a, b) => {
+  const n = a.length, m = b.length;
+  const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i2 = n - 1;i2 >= 0; i2--) {
+    for (let j2 = m - 1;j2 >= 0; j2--) {
+      dp[i2][j2] = a[i2] === b[j2] ? dp[i2 + 1][j2 + 1] + 1 : Math.max(dp[i2 + 1][j2], dp[i2][j2 + 1]);
+    }
+  }
+  const ops = [];
+  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;
+};
+var splitLines = (text) => {
+  if (text === "")
+    return [];
+  const lines = text.split(`
+`);
+  if (lines[lines.length - 1] === "")
+    lines.pop();
+  return lines;
+};
+var unifiedDiff = (oldText, newText, oldLabel, newLabel, context = 3) => {
+  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);
+  const hunks = [];
+  let aLine = 0, bLine = 0;
+  let cur = null;
+  let trailingContext = 0;
+  for (let k = 0;k < ops.length; k++) {
+    const op = ops[k];
+    const isChange = op.tag !== " ";
+    if (isChange) {
+      if (!cur) {
+        const back = [];
+        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) {
+        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 = [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(`
+`);
+};
+
+// src/commands/diff.ts
+var diff = async (args) => {
+  const root = findProjectRoot(process.cwd());
+  const manifest = readManifest(root);
+  const config = loadConfig();
+  const apiUrl = requireApiUrl(config);
+  const token = requireToken(config);
+  info(c.dim("Comparing with the server…"));
+  const project = await getProject(apiUrl, token, manifest.uuid);
+  const scan = scanProject(root, manifest);
+  let entries = computeServerDiff(project, scan);
+  if (args._.length > 0) {
+    const keys = args._.map(toKey);
+    entries = entries.filter((e) => keys.some((k) => e.path === k || e.path.startsWith(k + "/")));
+  }
+  if (entries.length === 0) {
+    info(c.dim("No differences between local and server."));
+    return;
+  }
+  if (flagBool(args, "name-only")) {
+    for (const e of entries)
+      log(statusLabel(e) + e.path + (e.binary ? c.dim(" (binary)") : ""));
+    return;
+  }
+  for (const e of entries) {
+    if (e.binary) {
+      log(statusLabel(e) + e.path + c.dim(" (binary — content not shown)"));
+      continue;
+    }
+    const d = unifiedDiff(e.serverText ?? "", e.localText ?? "", `server${e.path}`, `local${e.path}`);
+    if (d)
+      log(`
+` + d);
+  }
+};
+var statusLabel = (e) => e.status === "added" ? c.green("  added    ") : e.status === "removed" ? c.red("  removed  ") : c.yellow("  modified ");
+
 // src/browserAuth.ts
 import { createServer } from "node:http";
 import { spawn } from "node:child_process";
@@ -455,101 +858,12 @@ var login = async (args) => {
 };
 
 // src/commands/preview.ts
-import { writeFileSync as writeFileSync5 } from "node:fs";
+import { writeFileSync as writeFileSync6 } from "node:fs";
 import { resolve as resolve2 } from "node:path";
 
 // src/compile/collect.ts
-import { readFileSync as readFileSync4 } from "node:fs";
-import { basename } from "node:path";
-
-// src/localFiles.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync3 } from "node:fs";
-import { join as join5, relative } from "node:path";
-var SKIP_DIRS = new Set([".lecodes", ".git", "node_modules"]);
-var SKIP_FILES = new Set(["tsconfig.json", "jsconfig.json", ".gitignore", ".DS_Store"]);
-var TEXT_EXTS = new Set([
-  "ts",
-  "tsx",
-  "js",
-  "jsx",
-  "mjs",
-  "cjs",
-  "json",
-  "svg",
-  "glsl",
-  "vert",
-  "frag",
-  "txt",
-  "md",
-  "css",
-  "html",
-  "xml",
-  "yml",
-  "yaml",
-  "csv"
-]);
-var ext = (name) => {
-  const i = name.lastIndexOf(".");
-  return i < 0 ? "" : name.slice(i + 1).toLowerCase();
-};
-var classifyKind = (name) => {
-  const e = ext(name);
-  if (e === "mat")
-    return "shader";
-  if (e === "scene")
-    return "scene";
-  return TEXT_EXTS.has(e) ? "text" : "resource";
-};
-var isTextKind = (kind) => kind !== "resource";
-var scanLocal = (root) => {
-  const files = [];
-  const dirs = [];
-  const walk = (dir) => {
-    for (const entry of readdirSync2(dir, { withFileTypes: true })) {
-      if (entry.isDirectory()) {
-        if (SKIP_DIRS.has(entry.name))
-          continue;
-        const abs = join5(dir, entry.name);
-        dirs.push(toKey(relative(root, abs)));
-        walk(abs);
-      } else if (entry.isFile()) {
-        if (SKIP_FILES.has(entry.name))
-          continue;
-        const abs = join5(dir, entry.name);
-        const bytes = readFileSync3(abs);
-        files.push({ path: toKey(relative(root, abs)), absPath: abs, sha: sha256(bytes) });
-      }
-    }
-  };
-  walk(root);
-  return { files, dirs };
-};
-var diffLocal = (manifest, scan) => {
-  const added = [];
-  const modified = [];
-  const localByPath = new Map(scan.files.map((f) => [f.path, f]));
-  for (const file of scan.files) {
-    const known = manifest.files[file.path];
-    if (!known)
-      added.push(file);
-    else if (known.sha !== file.sha)
-      modified.push(file);
-  }
-  const deleted = Object.keys(manifest.files).filter((path) => !localByPath.has(path));
-  const moves = new Map;
-  const claimed = new Set;
-  for (const file of added) {
-    const from = deleted.find((path) => !claimed.has(path) && manifest.files[path].sha === file.sha);
-    if (from) {
-      moves.set(file.path, from);
-      claimed.add(from);
-    }
-  }
-  return { added, modified, deleted, moves };
-};
-var hasChanges = (diff) => diff.added.length + diff.modified.length + diff.deleted.length > 0;
-
-// src/compile/collect.ts
+import { readFileSync as readFileSync6 } from "node:fs";
+import { basename as basename2 } from "node:path";
 var collectEntries = (root, manifest, project) => {
   const pathById = buildPaths(project.assets);
   const serverByPath = new Map;
@@ -561,7 +875,7 @@ var collectEntries = (root, manifest, project) => {
   const entries = [];
   const warnings = [];
   for (const file of scanLocal(root).files) {
-    const type = manifest.files[file.path]?.type ?? classifyKind(basename(file.path));
+    const type = manifest.files[file.path]?.type ?? classifyKind(basename2(file.path));
     if (type === "resource") {
       const src = serverByPath.get(file.path)?.fileSrc;
       if (!src)
@@ -573,7 +887,7 @@ var collectEntries = (root, manifest, project) => {
         warnings.push(`No compiled shader for ${file.path} — push it to compile the shader.`);
       entries.push({ path: file.path, type, shaders });
     } else {
-      entries.push({ path: file.path, type, text: readFileSync4(file.absPath, "utf8") });
+      entries.push({ path: file.path, type, text: readFileSync6(file.absPath, "utf8") });
     }
   }
   return { entries, warnings };
@@ -581,8 +895,8 @@ var collectEntries = (root, manifest, project) => {
 
 // src/compile/bundler.ts
 import * as esbuild from "esbuild";
-import { existsSync as existsSync3 } from "node:fs";
-import { dirname as dirname3, join as join6 } from "node:path";
+import { existsSync as existsSync4 } from "node:fs";
+import { dirname as dirname3, join as join7 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/compile/assetMacro.ts
@@ -625,32 +939,32 @@ import * as vec4 from "gl-matrix/vec4";
 `;
 var resolveRuntime = () => {
   const here = dirname3(fileURLToPath(import.meta.url));
-  const vendored = join6(here, "..", "runtime");
-  if (existsSync3(join6(vendored, "worker", "creator.js"))) {
-    const w = join6(vendored, "worker");
+  const vendored = join7(here, "..", "runtime");
+  if (existsSync4(join7(vendored, "worker", "creator.js"))) {
+    const w = join7(vendored, "worker");
     return {
       alias: {
-        creator: join6(w, "creator.js"),
-        ui: join6(w, "ui.js"),
-        animate: join6(w, "animate.js"),
-        utils: join6(w, "utils.js"),
-        "gl-matrix": join6(vendored, "gl-matrix")
+        creator: join7(w, "creator.js"),
+        ui: join7(w, "ui.js"),
+        animate: join7(w, "animate.js"),
+        utils: join7(w, "utils.js"),
+        "gl-matrix": join7(vendored, "gl-matrix")
       },
-      inject: [join6(w, "globals.js")]
+      inject: [join7(w, "globals.js")]
     };
   }
-  const repoRoot = join6(here, "..", "..", "..", "..");
-  const ws = join6(repoRoot, "packages", "worker", "src");
-  if (existsSync3(join6(ws, "index.ts"))) {
+  const repoRoot = join7(here, "..", "..", "..", "..");
+  const ws = join7(repoRoot, "packages", "worker", "src");
+  if (existsSync4(join7(ws, "index.ts"))) {
     return {
       alias: {
-        creator: join6(ws, "index.ts"),
-        ui: join6(ws, "ui.ts"),
-        animate: join6(ws, "animate.ts"),
-        utils: join6(ws, "utils.ts"),
-        "gl-matrix": join6(repoRoot, "packages", "backend", "src", "assets", "dependencies", "gl-matrix")
+        creator: join7(ws, "index.ts"),
+        ui: join7(ws, "ui.ts"),
+        animate: join7(ws, "animate.ts"),
+        utils: join7(ws, "utils.ts"),
+        "gl-matrix": join7(repoRoot, "packages", "backend", "src", "assets", "dependencies", "gl-matrix")
       },
-      inject: [join6(ws, "globals.ts")]
+      inject: [join7(ws, "globals.ts")]
     };
   }
   throw new CliError("Could not locate the compile runtime — try reinstalling lecodes-cli.");
@@ -833,8 +1147,10 @@ var preview = async (args) => {
   for (const w of warnings)
     warnErr(w);
   const out = flagStr(args, "o", "out");
-  if (out) {
-    writeFileSync5(resolve2(out), js);
+  if (out && isNullSink(out)) {
+    note(`Discarded output (${out})`);
+  } else if (out) {
+    writeFileSync6(resolve2(out), js);
     note(`Wrote ${out} (${js.length} bytes)`);
   } else {
     process.stdout.write(js);
@@ -846,9 +1162,37 @@ var preview = async (args) => {
 };
 
 // src/commands/render.ts
-import { writeFileSync as writeFileSync6 } from "node:fs";
+import { writeFileSync as writeFileSync7 } from "node:fs";
 import { resolve as resolve3 } from "node:path";
+var DEVICE_SAFE_AREA = {
+  none: [0, 0, 0, 0],
+  iphone: [47, 0, 34, 0],
+  android: [24, 0, 24, 0]
+};
+var resolveSafeArea = (args) => {
+  const explicit = flagStr(args, "safe-area");
+  if (explicit) {
+    const n = explicit.split(",").map((s) => Number(s.trim()));
+    if (n.length === 4 && n.every((v) => Number.isFinite(v)))
+      return n;
+    throw new CliError(`--safe-area expects "top,right,bottom,left" (4 numbers), got "${explicit}".`);
+  }
+  const device = flagStr(args, "device");
+  if (device) {
+    const preset = DEVICE_SAFE_AREA[device];
+    if (!preset)
+      throw new CliError(`Unknown --device "${device}". Options: ${Object.keys(DEVICE_SAFE_AREA).join(", ")}.`);
+    return preset;
+  }
+  return;
+};
 var render = async (args) => {
+  const timeoutMs = Number(flagStr(args, "timeout")) || 15000;
+  const killer = setTimeout(() => {
+    warnErr(`Render timed out after ${timeoutMs}ms (try --settle / --wait-network, or raise --timeout).`);
+    process.exit(1);
+  }, timeoutMs);
+  killer.unref?.();
   const root = findProjectRoot(process.cwd());
   const manifest = readManifest(root);
   const config = loadConfig();
@@ -871,54 +1215,81 @@ var render = async (args) => {
   }
   let renderer;
   try {
-    renderer = await import("lecodes-render");
+    renderer = await import("lecodes-renderer/headless");
   } catch {
-    throw new CliError("The renderer isn't installed. Run:  npm i -D lecodes-render");
+    throw new CliError("The renderer isn't installed. Run:  npm i -D lecodes-renderer");
   }
   const width = Number(flagStr(args, "width")) || 390;
   const height = Number(flagStr(args, "height")) || 844;
+  const settleStr = flagStr(args, "settle");
+  const timeStr = flagStr(args, "time");
+  const onConsole = flagBool(args, "logs") ? (level, text2) => logErr(`${c.dim(`[${level}]`)} ${text2}`) : undefined;
+  const timing = {
+    settleMs: settleStr !== undefined ? Number(settleStr) : undefined,
+    waitNetwork: flagBool(args, "wait-network"),
+    timeMs: timeStr !== undefined ? Number(timeStr) : undefined,
+    afterAnimations: !flagBool(args, "no-after-animations"),
+    safeArea: resolveSafeArea(args),
+    onConsole
+  };
+  const done = (flush) => flush(() => {
+    clearTimeout(killer);
+    process.exit(0);
+  });
   const pngFlag = flagStr(args, "png") ?? (flagBool(args, "png") ? "screenshot.png" : undefined);
   if (pngFlag !== undefined) {
     note("Rendering PNG…");
     const { png, warnings: pngWarnings } = await renderer.renderToPng(js, {
       width,
       height,
-      scale: Number(flagStr(args, "scale")) || 2
+      scale: Number(flagStr(args, "scale")) || 2,
+      ...timing
     });
-    const pngPath = resolve3(pngFlag);
-    writeFileSync6(pngPath, png);
     for (const w of [...warnings, ...pngWarnings])
       warnErr(w);
-    note(`Wrote ${pngFlag} (${png.length} bytes, ${width}x${height})`);
-    return;
+    if (isNullSink(pngFlag)) {
+      note(`Discarded PNG (${pngFlag})`);
+    } else {
+      writeFileSync7(resolve3(pngFlag), png);
+      note(`Wrote ${pngFlag} (${png.length} bytes, ${width}x${height})`);
+    }
+    return done((cb) => cb());
   }
   note("Rendering…");
-  const result = await renderer.renderToJson(js, { width, height });
+  const result = await renderer.renderToJson(js, { width, height, ...timing });
   for (const w of [...warnings, ...result.warnings])
     warnErr(w);
   const out = flagStr(args, "o", "out");
+  if (out && isNullSink(out)) {
+    note(`Discarded output (${out})`);
+    return done((cb) => cb());
+  }
   if (out) {
-    writeFileSync6(resolve3(out), result.text);
+    writeFileSync7(resolve3(out), result.text);
     note(`Wrote ${out} (${result.text.length} bytes)`);
-  } else {
-    process.stdout.write(result.text);
-    if (!result.text.endsWith(`
-`))
-      process.stdout.write(`
-`);
+    return done((cb) => cb());
   }
+  const text = result.text.endsWith(`
+`) ? result.text : result.text + `
+`;
+  return done((cb) => process.stdout.write(text, cb));
 };
 
 // src/commands/pull.ts
-import { existsSync as existsSync4, rmSync } from "node:fs";
-import { join as join7 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync6, rmSync, writeFileSync as writeFileSync8 } from "node:fs";
+import { dirname as dirname4, join as join8 } from "node:path";
 var pull = async (args) => {
   const root = findProjectRoot(process.cwd());
   const manifest = readManifest(root);
   const config = loadConfig();
   const apiUrl = requireApiUrl(config);
   const token = requireToken(config);
-  if (!flagBool(args, "force") && hasChanges(diffLocal(manifest, scanLocal(root)))) {
+  if (args._.length > 0) {
+    const project2 = await getProject(apiUrl, token, manifest.uuid);
+    await pullPaths(root, manifest, project2, args._.map(toKey), apiUrl, token);
+    return;
+  }
+  if (!flagBool(args, "force") && hasChanges(diffLocal(manifest, scanProject(root, manifest)))) {
     throw new CliError("You have local changes. Push them first, or run `lecodes pull --force` to discard them.");
   }
   info(c.dim("Fetching project…"));
@@ -926,8 +1297,8 @@ var pull = async (args) => {
   const remotePaths = new Set([...buildPaths(project.assets).entries()].filter(([id]) => project.assets.find((a) => a.id === id)?.type !== "folder").map(([, path]) => path));
   for (const path of Object.keys(manifest.files)) {
     if (!remotePaths.has(path)) {
-      const abs = join7(root, ...path.replace(/^\//, "").split("/"));
-      if (existsSync4(abs))
+      const abs = join8(root, ...path.replace(/^\//, "").split("/"));
+      if (existsSync5(abs))
         rmSync(abs);
     }
   }
@@ -941,42 +1312,110 @@ var pull = async (args) => {
   writeManifest(root, { ...manifest, name: project.name, baseHeadId: commits.headId, files });
   success(`Pulled latest into ${c.bold(manifest.name)}.`);
 };
+var kindOf2 = (type) => type === "file" ? "resource" : type;
+var pullPaths = async (root, manifest, project, paths, apiUrl, token) => {
+  const pathById = buildPaths(project.assets);
+  const byPath = new Map;
+  for (const asset of project.assets)
+    byPath.set(pathById.get(asset.id), asset);
+  const targets = [];
+  for (const path of paths) {
+    const asset = byPath.get(path);
+    if (!asset)
+      throw new CliError(`Not found on the server: ${path}`);
+    if (asset.type === "folder") {
+      const prefix = path + "/";
+      const under = project.assets.filter((a) => a.type !== "folder" && pathById.get(a.id).startsWith(prefix));
+      if (under.length === 0)
+        throw new CliError(`Folder is empty on the server: ${path}`);
+      targets.push(...under);
+    } else {
+      targets.push(asset);
+    }
+  }
+  const files = { ...manifest.files };
+  for (const asset of targets) {
+    const key = pathById.get(asset.id);
+    const abs = join8(root, ...key.replace(/^\//, "").split("/"));
+    mkdirSync6(dirname4(abs), { recursive: true });
+    let sha;
+    if (asset.type === "file") {
+      if (!asset.file?.src)
+        continue;
+      const bytes = await downloadBlob(apiUrl, asset.file.src);
+      writeFileSync8(abs, bytes);
+      sha = sha256(bytes);
+    } else {
+      const text = asset.text ?? "";
+      writeFileSync8(abs, text);
+      sha = sha256(text);
+    }
+    files[key] = { id: asset.id, type: kindOf2(asset.type), sha };
+    info(c.green(`  pulled  ${key}`));
+  }
+  writeManifest(root, { ...manifest, files });
+  success(`Pulled ${targets.length} file${targets.length === 1 ? "" : "s"} from the server.`);
+  info(c.dim("Local edits to other files are untouched. Run `lecodes diff` to review, then `lecodes push --force`."));
+};
 
 // src/commands/push.ts
-import { basename as basename2 } from "node:path";
-import { readFileSync as readFileSync5 } from "node:fs";
+import { basename as basename3 } from "node:path";
+import { readFileSync as readFileSync7 } from "node:fs";
 var push = async (args) => {
   const root = findProjectRoot(process.cwd());
   const manifest = readManifest(root);
   const config = loadConfig();
   const apiUrl = requireApiUrl(config);
   const token = requireToken(config);
-  const scan = scanLocal(root);
-  const diff = diffLocal(manifest, scan);
-  if (!hasChanges(diff)) {
-    info(c.dim("Working tree clean — nothing to push."));
+  const publish = flagBool(args, "publish");
+  const scan = scanProject(root, manifest);
+  const diff2 = diffLocal(manifest, scan);
+  if (!hasChanges(diff2)) {
+    if (publish) {
+      await publishProject(apiUrl, token, manifest.uuid);
+      success("No file changes — published the current project state.");
+    } else {
+      info(c.dim("Working tree clean — nothing to push."));
+    }
     return;
   }
-  if (!flagBool(args, "force") && manifest.baseHeadId !== null) {
+  const force = flagBool(args, "force");
+  if (!force && manifest.baseHeadId !== null) {
     const commits = await getCommits(apiUrl, token, manifest.uuid);
     if (commits.headId !== manifest.baseHeadId) {
-      throw new CliError("The project changed on the server since your last sync. Run `lecodes pull` first, or `lecodes push --force` to overwrite.");
+      throw new CliError("The project changed on the server since your last sync. Run `lecodes diff` to compare, `lecodes pull` to take the server's version, or `lecodes push --force` to overwrite.");
+    }
+  }
+  if (force) {
+    const project = await getProject(apiUrl, token, manifest.uuid);
+    const serverDiff = computeServerDiff(project, scan);
+    if (serverDiff.length) {
+      info(c.yellow(`--force will overwrite the server. ${serverDiff.length} file${serverDiff.length === 1 ? "" : "s"} change:`));
+      const label = { added: c.green("  create  "), removed: c.red("  delete  "), modified: c.yellow("  update  ") };
+      for (const e of serverDiff)
+        log(label[e.status] + e.path + (e.binary ? c.dim(" (binary)") : ""));
+      if (process.stdin.isTTY && !flagBool(args, "y", "yes")) {
+        if (!await confirm("Overwrite the server with your local copy?", false)) {
+          info(c.dim("Aborted."));
+          return;
+        }
+      }
     }
   }
   const message = (flagStr(args, "m", "message") ?? await prompt("Checkpoint message")) || "Update from lecodes CLI";
-  const sourceFor = (path) => manifest.files[path] ?? (diff.moves.has(path) ? manifest.files[diff.moves.get(path)] : undefined);
+  const sourceFor = (path) => manifest.files[path] ?? (diff2.moves.has(path) ? manifest.files[diff2.moves.get(path)] : undefined);
   const files = [];
   let uploaded = 0;
   for (const file of scan.files) {
     const source = sourceFor(file.path);
-    const kind = source?.type ?? classifyKind(basename2(file.path));
+    const kind = source?.type ?? classifyKind(basename3(file.path));
     const entry = { path: file.path, type: kind };
     if (source)
       entry.assetId = source.id;
     if (isTextKind(kind)) {
-      entry.text = readFileSync5(file.absPath, "utf8");
+      entry.text = readFileSync7(file.absPath, "utf8");
     } else if (!source || source.sha !== file.sha) {
-      const blob = await uploadBlob(apiUrl, token, manifest.uuid, basename2(file.path), readFileSync5(file.absPath));
+      const blob = await uploadBlob(apiUrl, token, manifest.uuid, basename3(file.path), readFileSync7(file.absPath));
       entry.blobFileId = blob.id;
       uploaded++;
     }
@@ -985,9 +1424,11 @@ var push = async (args) => {
   const folders = 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 });
+  const res = await sync(apiUrl, token, manifest.uuid, { message, files, folders, publish });
   if (!res.created) {
     info(c.dim("Server reported no changes."));
+    if (publish)
+      reportPublish(res);
     return;
   }
   const shaByPath = new Map(scan.files.map((f) => [f.path, f.sha]));
@@ -997,37 +1438,49 @@ var push = async (args) => {
   }
   writeManifest(root, { ...manifest, baseHeadId: res.headId, files: newFiles });
   const counts = [
-    diff.added.length - diff.moves.size && `${diff.added.length - diff.moves.size} added`,
-    diff.modified.length && `${diff.modified.length} modified`,
-    diff.moves.size && `${diff.moves.size} moved`,
-    diff.deleted.length - diff.moves.size && `${diff.deleted.length - diff.moves.size} deleted`
+    diff2.added.length - diff2.moves.size && `${diff2.added.length - diff2.moves.size} added`,
+    diff2.modified.length && `${diff2.modified.length} modified`,
+    diff2.moves.size && `${diff2.moves.size} moved`,
+    diff2.deleted.length - diff2.moves.size && `${diff2.deleted.length - diff2.moves.size} deleted`
   ].filter(Boolean).join(", ");
   success(`Pushed checkpoint${res.seq ? ` #${res.seq}` : ""}${counts ? ` (${counts})` : ""}: ${message}`);
+  if (publish)
+    reportPublish(res);
+};
+var reportPublish = (res) => {
+  if (res.published)
+    success("Published — the project is now live.");
+  else
+    warn(`Push landed, but publish failed: ${res.publishError ?? "unknown error"}`);
 };
 
 // src/commands/status.ts
 var status = async (_args) => {
   const root = findProjectRoot(process.cwd());
   const manifest = readManifest(root);
-  const diff = diffLocal(manifest, scanLocal(root));
+  const scan = scanProject(root, manifest);
+  const diff2 = diffLocal(manifest, scan);
   info(`Project ${c.bold(manifest.name)} (${manifest.uuid})`);
-  if (!hasChanges(diff)) {
-    info(c.dim("Working tree clean — nothing to push."));
+  const ignoredNote = scan.ignored.length ? c.dim(` (${scan.ignored.length} ignored)`) : "";
+  if (!hasChanges(diff2)) {
+    info(c.dim("Working tree clean — nothing to push.") + ignoredNote);
     return;
   }
-  for (const f of diff.added) {
-    if (!diff.moves.has(f.path))
+  for (const f of diff2.added) {
+    if (!diff2.moves.has(f.path))
       log(c.green(`  added     ${f.path}`));
   }
-  for (const f of diff.modified)
+  for (const f of diff2.modified)
     log(c.yellow(`  modified  ${f.path}`));
-  for (const [to, from] of diff.moves)
+  for (const [to, from] of diff2.moves)
     log(c.cyan(`  moved     ${from} → ${to}`));
-  const movedFrom = new Set(diff.moves.values());
-  for (const path of diff.deleted) {
+  const movedFrom = new Set(diff2.moves.values());
+  for (const path of diff2.deleted) {
     if (!movedFrom.has(path))
       log(c.red(`  deleted   ${path}`));
   }
+  if (scan.ignored.length)
+    info(c.dim(`  ${scan.ignored.length} ignored (.lecodesignore)`));
 };
 
 // src/index.ts
@@ -1043,27 +1496,44 @@ ${c.bold("Commands:")}
   clone <uuid|url> [dir]        Download a project's files + types into a new folder
                                   --no-types      skip the .d.ts / tsconfig generation
   status                        Show local changes vs the last sync
-  pull                          Overwrite local files with the project's current state
+  diff [path…]                  Show a unified diff of local vs the current server state
+                                  --name-only     list changed paths + status only
+  pull [path…]                  Overwrite local files with the project's current state
+                                  (with path… : pull only those files/folders, keep other edits)
                                   --force         discard uncommitted local changes
   push                          Push local changes as one new checkpoint
                                   -m, --message   checkpoint message
-                                  --force         push even if the server moved on
+                                  --publish       also deploy the project live (compile) with the push
+                                  --force         push even if the server moved on (shows + confirms
+                                                    which server files get overwritten)
+                                  -y, --yes       skip the --force overwrite confirmation
   preview                       Compile the local project to JS (prints to stdout)
                                   -o, --out <file>   write to a file instead of stdout
                                   --entry <path>     override the entrypoint
                                   --no-header        omit the metadata header
                                   --public-url <url> asset URL prefix (default: the API origin)
   render                        Render the local UI project to a semantic JSON description
-                                  (needs the optional 'lecodes-render' package; UI projects only)
+                                  (needs the optional 'lecodes-renderer' package; UI projects only)
                                   -o, --out <file>   write JSON to a file instead of stdout
                                   --png [file]       rasterize a PNG (default screenshot.png;
                                                        needs @napi-rs/canvas)
                                   --scale <n>        PNG device-pixel scale (default 2)
                                   --width/--height   viewport size (default 390x844)
                                   --entry <path>     override the entrypoint
+                                  --settle <ms>      wait for promises/timers/fetch before snapshot
+                                  --wait-network     let data fetches hit the real network
+                                  --logs             forward the app's console output (to stderr)
 
 Config lives in ~/.lecodes/config.json (override with LECODES_API / LECODES_TOKEN).`;
-var commands = { login, clone, status, pull, push, preview, render };
+var commands = { login, clone, status, diff, pull, push, preview, render };
+var readVersion = () => {
+  try {
+    const here = dirname5(fileURLToPath2(import.meta.url));
+    return JSON.parse(readFileSync8(join9(here, "..", "package.json"), "utf8")).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+};
 var main = async () => {
   const argv = process.argv.slice(2);
   const command = argv[0];
@@ -1071,6 +1541,10 @@ var main = async () => {
     log(HELP);
     return;
   }
+  if (command === "--version" || command === "-v" || command === "version") {
+    log(readVersion());
+    return;
+  }
   const run = commands[command];
   if (!run) {
     log(c.red(`Unknown command: ${command}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lecodes-cli",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Clone, edit and push LeCodes projects from your machine.",
   "type": "module",
   "license": "MIT",
@@ -21,7 +21,7 @@
   },
   "scripts": {
     "vendor-runtime": "bun scripts/vendor-runtime.ts",
-    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external esbuild --external lecodes-render --banner=\"#!/usr/bin/env node\"",
+    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external esbuild --external lecodes-renderer --banner=\"#!/usr/bin/env node\"",
     "typecheck": "tsc --noEmit",
     "dev": "bun run src/index.ts",
     "prepublishOnly": "bun run build"
@@ -30,14 +30,14 @@
     "esbuild": "^0.27.3"
   },
   "peerDependencies": {
-    "lecodes-render": "*"
+    "lecodes-renderer": "^0.1.1"
   },
   "peerDependenciesMeta": {
-    "lecodes-render": {
+    "lecodes-renderer": {
       "optional": true
     }
   },
   "devDependencies": {
-    "lecodes-render": "workspace:*"
+    "lecodes-renderer": "0.1.1"
   }
 }

package/runtime/worker/ui.js

@@ -713,8 +713,8 @@ var Router = /* @__PURE__ */ Object.freeze({
   push(screen) {
     _creatorUI.routerPush(screen);
   },
-  replace(screen) {
-    _creatorUI.routerReplace(screen);
+  replace(screen, opts) {
+    _creatorUI.routerReplace(screen, opts?.transition ?? "fade");
   },
   pop(to) {
     _creatorUI.routerPop(to ?? -1);