lecodes-cli 0.19.0 → 0.19.2

package/src/lecodes-design.d.ts

@@ -0,0 +1,191 @@
+// Types for the optional `lecodes-design` package's server entry (lazy-loaded by the `design`
+// command). The real package is installed separately; this lets the dynamic import typecheck
+// without it present.
+declare module "lecodes-design/server" {
+  export type CompiledScreen = { js: string, warnings: string[] }
+
+  export type RenderedScreen = { json?: string, png?: Buffer, warnings: string[] }
+
+  export type DesignServerOptions = {
+    root: string
+    designDir: string
+    name?: string
+    compileScreen: (id: string, state?: string) => Promise<CompiledScreen>
+    renderScreen?: (id: string, format: "json" | "png" | "both", state?: string) => Promise<RenderedScreen>
+    port?: number
+    appDir?: string
+    log?: (message: string) => void
+    /** True when a platform project backs this folder — decides who owns the conversation. */
+    linked?: boolean
+  }
+
+  export type DesignServer = {
+    port: number
+    url: string
+    close: () => void
+  }
+
+  export function startDesignServer(options: DesignServerOptions): Promise<DesignServer>
+
+  export type ArrangeSummary = {
+    changed: boolean
+    moved: number
+    previous: Record<string, [number, number]>
+    mode: "full" | "new" | "selection"
+    score?: { before: number, after: number }
+  }
+
+  export function arrangeDesign(designDir: string, opts?: { onlyNew?: boolean, only?: string[] }): ArrangeSummary
+
+  export type DesignScreen = {
+    id: string
+    file: string
+    desc?: string
+    pos: [number, number]
+    size: [number, number]
+    group?: string
+    role?: string
+    /** State ids discovered from the screen source (≥1). */
+    states: string[]
+    /** The canonical state (∈ states). */
+    canonical: string
+    /** Soft: default export has an annotated non-union param (states not discoverable). */
+    statesWarning?: string
+  }
+
+  export type DesignEdge = { from: string, to: string, label?: string, activator?: string }
+  export type ServedEdge = {
+    from: string
+    to: string
+    label?: string
+    activator?: string
+    index: number
+    fromState?: string
+    toState?: string
+  }
+  export type DesignGroup = { name: string, color: string, desc?: string, members: string[], impliedBy?: string }
+
+  /** A source-discovered tab bar (`defineTabs` in shared/ + mount callsites) — see tabbar-surface.md. */
+  export type DesignHub = {
+    name: string
+    file: string
+    /** Tab ids in declaration order (root screen ids). */
+    tabs: string[]
+    /** screen id → tab id for every screen that mounts the bar. */
+    lanes: Record<string, string>
+  }
+
+  export type DesignState = {
+    screens: DesignScreen[]
+    edges: ServedEdge[]
+    groups: DesignGroup[]
+    hubs: DesignHub[]
+    warnings: string[]
+  }
+
+  export function readDesignState(designDir: string): DesignState
+
+  export type ConceptReport = {
+    hasSpec: boolean
+    screenRefs: { id: string, exists: boolean }[]
+    screensWithoutRole: string[]
+    warnings: string[]
+  }
+
+  export function conceptReport(designDir: string, screens: DesignScreen[]): ConceptReport
+
+  /** Provenance: `share` = unverified stranger on the link, `ai` = Claude on a member's behalf. */
+  export type CommentOrigin = "share" | "editor" | "cli" | "ai"
+  /** A review comment pinned to the board (docs/design-comments-plan.md). */
+  export type CommentMessage = {
+    id: string
+    author: string
+    origin: CommentOrigin
+    at: string
+    body: string
+    editedAt?: string
+    mine?: boolean
+  }
+  /** What the pin was dropped on, captured from the laid-out tree at pin time. `name` is the author
+   *  `name` of the nearest named ancestor, `text` what it read; `path` is a weak positional hint. */
+  export type CommentTarget = { name?: string, text?: string, path?: string }
+  export type CommentAnchor = {
+    screen?: string
+    state?: string
+    target?: CommentTarget
+    point?: [number, number]
+  }
+  export type CommentThread = {
+    id: string
+    /** Absent until the platform allocates one — a thread started locally is a draft until pushed. */
+    number?: number
+    anchor: CommentAnchor
+    resolved: boolean
+    resolvedAt?: string | null
+    createdAt: string
+    updatedAt: string
+    commitId?: number | null
+    /** Set here and not yet sent; `lecodes push` delivers it. */
+    pendingResolve?: true
+    messages: CommentMessage[]
+    mine?: boolean
+  }
+
+  /** Read `design/comments/` — one file per thread (absent directory → no threads). */
+  export function listDesignComments(designDir: string): {
+    threads: CommentThread[]
+    canComment: boolean
+  }
+
+  /** Start a thread. Linked → a numberless draft `lecodes push` names; standalone → numbered now. */
+  export function startThread(
+    designDir: string,
+    draft: { anchor: CommentAnchor, body: string, author?: string, origin?: CommentOrigin },
+    mode: { linked: boolean },
+  ): CommentThread
+  /** Append a reply (marked pending until `lecodes push`). `as` overrides attribution — pass
+   *  Claude/ai when the assistant, not the developer, is writing. */
+  export function replyToThread(
+    designDir: string,
+    threadId: string,
+    body: string,
+    as?: { author?: string, origin?: CommentOrigin },
+  ): CommentThread
+  /** Flip resolved (marked pending until `lecodes push`). */
+  export function resolveThread(designDir: string, threadId: string, resolved: boolean): CommentThread
+
+  export type MirrorSummary = { added: number, updated: number, closed: number }
+  /** Fold the platform's OPEN threads into `design/comments/`. A local file the snapshot doesn't
+   *  carry was resolved or deleted upstream and is removed — unless it still has unsent writes. */
+  export function mirrorThreads(designDir: string, remote: CommentThread[]): MirrorSummary
+
+  export type QueuedThread = {
+    thread: CommentThread
+    file: string
+    pending: { newThread: boolean, messages: CommentMessage[], resolve: boolean }
+  }
+  /** Everything waiting to go up. Nothing leaves the machine except through `lecodes push`, which
+   *  drains exactly this. */
+  export function queuedThreads(designDir: string): QueuedThread[]
+  /** What a push actually delivered for one queued thread (`messageIds` holds LOCAL message ids). */
+  export type DeliveredWrites = { messageIds: Set<string>, resolve: boolean }
+  /** Adopt what the platform says the thread is now. Only what `delivered` names settles — the
+   *  rest keeps its pending flag, so a half-failed push retries instead of duplicating. */
+  export function settleQueued(
+    designDir: string,
+    queued: QueuedThread,
+    upstream: CommentThread,
+    delivered: DeliveredWrites,
+  ): void
+
+  /** How a thread is referred to: "#7", or "new" while it's an unpushed draft. */
+  export function threadRef(thread: CommentThread): string
+  /** The pre-directory `comments.json`, if it's still lying around. */
+  export function legacyCommentsFile(designDir: string): string | null
+
+  export type ScreenStates = { states: string[], canonical: string, warning?: string, error?: string }
+  /** Discover a screen's states from its source (the default export's first-param literal union). */
+  export function discoverScreenStates(source: string): ScreenStates
+  /** Split a `screen@state` reference on the last `@` (no `@` → no state). */
+  export function parseStateRef(ref: string): { screen: string, state?: string }
+}

