lecodes-cli 0.19.0 → 0.19.2

package/src/dev/devServer.ts

@@ -0,0 +1,292 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
+import { createReadStream, statSync } from "node:fs"
+import { join } from "node:path"
+import type { Manifest } from "../manifest"
+import { resolveLocalPath } from "../localFiles"
+import { collectLocalEntries } from "../compile/collectLocal"
+import { applyLocalShaders, isShaderArtifactName, shadersCacheDir } from "../compile/shaders"
+import { ambiguousEntryWarning, compileProject } from "../compile/projectCompile"
+import { applyProjectFonts } from "../compile/fonts"
+import { applyAppAssetIcons } from "../compile/assetIcons"
+import { renderDevScreen, renderPrelude } from "./clientTemplates"
+import { upgradeWebSocket, type WsConnection } from "./wsServer"
+import { toKey } from "../util"
+import { makeStackDemangler } from "../compile/nativeStack"
+
+/*
+ * The `lecodes dev` LAN server: serves the project to devices and hot-reloads it on change.
+ *
+ * All routes live under a capability-token base path (/t/<token>):
+ *   GET /t/<tok>/dev.js          the bootstrap bundle the QR points at (placeholder screen + prelude)
+ *   GET /t/<tok>/bundle.js?t=…   the current project bundle + reload prelude (?t=poll for no-WS hosts)
+ *   GET /t/<tok>/assets/<path>   files streamed from the working tree (the bundle's asset URLs)
+ *   GET /t/<tok>/shaders/<name>  locally compiled shader artifacts (.lecodes/shaders — matc)
+ *   GET /t/<tok>/version         {"v":N} — polling fallback
+ *   POST /t/<tok>/log            log/error backchannel for polling clients
+ *   WS  /t/<tok>/ws              reload push + log/error backchannel
+ *
+ * Compile is eager: the command calls recompile() on every file change; a successful compile bumps
+ * `v` and broadcasts {type:"reload", v} to connected sockets (polling clients see /version move).
+ * A failed compile keeps the last good bundle — devices stay on it until the next good compile.
+ */
+
+export type DevServerOptions = {
+  root: string
+  manifest: Manifest | null
+  name: string
+  /** The advertised origin baked into bundles + the prelude, e.g. "http://192.168.1.5:4499". */
+  origin: string
+  /** Bind address (default 0.0.0.0). */
+  bind?: string
+  port: number
+  token: string
+  entryOverride?: string
+  /** Diagnostics (compile errors, device logs); defaults to stderr-style silence-safe noop. */
+  log?: (msg: string) => void
+}
+
+export type RecompileResult =
+  | { ok: true, changed: boolean, v: number, warnings: string[] }
+  | { ok: false, error: string }
+
+export type DevServer = {
+  url: string
+  /** The token base path ("/t/<token>"). */
+  base: string
+  /** The actually-bound port (differs from options.port when 0 was passed, e.g. in tests). */
+  port: number
+  v: () => number
+  clientCount: () => number
+  recompile: () => Promise<RecompileResult>
+  close: () => void
+}
+
+const MIME: Record<string, string> = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", webp: "image/webp", gif: "image/gif",
+  svg: "image/svg+xml", ktx: "application/octet-stream", ktx2: "application/octet-stream",
+  glb: "model/gltf-binary", bin: "application/octet-stream",
+  mp3: "audio/mpeg", wav: "audio/wav", ogg: "audio/ogg", m4a: "audio/mp4",
+  mp4: "video/mp4", webm: "video/webm",
+  ttf: "font/ttf", otf: "font/otf", woff: "font/woff", woff2: "font/woff2",
+  json: "application/json", txt: "text/plain", js: "text/javascript",
+}
+
+const contentType = (path: string): string => {
+  const i = path.lastIndexOf(".")
+  return (i >= 0 && MIME[path.slice(i + 1).toLowerCase()]) || "application/octet-stream"
+}
+
+const sendText = (res: ServerResponse, status: number, type: string, body: string) => {
+  res.writeHead(status, { "content-type": type, "cache-control": "no-store" })
+  res.end(body)
+}
+
+const sendJson = (res: ServerResponse, status: number, body: unknown) =>
+  sendText(res, status, "application/json", JSON.stringify(body))
+
+const readBody = (req: IncomingMessage): Promise<string> =>
+  new Promise((resolve) => {
+    let body = ""
+    req.on("data", (c: Buffer) => { if (body.length < 256 * 1024) body += c.toString("utf8") })
+    req.on("end", () => resolve(body))
+    req.on("error", () => resolve(body))
+  })
+
+export const startDevServer = async (options: DevServerOptions): Promise<DevServer> => {
+  const { root, manifest, name, origin, token, entryOverride } = options
+  const log = options.log ?? (() => {})
+  const base = `/t/${token}`
+
+  // ---- compile state (the last good bundle; devices never see a broken one) ----------------------
+  let v = 0
+  let bundleJs: string | null = null
+  let compileChain: Promise<unknown> = Promise.resolve()
+
+  // The header's `// last-updated:` timestamp differs on every compile — ignore it when deciding
+  // whether anything really changed (a no-op save must not reload devices).
+  const stripVolatile = (js: string) => js.replace(/^\/\/ last-updated: .*$/m, "")
+
+  const compileOnce = async (): Promise<RecompileResult> => {
+    try {
+      const { entries, warnings } = collectLocalEntries(root, manifest, `${base}/assets`, { localShaders: true })
+      // Custom shaders compile LOCALLY via matc (downloaded on first use) into .lecodes/shaders,
+      // served under /shaders/ below — no push needed. Degrades to a warning when matc is
+      // unavailable; a broken .mat throws and fails this compile like any code error.
+      warnings.push(...(await applyLocalShaders(entries, { root, srcPrefix: `${base}/shaders` })).warnings)
+      // font() macro: vendor registry faces into assets/fonts/ (served from the working tree like
+      // any asset — LAN/offline friendly) and emit the `// fonts:` boot header.
+      const fontsHeader = await applyProjectFonts(entries, {
+        mode: "vendor",
+        root,
+        vendorDir: root,
+        vendorPrefix: "",
+        publicUrl: origin,
+        makeResourceEntry: (path, absPath) => ({ path, type: "resource", fileSrc: `${base}/assets` + encodeURI(path), absPath }),
+      })
+      // assetIcon() macro: resolve from the user-level cache (~/.lecodes/cache/icons) and inline —
+      // one registry fetch per icon ever, so hot recompiles stay LAN/offline friendly.
+      const iconsHeader = await applyAppAssetIcons(entries)
+      if (!entryOverride) {
+        const ambiguous = ambiguousEntryWarning(entries)
+        if (ambiguous) warnings.push(ambiguous)
+      }
+      const js = await compileProject({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader, iconsHeader })
+      const changed = bundleJs === null || stripVolatile(js) !== stripVolatile(bundleJs)
+      if (changed) {
+        bundleJs = js
+        v++
+        broadcast(JSON.stringify({ type: "reload", v }))
+      }
+      return { ok: true, changed, v, warnings }
+    } catch (e) {
+      return { ok: false, error: e instanceof Error ? e.message : String(e) }
+    }
+  }
+
+  // Serialized: a recompile requested mid-compile runs after it (compileOnce never rejects).
+  const recompile = (): Promise<RecompileResult> => {
+    const run = compileChain.then(compileOnce)
+    compileChain = run
+    return run
+  }
+
+  // dev.js: the placeholder project, compiled once per server start.
+  const devJs = await compileProject({
+    entries: [{ path: "/.dev-entry.ts", type: "text", text: renderDevScreen(name) }],
+    name: "LeCodes Dev",
+    publicUrl: origin,
+    entryOverride: "/.dev-entry.ts",
+    header: true,
+  })
+
+  // ---- websocket clients -------------------------------------------------------------------------
+  const clients = new Set<WsConnection>()
+  const broadcast = (text: string) => {
+    for (const client of clients) client.send(text)
+  }
+
+  // A device reports stacks against the bundle it evaluated ("module.js:5:51631" on the creator-pkg
+  // hosts) — rebuild the mapper whenever the bundle changes so those frames print as `main.ts:92:23`.
+  let demangleFor: { js: string, map: ((s: string) => string) | null } | null = null
+  const demangle = (text: string): string => {
+    if (bundleJs === null) return text
+    if (demangleFor?.js !== bundleJs) demangleFor = { js: bundleJs, map: makeStackDemangler(bundleJs) }
+    return demangleFor.map ? demangleFor.map(text) : text
+  }
+
+  const printDeviceMessage = (raw: string) => {
+    let m: { type?: string, level?: string, text?: string, v?: number } = {}
+    try { m = JSON.parse(raw) } catch { return }
+    if (m.type === "log") log(`[device:${m.level ?? "log"}] ${demangle(m.text ?? "")}`)
+    else if (m.type === "error") log(`[device:error] ${demangle(m.text ?? "")}`)
+  }
+
+  // ---- http --------------------------------------------------------------------------------------
+  const transportOf = (url: URL): "ws" | "poll" => (url.searchParams.get("t") === "poll" ? "poll" : "ws")
+
+  const handle = async (req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url ?? "/", origin)
+    const path = url.pathname
+    if (!path.startsWith(base + "/")) return sendText(res, 404, "text/plain", "Not found")
+    const route = path.slice(base.length)
+
+    if (route === "/dev.js") {
+      return sendText(res, 200, "text/javascript",
+        devJs + "\n" + renderPrelude({ origin, base, transport: transportOf(url), v: -1 }))
+    }
+    if (route === "/bundle.js") {
+      if (bundleJs === null) return sendText(res, 503, "text/plain", "No successful compile yet — check the terminal.")
+      return sendText(res, 200, "text/javascript",
+        bundleJs + "\n" + renderPrelude({ origin, base, transport: transportOf(url), v }))
+    }
+    if (route === "/version") {
+      return sendJson(res, 200, { v })
+    }
+    if (route === "/log" && req.method === "POST") {
+      printDeviceMessage(await readBody(req))
+      return sendJson(res, 200, { ok: true })
+    }
+    if (route.startsWith("/shaders/")) {
+      const name = route.slice("/shaders/".length)
+      if (!isShaderArtifactName(name)) return sendText(res, 400, "text/plain", "Bad path")
+      const abs = join(shadersCacheDir(root), name)
+      try {
+        if (!statSync(abs).isFile()) throw new Error("not a file")
+      } catch {
+        return sendText(res, 404, "text/plain", "Not found")
+      }
+      res.writeHead(200, { "content-type": "application/octet-stream", "cache-control": "no-store" })
+      createReadStream(abs).pipe(res)
+      return
+    }
+    if (route.startsWith("/assets/")) {
+      let key: string
+      try {
+        key = toKey(decodeURIComponent(route.slice("/assets".length)))
+      } catch {
+        return sendText(res, 400, "text/plain", "Bad path")
+      }
+      const abs = resolveLocalPath(root, key)
+      if (!abs || !statSync(abs).isFile()) return sendText(res, 404, "text/plain", "Not found")
+      res.writeHead(200, { "content-type": contentType(key), "cache-control": "no-store" })
+      createReadStream(abs).pipe(res)
+      return
+    }
+    return sendText(res, 404, "text/plain", "Not found")
+  }
+
+  const server: Server = createServer((req, res) => {
+    handle(req, res).catch((e) => {
+      log(`request failed: ${e instanceof Error ? e.message : String(e)}`)
+      if (!res.headersSent) sendText(res, 500, "text/plain", "Internal error")
+    })
+  })
+
+  server.on("upgrade", (req, socket) => {
+    const url = new URL(req.url ?? "/", origin)
+    if (url.pathname !== base + "/ws") {
+      socket.destroy()
+      return
+    }
+    const conn = upgradeWebSocket(req, socket, {
+      onMessage: (text) => {
+        let m: { type?: string, v?: number } = {}
+        try { m = JSON.parse(text) } catch { /* not ours */ }
+        if (m.type === "hello") {
+          // A (re)connecting world announces what it runs; nudge it forward if it's stale.
+          if (typeof m.v === "number" && m.v !== v && bundleJs !== null) {
+            conn?.send(JSON.stringify({ type: "reload", v }))
+          }
+        } else {
+          printDeviceMessage(text)
+        }
+      },
+      onClose: () => { if (conn) clients.delete(conn) },
+    })
+    if (conn) clients.add(conn)
+  })
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(options.port, options.bind ?? "0.0.0.0", () => {
+      server.removeListener("error", reject)
+      resolve()
+    })
+  })
+
+  const address = server.address()
+  const boundPort = typeof address === "object" && address !== null ? address.port : options.port
+
+  return {
+    url: `${origin}${base}/dev.js`,
+    base,
+    port: boundPort,
+    v: () => v,
+    clientCount: () => clients.size,
+    recompile,
+    close: () => {
+      for (const client of clients) client.close()
+      server.close()
+    },
+  }
+}

