aigpu 0.3.1

package/dist/cli/lib/docs/service.js

@@ -0,0 +1,119 @@
+import { findDocs } from "./commands/find.js";
+import { grepDocs } from "./commands/grep.js";
+import { listDocs } from "./commands/ls.js";
+import { resolveDocsTarget } from "./commands/resolve.js";
+import { listDocSymbols } from "./commands/symbols.js";
+import { DocsError } from "./errors.js";
+import { buildIndex, normalizePath } from "./index.js";
+
+export function createDocsService(index = buildIndex()) {
+  return {
+    execute(input) {
+      if (input.operation === "read" || input.operation === "resolve") {
+        const resolved = resolveOne(index, input.target);
+        if (input.operation === "resolve") {
+          return {
+            operation: "resolve",
+            target: input.target,
+            ...recordMetadata(resolved),
+          };
+        }
+        return {
+          operation: "read",
+          document: {
+            ...recordMetadata(resolved),
+            summary: resolved.summary,
+            content: resolved.content.trimEnd(),
+          },
+        };
+      }
+      if (input.operation === "list") {
+        const path = normalizePath(input.path ?? "/");
+        const entries = listDocs(index, path);
+        if (!entries) {
+          throw new DocsError("AIGPU-DOCS-NOT-FOUND", `Path not found: ${path}`, {
+            target: path,
+            lookup: "path",
+          });
+        }
+        return {
+          operation: "list",
+          path,
+          entries,
+        };
+      }
+      if (input.operation === "grep") {
+        const matches = grepDocs(index, {
+          pattern: input.pattern,
+          ignoreCase: input.ignoreCase,
+          packageName: input.package,
+        });
+        if (matches.length === 0) {
+          throw new DocsError("AIGPU-DOCS-NOT-FOUND", `No matches for: ${input.pattern}`, {
+            pattern: input.pattern,
+          });
+        }
+        const limit = Math.min(Math.max(input.limit ?? 50, 1), 200);
+        return {
+          operation: "grep",
+          pattern: input.pattern,
+          truncated: matches.length > limit,
+          matches: matches.slice(0, limit),
+        };
+      }
+      if (input.operation === "symbols") {
+        const query = input.query?.toLowerCase();
+        const symbols = listDocSymbols(index)
+          .filter((symbol) => !input.package || matchesPackage(symbol.package, input.package))
+          .filter((symbol) => !query || Object.values(symbol).some((value) => value.toLowerCase().includes(query)));
+        const limit = Math.min(Math.max(input.limit ?? 50, 1), 200);
+        return {
+          operation: "symbols",
+          truncated: symbols.length > limit,
+          symbols: symbols.slice(0, limit),
+        };
+      }
+      if (input.operation !== "search") throw new Error(`Unsupported docs operation: ${input.operation}`);
+      const found = findDocs(index, input.query);
+      if (found.results.length === 0) {
+        throw new DocsError("AIGPU-DOCS-NOT-FOUND", `No docs found for: ${input.query}`, {
+          query: input.query,
+        });
+      }
+      return {
+        operation: "search",
+        truncated: found.truncated,
+        results: found.results,
+      };
+    },
+  };
+}
+
+function matchesPackage(recordPackage, filter) {
+  return recordPackage === filter || recordPackage.startsWith(`${filter}/`);
+}
+
+function resolveOne(index, target) {
+  const { resolved, lookup } = resolveDocsTarget(index, target);
+  if (!resolved) {
+    const kind = lookup === "path" ? "Path" : "Symbol";
+    throw new DocsError("AIGPU-DOCS-NOT-FOUND", `${kind} not found: ${target}`, { target, lookup });
+  }
+  if (Array.isArray(resolved)) {
+    throw new DocsError("AIGPU-DOCS-AMBIGUOUS", `Ambiguous symbol: ${target}`, {
+      target,
+      candidates: resolved.map(recordMetadata),
+    });
+  }
+  return resolved;
+}
+
+function recordMetadata(record) {
+  return {
+    symbol: record.symbol,
+    package: record.package,
+    virtualPath: record.virtualPath,
+    repoPath: record.repoPath,
+    kind: record.kind,
+  };
+}

package/dist/cli/lib/doctor/run.js