package/src/lecodes-renderer.d.ts

@@ -0,0 +1,131 @@
+// Types for the optional `lecodes-renderer` package's node headless entry (lazy-loaded by the
+// `render` command). The real package is installed separately; this lets the dynamic import
+// typecheck without it present.
+declare module "lecodes-renderer/headless" {
+  export type RenderOptions = {
+    width?: number
+    height?: number
+    images?: Record<string, { width: number, height: number }>
+    /** Max ms to wait for promises/timers/fetch/image decode before snapshotting (ends early on idle). */
+    settleMs?: number
+    /** Let data fetches hit the real network (off by default). */
+    waitNetwork?: boolean
+    /** Resolve `lecodesfile://<abs-path>` resource URLs from the local filesystem (the `render`
+     *  command emits these for a local project's assets). */
+    localAssets?: boolean
+    /** Render at this animation time (ms); 0 = the initial frame-0 state. */
+    timeMs?: number
+    /** Advance animations to their resting state before snapshotting (default true). */
+    afterAnimations?: boolean
+    /** Override safe-area insets [top, right, bottom, left] (px) for the `safe-*` keywords. */
+    safeArea?: [number, number, number, number]
+    /** Receive the project's console.* output (unset → swallowed). */
+    onConsole?: (level: string, text: string) => void
+    /** Canned `_creatorUtils.fetch` responses (URL pattern → { status?, json?, text? }); they beat
+     *  every other fetch path, including waitNetwork. */
+    fixtures?: Fixtures
+  }
+  export type FetchFixture = { status?: number, json?: unknown, text?: string }
+  export type Fixtures = Record<string, FetchFixture>
+  export function validateFixtures(fixtures: Fixtures): void
+  export type RenderResult = { text: string, tree: unknown, warnings: string[] }
+  export function renderToJson(js: string, opts?: RenderOptions): Promise<RenderResult>
+
+  /** A frame region in logical px: a named node (its layout rect) or an explicit rect. */
+  export type ClipTarget = string | { x: number, y: number, width: number, height: number }
+  export type PngOptions = RenderOptions & { scale?: number, clip?: ClipTarget }
+  export type PngResult = { png: Buffer, width: number, height: number, warnings: string[] }
+  export function renderToPng(js: string, opts?: PngOptions): Promise<PngResult>
+
+  // ---- top-down map (lecodes render --map) ----
+  export type MapRenderOptions = { maxPx?: number, title?: string, labelAll?: boolean }
+  export function renderToMap(
+    js: string, opts?: RenderOptions & MapRenderOptions,
+  ): Promise<{ png: Buffer, data: unknown, warnings: string[] }>
+
+  // ---- interactive session (tap/type/scroll/wait between snapshots) ----
+  export type SessionTarget = string | { x: number, y: number }
+  export type SessionOptions = RenderOptions & {
+    /** Which safe-area edges are exact-height system bars (Android) vs clearance insets (iOS). */
+    safeAreaBars?: ("top" | "right" | "bottom" | "left")[]
+    /** true → require @napi-rs/canvas (throw if missing); false → JSON metrics only (no png());
+     *  "auto" (default) → rasterize when the package is installed. */
+    raster?: boolean | "auto"
+    /** Device-pixel scale for png() (default 2). */
+    scale?: number
+  }
+  export type Session = {
+    warnings: string[]
+    canRasterize: boolean
+    find: (target: string) => unknown | null
+    tap: (target: SessionTarget) => Promise<void>
+    type: (target: SessionTarget, text: string) => Promise<void>
+    fill: (value?: string) => Promise<void>
+    scroll: (delta: number, target?: SessionTarget) => Promise<void>
+    wait: (ms: number) => Promise<void>
+    frames: (n: number) => Promise<void>
+    drag: (from: SessionTarget, to: SessionTarget, opts?: { ms?: number }) => Promise<void>
+    hold: (target: SessionTarget, ms: number) => Promise<void>
+    keyDown: (code: string) => void
+    keyUp: (code: string) => void
+    key: (code: string, ms: number) => Promise<void>
+    settle: (ms?: number) => Promise<void>
+    json: () => unknown
+    text: () => string
+    png: (opts?: { clip?: ClipTarget }) => Promise<Buffer>
+    clipRect: (clip: ClipTarget) => { x: number, y: number, width: number, height: number }
+    logs: () => string[]
+    screenName: () => string | null
+    value: (target: string) => string
+    clock: () => number
+    dispose: () => void
+  }
+  export function createSession(js: string, opts?: SessionOptions): Promise<Session>
+
+  // ---- scenario engine (lecodes render --script / lecodes test) ----
+  export type ExpectSpec = {
+    text?: string
+    notText?: string
+    node?: string
+    notNode?: string
+    screen?: string
+    value?: { target: string, equals: string }
+    log?: string
+  }
+  export type ScenarioStep = {
+    name?: string
+    tap?: SessionTarget
+    type?: string
+    text?: string
+    fill?: { value?: string }
+    scroll?: string | number
+    by?: number
+    wait?: number
+    frames?: number
+    drag?: SessionTarget
+    to?: SessionTarget
+    ms?: number
+    hold?: SessionTarget
+    key?: string
+    keyDown?: string
+    keyUp?: string
+    /** 3D inspection camera (scene3d report): named auto-fitted view, fixed eye/look-at, or "off". */
+    view?: "iso" | "top" | "front" | "side" | "back" | "off"
+    fov?: number
+    camera?: { at: [number, number, number], lookAt: [number, number, number], fov?: number } | "off"
+    expect?: ExpectSpec
+    screenshot?: string
+    clip?: ClipTarget
+    json?: string
+    /** Write the annotated top-down map of the 3D scene: `<path>.png` + `<path>.json` data. */
+    map?: string
+  }
+  export type ScenarioIO = { write: (relPath: string, data: string | Uint8Array) => void }
+  export type StepOutcome = { index: number, desc: string, ok: boolean, error?: string }
+  export type ScenarioOutcome = { ok: boolean, steps: StepOutcome[], failureArtifacts: string[] }
+  export function parseScenarioSteps(raw: unknown): ScenarioStep[]
+  export function describeStep(step: ScenarioStep): string
+  export function runScenario(
+    session: Session, steps: ScenarioStep[], io: ScenarioIO, opts?: { artifactPrefix?: string },
+  ): Promise<ScenarioOutcome>
+}

