@n6k.io/build 0.0.1

package/src/storybook/decorators.tsx

@@ -0,0 +1,93 @@
+import { useEffect, useState, type ReactNode } from "react";
+import type { Decorator } from "@storybook/react";
+import { useAttach, useDuckDB } from "@n6k.io/db/react";
+import type { within } from "storybook/test";
+import { seedDemoData } from "./seed-demo-data";
+import { StoryShell } from "./story-shell";
+
+export const DUCKDB_READY_TESTID = "duckdb-ready";
+
+// Wait for the SeededGate's positive ready sentinel. DuckDB-WASM cold-boots and
+// then seeds the demo data, which is variable under a contended headless test
+// run, so this single await needs a generous timeout (kept under the story
+// project's testTimeout); after it resolves, callers can use default `findBy*`.
+export async function waitForDuckDbReady(
+  canvas: ReturnType<typeof within>,
+  timeout = 25_000,
+): Promise<void> {
+  await canvas.findByTestId(DUCKDB_READY_TESTID, undefined, { timeout });
+}
+
+type SeedStatus = "pending" | "ready" | "error";
+
+const STORY_CATALOG = "page_db";
+
+function SeededGate({ children }: { children: ReactNode }) {
+  // Register the catalog with the provider so `useQuery({ catalogs: [...] })`
+  // gates pass. TYPE DUCKDB attaches an in-memory database without going
+  // through the n6k WebSocket driver (which requires a real fetch URL).
+  useAttach(STORY_CATALOG, ":memory:", { TYPE: "DUCKDB" });
+
+  const { conn, status, attached, error } = useDuckDB();
+  const [seedStatus, setSeedStatus] = useState<SeedStatus>("pending");
+  const [seedError, setSeedError] = useState<string | null>(null);
+
+  const catalogAttached = attached[STORY_CATALOG] !== undefined;
+
+  useEffect(() => {
+    if (status !== "ready" || !conn || !catalogAttached) return;
+    let cancelled = false;
+    seedDemoData(conn)
+      .then(() => {
+        if (!cancelled) setSeedStatus("ready");
+      })
+      .catch((e: Error) => {
+        if (cancelled) return;
+        setSeedError(e.message);
+        setSeedStatus("error");
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [conn, status, catalogAttached]);
+
+  if (error) {
+    return (
+      <div className="p-4 text-sm text-destructive">DuckDB error: {error}</div>
+    );
+  }
+  if (seedStatus === "error") {
+    return (
+      <div className="p-4 text-sm text-destructive">
+        Seed error: {seedError}
+      </div>
+    );
+  }
+  if (status !== "ready" || !catalogAttached || seedStatus !== "ready") {
+    return (
+      <div className="p-4 text-sm text-muted-foreground">
+        Loading DuckDB & seeding demo data…
+      </div>
+    );
+  }
+  return (
+    <>
+      <span data-testid={DUCKDB_READY_TESTID} hidden />
+      {children}
+    </>
+  );
+}
+
+export const withSeededDuckDb: Decorator = (Story) => (
+  <StoryShell>
+    <SeededGate>
+      <Story />
+    </SeededGate>
+  </StoryShell>
+);
+
+export const withDuckDb: Decorator = (Story) => (
+  <StoryShell>
+    <Story />
+  </StoryShell>
+);

package/src/storybook/index.ts

@@ -0,0 +1,13 @@
+// Shared Storybook scaffolding for n6k packages — the DuckDB provider stack,
+// decorators, demo-data seeder, and preview parameters. Consumers wire the Vite
+// plugins (workers/wasm/cross-origin) from `@n6k.io/build/vite` in their
+// `.storybook/main.ts`, and import the runtime pieces below from here.
+export {
+  withDuckDb,
+  withSeededDuckDb,
+  waitForDuckDbReady,
+  DUCKDB_READY_TESTID,
+} from "./decorators";
+export { StoryShell } from "./story-shell";
+export { seedDemoData } from "./seed-demo-data";
+export { previewParameters } from "./preview";

package/src/storybook/preview.ts

@@ -0,0 +1,17 @@
+import type { Preview } from "@storybook/react";
+
+/**
+ * Shared Storybook preview parameters for n6k packages. Each package's own
+ * `.storybook/preview.tsx` spreads these and adds its own theme CSS import.
+ */
+export const previewParameters: NonNullable<Preview["parameters"]> = {
+  controls: {
+    matchers: {
+      color: /(background|color)$/i,
+      date: /Date$/i,
+    },
+  },
+  a11y: {
+    test: "todo",
+  },
+};

package/src/storybook/seed-demo-data.ts

@@ -0,0 +1,206 @@
+// Seeds an in-memory DuckDB catalog named `page_db` with three demo tables.
+// Used by Storybook stories so DataBlockSourcePicker finds tables under the
+// same catalog name the production code uses.
+//
+// Tables created in page_db.main:
+//   - users   (25 rows)
+//   - orders  (80 rows)
+//   - events  (150 rows)
+//   - notes   (2 rows; sequence-default PK + a defaulted `label`)
+//
+// Idempotent: safe to call multiple times in the same connection.
+
+type Conn = {
+  query: (sql: string) => Promise<unknown>;
+};
+
+const USER_NAMES: string[] = [
+  "Alice Johnson",
+  "Bob Smith",
+  "Charlie Brown",
+  "Diana Prince",
+  "Eve Davis",
+  "Frank Miller",
+  "Grace Lee",
+  "Hank Wilson",
+  "Ivy Chen",
+  "Jack Taylor",
+  "Kate Adams",
+  "Liam Garcia",
+  "Maya Patel",
+  "Noah Kim",
+  "Olivia Wong",
+  "Peter Singh",
+  "Quinn Murphy",
+  "Rita Lopez",
+  "Sam Cohen",
+  "Tara Reyes",
+  "Uma Khan",
+  "Victor Park",
+  "Wendy Cruz",
+  "Xander Yu",
+  "Yara Hassan",
+];
+
+const COUNTRIES = ["US", "UK", "CA", "DE", "FR"];
+const ORDER_STATUSES = ["pending", "paid", "shipped", "cancelled"];
+const EVENT_NAMES = [
+  "page_view",
+  "click",
+  "signup",
+  "purchase",
+  "logout",
+  "search",
+];
+
+function sqlString(s: string): string {
+  return `'${s.replaceAll("'", "''")}'`;
+}
+
+function emailFor(name: string): string {
+  return name.toLowerCase().replaceAll(/\s+/g, ".") + "@example.com";
+}
+
+// Deterministic LCG so generated data is stable across runs.
+function rng(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (state * 1_664_525 + 1_013_904_223) >>> 0;
+    return state / 2 ** 32;
+  };
+}
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+
+function timestampAt(baseMs: number, offsetHours: number): string {
+  const d = new Date(baseMs + offsetHours * 3_600_000);
+  const yyyy = d.getUTCFullYear();
+  const mm = pad2(d.getUTCMonth() + 1);
+  const dd = pad2(d.getUTCDate());
+  const hh = pad2(d.getUTCHours());
+  const mi = pad2(d.getUTCMinutes());
+  const ss = pad2(d.getUTCSeconds());
+  return `${yyyy}-${mm}-${dd} ${hh}:${mi}:${ss}`;
+}
+
+function buildUsersInsert(): string {
+  const base = Date.UTC(2026, 0, 1, 9, 0, 0);
+  const rows = USER_NAMES.map((name, i) => {
+    const id = i + 1;
+    const email = emailFor(name);
+    const active = i % 3 !== 0;
+    const createdAt = timestampAt(base, i * 13);
+    return `(${id}, ${sqlString(name)}, ${sqlString(email)}, ${active ? "TRUE" : "FALSE"}, TIMESTAMP ${sqlString(createdAt)})`;
+  });
+  return `INSERT INTO page_db.main.users VALUES\n  ${rows.join(",\n  ")}`;
+}
+
+function buildOrdersInsert(): string {
+  const base = Date.UTC(2026, 0, 1, 0, 0, 0);
+  const r = rng(42);
+  const rows: string[] = [];
+  for (let i = 0; i < 80; i++) {
+    const id = i + 1;
+    const userId = Math.floor(r() * USER_NAMES.length) + 1;
+    const amount = (50 + Math.floor(r() * 95_000) / 100).toFixed(2);
+    const country = COUNTRIES[Math.floor(r() * COUNTRIES.length)];
+    const status = ORDER_STATUSES[Math.floor(r() * ORDER_STATUSES.length)];
+    const createdAt = timestampAt(base, i * 7);
+    rows.push(
+      `(${id}, ${userId}, ${amount}, ${sqlString(country!)}, ${sqlString(status!)}, TIMESTAMP ${sqlString(createdAt)})`,
+    );
+  }
+  return `INSERT INTO page_db.main.orders VALUES\n  ${rows.join(",\n  ")}`;
+}
+
+function buildEventsInsert(): string {
+  const base = Date.UTC(2026, 3, 1, 0, 0, 0);
+  const r = rng(7);
+  const rows: string[] = [];
+  for (let i = 0; i < 150; i++) {
+    const id = i + 1;
+    const userId = Math.floor(r() * USER_NAMES.length) + 1;
+    const name = EVENT_NAMES[Math.floor(r() * EVENT_NAMES.length)];
+    const ts = timestampAt(base, i * 3);
+    rows.push(
+      `(${id}, ${userId}, ${sqlString(name!)}, TIMESTAMP ${sqlString(ts)})`,
+    );
+  }
+  return `INSERT INTO page_db.main.events VALUES\n  ${rows.join(",\n  ")}`;
+}
+
+export async function seedDemoData(conn: Conn): Promise<void> {
+  // Catalog `page_db` is attached by the storybook decorator via useAttach so
+  // `useQuery({ catalogs: ['page_db'] })` proceeds. Don't re-attach here.
+
+  await conn.query(`DROP TABLE IF EXISTS page_db.main.notes`);
+  await conn.query(`DROP SEQUENCE IF EXISTS page_db.main.seq_notes_id`);
+  await conn.query(`DROP TABLE IF EXISTS page_db.main.events`);
+  await conn.query(`DROP TABLE IF EXISTS page_db.main.orders`);
+  await conn.query(`DROP TABLE IF EXISTS page_db.main.users`);
+  // Dropped after the tables that reference it.
+  await conn.query(`DROP TYPE IF EXISTS page_db.main.order_priority`);
+
+  await conn.query(`
+    CREATE TABLE page_db.main.users (
+      id INTEGER PRIMARY KEY,
+      name VARCHAR,
+      email VARCHAR,
+      active BOOLEAN,
+      created_at TIMESTAMP
+    )
+  `);
+  await conn.query(buildUsersInsert());
+
+  await conn.query(`
+    CREATE TABLE page_db.main.orders (
+      id INTEGER PRIMARY KEY,
+      user_id INTEGER,
+      amount DECIMAL(10,2),
+      country VARCHAR,
+      status VARCHAR,
+      created_at TIMESTAMP
+    )
+  `);
+  await conn.query(buildOrdersInsert());
+
+  // A Select-style column: an ENUM domain surfaced via meta.enumValues so the
+  // grid's enum cell editor (and the Select property type) have real data.
+  // Added after the INSERT so the value-less INSERT above stays valid.
+  await conn.query(
+    `CREATE TYPE page_db.main.order_priority AS ENUM ('low', 'med', 'high')`,
+  );
+  await conn.query(
+    `ALTER TABLE page_db.main.orders ADD COLUMN priority page_db.main.order_priority`,
+  );
+  await conn.query(
+    `UPDATE page_db.main.orders SET priority = 'high' WHERE id % 3 = 0`,
+  );
+
+  await conn.query(`
+    CREATE TABLE page_db.main.events (
+      id INTEGER PRIMARY KEY,
+      user_id INTEGER,
+      name VARCHAR,
+      ts TIMESTAMP
+    )
+  `);
+  await conn.query(buildEventsInsert());
+
+  // `notes` demonstrates database defaults: a sequence-backed primary key and a
+  // defaulted `label`, so a draft row committed with those cells left blank
+  // (omitted from the INSERT) is auto-filled by the catalog.
+  await conn.query(`CREATE SEQUENCE page_db.main.seq_notes_id START 1`);
+  await conn.query(`
+    CREATE TABLE page_db.main.notes (
+      id INTEGER PRIMARY KEY DEFAULT nextval('page_db.main.seq_notes_id'),
+      label VARCHAR DEFAULT 'Untitled',
+      done BOOLEAN DEFAULT false
+    )
+  `);
+  await conn.query(
+    `INSERT INTO page_db.main.notes (label, done) VALUES ('Buy milk', false), ('Ship release', true)`,
+  );
+}

package/src/storybook/story-shell.tsx

@@ -0,0 +1,21 @@
+import { useMemo, type ReactNode } from "react";
+import { DuckDBProvider } from "@n6k.io/db/react";
+import { N6K_DEFAULT_WORKER_URLS } from "@n6k.io/db/workers";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+/**
+ * The provider stack every n6k story needs: a fresh react-query client and a
+ * DuckDB-WASM context. Worker URLs come straight from the driver's canonical
+ * manifest (`N6K_DEFAULT_WORKER_URLS`) rather than being hardcoded, so they can
+ * never drift from what the `bundleN6kWorkers` Vite middleware actually serves.
+ */
+export function StoryShell({ children }: { children: ReactNode }) {
+  const queryClient = useMemo(() => new QueryClient(), []);
+  return (
+    <QueryClientProvider client={queryClient}>
+      <DuckDBProvider duckdbOptions={N6K_DEFAULT_WORKER_URLS}>
+        {children}
+      </DuckDBProvider>
+    </QueryClientProvider>
+  );
+}

package/src/templates/contents-mdx.hbs

@@ -0,0 +1,9 @@
+{{{wrapperImports}}}
+{{{layoutImports}}}
+import Content from '{{{mdxPath}}}'; export default function App() { return (
+{{{wrapperOpen}}}
+{{{layoutOpen}}}
+<Content />
+{{{layoutClose}}}
+{{{wrapperClose}}}
+); }

package/src/templates/entry.hbs

@@ -0,0 +1,4 @@
+import { createRoot, hydrateRoot } from 'react-dom/client'; import App from '{{{appModule}}}';
+const root = document.getElementById('root'); if (root.children.length > 0) {
+hydrateRoot(root,
+<App />); } else { createRoot(root).render(<App />); }

package/src/templates/page.hbs

@@ -0,0 +1,18 @@
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {{#if title}}<title>{{title}}</title>{{/if}}
+    {{#if description}}<meta
+        name="description"
+        content="{{description}}"
+      />{{/if}}
+    <link rel="stylesheet" href="{{assetPrefix}}/styles.css" />
+    {{{headTags}}}
+  </head>
+  <body>
+    <div id="root">{{{content}}}</div>
+    <script type="module" src="{{assetPrefix}}/{{slug}}.js"></script>
+    {{{scripts}}}
+  </body>
+</html>

package/src/util/logger.ts

@@ -0,0 +1,42 @@
+import pino from "pino";
+
+let logger = pino({ level: "silent" });
+
+export function initLogger(debug: boolean) {
+  if (debug) {
+    logger = pino({
+      level: "debug",
+      transport: { target: "pino-pretty" },
+    });
+  }
+}
+
+// pino does not expose its underlying stream in its public types, so narrow to
+// the one method we need (`end`) via a runtime type guard rather than a cast.
+function hasFlushableStream(
+  l: unknown,
+): l is { stream: { end: (cb: () => void) => void } } {
+  return (
+    typeof l === "object" &&
+    l !== null &&
+    "stream" in l &&
+    typeof l.stream === "object" &&
+    l.stream !== null &&
+    "end" in l.stream &&
+    typeof l.stream.end === "function"
+  );
+}
+
+export function flushLogger(): Promise<void> {
+  return new Promise((resolve) => {
+    logger.flush(() => {
+      if (hasFlushableStream(logger)) {
+        logger.stream.end(() => resolve());
+      } else {
+        resolve();
+      }
+    });
+  });
+}
+
+export { logger };

package/src/vite/cross-origin.ts

@@ -0,0 +1,19 @@
+import type { Plugin } from "vite";
+
+/**
+ * Vite plugin: set COOP/COEP response headers in dev so the page is
+ * cross-origin isolated — required for SharedArrayBuffer, which the n6k duckdb
+ * workers use to synchronize with the WASM instance.
+ */
+export function crossOriginIsolation(): Plugin {
+  return {
+    name: "cross-origin-isolation",
+    configureServer(server) {
+      server.middlewares.use((_req, res, next) => {
+        res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+        res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+        next();
+      });
+    },
+  };
+}

package/src/vite/index.ts

@@ -0,0 +1,6 @@
+// Vite-specific n6k build glue. Framework-agnostic cores live in
+// `../workers/manifest` and `../wasm/extensions`; these plugins wire them into
+// a Vite dev server / build.
+export { bundleN6kWorkers } from "./workers.ts";
+export { n6kWasmExtensions } from "./wasm.ts";
+export { crossOriginIsolation } from "./cross-origin.ts";

package/src/vite/wasm.ts

@@ -0,0 +1,67 @@
+import path from "node:path";
+import fs from "node:fs";
+import type { Plugin } from "vite";
+import { wasmDir } from "@n6k.io/db/wasm-dir";
+import { collectN6kWasmFiles, N6K_WASM_MIME } from "../wasm/extensions.ts";
+
+/**
+ * Vite plugin: serve n6k duckdb WASM extensions in dev AND emit them into the
+ * client bundle for prod. Without prod-emit, paths like
+ * `/v1.5.1/wasm_eh/n6k.duckdb_extension.wasm` 404 at runtime.
+ */
+export function n6kWasmExtensions(): Plugin {
+  const files = collectN6kWasmFiles(wasmDir);
+  if (files.length === 0) {
+    throw new Error(
+      [
+        "",
+        `[n6k] WASM extensions not found at ${wasmDir}`,
+        "[n6k] vite cannot start/build without them — DuckDB would fail at runtime with a cryptic 404 on /vX.Y.Z/wasm_*/n6k.duckdb_extension.wasm.",
+        "[n6k] Fix: build & copy the WASM extensions into the linked driver package:",
+        "[n6k]   cd ../duckdb-driver && make wasm_mvp wasm_threads wasm_eh npm_db_wasm",
+        "",
+      ].join("\n"),
+    );
+  }
+  const byUrl = new Map(files.map((f) => ["/" + f.rel, f.abs]));
+
+  return {
+    name: "n6k-wasm-extensions",
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const abs = byUrl.get(req.url ?? "");
+        if (!abs) {
+          if (
+            req.url &&
+            /^\/v[\d.]+\/wasm_(mvp|eh|threads)\/.+\.wasm$/.test(req.url)
+          ) {
+            console.error(
+              `[n6k] 404 wasm extension: ${req.url} — run \`make npm_db_wasm\` in duckdb-driver`,
+            );
+          }
+          next();
+          return;
+        }
+        const ext = path.extname(abs);
+        res.setHeader(
+          "Content-Type",
+          N6K_WASM_MIME[ext] ?? "application/octet-stream",
+        );
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Cross-Origin-Resource-Policy", "cross-origin");
+        fs.createReadStream(abs).pipe(res);
+      });
+    },
+    async generateBundle() {
+      // Only emit into the client bundle (large binaries; server bundle doesn't need them)
+      if (this.environment.name !== "client") return;
+      for (const f of files) {
+        this.emitFile({
+          type: "asset",
+          fileName: f.rel,
+          source: await fs.promises.readFile(f.abs),
+        });
+      }
+    },
+  };
+}

package/src/vite/workers.ts

@@ -0,0 +1,91 @@
+import type { Plugin } from "vite";
+import {
+  N6K_WORKER_ENTRIES,
+  N6K_WORKER_DEV_URLS,
+  N6K_WORKERS_VIRTUAL_ID,
+  N6K_WORKERS_RESOLVED_ID,
+  resolveN6kWorkerSource,
+  bundleN6kWorker,
+} from "../workers/manifest.ts";
+
+/**
+ * Vite plugin: serve the n6k workers from a single source of truth.
+ *
+ * The app imports its worker URLs from `virtual:n6k-workers` rather than
+ * hardcoding them, so this plugin owns the logical-name → real-URL mapping and
+ * returns the right value per mode:
+ *  - dev: stable `/_n6k/workers/*.js` paths, re-bundled per request (no-store)
+ *  - prod client build: content-hashed assets via Rollup's file-URL placeholder
+ *  - SSR build: the stable paths (workers never run there)
+ */
+export function bundleN6kWorkers(): Plugin {
+  let isBuild = false;
+  return {
+    name: "bundle-n6k-workers",
+    configResolved(c) {
+      isBuild = c.command === "build";
+    },
+    resolveId(id) {
+      if (id === N6K_WORKERS_VIRTUAL_ID) return N6K_WORKERS_RESOLVED_ID;
+    },
+    async load(id) {
+      if (id !== N6K_WORKERS_RESOLVED_ID) return;
+      // Prod client build: emit each worker as a content-hashed asset and point
+      // the export at Rollup's file-URL placeholder. Rollup rewrites it to the
+      // final hashed, base-prefixed URL — so the browser auto-busts when the
+      // worker source changes and can otherwise cache it immutably.
+      if (isBuild && this.environment?.name === "client") {
+        const lines: string[] = [];
+        for (const e of N6K_WORKER_ENTRIES) {
+          const code = await bundleN6kWorker(resolveN6kWorkerSource(e.src));
+          const ref = this.emitFile({
+            type: "asset",
+            name: e.file,
+            source: code,
+          });
+          lines.push(
+            `export const ${e.exportName} = import.meta.ROLLUP_FILE_URL_${ref};`,
+          );
+        }
+        return lines.join("\n");
+      }
+      // Dev (re-bundled per request by the middleware below) and the SSR build
+      // (workers never run there): the stable `/_n6k/workers/*.js` paths.
+      return N6K_WORKER_ENTRIES.map(
+        (e) =>
+          `export const ${e.exportName} = ${JSON.stringify(
+            `/_n6k/workers/${e.file}`,
+          )};`,
+      ).join("\n");
+    },
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => {
+        const pathname = (req.url ?? "").split("?", 1)[0];
+        const rel = N6K_WORKER_DEV_URLS[pathname];
+        if (!rel) {
+          next();
+          return;
+        }
+        const src = resolveN6kWorkerSource(rel);
+        bundleN6kWorker(src)
+          .then((code) => {
+            res.setHeader("Content-Type", "text/javascript");
+            // Re-bundled from source on every request with no content hash in
+            // the URL. `no-cache` (store-but-revalidate) is unreliable without a
+            // validator (no ETag is sent), so the browser can serve a stale
+            // worker after the source changes. `no-store` forbids storing it at
+            // all, so `new Worker(url)` always fetches the freshly-bundled code.
+            res.setHeader("Cache-Control", "no-store");
+            res.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+            res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+            res.end(code);
+          })
+          .catch((err: Error) => {
+            console.error(`[n6k] failed to bundle ${rel}:`, err);
+            res.statusCode = 500;
+            res.end(`/* n6k worker bundle error: ${err.message} */`);
+          });
+      });
+    },
+  };
+}

package/src/wasm/extensions.ts

@@ -0,0 +1,32 @@
+import path from "node:path";
+import fs from "node:fs";
+
+export const N6K_WASM_MIME: Record<string, string> = {
+  ".wasm": "application/wasm",
+  ".json": "application/json",
+  ".js": "text/javascript",
+};
+
+export interface N6kWasmFile {
+  /** Path relative to the wasm root, e.g. `v1.5.1/wasm_eh/n6k.duckdb_extension.wasm`. */
+  rel: string;
+  /** Absolute path on disk. */
+  abs: string;
+}
+
+/** Recursively collect every file under a wasm-extensions root directory. */
+export function collectN6kWasmFiles(root: string): N6kWasmFile[] {
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) return [];
+  const out: N6kWasmFile[] = [];
+  function walk(dir: string, prefix: string) {
+    for (const name of fs.readdirSync(dir)) {
+      const abs = path.join(dir, name);
+      const rel = prefix ? `${prefix}/${name}` : name;
+      const stat = fs.statSync(abs);
+      if (stat.isDirectory()) walk(abs, rel);
+      else if (stat.isFile()) out.push({ rel, abs });
+    }
+  }
+  walk(root, "");
+  return out;
+}