@@ -0,0 +1,236 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const require = createRequire(import.meta.url);
+const statuses = new Set(["ok", "warn", "fail", "skip"]);
+
+export const probeRegistry = [
+  { id: "binary-resolution", platforms: ["all"], run: probeBinaryResolution },
+  { id: "binary-compatibility", platforms: ["all"], run: probeBinaryCompatibility },
+  { id: "software-renderer-cache", platforms: ["all"], run: probeSoftwareRendererCache },
+  { id: "linux-glibc", platforms: ["linux"], run: probeGlibc },
+  { id: "linux-vulkan-loader", platforms: ["linux"], run: probeVulkanLoader },
+  { id: "linux-vulkan-icd", platforms: ["linux"], run: probeVulkanIcd },
+  { id: "linux-mesa", platforms: ["linux"], run: probeMesa },
+  { id: "linux-display", platforms: ["linux"], run: probeDisplay },
+  { id: "macos-version", platforms: ["darwin"], run: probeMacVersion },
+  { id: "macos-architecture", platforms: ["darwin"], run: probeMacArchitecture },
+  { id: "windows-version", platforms: ["win32"], run: probeWindowsVersion },
+];
+
+export async function runProbeRegistry(registry, context) {
+  const findings = [];
+  for (const probe of registry) {
+    if (!probe.platforms.includes("all") && !probe.platforms.includes(context.platform)) continue;
+    const result = await probe.run(context);
+    if (!statuses.has(result.status)) throw new Error(`Invalid status from probe ${probe.id}: ${result.status}`);
+    findings.push({ probe: probe.id, ...result });
+  }
+  return findings;
+}
+
+export async function runDoctor(args, overrides = {}) {
+  if (args.includes("--help") || args.includes("-h")) {
+    return { code: 0, stdout: "Usage: aigpu doctor [--no-render] [--pretty]\n\nDiagnose whether this machine can render headless with aigpu/node. JSON is written by default.\n" };
+  }
+  const unknown = args.find((arg) => arg !== "--no-render" && arg !== "--pretty");
+  if (unknown) return { code: 1, stderr: `Unknown doctor option: ${unknown}\n` };
+
+  const context = createContext(overrides);
+  const findings = await runProbeRegistry(probeRegistry, context);
+  let adapter = null;
+  let verdict = "unverified";
+
+  if (args.includes("--no-render")) {
+    findings.push({ probe: "render", status: "skip", evidence: "Real render skipped by --no-render; health is unverified." });
+  } else {
+    let rendered;
+    try {
+      rendered = await context.render();
+      adapter = rendered.adapter;
+      verdict = "healthy";
+      findings.push({ probe: "render", status: "ok", evidence: `Rendered and read back a 16x16 offscreen target with ${adapter.name} (${adapter.type}).` });
+    } catch (error) {
+      verdict = "unhealthy";
+      findings.push({ probe: "render", status: "fail", evidence: errorEvidence(error), prescription: lavapipePrescription(context.osRelease) });
+    } finally {
+      rendered?.dispose?.();
+    }
+  }
+
+  const report = { verdict, adapter, findings };
+  return { code: verdict === "healthy" ? 0 : 1, stdout: args.includes("--pretty") ? prettyReport(report) : `${JSON.stringify(report)}\n` };
+}
+
+function createContext(overrides) {
+  const env = overrides.env ?? process.env;
+  const platform = overrides.platform ?? process.platform;
+  const command = overrides.command ?? defaultCommand;
+  return {
+    platform,
+    arch: overrides.arch ?? process.arch,
+    env,
+    osRelease: overrides.osRelease ?? (platform === "linux" ? parseOsRelease(safeRead("/etc/os-release")) : {}),
+    exists: overrides.exists ?? existsSync,
+    listIcds: overrides.listIcds ?? (() => defaultIcdFiles(env)),
+    command,
+    glibc: overrides.glibc ?? runtimeGlibc(),
+    release: overrides.release ?? command(platform === "win32" ? "cmd" : "uname", platform === "win32" ? ["/c", "ver"] : ["-r"]),
+    render: overrides.render ?? realRender,
+    softwareRenderer: overrides.softwareRenderer ?? softwareRendererState,
+  };
+}
+
+function probeBinaryResolution(context) {
+  if (context.env.AIGPU_DAWN_BINARY) {
+    const path = resolve(context.env.AIGPU_DAWN_BINARY);
+    return context.exists(path)
+      ? { status: "ok", evidence: `AIGPU_DAWN_BINARY resolves to ${path}.` }
+      : { status: "fail", evidence: `AIGPU_DAWN_BINARY points to missing file ${path}.`, prescription: "Set AIGPU_DAWN_BINARY to a verified Dawn .node file, or unset it to use the normal resolution chain." };
+  }
+  const cache = context.env.AIGPU_CACHE_DIR ?? context.env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+  try {
+    const stock = require.resolve("webgpu");
+    return { status: "ok", evidence: `Normal chain will try aigpu cache under ${cache}, then stock webgpu at ${stock}, then the downloadable prebuild.` };
+  } catch {
+    return { status: "warn", evidence: `No stock webgpu package resolved; normal chain will try aigpu cache under ${cache}, then download the portable Dawn prebuild if supported.` };
+  }
+}
+
+async function probeSoftwareRendererCache(context) {
+  const state = await (context.softwareRenderer?.() ?? { path: null, error: null });
+  if (state.path) return { status: "ok", evidence: `Portable software renderer 25.0.7-aigpu.1 is cached and sha256-verified at ${state.path}.` };
+  return { status: "skip", evidence: state.error ? `Portable software renderer cache is unusable: ${state.error}` : "Portable software renderer is not cached (it is installed only with explicit consent)." };
+}
+
+function probeBinaryCompatibility(context) {
+  const path = context.env.AIGPU_DAWN_BINARY;
+  if (!path) return { status: "ok", evidence: `Normal Dawn resolution selects a binary for process ${context.platform}/${context.arch}.` };
+  const lower = path.toLowerCase();
+  const namedArch = ["arm64", "x64", "ia32"].find((arch) => lower.includes(arch));
+  const namedPlatform = lower.includes("linux") ? "linux" : lower.includes("darwin") || lower.includes("macos") ? "darwin" : lower.includes("win32") || lower.includes("windows") ? "win32" : null;
+  if ((namedArch && namedArch !== context.arch) || (namedPlatform && namedPlatform !== context.platform)) {
+    return { status: "fail", evidence: `${path} appears to target ${namedPlatform ?? "unknown platform"}/${namedArch ?? "unknown architecture"}, but this process is ${context.platform}/${context.arch}.`, prescription: "Use a Dawn .node binary matching process.platform and process.arch." };
+  }
+  return { status: "ok", evidence: `${path} has no filename mismatch with process ${context.platform}/${context.arch}; native loading is verified by the render probe.` };
+}
+
+function probeGlibc(context) {
+  return context.glibc ? { status: "ok", evidence: `glibc ${context.glibc}.` } : { status: "warn", evidence: "glibc version could not be detected (the host may use another libc)." };
+}
+
+function probeVulkanLoader(context) {
+  const paths = ["/usr/lib/libvulkan.so.1", "/usr/lib64/libvulkan.so.1", "/usr/lib/x86_64-linux-gnu/libvulkan.so.1", "/usr/lib/aarch64-linux-gnu/libvulkan.so.1"];
+  const found = paths.find(context.exists);
+  const ldconfig = context.command("ldconfig", ["-p"]);
+  if (found || /libvulkan\.so\.1/u.test(ldconfig ?? "")) return { status: "ok", evidence: found ? `Vulkan loader found at ${found}.` : "Vulkan loader libvulkan.so.1 is registered with ldconfig." };
+  return { status: "fail", evidence: "Vulkan loader libvulkan.so.1 was not found.", prescription: prescriptionsFor(context.osRelease).install };
+}
+
+async function probeVulkanIcd(context) {
+  const files = context.listIcds();
+  if (files.length) return { status: "ok", evidence: `Vulkan ICD manifests: ${files.join(", ")}.` };
+  const softwareRenderer = await (context.softwareRenderer?.() ?? { path: null });
+  if (softwareRenderer.path) return { status: "skip", evidence: "No system Vulkan ICD manifest was found; the cached portable software renderer is available as the automatic last resort." };
+  return { status: "fail", evidence: "No Vulkan ICD manifest was found in /usr/share/vulkan/icd.d, VK_ICD_FILENAMES, or VK_DRIVER_FILES.", prescription: lavapipePrescription(context.osRelease) };
+}
+
+function probeMesa(context) {
+  const outputs = [context.command("glxinfo", ["-B"]), context.command("vulkaninfo", ["--summary"])].filter(Boolean).join("\n");
+  const match = outputs.match(/Mesa[^\d]*(\d+)\.(\d+)(?:\.\d+)?/iu);
+  if (!match) return { status: "skip", evidence: "Mesa version was not detected; the render probe verifies the active driver." };
+  const version = `${match[1]}.${match[2]}`;
+  return Number(match[1]) < 23
+    ? { status: "warn", evidence: `Mesa ${version} detected; Mesa 23 or newer is recommended for lavapipe.`, prescription: prescriptionsFor(context.osRelease).install }
+    : { status: "ok", evidence: `Mesa ${version} detected (>=23).` };
+}
+
+function probeDisplay(context) {
+  const display = context.env.DISPLAY;
+  const wayland = context.env.WAYLAND_DISPLAY;
+  return !display && !wayland
+    ? { status: "ok", evidence: "DISPLAY and WAYLAND_DISPLAY are unset; this is valid for headless Vulkan." }
+    : { status: "ok", evidence: `Display state: DISPLAY=${display ?? "unset"}, WAYLAND_DISPLAY=${wayland ?? "unset"}; Dawn may select its OpenGL path.` };
+}
+function probeMacVersion(context) { return { status: "ok", evidence: `macOS ${context.command("sw_vers", ["-productVersion"]) ?? context.release ?? "unknown"}.` }; }
+function probeMacArchitecture(context) {
+  const translated = context.command("sysctl", ["-in", "sysctl.proc_translated"]) === "1";
+  return { status: "ok", evidence: `${context.arch}${translated ? " under Rosetta 2" : " native process"}; binary compatibility is verified by loading and rendering.` };
+}
+function probeWindowsVersion(context) { return { status: "ok", evidence: `Windows ${context.release ?? "unknown"}; D3D12 availability is verified by the render probe.` }; }
+
+export function prescriptionsFor(osRelease) {
+  const ids = `${osRelease.ID ?? ""} ${osRelease.ID_LIKE ?? ""}`.toLowerCase();
+  const install = /debian|ubuntu/u.test(ids)
+    ? "apt-get update && apt-get install -y libvulkan1 libdrm2 zlib1g libzstd1 libudev1 mesa-vulkan-drivers"
+    : /fedora|rhel|centos|amzn/u.test(ids)
+      ? "dnf install -y vulkan-loader libdrm zlib libzstd systemd-libs mesa-vulkan-drivers"
+      : "Install the Vulkan loader, libdrm, zlib, zstd, libudev, and Mesa Vulkan drivers (lavapipe) with this distribution's package manager.";
+  const discoverIcd = "$(find /usr/share/vulkan/icd.d -name 'lvp_icd*.json' | head -1)";
+  return { install, env: `export VK_ICD_FILENAMES=${discoverIcd}\nexport VK_DRIVER_FILES=$VK_ICD_FILENAMES` };
+}
+function lavapipePrescription(osRelease) {
+  const prescription = prescriptionsFor(osRelease);
+  return `run: npx aigpu install-software-renderer\nAlternative (system packages): ${prescription.install}\n${prescription.env}`;
+}
+async function softwareRendererState() {
+  try {
+    const { getCachedSoftwareRenderer } = await import("@aigpu/adapter-node/install-software-renderer");
+    return { path: getCachedSoftwareRenderer(), error: null };
+  } catch (error) { return { path: null, error: errorEvidence(error) }; }
+}
+
+async function realRender() {
+  const { init, effect, frame, target } = await import("aigpu/node");
+  const gpu = await init();
+  try {
+    const colorTarget = target(gpu, { size: [16, 16], format: "rgba8unorm", label: "aigpu-doctor" });
+    const probe = effect(gpu, "@fragment fn main() -> @location(0) vec4f { return vec4f(0.25, 0.5, 0.75, 1.0); }");
+    frame(gpu, (current) => current.pass({ target: colorTarget }, (encoder) => encoder.draw(probe)));
+    const pixels = await colorTarget.read();
+    if (!pixels || pixels.byteLength < 16 * 16 * 4) throw new Error("render readback returned too few bytes");
+    const info = gpu.device?.adapterInfo ?? {};
+    const name = info.description || info.device || info.vendor || "unknown adapter";
+    const type = info.adapterType || info.type || (/llvmpipe|lavapipe|swiftshader|software|cpu/iu.test(name) ? "cpu" : "unknown");
+    return { adapter: { name: String(name), type: String(type) }, dispose: () => gpu.dispose() };
+  } catch (error) {
+    gpu.dispose();
+    throw error;
+  }
+}
+
+export function parseOsRelease(contents) {
+  const result = {};
+  for (const line of contents.split(/\r?\n/u)) {
+    const match = line.match(/^([A-Z][A-Z0-9_]*)=(.*)$/u);
+    if (match) result[match[1]] = match[2].replace(/^(["'])(.*)\1$/u, "$2");
+  }
+  return result;
+}
+function defaultIcdFiles(env) {
+  const explicit = [env.VK_ICD_FILENAMES, env.VK_DRIVER_FILES].filter(Boolean).flatMap((value) => value.split(":"));
+  let scanned = [];
+  try { scanned = readdirSync("/usr/share/vulkan/icd.d").filter((name) => name.endsWith(".json")).map((name) => join("/usr/share/vulkan/icd.d", name)); } catch {}
+  return [...new Set([...explicit, ...scanned])].filter(Boolean);
+}
+function defaultCommand(command, args) {
+  const result = spawnSync(command, args, { encoding: "utf8", timeout: 3000 });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+function runtimeGlibc() { try { return process.report?.getReport()?.header?.glibcVersionRuntime ?? null; } catch { return null; } }
+function safeRead(path) { try { return readFileSync(path, "utf8"); } catch { return ""; } }
+function errorEvidence(error) {
+  const details = error && typeof error === "object" ? error : {};
+  return `${details.code ? `${details.code}: ` : ""}${String(details.message ?? error)}`;
+}
+function prettyReport(report) {
+  const lines = [`Verdict: ${report.verdict}`, `Adapter: ${report.adapter ? `${report.adapter.name} (${report.adapter.type})` : "none"}`, "", "Findings:"];
+  for (const finding of report.findings) {
+    lines.push(`  [${finding.status.toUpperCase()}] ${finding.probe}: ${finding.evidence}`);
+    if (finding.prescription) lines.push(...finding.prescription.split("\n").map((line) => `    Fix: ${line}`));
+  }
+  return `${lines.join("\n")}\n`;
+}

package/dist/cli/lib/examples/errors.js

@@ -0,0 +1,13 @@
+export class ExamplesError extends Error {
+  constructor(code, message, exitCode = 5, details) { super(message); this.name = 'ExamplesError'; this.code = code; this.exitCode = exitCode; this.details = details; }
+}
+export const usage = (message) => new ExamplesError('AIGPU-EXAMPLES-USAGE', message, 2);
+export const notFound = (message) => new ExamplesError('AIGPU-EXAMPLES-NOT-FOUND', message, 3);
+export const network = (message) => new ExamplesError('AIGPU-EXAMPLES-NETWORK', message, 4);
+export const integrity = (message) => new ExamplesError('AIGPU-EXAMPLES-INTEGRITY', message, 5);
+export const destinationExists = (message) => new ExamplesError('AIGPU-EXAMPLES-DESTINATION-EXISTS', message, 6);
+export const filesystem = (message) => new ExamplesError('AIGPU-EXAMPLES-FILESYSTEM', message, 7);
+export function errorResult(error) {
+  const e = error instanceof ExamplesError ? error : filesystem(error instanceof Error ? error.message : String(error));
+  return { code: e.exitCode, stderr: `${JSON.stringify({ error: { code: e.code, message: e.message, ...(e.details === undefined ? {} : { details: e.details }) } })}\n` };
+}

package/dist/cli/lib/examples/hashing.js

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+export const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const field = (value) => `${Buffer.byteLength(value)}:${value}\n`;
+export function aggregateSha256(manifest) {
+  let value = `aigpu-example-aggregate/v1\0${field(manifest.id)}${field(manifest.title)}${field(manifest.description)}`;
+  value += `${manifest.tags.length}\n${manifest.tags.map(field).join('')}${manifest.capabilities.length}\n${manifest.capabilities.map(field).join('')}${manifest.files.length}\n`;
+  for (const file of manifest.files) value += `${field(file.path)}${field(file.contentType)}${file.size}\n${file.sha256}\n`;
+  return sha256(value);
+}

package/dist/cli/lib/examples/help.js

@@ -0,0 +1,13 @@
+export const examplesHelp = `aigpu examples — inspect local example source (never executes code)
+
+The catalog is read from ./examples or AIGPU_EXAMPLES_DIR. No network request is made.
+Canonical local invocation: npx aigpu examples ...
+
+Usage:
+  aigpu examples search <query> [--any] [--limit <n>] [--revision <sha256>] [--root <dir>] [--pretty]
+  aigpu examples show <id> [--revision <sha256>] [--root <dir>] [--pretty]
+  aigpu examples cat <id> <path> [--revision <sha256>] [--root <dir>] [--json]
+  aigpu examples pull <id> --out <directory> [--revision <sha256>] [--root <dir>] [--force] [--pretty]
+
+The pull operation uses an atomic, symlink-safe local copy. MCP also exposes this local catalog over stdio.
+`;

package/dist/cli/lib/examples/local-source.js

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { extname, relative, resolve, sep } from "node:path";
+import { filesystem, integrity, notFound } from "./errors.js";
+import { assertSafeRelativePath } from "./paths.js";
+
+const SKIP = new Set([".git", "node_modules", "dist", "build", ".next", ".cache"]);
+const CONTENT_TYPES = new Map([
+  [".css", "text/css"],
+  [".html", "text/html"],
+  [".js", "text/javascript"],
+  [".json", "application/json"],
+  [".md", "text/markdown"],
+  [".mjs", "text/javascript"],
+  [".jsx", "text/jsx"],
+  [".svelte", "text/svelte"],
+  [".ts", "text/typescript"],
+  [".tsx", "text/tsx"],
+  [".vue", "text/vue"],
+  [".wgsl", "text/plain"],
+]);
+
+/**
+ * Filesystem-backed example source. It is intentionally local-only: no HTTP client, registry,
+ * telemetry, or hosted catalog is involved. The directory can be changed with AIGPU_EXAMPLES_DIR.
+ */
+export class LocalExamplesSource {
+  constructor({ root = process.env.AIGPU_EXAMPLES_DIR ?? resolve(process.cwd(), "examples") } = {}) {
+    this.root = resolve(root);
+  }
+
+  async getIndex({ revision } = {}) {
+    const examples = await this.#discoverExamples();
+    const computedRevision = sha256(JSON.stringify(examples.map(({ files, ...entry }) => ({ ...entry, files: files.map(file => [file.path, file.sha256, file.size]) }))));
+    if (revision && revision !== computedRevision) throw integrity(`Local examples revision is ${computedRevision}, not ${revision}`);
+    return {
+      index: { revision: computedRevision, generatedAt: new Date().toISOString(), examples },
+      offline: true,
+    };
+  }
+
+  async getManifest(index, id) {
+    const entry = index.examples.find((candidate) => candidate.id === id);
+    if (!entry) throw notFound(`Local example not found: ${id}`);
+    const files = entry.files.map((file) => ({ ...file, url: `file://${resolve(this.root, id, file.path)}` }));
+    return {
+      id,
+      revision: index.revision,
+      title: entry.title,
+      description: entry.description,
+      files,
+      aggregateSha256: sha256(JSON.stringify(files.map(file => [file.path, file.size, file.sha256]))),
+    };
+  }
+
+  async getFile(manifest, file) {
+    assertSafeRelativePath(file.path);
+    const exampleRoot = await this.#safeExampleRoot(manifest.id);
+    const path = resolve(exampleRoot, file.path);
+    const fromRoot = relative(exampleRoot, path);
+    if (!fromRoot || fromRoot === ".." || fromRoot.startsWith(`..${sep}`)) throw filesystem(`Example file escapes its root: ${file.path}`);
+    let bytes;
+    try {
+      const stat = await lstat(path);
+      if (!stat.isFile()) throw new Error("not a regular file");
+      bytes = await readFile(path);
+    } catch (error) {
+      if (error?.code === "ENOENT") throw notFound(`Local example file not found: ${file.path}`);
+      throw filesystem(`Cannot read local example file ${file.path}: ${error.message}`);
+    }
+    if (bytes.byteLength !== file.size || sha256(bytes) !== file.sha256) throw integrity(`Local example integrity mismatch: ${file.path}`);
+    return bytes;
+  }
+
+  async #discoverExamples() {
+    let entries;
+    try {
+      entries = await readdir(this.root, { withFileTypes: true });
+    } catch (error) {
+      if (error?.code === "ENOENT") throw notFound(`Examples directory does not exist: ${this.root}`);
+      throw filesystem(`Cannot read examples directory: ${error.message}`);
+    }
+    const examples = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!entry.isDirectory() || SKIP.has(entry.name) || entry.name.startsWith(".")) continue;
+      const files = await collectFiles(resolve(this.root, entry.name));
+      if (files.length === 0) continue;
+      const packageInfo = await readPackageJson(resolve(this.root, entry.name));
+      const tags = [...new Set([entry.name, ...entry.name.split(/[^a-z0-9]+/iu).filter(Boolean), "webgpu", "aigpu"])]
+        .map((tag) => tag.toLowerCase());
+      examples.push({
+        id: entry.name,
+        title: packageInfo?.name ?? titleFromId(entry.name),
+        description: packageInfo?.description ?? `Local AIGpu example: ${titleFromId(entry.name)}.`,
+        tags,
+        capabilities: ["webgpu", "local"],
+        fileCount: files.length,
+        files,
+      });
+    }
+    return examples;
+  }
+
+  async #safeExampleRoot(id) {
+    assertSafeRelativePath(id);
+    const path = resolve(this.root, id);
+    const fromRoot = relative(this.root, path);
+    if (!fromRoot || fromRoot === ".." || fromRoot.startsWith(`..${sep}`)) throw filesystem(`Example id escapes the examples root: ${id}`);
+    const stat = await lstat(path).catch((error) => { throw error?.code === "ENOENT" ? notFound(`Local example not found: ${id}`) : error; });
+    if (!stat.isDirectory()) throw notFound(`Local example not found: ${id}`);
+    return path;
+  }
+}
+
+async function collectFiles(root, prefix = "") {
+  const entries = await readdir(root, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (SKIP.has(entry.name) || entry.name.startsWith(".")) continue;
+    const path = resolve(root, entry.name);
+    const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) files.push(...await collectFiles(path, relativePath));
+    else if (entry.isFile()) {
+      const bytes = await readFile(path);
+      files.push({ path: relativePath, size: bytes.byteLength, sha256: sha256(bytes), contentType: CONTENT_TYPES.get(extname(entry.name).toLowerCase()) ?? "application/octet-stream" });
+    }
+  }
+  return files;
+}
+
+async function readPackageJson(root) {
+  try { return JSON.parse(await readFile(resolve(root, "package.json"), "utf8")); }
+  catch { return undefined; }
+}
+
+function titleFromId(id) {
+  return id.replace(/[-_]+/gu, " ").replace(/\b\w/gu, (letter) => letter.toUpperCase());
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}