package/src/localFiles.ts

@@ -0,0 +1,144 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { join, relative } from "node:path"
+import { sanitizeAssetName } from "lecodes-sdk/compile/assetName"
+import { sha256, toKey } from "./util"
+import { loadIgnore, type IgnoreMatcher } from "./ignore"
+import type { FileKind, Manifest } from "./manifest"
+
+/* Scanning the working tree and diffing it against the manifest. Paths are normalized to posix
+ * keys ("/a/b.ts") so they line up with the asset tree regardless of OS. */
+
+// Directories never treated as project content. tsconfig.json / .gitignore etc. are skipped as
+// files (see SKIP_FILES) since they're CLI/tooling artifacts, not assets.
+const SKIP_DIRS = new Set([".lecodes", ".git", "node_modules"])
+const SKIP_FILES = new Set(["tsconfig.json", "jsconfig.json", ".gitignore", ".lecodesignore", ".DS_Store"])
+
+// Extensions stored as text by the platform. ".mat" -> shader, ".scene" -> scene; everything
+// else (images, audio, glb, ...) is a binary resource.
+const TEXT_EXTS = new Set([
+  "ts", "tsx", "js", "jsx", "mjs", "cjs", "json", "svg", "glsl", "vert", "frag",
+  "txt", "md", "css", "html", "xml", "yml", "yaml", "csv",
+])
+
+const ext = (name: string) => {
+  const i = name.lastIndexOf(".")
+  return i < 0 ? "" : name.slice(i + 1).toLowerCase()
+}
+
+/** Best-effort kind for a file the user added locally (known files keep their manifest type). */
+export const classifyKind = (name: string): FileKind => {
+  const e = ext(name)
+  if (e === "mat") return "shader"
+  if (e === "scene") return "scene"
+  return TEXT_EXTS.has(e) ? "text" : "resource"
+}
+
+export const isTextKind = (kind: FileKind) => kind !== "resource"
+
+export type LocalFile = { path: string, absPath: string, sha: string }
+
+export type LocalScan = { files: LocalFile[], dirs: string[], ignored: string[] }
+
+export type ScanOptions = {
+  /** A `.lecodesignore` matcher; untracked matching files/dirs are skipped (see ignore.ts). */
+  ignore?: IgnoreMatcher
+  /** Paths already in the project — never ignored, so an ignore rule can't drop an existing asset. */
+  tracked?: Set<string>
+}
+
+/** Recursively scan the working tree, skipping ignored dirs/files; hashes each file. */
+export const scanLocal = (root: string, opts: ScanOptions = {}): LocalScan => {
+  const { ignore, tracked } = opts
+  const files: LocalFile[] = []
+  const dirs: string[] = []
+  const ignored: string[] = []
+  const isTracked = (key: string) => tracked?.has(key) ?? false
+  // Don't prune a dir that contains a tracked file (e.g. an ignored `assets/` that holds a real asset).
+  const hasTrackedUnder = (key: string) => {
+    if (!tracked) return false
+    const prefix = key + "/"
+    for (const t of tracked) if (t.startsWith(prefix)) return true
+    return false
+  }
+  // `parentIgnored`: we descended into an ignored directory only because it holds a tracked file.
+  // Everything else inside it stays ignored (gitignore: an ignored dir's contents are ignored even
+  // when a single file is force-tracked).
+  const walk = (dir: string, parentIgnored: boolean) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const abs = join(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(readFileSync(abs)) })
+      }
+    }
+  }
+  walk(root, false)
+  return { files, dirs, ignored }
+}
+
+/**
+ * The file a project key ("/img/logo.png") points at on disk. Keys carry the canonical spelling of
+ * each name (toKey), so a file whose real name isn't canonical — an NBSP, a decomposed "й" on a
+ * byte-exact filesystem — is found by matching sanitized names in its folder.
+ */
+export const resolveLocalPath = (root: string, key: string): string | null => {
+  const direct = join(root, key.slice(1))
+  if (existsSync(direct)) return direct
+  let dir = root
+  try {
+    for (const name of key.slice(1).split("/")) {
+      const match = readdirSync(dir).find(entry => entry === name || sanitizeAssetName(entry) === name)
+      if (!match) return null
+      dir = join(dir, match)
+    }
+  } catch {
+    return null // a segment that isn't a readable directory
+  }
+  return dir
+}
+
+/** Scan honoring the project's `.lecodesignore` (untracked files only). The common entry point. */
+export const scanProject = (root: string, manifest: Manifest): LocalScan =>
+  scanLocal(root, { ignore: loadIgnore(root), tracked: new Set(Object.keys(manifest.files)) })
+
+export type Diff = {
+  added: LocalFile[]
+  modified: LocalFile[]
+  deleted: string[]
+  /** newPath -> oldPath, detected by matching content of an added file to a deleted one. */
+  moves: Map<string, string>
+}
+
+/** Compare a local scan against the manifest's recorded state. */
+export const diffLocal = (manifest: Manifest, scan: LocalScan): Diff => {
+  const added: LocalFile[] = []
+  const modified: LocalFile[] = []
+  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))
+
+  // Pair each added file with a deleted file of identical content -> a move/rename.
+  const moves = new Map<string, string>()
+  const claimed = new Set<string>()
+  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 }
+}
+
+export const hasChanges = (diff: Diff) => diff.added.length + diff.modified.length + diff.deleted.length > 0

