@jxsuite/import 0.40.0 → 0.40.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/import",
-  "version": "0.40.0",
+  "version": "0.40.1",
   "description": "Clone a live website into a Jx project",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,8 @@
     "./capture": "./src/capture.ts",
     "./to-jx": "./src/to-jx.ts",
     "./emit": "./src/emit.ts",
+    "./io": "./src/io.ts",
+    "./pipeline": "./src/pipeline.ts",
     "./run": "./src/run.ts",
     "./verify": "./src/verify.ts",
     "./breakpoint-plan": "./src/breakpoint-plan.ts"
@@ -33,8 +35,8 @@
     "import": "bun run src/cli.ts"
   },
   "dependencies": {
-    "@jxsuite/markup": "^0.4.8",
-    "@jxsuite/schema": "^2.0.0",
+    "@jxsuite/markup": "^0.4.9",
+    "@jxsuite/schema": "^2.1.0",
     "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
     "puppeteer-core": "^24.9.0"
@@ -44,6 +46,6 @@
     "happy-dom": "^20.10.6"
   },
   "optionalDependencies": {
-    "@jxsuite/compiler": "^3.0.0"
+    "@jxsuite/compiler": "^3.1.0"
   }
 }

package/src/ai-componentize.ts

@@ -15,7 +15,17 @@ import type { ExtractedComponent, ComponentizeResult } from "./componentize.ts";
 export interface AiComponentizeOptions {
   apiKey: string;
   baseUrl?: string | undefined;
-  model?: string | undefined;
+  /**
+   * The model id, and it has no default on purpose.
+   *
+   * `"gpt-4o-mini"` used to be one, which was harmless while the only caller was the OSS CLI
+   * pointing at OpenAI and wrong the moment a backend brokered anything else: Workers AI answers a
+   * model it does not know with a 404, `callLlm` reads that as "the LLM failed", and every
+   * component silently keeps its heuristic `component-div-0` name. A required id makes the caller
+   * that knows which provider it is talking to say so. The CLI and the OSS server still default to
+   * `gpt-4o-mini` — at their own call site, in `run.ts`.
+   */
+  model: string;
 }
 
 interface RenameResult {
@@ -58,7 +68,7 @@ Respond with ONLY the JSON object, no markdown fences or explanation.`;
 
 async function callLlm(prompt: string, opts: AiComponentizeOptions): Promise<RenameResult | null> {
   const baseUrl = opts.baseUrl || "https://api.openai.com/v1";
-  const model = opts.model || "gpt-4o-mini";
+  const { model } = opts;
 
   const response = await fetch(`${baseUrl}/chat/completions`, {
     method: "POST",

package/src/asset-collect.ts

@@ -5,7 +5,7 @@
  * SVGs are kept as-is (no download needed). Returns absolute URLs for downloading.
  */
 
-import type { Page } from "puppeteer-core";
+import type { ImportPage } from "./capture.ts";
 import { SRCSET_SEPARATOR } from "./srcset.ts";
 
 export interface DiscoveredAsset {
@@ -46,7 +46,7 @@ export interface AssetCollectionResult {
  * Collect all asset URLs from the live page DOM and stylesheets. Runs entirely in-browser via
  * page.evaluate() — no per-element round-trips.
  */
-export async function collectAssets(page: Page): Promise<AssetCollectionResult> {
+export async function collectAssets(page: ImportPage): Promise<AssetCollectionResult> {
   /*
    * The separator crosses into the page as a SOURCE STRING: an evaluated body is serialised and
    * re-parsed in the browser, so it cannot close over a value declared out here.

package/src/asset-download.ts

@@ -5,9 +5,9 @@
  * subdirectories by type: images/, fonts/, icons/.
  */
 
-import { join, extname } from "node:path";
-import { mkdir } from "node:fs/promises";
+import { extname } from "node:path";
 import type { DiscoveredAsset } from "./asset-collect.ts";
+import type { ImportIo } from "./io.ts";
 
 export interface DownloadResult {
   /**
@@ -127,7 +127,7 @@ function isBlocked(url: string): boolean {
 
 export async function downloadAssets(
   assets: DiscoveredAsset[],
-  outDir: string,
+  io: ImportIo,
   sourceUrl?: string,
 ): Promise<DownloadResult> {
   const rewriteMap = new Map<string, string>();
@@ -143,12 +143,11 @@ export async function downloadAssets(
     }
   }
 
-  // Create subdirectories
-  const assetsDir = join(outDir, "public", "assets");
-  await mkdir(join(assetsDir, "images"), { recursive: true });
-  await mkdir(join(assetsDir, "fonts"), { recursive: true });
-  await mkdir(join(assetsDir, "icons"), { recursive: true });
-  await mkdir(join(assetsDir, "other"), { recursive: true });
+  // Create subdirectories (a sink with no directories declines — see ImportIo.mkdir)
+  const assetsDir = "public/assets";
+  for (const subdir of ["images", "fonts", "icons", "other"]) {
+    await io.mkdir?.(`${assetsDir}/${subdir}`);
+  }
 
   // Track filenames to avoid collisions
   const usedNames = new Map<string, number>();
@@ -172,7 +171,7 @@ export async function downloadAssets(
     }
     usedNames.set(nameKey, count + 1);
 
-    const destPath = join(assetsDir, subdir, filename);
+    const destPath = `${assetsDir}/${subdir}/${filename}`;
     // The site-absolute path the built asset is served from. `public/` is the compiler's static
     // ROOT — its contents land at dist/<path>, so the "public/" segment must not survive into a
     // Reference, and the leading slash must be there or a reference from /components/x.js or a
@@ -195,7 +194,7 @@ export async function downloadAssets(
 
       const buffer = await response.arrayBuffer();
       totalBytes += buffer.byteLength;
-      await Bun.write(destPath, buffer);
+      await io.write(destPath, new Uint8Array(buffer));
       rewriteMap.set(url, relativePath);
     } catch {
       failed.push(url);

package/src/browser-local.ts

@@ -0,0 +1,67 @@
+/**
+ * Launching a real Chrome on this machine — the one module in the import that loads
+ * `puppeteer-core` as a VALUE.
+ *
+ * It is separate from `capture.ts` for a bundling reason rather than a tidiness one.
+ * `puppeteer-core` cannot run in workerd at all (it reaches for `child_process`, `net` and a binary
+ * on disk), and a Worker bundler follows value imports transitively — so a single `import { launch
+ * }` anywhere in `pipeline.ts`'s graph would pull the whole of it in and fail the deploy. Keeping
+ * the launch here, and having every phase take a browser it was HANDED, is what lets Jx Cloud run
+ * the same pipeline against a `@cloudflare/puppeteer` session.
+ */
+
+import { launch } from "puppeteer-core";
+import type { Browser } from "puppeteer-core";
+
+const DEFAULT_CHROME_PATHS = [
+  "google-chrome-stable",
+  "google-chrome",
+  "chromium-browser",
+  "chromium",
+];
+
+function findChrome(executablePath?: string): string {
+  if (executablePath) {
+    return executablePath;
+  }
+  const env = process.env.CHROME_PATH;
+  if (env) {
+    return env;
+  }
+
+  for (const name of DEFAULT_CHROME_PATHS) {
+    const path = Bun.which(name);
+    if (path) {
+      return path;
+    }
+  }
+  throw new Error(
+    "Could not find Chrome/Chromium. Set CHROME_PATH or install google-chrome-stable.",
+  );
+}
+
+let _browser: Browser | null = null;
+
+export interface LaunchOptions {
+  /** Explicit browser binary. Wins over CHROME_PATH and PATH discovery. */
+  executablePath?: string;
+}
+
+export async function launchBrowser(options?: LaunchOptions): Promise<Browser> {
+  if (_browser?.connected) {
+    return _browser;
+  }
+  _browser = await launch({
+    executablePath: findChrome(options?.executablePath),
+    headless: true,
+    args: ["--no-sandbox", "--disable-gpu"],
+  });
+  return _browser;
+}
+
+export async function closeBrowser(): Promise<void> {
+  if (_browser?.connected) {
+    await _browser.close();
+    _browser = null;
+  }
+}

package/src/capture.ts

@@ -1,5 +1,44 @@
-import { launch } from "puppeteer-core";
-import type { Browser, Page } from "puppeteer-core";
+/**
+ * Page capture, and the browser surface the whole import is written against.
+ *
+ * That surface is declared STRUCTURALLY here rather than imported from `puppeteer-core`, and the
+ * reason is bundling, not taste: `puppeteer-core` is unloadable in workerd, and a Worker bundler
+ * follows value imports transitively, so a single one anywhere in `pipeline.ts`'s graph would fail
+ * the deploy. Naming only `newPage` — and, on a page, the five calls the phases actually make —
+ * lets the same code drive a local Chrome (`browser-local.ts`) or a `@cloudflare/puppeteer`
+ * session, both of which provide exactly this and more.
+ */
+
+/**
+ * What `evaluate` hands the in-page function.
+ *
+ * A homomorphic mapped type rather than plain `Params`, because puppeteer's own `evaluate` declares
+ * its parameters through one (it unwraps `JSHandle`s there). Two generic signatures only relate
+ * when they are shaped alike, and with a bare tuple puppeteer's `Page` stops being assignable to
+ * `ImportPage` — which is the one thing this interface has to be true of.
+ */
+export type PageArgs<Params extends unknown[]> = { [K in keyof Params]: Params[K] };
+
+export interface ImportPage {
+  goto: (
+    url: string,
+    options?: {
+      waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+      timeout?: number;
+    },
+  ) => Promise<unknown>;
+  setViewport: (viewport: { width: number; height: number }) => Promise<unknown>;
+  evaluate: <Params extends unknown[], R>(
+    fn: (...params: PageArgs<Params>) => R,
+    ...args: Params
+  ) => Promise<Awaited<R>>;
+  screenshot: (options?: { fullPage?: boolean; type?: "png" }) => Promise<Uint8Array>;
+  close: () => Promise<unknown>;
+}
+
+export interface ImportBrowser {
+  newPage: () => Promise<ImportPage>;
+}
 
 export interface CaptureResult {
   url: string;
@@ -7,61 +46,8 @@ export interface CaptureResult {
   bodyHtml: string;
   /** Discovered same-origin links for the crawler (Phase 3). */
   links: string[];
-  /** The puppeteer Page, kept open for style capture (Phase 1). Caller must close. */
-  page: Page;
-}
-
-const DEFAULT_CHROME_PATHS = [
-  "google-chrome-stable",
-  "google-chrome",
-  "chromium-browser",
-  "chromium",
-];
-
-function findChrome(executablePath?: string): string {
-  if (executablePath) {
-    return executablePath;
-  }
-  const env = process.env.CHROME_PATH;
-  if (env) {
-    return env;
-  }
-
-  for (const name of DEFAULT_CHROME_PATHS) {
-    const path = Bun.which(name);
-    if (path) {
-      return path;
-    }
-  }
-  throw new Error(
-    "Could not find Chrome/Chromium. Set CHROME_PATH or install google-chrome-stable.",
-  );
-}
-
-let _browser: Browser | null = null;
-
-export interface LaunchOptions {
-  /** Explicit browser binary. Wins over CHROME_PATH and PATH discovery. */
-  executablePath?: string;
-}
-
-export async function launchBrowser(options?: LaunchOptions): Promise<Browser> {
-  if (_browser?.connected) {
-    return _browser;
-  }
-  _browser = await launch({
-    executablePath: findChrome(options?.executablePath),
-    headless: true,
-    args: ["--no-sandbox", "--disable-gpu"],
-  });
-  return _browser;
-}
-
-export async function closeBrowser(): Promise<void> {
-  if (_browser?.connected) {
-    await _browser.close();
-    _browser = null;
-  }
+  /** The page, kept open for style capture (Phase 1). Caller must close. */
+  page: ImportPage;
 }
 
 export interface CaptureOptions {
@@ -73,7 +59,7 @@ export interface CaptureOptions {
  * Scroll the page to the bottom in steps to trigger lazy-loaded images and intersection-observer
  * content, then scroll back to top. Settles between steps to let content render.
  */
-async function scrollToRevealAll(page: Page): Promise<void> {
+async function scrollToRevealAll(page: ImportPage): Promise<void> {
   await page.evaluate(async () => {
     const delay = (ms: number) =>
       new Promise<void>((r) => {
@@ -111,15 +97,18 @@ async function scrollToRevealAll(page: Page): Promise<void> {
 /**
  * Capture a page's DOM. Returns the page object still open — the caller is responsible for closing
  * it (after style capture in Phase 1, or immediately).
+ *
+ * The browser is a parameter and has no default. It used to fall back to launching a local Chrome,
+ * and that fallback was the value import of `puppeteer-core` that kept this module — and everything
+ * that reaches it — out of a Worker.
  */
 export async function capturePage(
   url: string,
-  browser?: Browser,
+  browser: ImportBrowser,
   options?: CaptureOptions,
 ): Promise<CaptureResult> {
   const { scrollToBottom = true } = options ?? {};
-  const br = browser ?? (await launchBrowser());
-  const page: Page = await br.newPage();
+  const page = await browser.newPage();
   await page.setViewport({ width: 1440, height: 900 });
 
   await page.goto(url, { waitUntil: "networkidle0", timeout: 30_000 });

package/src/crawl.ts

@@ -1,5 +1,6 @@
-import { launchBrowser, capturePage } from "./capture.ts";
-import type { CaptureResult } from "./capture.ts";
+import { capturePage } from "./capture.ts";
+import type { CaptureResult, ImportBrowser } from "./capture.ts";
+import type { ImportIo } from "./io.ts";
 import { convertToJx } from "./to-jx.ts";
 import type { ToJxResult } from "./to-jx.ts";
 import { captureStyles } from "./style-capture.ts";
@@ -19,7 +20,10 @@ import { applyTokens } from "./css-tokens.ts";
 
 export interface CrawlOptions {
   url: string;
-  outDir: string;
+  /** The browser to capture with. The crawl never launches one — see `browser-local.ts`. */
+  browser: ImportBrowser;
+  /** Where downloaded assets go. */
+  io: ImportIo;
   maxDepth: number;
   maxPages: number;
   maxNodesPerPage: number;
@@ -52,8 +56,8 @@ export interface CrawledPage {
   jx: ToJxResult;
   depth: number;
   links: string[];
-  /** Reference screenshot PNG buffer, present when captureScreenshots is true. */
-  screenshot?: Buffer | undefined;
+  /** Reference screenshot PNG bytes, present when captureScreenshots is true. */
+  screenshot?: Uint8Array | undefined;
 }
 
 export interface CrawlResult {
@@ -187,7 +191,8 @@ function isDisallowed(url: string, disallowedPaths: Set<string>): boolean {
 export async function crawlSite(options: CrawlOptions): Promise<CrawlResult> {
   const {
     url,
-    outDir,
+    browser,
+    io,
     maxDepth,
     maxPages,
     maxNodesPerPage,
@@ -199,7 +204,6 @@ export async function crawlSite(options: CrawlOptions): Promise<CrawlResult> {
   } = options;
 
   const { origin } = new URL(url);
-  const browser = await launchBrowser();
 
   // Fetch robots.txt
   let disallowedPaths = new Set<string>();
@@ -261,11 +265,9 @@ export async function crawlSite(options: CrawlOptions): Promise<CrawlResult> {
         `  ⚠ Page exceeds node cap (${jx.nodeCount} > ${maxNodesPerPage}), skipping styles/assets`,
       );
       skippedByNodeCap.push(entry.url);
-      let screenshot: Buffer | undefined;
+      let screenshot: Uint8Array | undefined;
       if (options.captureScreenshots) {
-        screenshot = Buffer.from(
-          await capture.page.screenshot({ fullPage: fullPageScreenshots, type: "png" }),
-        );
+        screenshot = await capture.page.screenshot({ fullPage: fullPageScreenshots, type: "png" });
       }
       await capture.page.close();
 
@@ -363,7 +365,7 @@ export async function crawlSite(options: CrawlOptions): Promise<CrawlResult> {
         }
 
         if (collected.assets.length > 0) {
-          const downloaded = await downloadAssets(collected.assets, outDir, entry.url);
+          const downloaded = await downloadAssets(collected.assets, io, entry.url);
           if (downloaded.rewriteMap.size > 0) {
             rewriteAssetUrls(jx.document, downloaded.rewriteMap, entry.url);
             // Collect font rewrites (R2)
@@ -381,11 +383,9 @@ export async function crawlSite(options: CrawlOptions): Promise<CrawlResult> {
       }
     }
 
-    let screenshot: Buffer | undefined;
+    let screenshot: Uint8Array | undefined;
     if (options.captureScreenshots) {
-      screenshot = Buffer.from(
-        await capture.page.screenshot({ fullPage: fullPageScreenshots, type: "png" }),
-      );
+      screenshot = await capture.page.screenshot({ fullPage: fullPageScreenshots, type: "png" });
     }
     await capture.page.close();
 

package/src/emit.ts

@@ -1,9 +1,8 @@
-import { join, dirname } from "node:path";
-import { mkdir } from "node:fs/promises";
 import type { JxElement } from "@jxsuite/schema/types";
 import { componentize } from "./componentize.ts";
 import { stripClasses } from "./strip-classes.ts";
 import type { ComponentizeOptions, ComponentizeResult } from "./componentize.ts";
+import type { ImportIo } from "./io.ts";
 
 /**
  * The `$media` key the base width lives under — a number of CSS pixels, not a query.
@@ -21,14 +20,22 @@ function mediaKeyWidth(key: string): number {
 }
 
 export interface EmitResult {
-  /** Absolute paths of every file written. */
+  /** Project-relative, forward-slashed paths of every file written, in the order they were written. */
   files: string[];
   /** How many source-site class names were removed on the way out. */
   classesStripped: number;
+  /**
+   * The exact `project.json` text that was written.
+   *
+   * Returned rather than left to be read back, because a caller with no filesystem cannot read it
+   * back at all: Jx Cloud commits the emitted file set to git and needs the configuration to name
+   * the project, and re-deriving it here would be a second writer on the same bytes.
+   */
+  projectJson: string;
 }
 
 export interface EmitOptions {
-  outDir: string;
+  io: ImportIo;
   title: string;
   document: JxElement;
   sourceUrl: string;
@@ -41,7 +48,8 @@ export interface EmitOptions {
 }
 
 export interface MultiEmitOptions {
-  outDir: string;
+  /** Where the emitted files go. See `io.ts` — a disk is one implementation, not the requirement. */
+  io: ImportIo;
   title: string;
   sourceUrl: string;
   /** Map of route path (e.g. "pages/index.json") → Jx document. */
@@ -65,7 +73,7 @@ export interface MultiEmitOptions {
 }
 
 export async function emitProject({
-  outDir,
+  io,
   title,
   document,
   sourceUrl,
@@ -74,7 +82,7 @@ export async function emitProject({
   componentizeOptions,
 }: EmitOptions): Promise<EmitResult> {
   return emitMultiPageProject({
-    outDir,
+    io,
     title,
     sourceUrl,
     pages: new Map([["pages/index.json", document]]),
@@ -85,7 +93,7 @@ export async function emitProject({
 }
 
 export async function emitMultiPageProject({
-  outDir,
+  io,
   title,
   pages,
   layout,
@@ -97,10 +105,12 @@ export async function emitMultiPageProject({
   fontRewriteMap,
   styleTokens,
 }: MultiEmitOptions): Promise<EmitResult> {
-  await mkdir(join(outDir, "pages"), { recursive: true });
-  await mkdir(join(outDir, "layouts"), { recursive: true });
-  await mkdir(join(outDir, "components"), { recursive: true });
-  await mkdir(join(outDir, "public"), { recursive: true });
+  /* Seeded even when nothing lands in them, so a host that opened the project at the seed event
+     sees the shape it expects rather than a directory that grows one folder at a time. A sink with
+     no directories declines by not implementing it. */
+  for (const dir of ["pages", "layouts", "components", "public"]) {
+    await io.mkdir?.(dir);
+  }
 
   /*
    * Only keys the project schema declares (#228). `title` and `description` are page-level keys and
@@ -207,10 +217,8 @@ export async function emitMultiPageProject({
         fontCss = fontCss.replaceAll(pattern, (m) => byForm.get(m) ?? m);
       }
     }
-    const fontsDir = join(outDir, "public", "assets");
-    await mkdir(fontsDir, { recursive: true });
-    const fontsCssPath = join(fontsDir, "fonts.css");
-    await Bun.write(fontsCssPath, fontCss);
+    const fontsCssPath = "public/assets/fonts.css";
+    await io.write(fontsCssPath, fontCss);
     files.push(fontsCssPath);
 
     // Add fonts.css to project head
@@ -223,9 +231,9 @@ export async function emitMultiPageProject({
     });
   }
 
-  const projectPath = join(outDir, "project.json");
-  await Bun.write(projectPath, `${JSON.stringify(projectJson, null, 2)}\n`);
-  files.push(projectPath);
+  const projectText = `${JSON.stringify(projectJson, null, 2)}\n`;
+  await io.write("project.json", projectText);
+  files.push("project.json");
 
   /*
    * Classes go here, at the last possible moment, and that placement is the whole design.
@@ -245,8 +253,8 @@ export async function emitMultiPageProject({
 
   // Write components
   for (const [fileName, compDoc] of componentFiles) {
-    const compPath = join(outDir, "components", fileName);
-    await Bun.write(compPath, `${JSON.stringify(compDoc, null, 2)}\n`);
+    const compPath = `components/${fileName}`;
+    await io.write(compPath, `${JSON.stringify(compDoc, null, 2)}\n`);
     files.push(compPath);
   }
 
@@ -267,14 +275,12 @@ export async function emitMultiPageProject({
         ...((pageDoc.$elements as JxElement[]) ?? []),
       ] as JxElement[];
     }
-    const pagePath = join(outDir, route);
-    await mkdir(dirname(pagePath), { recursive: true });
-    await Bun.write(pagePath, `${JSON.stringify(pageDoc, null, 2)}\n`);
-    files.push(pagePath);
+    await io.write(route, `${JSON.stringify(pageDoc, null, 2)}\n`);
+    files.push(route);
   }
 
   // Write layout
-  const layoutPath = join(outDir, "layouts", "base.json");
+  const layoutPath = "layouts/base.json";
   const layoutDoc: JxElement = layout ?? {
     tagName: "div",
     children: [{ tagName: "slot" }],
@@ -286,10 +292,10 @@ export async function emitMultiPageProject({
     ];
   }
   classesStripped += stripClasses(layoutDoc);
-  await Bun.write(layoutPath, `${JSON.stringify(layoutDoc, null, 2)}\n`);
+  await io.write(layoutPath, `${JSON.stringify(layoutDoc, null, 2)}\n`);
   files.push(layoutPath);
 
-  return { classesStripped, files };
+  return { classesStripped, files, projectJson: projectText };
 }
 
 function extractStateDefaults(node: JxElement | string, out: Record<string, string>) {

package/src/index.ts

@@ -1,4 +1,7 @@
-export { capturePage, launchBrowser, closeBrowser } from "./capture.ts";
+export { capturePage } from "./capture.ts";
+export { launchBrowser, closeBrowser } from "./browser-local.ts";
+export { createLocalIo } from "./io.ts";
+export { runImportPipeline } from "./pipeline.ts";
 export { importSite } from "./run.ts";
 export { convertToJx } from "./to-jx.ts";
 export { emitProject, emitMultiPageProject } from "./emit.ts";
@@ -33,13 +36,16 @@ export {
   serveDirectory,
   routeToUrlPath,
 } from "./verify.ts";
-export type { CaptureResult, LaunchOptions } from "./capture.ts";
+export type { CaptureResult, ImportBrowser, ImportPage } from "./capture.ts";
+export type { LaunchOptions } from "./browser-local.ts";
+export type { ImportIo } from "./io.ts";
 export type {
-  ImportSiteOptions,
+  ImportPipelineOptions,
+  ImportPipelineResult,
   ImportProgressEvent,
   ImportPhase,
-  ImportSiteResult,
-} from "./run.ts";
+} from "./pipeline.ts";
+export type { ImportSiteOptions, ImportSiteResult } from "./run.ts";
 export type { ToJxResult } from "./to-jx.ts";
 export type { EmitOptions, EmitResult, MultiEmitOptions } from "./emit.ts";
 export type { CapturedStyle, StyleCaptureResult } from "./style-capture.ts";

package/src/io.ts

@@ -0,0 +1,52 @@
+/**
+ * The sink every file an import produces goes through.
+ *
+ * The pipeline used to call `Bun.write(join(outDir, …))` at six sites, which made "run an import"
+ * and "have a writable filesystem" the same requirement. Jx Cloud is a Cloudflare Worker: it has
+ * neither `Bun` nor a disk, and commits the emitted project straight to git. So the destination is
+ * a parameter now — `createLocalIo` is the disk implementation and the only one that imports
+ * `node:fs`, and a Worker supplies its own without the pipeline knowing the difference.
+ */
+
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export interface ImportIo {
+  /**
+   * Write one file.
+   *
+   * `relPath` is PROJECT-RELATIVE and forward-slashed — `"pages/blog/post.json"`, never an absolute
+   * path and never a backslash. A sink that has no filesystem uses it as a key verbatim; a sink
+   * that does joins it onto its own root.
+   */
+  write: (relPath: string, data: string | Uint8Array) => Promise<void>;
+  /**
+   * Create an empty directory, if directories are a thing this sink has.
+   *
+   * Optional because they usually are not: a git tree, an object store and a zip all record only
+   * the files, and an empty directory is unrepresentable in every one of them. The local import
+   * still seeds `pages/`, `layouts/`, `components/` and `public/` up front so a host can open the
+   * project the moment the run starts, which is what this exists for.
+   */
+  mkdir?: (relPath: string) => Promise<void>;
+}
+
+/** Split a project-relative path into segments, so a sink's own separator is the one used. */
+function toSegments(relPath: string): string[] {
+  return relPath.split("/").filter((segment) => segment !== "");
+}
+
+/** The disk sink: `outDir` plus the relative path, with parent directories created on demand. */
+export function createLocalIo(outDir: string): ImportIo {
+  const resolve = (relPath: string): string => join(outDir, ...toSegments(relPath));
+  return {
+    async write(relPath, data) {
+      const path = resolve(relPath);
+      await mkdir(dirname(path), { recursive: true });
+      await Bun.write(path, data);
+    },
+    async mkdir(relPath) {
+      await mkdir(resolve(relPath), { recursive: true });
+    },
+  };
+}