package/dist/cli/lib/examples/paths.js

@@ -0,0 +1,12 @@
+import { posix } from 'node:path';
+import { integrity } from './errors.js';
+export function assertSafeRelativePath(value) {
+  let decoded;
+  try { decoded = decodeURIComponent(value); } catch { throw integrity(`Invalid encoded path: ${value}`); }
+  if (!value || decoded !== value || value !== posix.normalize(value) || value.startsWith('/') || value.startsWith('\\') || value.includes('\\') || value.includes('%') || /^[A-Za-z]:/.test(value) || /[\0-\x1f\x7f]/.test(value) || value.split('/').some((p) => !p || p === '.' || p === '..')) throw integrity(`Unsafe source path: ${value}`);
+  return value;
+}
+export function assertUniquePaths(files) {
+ const exact = new Set(), folded = new Set();
+ for (const file of files) { const p=assertSafeRelativePath(file.path); const f=p.normalize('NFC').toLocaleLowerCase('en-US'); if(exact.has(p)||folded.has(f)) throw integrity(`Colliding source path: ${p}`); exact.add(p); folded.add(f); }
+}

package/dist/cli/lib/examples/pull.js

@@ -0,0 +1,58 @@
+import { constants,existsSync,renameSync,rmSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { mkdir,lstat,open,readFile,readdir,rename,rm,rmdir,writeFile } from 'node:fs/promises';
+import { dirname,basename,parse,relative,resolve,join,sep } from 'node:path';
+import { ExamplesError,destinationExists,filesystem,integrity } from './errors.js';
+
+const MAX_PULL_BYTES = 32 * 1024 * 1024;
+
+const TOKEN=/^[a-f0-9]{32}$/;
+const SELF_START=`${process.pid}:${Date.now()-Math.round(process.uptime()*1000)}`;
+// Darwin O_NOFOLLOW_ANY rejects symlinks anywhere in a path; combining it with O_NOFOLLOW returns EINVAL.
+const DARWIN_NOFOLLOW_ANY=process.platform==='darwin'?0x20000000:0;
+async function exists(path){try{return await lstat(path)}catch(e){if(e.code==='ENOENT')return;throw e}}
+function portablePath(path,platform){const full=resolve(path);if(platform!=='darwin'||process.platform!=='darwin')return full;for(const prefix of ['/tmp','/var','/etc'])if(full===prefix||full.startsWith(`${prefix}/`))return `/private${full}`;return full;}
+async function portableParent(destination,platform){const output=resolve(destination),absolute=portablePath(output,platform),parent=dirname(absolute),root=parse(parent).root;let directory;try{let cursor=root;for(const part of relative(root,parent).split(sep).filter(Boolean)){cursor=join(cursor,part);let stat=await exists(cursor);if(!stat){try{await mkdir(cursor,{mode:0o700})}catch(e){if(e.code!=='EEXIST')throw e}stat=await lstat(cursor)}if(stat.isSymbolicLink()||!stat.isDirectory())throw filesystem(`Unsafe destination directory: ${cursor}`);const checked=await open(cursor,constants.O_RDONLY|constants.O_DIRECTORY|DARWIN_NOFOLLOW_ANY);await checked.close()}directory=await open(parent,constants.O_RDONLY|constants.O_DIRECTORY|DARWIN_NOFOLLOW_ANY);return {absolute,parent,output,portable:true,parentIdentity:identity(await directory.stat()),close:()=>directory.close()}}catch(e){await directory?.close().catch(()=>{});if(e?.code?.startsWith?.('AIGPU-'))throw e;throw filesystem(`Unsafe destination parent: ${e.message}`)}}
+async function safeParent(destination,platform=process.platform){if(platform==='darwin')return portableParent(destination,platform);if(platform!=='linux')throw filesystem(`Safe destination storage is unsupported on ${platform}`);const output=resolve(destination),root=parse(output).root,parts=relative(root,dirname(output)).split(sep).filter(Boolean);let directory;try{directory=await open(root,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);for(const part of parts){const child=`/proc/self/fd/${directory.fd}/${part}`;let next;try{next=await open(child,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW)}catch(e){if(e.code!=='ENOENT')throw e;try{await mkdir(child,{mode:0o700})}catch(mkdirError){if(mkdirError.code!=='EEXIST')throw mkdirError}next=await open(child,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW)}await directory.close();directory=next}const parent=`/proc/self/fd/${directory.fd}`;return {absolute:`${parent}/${basename(output)}`,parent,output,portable:false,close:()=>directory.close()}}catch(e){await directory?.close().catch(()=>{});throw filesystem(`Unsafe destination parent: ${e.message}`)}}
+async function startTime(pid,platform){if(platform!=='linux'){if(pid===process.pid)return SELF_START;try{process.kill(pid,0);return 'alive'}catch(e){return e.code==='EPERM'?'alive':undefined}}try{const value=await readFile(`/proc/${pid}/stat`,'utf8'),tail=value.slice(value.lastIndexOf(')')+2).split(' ');return tail[19]}catch{return}}
+const identity=s=>({dev:String(s.dev),ino:String(s.ino)});
+const same=(s,id)=>!!s&&!!id&&!s.isSymbolicLink()&&String(s.dev)===id.dev&&String(s.ino)===id.ino;
+async function assertParent(destination){if(destination.portable&&!same(await exists(destination.parent),destination.parentIdentity))throw filesystem('Destination parent identity changed');}
+// This closes the staging window deterministically. Node has no portable rename-if-absent for
+// directories, so the parent lock still only serializes cooperating AIGPU writers; a hostile writer
+// with access to the parent could race between this final check and rename().
+async function assertDestinationUnclaimed(initial,destination,reported){if(!initial&&await exists(destination))throw destinationExists(`Destination already exists: ${reported}`);}
+function names(name,token){return {temp:`.${name}.aigpu-tmp-${token}`,backup:`.${name}.aigpu-old-${token}`,stamp:`.${name}.aigpu-published-${token}`};}
+function validOwner(value,name){if(!value||!TOKEN.test(value.token)||!Number.isInteger(value.pid)||typeof value.start!=='string')return false;const expected=names(name,value.token);return value.temp===expected.temp&&value.backup===expected.backup&&value.stamp===expected.stamp;}
+async function readOwner(lock,name){try{const s=await lstat(join(lock,'owner'));if(s.isSymbolicLink()||!s.isFile())return;const value=JSON.parse(await readFile(join(lock,'owner'),'utf8'));return validOwner(value,name)?value:undefined}catch{return}}
+async function active(owner,platform){const current=await startTime(owner.pid,platform);return platform==='linux'||owner.pid===process.pid?current===owner.start:current!==undefined;}
+async function writeExclusive(path,bytes,portable){let handle;try{handle=await open(path,constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|(portable?DARWIN_NOFOLLOW_ANY:constants.O_NOFOLLOW),0o600);await handle.writeFile(bytes);await handle.sync()}finally{await handle?.close()}}
+async function writeOwner(lock,owner,portable){const path=join(lock,'owner'),tmp=join(lock,`.owner-${owner.token}`);await writeExclusive(tmp,Buffer.from(JSON.stringify(owner)+'\n'),portable);await rename(tmp,path);}
+async function removeLock(lock,name,token){const owner=await readOwner(lock,name);if(!owner||owner.token!==token)return;const entries=await readdir(lock);if(entries.some(entry=>entry!=='owner'))throw filesystem('Unsafe destination lock contents');await rm(join(lock,'owner'));await rmdir(lock);}
+async function acquire(lock,name,destination,platform,guard){let stale;const portable=platform==='darwin';for(let attempt=0;attempt<3;attempt++){const token=randomBytes(16).toString('hex'),owned=names(name,token),owner={pid:process.pid,start:await startTime(process.pid,platform),token,...owned,phase:'locked'};if(!owner.start)throw filesystem('Cannot determine process identity');try{await guard();await mkdir(lock,{mode:0o700});await guard();await writeExclusive(join(lock,'owner'),Buffer.from(JSON.stringify(owner)+'\n'),portable);return {owner,stale}}catch(e){if(e.code!=='EEXIST')throw filesystem(e.message);const s=await exists(lock);if(!s||s.isSymbolicLink()||!s.isDirectory())throw filesystem('Unsafe destination lock');const previous=await readOwner(lock,name);if(!previous)throw filesystem('Unauthenticated destination lock');if(await active(previous,platform))throw destinationExists(`Destination is busy: ${destination}`);const entries=await readdir(lock);if(entries.some(entry=>entry!=='owner'))throw filesystem('Unsafe stale destination lock');await rm(join(lock,'owner'));await rmdir(lock);stale=previous;}}throw filesystem('Cannot recover stale destination lock');}
+async function ownedStamp(path,token){try{const s=await lstat(path);return s.isFile()&&!s.isSymbolicLink()&&(await readFile(path,'utf8'))===token}catch{return false}}
+async function removeOwnedDirectory(path,id){const s=await exists(path);if(same(s,id)&&s.isDirectory())await rm(path,{recursive:true,force:true});}
+async function writeStaged(root,path,parts,bytes,portable,beforeFileWrite){if(!portable){let directory=root,owned=false;try{for(const part of parts.slice(0,-1)){const child=`/proc/self/fd/${directory.fd}/${part}`;try{await mkdir(child,{mode:0o700})}catch(e){if(e.code!=='EEXIST')throw e}const next=await open(child,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);if(owned)await directory.close();directory=next;owned=true}const visible=join(path,...parts.slice(0,-1)),directoryIdentity=identity(await directory.stat());if(beforeFileWrite)await beforeFileWrite();await writeFile(`/proc/self/fd/${directory.fd}/${parts.at(-1)}`,bytes,{mode:0o600,flag:'wx'});if(!same(await exists(visible),directoryIdentity))throw filesystem('Staging directory identity changed');}finally{if(owned)await directory.close().catch(()=>{})}return}const rootIdentity=identity(await root.stat());if(!same(await exists(path),rootIdentity))throw filesystem('Staging directory identity changed');let directory=path;for(const part of parts.slice(0,-1)){directory=join(directory,part);try{await mkdir(directory,{mode:0o700})}catch(e){if(e.code!=='EEXIST')throw e}const stat=await lstat(directory);if(stat.isSymbolicLink()||!stat.isDirectory())throw filesystem(`Unsafe staging directory: ${part}`);const checked=await open(directory,constants.O_RDONLY|constants.O_DIRECTORY|DARWIN_NOFOLLOW_ANY);await checked.close();if(!same(await exists(path),rootIdentity))throw filesystem('Staging directory identity changed')}const directoryIdentity=identity(await lstat(directory));if(beforeFileWrite)await beforeFileWrite();await writeExclusive(join(directory,parts.at(-1)),bytes,true);if(!same(await exists(directory),directoryIdentity)||!same(await exists(path),rootIdentity))throw filesystem('Staging directory identity changed');}
+async function recover(parent,name,absolute,owner){if(!owner)return;const temp=join(parent,owner.temp),backup=join(parent,owner.backup),stamp=join(parent,owner.stamp),old=await exists(backup),current=await exists(absolute);if(old){if(!same(old,owner.backupIdentity)||!old.isDirectory())throw filesystem('Unauthenticated stale pull backup');const published=owner.phase==='published'&&current?.isDirectory()&&!current.isSymbolicLink()&&await ownedStamp(stamp,owner.token);if(published){await rm(backup,{recursive:true});await rm(stamp,{force:true});}else{if(current){const quarantine=join(parent,`.${name}.aigpu-rejected-${randomBytes(16).toString('hex')}`);await rename(absolute,quarantine);}await rename(backup,absolute);await rm(stamp,{force:true});}}await removeOwnedDirectory(temp,owner.tempIdentity);}
+function guardSignals(restore){let handled=false;const handlers={SIGINT:()=>handle('SIGINT'),SIGTERM:()=>handle('SIGTERM')},close=()=>{for(const [signal,handler] of Object.entries(handlers))process.off(signal,handler);},handle=signal=>{if(handled)return;handled=true;close();try{restore()}finally{process.kill(process.pid,signal)}};for(const [signal,handler] of Object.entries(handlers))process.once(signal,handler);return close;}
+
+export async function pullExample(client,manifest,destination,{force=false,offline=false,beforeFileWrite,beforePublish,afterBackupRename,afterPublish,platform=process.platform,signal}={}){
+ signal?.throwIfAborted();
+ const total=manifest.files.reduce((n,f)=>n+f.size,0);if(total>MAX_PULL_BYTES)throw integrity('Example exceeds 32 MiB pull limit');
+ const safeDestination=await safeParent(destination,platform),guard=()=>assertParent(safeDestination),{absolute,parent,output}=safeDestination,name=basename(output),lock=join(parent,`.${name}.aigpu.lock`);let acquired;try{acquired=await acquire(lock,name,destination,platform,guard)}catch(e){await safeDestination.close().catch(()=>{});throw e}const owner=acquired.owner,temp=join(parent,owner.temp),backup=join(parent,owner.backup),stamp=join(parent,owner.stamp);
+ let moved=false,published=false,stage;
+ try{
+  await guard();
+  await recover(parent,name,absolute,acquired.stale);
+  const current=await exists(absolute);if(current&&!force)throw destinationExists(`Destination already exists: ${destination}`);if(current&&(current.isSymbolicLink()||!current.isDirectory()))throw filesystem('Destination must be a real directory');
+  await guard();await mkdir(temp,{mode:0o700});stage=await open(temp,constants.O_RDONLY|constants.O_DIRECTORY|(safeDestination.portable?DARWIN_NOFOLLOW_ANY:constants.O_NOFOLLOW));owner.tempIdentity=identity(await stage.stat());owner.phase='staging';await writeOwner(lock,owner,safeDestination.portable);
+  let next=0;async function worker(){while(true){signal?.throwIfAborted();const i=next++;if(i>=manifest.files.length)return;const file=manifest.files[i],bytes=await client.getFile(manifest,file,{offline,signal});signal?.throwIfAborted();await writeStaged(stage,temp,file.path.split('/'),bytes,safeDestination.portable,beforeFileWrite);}}
+  await Promise.all(Array.from({length:Math.min(4,manifest.files.length)},worker));
+  const unguard=guardSignals(()=>{if(!published&&existsSync(backup)&&!existsSync(absolute)){try{renameSync(backup,absolute)}catch{}moved=false;}try{rmSync(temp,{recursive:true,force:true})}catch{}try{rmSync(lock,{recursive:true,force:true})}catch{}});
+  try{if(current){await guard();owner.backupIdentity=identity(current);owner.phase='backup-planned';await writeOwner(lock,owner,safeDestination.portable);await rename(absolute,backup);moved=true;if(afterBackupRename)await afterBackupRename();if(!same(await lstat(backup),owner.backupIdentity))throw filesystem('Pull backup identity changed');owner.phase='backed-up';await writeOwner(lock,owner,safeDestination.portable);}if(beforePublish)await beforePublish();await guard();if(!same(await stage.stat(),owner.tempIdentity)||!same(await exists(temp),owner.tempIdentity))throw filesystem('Staging directory identity changed');await assertDestinationUnclaimed(current,absolute,destination);signal?.throwIfAborted();await rename(temp,absolute);if(!same(await exists(absolute),owner.tempIdentity)){const rejected=join(parent,`.${name}.aigpu-rejected-${randomBytes(16).toString('hex')}`);await rename(absolute,rejected).catch(()=>{});throw filesystem('Published staging identity changed')}published=true;moved=false;await writeExclusive(stamp,Buffer.from(owner.token),safeDestination.portable);owner.phase='published';await writeOwner(lock,owner,safeDestination.portable);}finally{unguard()}
+  if(afterPublish)await afterPublish();
+  if(await exists(backup)){const old=await exists(backup);if(!same(old,owner.backupIdentity))throw filesystem('Pull backup identity changed');await rm(backup,{recursive:true});}await rm(stamp,{force:true});
+  return {out:output,files:manifest.files.length,bytes:total};
+ }catch(e){if(moved&&!published)await rename(backup,absolute).catch(()=>{});else if(published)await recover(parent,name,absolute,owner).catch(()=>{});if(e instanceof ExamplesError||e?.name==='AbortError'||signal?.aborted&&e===signal.reason)throw e;throw filesystem(`Pull failed: ${e.message}`);
+ }finally{await stage?.close().catch(()=>{});await removeOwnedDirectory(temp,owner.tempIdentity).catch(()=>{});await removeLock(lock,name,owner.token).catch(()=>{});await safeDestination.close().catch(()=>{});}
+}