package/src/manifest.ts

@@ -0,0 +1,46 @@
+import { dirname, join } from "node:path"
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs"
+import { CliError } from "./util"
+
+/* The per-checkout state in <root>/.lecodes/manifest.json: which remote project this is, the
+ * head we last synced from (for drift detection), and a path -> { id, type, sha } map used to
+ * diff local edits against on push. */
+
+export type FileKind = "text" | "shader" | "scene" | "resource"
+
+export type ManifestFile = { id: number, type: FileKind, sha: string }
+
+export type Manifest = {
+  uuid: string
+  apiUrl: string
+  name: string
+  baseHeadId: number | null
+  files: Record<string, ManifestFile>
+}
+
+export const LECODES_DIR = ".lecodes"
+const manifestPath = (root: string) => join(root, LECODES_DIR, "manifest.json")
+
+/** Walk up from `start` to find the project root (the dir holding .lecodes/manifest.json). */
+export const findProjectRoot = (start: string): string => {
+  let dir = start
+  while (true) {
+    if (existsSync(manifestPath(dir))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) throw new CliError("Not inside a lecodes project (no .lecodes/manifest.json found).")
+    dir = parent
+  }
+}
+
+export const readManifest = (root: string): Manifest => {
+  try {
+    return JSON.parse(readFileSync(manifestPath(root), "utf8")) as Manifest
+  } catch {
+    throw new CliError("Could not read .lecodes/manifest.json — is this a lecodes project?")
+  }
+}
+
+export const writeManifest = (root: string, manifest: Manifest) => {
+  mkdirSync(join(root, LECODES_DIR), { recursive: true })
+  writeFileSync(manifestPath(root), JSON.stringify(manifest, null, 2))
+}