package/src/dev/wsServer.ts

@@ -0,0 +1,144 @@
+import { createHash } from "node:crypto"
+import type { IncomingMessage } from "node:http"
+import type { Duplex } from "node:stream"
+
+/*
+ * A minimal RFC 6455 WebSocket server for the `lecodes dev` reload channel — dependency-free, like
+ * the rest of the CLI. Scope: server side only, text frames (the protocol is small JSON messages),
+ * ping→pong, close handshake. No fragmentation support (continuation frames are dropped) and no
+ * extensions — fine for OkHttp/NSURLSession/WinHTTP clients sending short messages.
+ */
+
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+/** Sec-WebSocket-Accept for a client's Sec-WebSocket-Key (RFC 6455 §4.2.2). */
+export const acceptKey = (key: string): string =>
+  createHash("sha1").update(key + WS_GUID).digest("base64")
+
+/** A server→client text frame (FIN, unmasked — servers MUST NOT mask). */
+export const encodeTextFrame = (text: string): Buffer => {
+  const payload = Buffer.from(text, "utf8")
+  const len = payload.length
+  let header: Buffer
+  if (len < 126) {
+    header = Buffer.from([ 0x81, len ])
+  } else if (len < 65536) {
+    header = Buffer.alloc(4)
+    header[0] = 0x81
+    header[1] = 126
+    header.writeUInt16BE(len, 2)
+  } else {
+    header = Buffer.alloc(10)
+    header[0] = 0x81
+    header[1] = 127
+    header.writeBigUInt64BE(BigInt(len), 2)
+  }
+  return Buffer.concat([ header, payload ])
+}
+
+const encodeControlFrame = (opcode: number, payload: Buffer = Buffer.alloc(0)): Buffer =>
+  Buffer.concat([ Buffer.from([ 0x80 | opcode, Math.min(payload.length, 125) ]), payload.subarray(0, 125) ])
+
+export const OPCODE = { CONTINUATION: 0x0, TEXT: 0x1, BINARY: 0x2, CLOSE: 0x8, PING: 0x9, PONG: 0xa } as const
+
+export type WsFrame = { opcode: number, payload: Buffer }
+
+/** Stateful frame decoder: feed raw socket chunks, get complete (unmasked) frames back. */
+export const createFrameDecoder = () => {
+  let buf: Buffer = Buffer.alloc(0)
+  return (chunk: Buffer): WsFrame[] => {
+    buf = buf.length === 0 ? chunk : Buffer.concat([ buf, chunk ])
+    const frames: WsFrame[] = []
+    while (buf.length >= 2) {
+      const opcode = buf[0] & 0x0f
+      const masked = (buf[1] & 0x80) !== 0
+      let len = buf[1] & 0x7f
+      let off = 2
+      if (len === 126) {
+        if (buf.length < 4) break
+        len = buf.readUInt16BE(2)
+        off = 4
+      } else if (len === 127) {
+        if (buf.length < 10) break
+        len = Number(buf.readBigUInt64BE(2))
+        off = 10
+      }
+      const maskLen = masked ? 4 : 0
+      if (buf.length < off + maskLen + len) break
+      let payload = buf.subarray(off + maskLen, off + maskLen + len)
+      if (masked) {
+        const mask = buf.subarray(off, off + 4)
+        const unmasked = Buffer.alloc(len)
+        for (let i = 0; i < len; i++) unmasked[i] = payload[i] ^ mask[i & 3]
+        payload = unmasked
+      }
+      buf = buf.subarray(off + maskLen + len)
+      frames.push({ opcode, payload })
+    }
+    return frames
+  }
+}
+
+export type WsConnection = {
+  send: (text: string) => void
+  close: () => void
+}
+
+export type WsHandlers = {
+  onMessage: (text: string) => void
+  /** Fired exactly once, however the connection ends. */
+  onClose: () => void
+}
+
+/**
+ * Complete the upgrade handshake on an `http.Server` `'upgrade'` event and speak WebSocket on the
+ * raw socket. Returns null (socket destroyed) if the request isn't a valid upgrade.
+ */
+export const upgradeWebSocket = (req: IncomingMessage, socket: Duplex, handlers: WsHandlers): WsConnection | null => {
+  const key = req.headers["sec-websocket-key"]
+  if (typeof key !== "string" || (req.headers.upgrade ?? "").toLowerCase() !== "websocket") {
+    socket.destroy()
+    return null
+  }
+  socket.write(
+    "HTTP/1.1 101 Switching Protocols\r\n" +
+    "Upgrade: websocket\r\n" +
+    "Connection: Upgrade\r\n" +
+    `Sec-WebSocket-Accept: ${acceptKey(key)}\r\n\r\n`,
+  )
+
+  let open = true
+  const finish = () => {
+    if (!open) return
+    open = false
+    handlers.onClose()
+  }
+  const decode = createFrameDecoder()
+  socket.on("data", (chunk: Buffer) => {
+    for (const frame of decode(chunk)) {
+      if (frame.opcode === OPCODE.TEXT) {
+        handlers.onMessage(frame.payload.toString("utf8"))
+      } else if (frame.opcode === OPCODE.PING) {
+        if (open) socket.write(encodeControlFrame(OPCODE.PONG, frame.payload))
+      } else if (frame.opcode === OPCODE.CLOSE) {
+        if (open) socket.write(encodeControlFrame(OPCODE.CLOSE))
+        socket.end()
+        finish()
+      }
+    }
+  })
+  socket.on("close", finish)
+  socket.on("error", () => socket.destroy())
+
+  return {
+    send: (text: string) => {
+      if (open) socket.write(encodeTextFrame(text))
+    },
+    close: () => {
+      if (!open) return
+      socket.write(encodeControlFrame(OPCODE.CLOSE))
+      socket.end()
+      finish()
+    },
+  }
+}

package/src/distRoot.ts

@@ -0,0 +1,20 @@
+import { existsSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/* Root of the CLI's on-disk companion files (runtime/ with the vendored SDK source + type bundle).
+ *
+ * Two distribution shapes:
+ *  - npm package / monorepo dev: this module lives in dist/ (or src/), companions at ../runtime —
+ *    resolve relative to import.meta.url as before.
+ *  - standalone binary (`bun build --compile`, see scripts/build-bin.ts): import.meta.url points into
+ *    the virtual bunfs archive which does NOT exist on disk, so the companions ship in the release
+ *    archive NEXT TO the executable and are resolved via process.execPath. */
+export const distRoot = (() => {
+  const candidates = [
+    join(dirname(fileURLToPath(import.meta.url)), ".."), // package root (dist/.. or src/..)
+    dirname(process.execPath),                           // standalone binary: next to the exe
+  ]
+  for (const c of candidates) if (existsSync(join(c, "runtime"))) return c
+  return candidates[0]
+})()

package/src/ignore.ts

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+/*
+ * `.lecodesignore` support — keeps scratch files (temp probes, render screenshots, logs) out of
+ * `status` / `push` so they never land in a checkpoint. Syntax is a practical subset of .gitignore:
+ *   - blank lines and `# comments` are skipped
+ *   - `!pattern` re-includes something a previous pattern ignored
+ *   - a trailing `/` matches directories only
+ *   - a leading `/` (or any embedded `/`) anchors the pattern to the project root
+ *   - `*` matches within a path segment, `**` across segments, `?` a single char
+ *   - a slash-free pattern (e.g. `_*`, `*.png`) matches a basename at any depth
+ *
+ * IMPORTANT: ignores apply to UNTRACKED files only. A file already in the project (recorded in the
+ * manifest) is always tracked, even if it matches a pattern — so ignoring `*.png` can never make an
+ * existing image asset silently disappear from the project. Pruning happens in `scanLocal`.
+ */
+
+export type IgnoreMatcher = (key: string, isDir: boolean) => boolean
+
+type Rule = { re: RegExp, negate: boolean, dirOnly: boolean }
+
+// Always applied, even with no .lecodesignore — only patterns that are never real project assets, so
+// they're safe as invisible defaults. Everything asset-shaped (*.png, *.json, …) is opt-in via the
+// file written at clone time (see DEFAULT_IGNORE_FILE). `.artifacts/` is `lecodes test`'s
+// failure-frame dump dir (tests/.artifacts/) — regenerated scratch, never a project asset.
+// `dist/` is `lecodes app build desktop`'s default output (<root>/dist/<slug>, appDesktop.ts) —
+// same class, but it must be ignored for a second, load-bearing reason: that folder holds a COPY of
+// the host's runtime assets (lit.filamat, uberarchive.bin, …). Collected as project assets they get
+// staged next to the bundle, and onFetchLocal searches the bundle's dir BEFORE the host's assets dir
+// (main.cpp) — so the copy shadows the host's own. Harmless while every host was OpenGL and the
+// bytes matched; fatal once a build output can come from the Vulkan host, where the shadowing
+// lit.filamat is SPIR-V and Filament aborts with "not built for any of the OpenGL backend's
+// supported shader languages".
+// `.env` / `.env.*`: the project's LECODES_* config (projectEnv.ts) — it holds tokens and keystore
+// passwords, so it never leaves the machine whatever .lecodesignore says.
+const BUILTIN_PATTERNS = ["node_modules/", ".git/", "_*", "*.log", ".DS_Store", ".artifacts/", "dist/", ".env", ".env.*"]
+
+/** Template `.lecodesignore` written on clone — the explicit, editable "what we don't push" list. */
+export const 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, .artifacts)
+# always apply.
+
+# Render / preview outputs (the default \`lecodes render --png\` target)
+screenshot.png
+shots/
+
+# Design-board comments live on the platform; design/comments/ is the local mirror of the
+# open ones (\`lecodes design comments pull\`) — read by Claude, but pushing it back as
+# project files would only duplicate the database.
+design/comments/
+
+# Image & other binary assets ARE pushed by default — they're real project resources.
+# Uncomment a pattern below only if you want to keep some untracked ones out of pushes.
+# *.png
+
+# Local notes & dumps (uncomment to ignore)
+# *.json
+# notes.md
+`
+
+/** Translate a glob (one path segment's worth of `*`/`?`/`**`) into a regex fragment. */
+const translate = (glob: string): string => {
+  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++ } // `**/` spans dirs
+      else re += "[^/]*"
+    } else if (ch === "?") re += "[^/]"
+    else if (ch === "/") re += "/"
+    else if ("\\^$.|+()[]{}".includes(ch)) re += "\\" + ch
+    else re += ch
+  }
+  return re
+}
+
+const compile = (raw: string): Rule | null => {
+  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)
+  // `(/.*)?$` lets a directory pattern also match files nested under it, matching gitignore behavior
+  // even without relying on directory pruning.
+  const re = anchored ? new RegExp("^/" + body + "(/.*)?$") : new RegExp("(^|/)" + body + "(/.*)?$")
+  return { re, negate, dirOnly }
+}
+
+const buildMatcher = (rules: Rule[]): IgnoreMatcher => (key, isDir) => {
+  let ignored = false
+  for (const r of rules) {
+    if (r.dirOnly && !isDir) continue // a `foo/` rule only matches dirs directly (files via prune)
+    if (r.re.test(key)) ignored = !r.negate
+  }
+  return ignored
+}
+
+/** Compile a standalone glob list (same syntax as .lecodesignore lines, including `!` re-includes)
+ *  into a file-path matcher — used for app.json's `resources.remote` patterns. */
+export const buildGlobMatcher = (patterns: string[]): ((path: string) => boolean) => {
+  // Matching is over FILE paths — normalize `videos/` (dir-only, would match nothing here) to
+  // `videos`, whose `(/.*)?$` tail matches everything under the directory.
+  const rules = patterns.map((p) => compile(p.trim().replace(/\/+$/, ""))).filter((r): r is Rule => r !== null)
+  const match = buildMatcher(rules)
+  // Anchored rules compile to `^/…` — they expect the canonical leading-slash key form.
+  return (path) => match(path.startsWith("/") ? path : "/" + path, false)
+}
+
+/** Read `<root>/.lecodesignore` (if any) and combine with the built-in defaults into a matcher. */
+export const loadIgnore = (root: string): IgnoreMatcher => {
+  const lines = [...BUILTIN_PATTERNS]
+  const file = join(root, ".lecodesignore")
+  if (existsSync(file)) {
+    try { lines.push(...readFileSync(file, "utf8").split(/\r?\n/)) } catch { /* unreadable → defaults only */ }
+  }
+  const rules = lines.map(compile).filter((r): r is Rule => r !== null)
+  return buildMatcher(rules)
+}
+
+/** Write the template `.lecodesignore` if the project doesn't have one yet (used on clone). */
+export const writeDefaultIgnore = (root: string) => {
+  const file = join(root, ".lecodesignore")
+  if (!existsSync(file)) writeFileSync(file, DEFAULT_IGNORE_FILE)
+}
+
+/* `.gitignore` for the project's OWN git repo. `.lecodes/` is per-checkout state — regenerable IDE
+ * types (`lecodes update`) + `manifest.json`, this machine's push cursor (baseHeadId + per-file shas).
+ * Committing it makes collaborators fight over the cursor and ship stale types, so every scaffold
+ * path (init / clone / link) makes sure it's ignored. Render outputs mirror DEFAULT_IGNORE_FILE. */
+export const DEFAULT_GITIGNORE = `# LeCodes per-checkout state: generated IDE types + this machine's sync cursor
+# (.lecodes/manifest.json). Regenerate with \`lecodes update\` / re-attach with \`lecodes link\`.
+.lecodes/
+
+# Render / preview outputs and test failure frames
+screenshot.png
+shots/
+tests/.artifacts/
+tests/.shots/
+
+node_modules/
+
+dist/
+`
+
+/** Create `.gitignore` if missing; if it exists but doesn't ignore `.lecodes/`, append that rule.
+ * Returns what happened so callers can log it ("created" | "updated" | null). */
+export const ensureGitignore = (root: string): "created" | "updated" | null => {
+  const file = join(root, ".gitignore")
+  if (!existsSync(file)) { writeFileSync(file, DEFAULT_GITIGNORE); return "created" }
+  const text = readFileSync(file, "utf8")
+  const covered = text.split(/\r?\n/).some(l => /^\/?\.lecodes\/?\s*$/.test(l.trim()))
+  if (covered) return null
+  const sep = text.length === 0 || text.endsWith("\n") ? "" : "\n"
+  writeFileSync(file, `${text}${sep}\n# LeCodes per-checkout state (generated types + sync cursor) — not source\n.lecodes/\n`)
+  return "updated"
+}