package/src/matcTool.ts

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync } from "node:fs"
+import { homedir } from "node:os"
+import { join, resolve } from "node:path"
+import { downloadReleaseArchive, fetchReleaseProduct, semverNewer, type ManifestVersion } from "./releases"
+import { CliError, note } from "./util"
+
+/*
+ * Filament's matc (material compiler) — the tool behind LOCAL shader compile: `lecodes dev`
+ * compiles a project's .mat files into the per-platform .filamat artifact family with it
+ * (src/compile/shaders.ts), instead of requiring a push so the server compiles them.
+ *
+ * The binary is NOT shipped with the CLI (most projects have no custom shaders). It downloads on
+ * first use from the same S3 release bucket as the desktop renderer (product "matc" in
+ * releases/versions.json — published by scripts/release/release-windows.ps1 / release-ubuntu.sh
+ * from the desktop build's in-tree filament host tools, so it always matches the engines the
+ * hosts ship). Cache: ~/.lecodes/matc/matc-<version>/. LECODES_MATC overrides resolution entirely
+ * (local dev: point it at packages/desktop/build/creator-gl/filament/tools/matc/matc.exe).
+ *
+ * No version pin: a filamat's compatibility is tied to the vendored Filament, which changes
+ * rarely — resolution takes the newest cached copy, else downloads `latest`. `lecodes shaders
+ * update` moves an existing cache forward after an engine upgrade.
+ *
+ * Platforms: windows-x64, linux-x64, macos-arm64. On Windows/Linux matc rides the DESKTOP build
+ * (filament's host tools build in-tree there). macOS has no such tree — release-macos.sh builds the
+ * app from the vendored xcframeworks — so its matc comes from creator-gl's own host-tool build
+ * (`out/cmake-release/filament/tools/matc`), which is the same filament tree those xcframeworks are
+ * compiled from. Same guarantee, different source; see scripts/release/release-macos.sh.
+ *
+ * macos-x64 is deliberately absent: the host tools are built for the machine doing the release, and
+ * only Apple Silicon is built today (release-macos.sh skips Intel for the same reason).
+ */
+
+const matcName = () => (process.platform === "win32" ? "matc.exe" : "matc")
+
+const platformKey = (): string => {
+  if (process.platform === "win32") return "windows-x64"
+  if (process.platform === "linux") return "linux-x64"
+  if (process.platform === "darwin") {
+    // Intel Macs have no published matc (see the platform note above). Rosetta would run an
+    // arm64 binary anyway, but publishing a key we never build is how a download turns into a
+    // corrupt-archive error instead of a readable one.
+    if (process.arch !== "arm64") {
+      throw new CliError(
+        "matc isn't published for Intel macOS — set LECODES_MATC to a locally built matc " +
+        "(creator-gl/out/cmake-release/filament/tools/matc), or push the project once so shaders " +
+        "compile on the server.",
+      )
+    }
+    return "macos-arm64"
+  }
+  throw new CliError(`matc isn't published for ${process.platform}.`)
+}
+
+const cacheRoot = () => join(homedir(), ".lecodes", "matc")
+
+/** Locate the matc binary inside a cache/stage dir (the archive may or may not nest a folder). */
+const findMatc = (dir: string): string | null => {
+  const name = matcName()
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name)
+    if (entry.isFile() && entry.name === name) return p
+    if (entry.isDirectory()) { const found = findMatc(p); if (found) return found }
+  }
+  return null
+}
+
+/** Versions with a working matc binary in the cache, newest first. */
+export const installedMatcVersions = (): string[] => {
+  try {
+    return readdirSync(cacheRoot(), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith("matc-"))
+      .map((e) => e.name.slice("matc-".length))
+      .filter((v) => findMatc(join(cacheRoot(), `matc-${v}`)) !== null)
+      .sort(semverNewer)
+  } catch {
+    return []
+  }
+}
+
+export const fetchMatcManifest = (): Promise<{ latest: string, versions: ManifestVersion[] }> =>
+  fetchReleaseProduct("matc", "matc (shader compiler)")
+
+const downloadMatc = async (version: string, versions: ManifestVersion[], dest: string): Promise<void> => {
+  const key = platformKey()
+  const file = versions.find((v) => v.version === version)?.files[key]
+  if (!file) {
+    throw new CliError(
+      `matc ${version} [${key}] isn't published — push the project once so shaders compile on the ` +
+      `server, or set LECODES_MATC to a locally built matc.`,
+    )
+  }
+  note(`Downloading the shader compiler (matc ${version}, ${(file.size / 1024 / 1024).toFixed(1)} MB)…`)
+  await downloadReleaseArchive(file, {
+    cacheRoot: cacheRoot(),
+    dest,
+    validate: (dir) => (findMatc(dir) ? null : "The downloaded archive doesn't contain the matc binary."),
+  })
+}
+
+/** The matc binary WITHOUT touching the network: LECODES_MATC override → newest cached version →
+ *  null. `lecodes shaders` status uses this (a status command must not download). */
+export const resolveMatcExeCached = (): string | null => {
+  const override = process.env.LECODES_MATC
+  if (override) {
+    if (!existsSync(override)) throw new CliError(`LECODES_MATC points at "${override}" which doesn't exist.`)
+    return resolve(override)
+  }
+  const cached = installedMatcVersions()[0]
+  return cached ? findMatc(join(cacheRoot(), `matc-${cached}`)) : null
+}
+
+/** The matc binary: LECODES_MATC override → newest cached version → download the latest release.
+ *  Throws CliError when unavailable (callers degrade to the push-once server-compile warning). */
+export const resolveMatcExe = async (): Promise<string> => {
+  const cached = resolveMatcExeCached()
+  if (cached) return cached
+  const { latest, versions } = await fetchMatcManifest()
+  const dir = join(cacheRoot(), `matc-${latest}`)
+  await downloadMatc(latest, versions, dir)
+  const exe = findMatc(dir)
+  if (!exe) throw new CliError(`matc cache at ${dir} is broken — delete the folder and retry.`)
+  return exe
+}
+
+/** `lecodes shaders update`: download the newest published matc (cached versions stay; the newest
+ *  wins resolution). Run it after an engine upgrade so local shader artifacts match the hosts. */
+export const updateMatc = async (): Promise<void> => {
+  const { latest, versions } = await fetchMatcManifest()
+  const before = installedMatcVersions()[0]
+  const dir = join(cacheRoot(), `matc-${latest}`)
+  if (existsSync(dir) && findMatc(dir) !== null) {
+    note(`Already up to date: matc ${latest}.`)
+    return
+  }
+  await downloadMatc(latest, versions, dir)
+  note(before ? `matc updated to ${latest} (was ${before}).` : `matc ${latest} installed.`)
+}