@uniweb/unipress 0.2.2

package/src/foundation-loader.js

@@ -0,0 +1,229 @@
+// Resolve a foundation reference to an absolute filesystem path.
+//
+// Returns a path string. Does NOT import or evaluate the foundation —
+// that's the orchestrator's job (M3b). This separation lets the resolver
+// be tested without going through React, and lets the orchestrator be
+// tested with a hand-supplied path.
+//
+// Five accepted ref forms:
+//
+//   1. URL ............ https://.../foundation.js  — downloaded + cached
+//   2. Local path ..... ./foo, ../foo, /abs/foo, ./foo/dist/foundation.js
+//   3. Registry ref ... @<namespace>/<name>@<version> — constructed into a
+//                       URL via the registry base (UNIWEB_REGISTRY_URL or
+//                       the production default), then resolved as URL
+//   4. Catalog id ..... academic-metrics, book, … — looked up in
+//                       foundations-data.js, then resolved as URL
+//   5. Package name ... my-foundation, @org/foo (no @version suffix)
+//
+// Resolution order for a bare name: registry-ref first (if it matches the
+// scoped @ns/name@ver pattern), then catalog, then package. The registry
+// ref is the authoritative form scaffolded documents pin — it works for
+// any user of the foundation regardless of whether they have the catalog
+// id resolved locally.
+//
+// The chosen entry for a package is its `exports['./dist']` map, NOT the
+// default `.` entry — the default points at source (_entry.generated.js)
+// and is only valid inside a Vite build. `dist/foundation.js` is the
+// built artifact (the federated module) that Node can import.
+
+import { existsSync, statSync, readFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { resolve, isAbsolute, join, dirname } from 'node:path'
+import { FoundationResolutionError } from './errors.js'
+import { findCatalogEntry } from './catalog.js'
+import { fetchFoundationToCache } from './foundation-fetch.js'
+
+const URL_PATTERN = /^https?:\/\//
+const PATH_PATTERN = /^(\.\.?[\/\\]|[\/\\]|[A-Za-z]:[\/\\])/
+// Registry ref: @<namespace>/<name>@<version>. Namespace + name follow npm's
+// scoped-package allowed character set (lowercase alphanumerics, _, -, .).
+// Version is anything semver-shaped — exact match isn't enforced here; the
+// registry decides what's valid.
+const REGISTRY_REF_PATTERN = /^@([a-z0-9][a-z0-9._-]*)\/([a-z0-9][a-z0-9._-]*)@([0-9a-z][0-9a-z.\-+]*)$/i
+const DEFAULT_REGISTRY_BASE = 'https://site-router.uniweb-edge.workers.dev'
+const DEFAULT_BUILT_ENTRY = 'dist/foundation.js'
+
+function getRegistryBase() {
+  const raw = process.env.UNIWEB_REGISTRY_URL || DEFAULT_REGISTRY_BASE
+  return raw.replace(/\/$/, '')
+}
+
+function buildRegistryUrl(namespace, name, version) {
+  return `${getRegistryBase()}/registry/packages/${namespace}/${name}/${version}/foundation.js`
+}
+
+export async function resolveFoundationRef(ref, { anchorDir, onProgress = () => {} } = {}) {
+  if (!ref || typeof ref !== 'string') {
+    throw new FoundationResolutionError(
+      `foundation ref is required (got ${ref === undefined ? 'undefined' : JSON.stringify(ref)})`
+    )
+  }
+
+  if (URL_PATTERN.test(ref)) {
+    return resolveUrlRef(ref, { onProgress })
+  }
+
+  if (PATH_PATTERN.test(ref)) {
+    return resolvePathRef(ref, anchorDir)
+  }
+
+  const registryMatch = ref.match(REGISTRY_REF_PATTERN)
+  if (registryMatch) {
+    return resolveRegistryRef(ref, registryMatch, { onProgress })
+  }
+
+  const catalogEntry = findCatalogEntry(ref)
+  if (catalogEntry) {
+    return resolveCatalogRef(ref, catalogEntry, { onProgress })
+  }
+
+  return resolvePackageRef(ref, anchorDir)
+}
+
+async function resolveRegistryRef(ref, match, { onProgress }) {
+  const [, namespace, name, version] = match
+  const url = buildRegistryUrl(namespace, name, version)
+  const resolvedPath = await fetchFoundationToCache(url, { onProgress })
+  return { ref, source: 'registry', resolvedPath, registryUrl: url }
+}
+
+async function resolveUrlRef(url, { onProgress }) {
+  const resolvedPath = await fetchFoundationToCache(url, { onProgress })
+  return { ref: url, source: 'url', resolvedPath }
+}
+
+async function resolveCatalogRef(id, entry, { onProgress }) {
+  // Prefer the registry ref under the new shape (entry.foundation.ref);
+  // fall back to legacy shape (entry.source.url) for any entries still
+  // on the v0.1 layout.
+  const ref = entry?.foundation?.ref
+  if (ref) {
+    const m = ref.match(REGISTRY_REF_PATTERN)
+    if (m) {
+      const result = await resolveRegistryRef(ref, m, { onProgress })
+      return { ...result, ref: id, source: 'catalog', catalogEntry: entry }
+    }
+  }
+  const url = entry?.foundation?.source?.url ?? entry?.source?.url
+  if (!url) {
+    throw new FoundationResolutionError(
+      `catalog entry '${id}' has no foundation.ref or source.url\n` +
+      `hint: pass --foundation <path-or-url> to bypass the catalog`
+    )
+  }
+  const resolvedPath = await fetchFoundationToCache(url, { onProgress })
+  return { ref: id, source: 'catalog', resolvedPath, catalogEntry: entry }
+}
+
+function resolvePathRef(ref, anchorDir) {
+  if (!anchorDir) {
+    throw new FoundationResolutionError(
+      `cannot resolve relative foundation path '${ref}' without an anchor directory`
+    )
+  }
+
+  const absolute = isAbsolute(ref) ? ref : resolve(anchorDir, ref)
+
+  if (!existsSync(absolute)) {
+    throw new FoundationResolutionError(
+      `foundation path does not exist: ${absolute}\n` +
+      `hint: did you build the foundation? (pnpm --filter <foundation> build)`
+    )
+  }
+
+  const stat = statSync(absolute)
+  const file = stat.isDirectory() ? join(absolute, DEFAULT_BUILT_ENTRY) : absolute
+
+  if (!existsSync(file)) {
+    throw new FoundationResolutionError(
+      `expected built foundation at ${file}\n` +
+      `hint: did you build the foundation? (pnpm --filter <foundation> build)`
+    )
+  }
+
+  return { ref, source: 'path', resolvedPath: file }
+}
+
+async function resolvePackageRef(name, anchorDir) {
+  if (!anchorDir) {
+    throw new FoundationResolutionError(
+      `cannot resolve foundation package '${name}' without an anchor directory`
+    )
+  }
+
+  // Walk up from anchorDir looking for node_modules/<name>/. Bypasses
+  // Node's exports-map enforcement (which blocks `<pkg>/package.json`
+  // access unless the package explicitly whitelists it). pnpm's hoisting
+  // and workspace symlinks land where this expects.
+  const pkgRoot = findPackageDir(name, anchorDir)
+  if (!pkgRoot) {
+    throw new FoundationResolutionError(
+      `cannot find foundation package '${name}' from ${anchorDir}\n` +
+      `hint: is the package installed? (pnpm install / pnpm add ${name})\n` +
+      `hint: if it's not on npm, pass a local path: --foundation ../path/to/foundation`
+    )
+  }
+
+  const pkgJsonPath = join(pkgRoot, 'package.json')
+  const pkg = existsSync(pkgJsonPath)
+    ? JSON.parse(await readFile(pkgJsonPath, 'utf8'))
+    : null
+
+  // Prefer the explicit `./dist` exports subpath if declared; otherwise
+  // fall back to the convention `dist/foundation.js`.
+  const distExport = pickBuiltEntry(pkg?.exports)
+  const file = distExport
+    ? resolve(pkgRoot, distExport)
+    : join(pkgRoot, DEFAULT_BUILT_ENTRY)
+
+  if (!existsSync(file)) {
+    const cause = distExport
+      ? `package '${name}' declares exports['./dist'] = '${distExport}' but file is missing`
+      : `package '${name}' has no exports['./dist'] entry, and ${DEFAULT_BUILT_ENTRY} is missing`
+    throw new FoundationResolutionError(
+      `${cause}\n` +
+      `hint: build the foundation (pnpm --filter ${name} build)`
+    )
+  }
+
+  return { ref: name, source: 'package', resolvedPath: file, packageRoot: pkgRoot, packageVersion: pkg?.version }
+}
+
+function findPackageDir(name, fromDir) {
+  let dir = fromDir
+  while (true) {
+    const candidate = join(dir, 'node_modules', name)
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+// A foundation's `exports['./dist']` entry points at the built `foundation.js`.
+// The value can be a string or a conditional-exports object; we accept both.
+function pickBuiltEntry(exports) {
+  if (!exports || typeof exports !== 'object') return null
+  const dist = exports['./dist']
+  if (!dist) return null
+  if (typeof dist === 'string') return dist
+  if (typeof dist === 'object') {
+    return dist.default || dist.import || dist.node || null
+  }
+  return null
+}
+
+// Resolve the foundation ref for a unipress run. CLI flag overrides
+// `document.yml`'s `foundation:` field; otherwise we use what the
+// content config declares.
+export async function resolveFoundation({ cliRef, configRef, anchorDir, onProgress = () => {} }) {
+  const ref = cliRef ?? configRef
+  if (!ref) {
+    throw new FoundationResolutionError(
+      `no foundation specified\n` +
+      `hint: set 'foundation:' in document.yml, or pass --foundation <ref>`
+    )
+  }
+  return resolveFoundationRef(ref, { anchorDir, onProgress })
+}

package/src/foundations-data.js

@@ -0,0 +1,122 @@
+/**
+ * unipress template catalog.
+ *
+ * Each entry is one starter pattern users pick at `unipress create` time.
+ * A template pins a foundation (the runtime artifact unipress loads at
+ * compile) and ships starter content that exercises that foundation.
+ *
+ * Multiple templates can pin the same foundation — `book`, `monograph`,
+ * and `report` all use `@uniweb/book` with different starter content,
+ * different `book.structure:` defaults, and different sample chapters.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * Resolution path
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * `unipress create my-doc --template book`:
+ *   1. catalog lookup (this file) → entry.foundation.ref + entry.scaffold.
+ *   2. scaffold copies templates-data.js[entry.scaffold] into my-doc/. The
+ *      bundled document.yml has `foundation: <entry.foundation.ref>` (the
+ *      registry-ref form, e.g., '@uniweb/book@0.1.0' — rewritten from the
+ *      committed dev path-ref by scripts/generate-templates-data.js).
+ *
+ * `unipress compile my-doc`:
+ *   1. document.yml `foundation: '@uniweb/book@0.1.0'` is parsed as a
+ *      registry ref by foundation-loader.js.
+ *   2. The loader constructs a URL from the registry base
+ *      (UNIWEB_REGISTRY_URL or the production default at
+ *      site-router.uniweb-edge.workers.dev) → fetches + caches.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * source.url
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * Each entry's `foundation.source.url` is the human-meaningful "where this
+ * foundation lives" pointer shown in `list-templates` output and post-create
+ * messages. It does NOT drive resolution under the registry-ref-in-document.yml
+ * model — foundation-loader builds its own URL from the ref + base. The
+ * URL is included for transparency.
+ *
+ * v0.2 entries pin local-registry URLs (http://localhost:4001/...) so
+ * foundation devs running `uniweb publish --local` can verify resolution
+ * end-to-end. TF8 of the unipress-foundations-and-templates plan switches
+ * these to the production registry once the foundations publish there.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * Storage format
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * Stored as a plain JS module (not YAML) so `bun build --compile` can
+ * inline it at bundle time. The compiled binary has no filesystem for
+ * runtime reads.
+ */
+
+const LOCAL_REGISTRY_BASE = 'http://localhost:4001/registry/packages'
+
+function localUrl(namespace, name, version) {
+  return `${LOCAL_REGISTRY_BASE}/${namespace}/${name}/${version}/foundation.js`
+}
+
+const BOOK_FOUNDATION = {
+  ref: '@uniweb/book@0.1.0',
+  source: { url: localUrl('uniweb', 'book', '0.1.0') },
+}
+
+const DATA_FOUNDATION = {
+  ref: '@uniweb/data@0.1.0',
+  source: { url: localUrl('uniweb', 'data', '0.1.0') },
+}
+
+export const FOUNDATIONS = [
+  {
+    id: 'book',
+    name: 'Book',
+    description:
+      'Long-form prose with chapters. Title page, copyright, TOC, ' +
+      'and trade-6x9 trim by default. Compiles to PDF (Typst), Typst ' +
+      'source bundle, Paged.js HTML, or EPUB.',
+    outputs: ['pdf', 'typst', 'pagedjs', 'epub'],
+    foundation: BOOK_FOUNDATION,
+    scaffold: 'book',
+  },
+  {
+    id: 'monograph',
+    name: 'Monograph',
+    description:
+      'Scholarly long-form work. Same foundation as `book` with ' +
+      'footnote-heavy starter content and academic-typography defaults.',
+    outputs: ['pdf', 'typst', 'pagedjs', 'epub'],
+    foundation: BOOK_FOUNDATION,
+    scaffold: 'monograph',
+  },
+  {
+    id: 'report',
+    name: 'Report',
+    description:
+      'Long-form report with mixed prose and tables. Same foundation as ' +
+      '`book`, configured for technical writing rather than narrative.',
+    outputs: ['pdf', 'typst', 'pagedjs', 'epub'],
+    foundation: BOOK_FOUNDATION,
+    scaffold: 'report',
+  },
+  {
+    id: 'data-report',
+    name: 'Data Report',
+    description:
+      'Aggregate metrics across a set of records — publications, funding, ' +
+      'supervisions. Emits both a downloadable Excel workbook and a Word report.',
+    outputs: ['xlsx', 'docx'],
+    foundation: DATA_FOUNDATION,
+    scaffold: 'data-report',
+  },
+  {
+    id: 'directory',
+    name: 'Directory',
+    description:
+      'Listing of records (people, organizations, items) with filterable ' +
+      'fields and a queryable surface. Emits Excel + Word output.',
+    outputs: ['xlsx', 'docx'],
+    foundation: DATA_FOUNDATION,
+    scaffold: 'directory',
+  },
+]

package/src/index.js

@@ -0,0 +1,8 @@
+// Public programmatic surface for `unipress`.
+//
+// v0 is CLI-first. This file exists so `import '@uniweb/unipress'` doesn't fail and
+// so future API exports (defineUnipressConfig, etc.) have a stable home.
+
+export function defineUnipressConfig(config) {
+  return config
+}

package/src/orchestrator.js

@@ -0,0 +1,150 @@
+// Import a built foundation and wire it to a content object.
+//
+// `initPrerender` from @uniweb/runtime/ssr does the actual work: it builds
+// the Website graph (Pages, Blocks), installs the SSR childBlockRenderer,
+// installs SSR-safe routing shims, and propagates base path. We hand it
+// the loaded foundation module and the content object; we get back a
+// configured `uniweb` instance whose `activeWebsite` is fully populated.
+//
+// Compile-time dispatch goes through `foundation.compileDocument` (and its
+// lower-level sibling `compileSubtree`) — re-exports the foundation's build
+// adds when the foundation itself imports @uniweb/press. This keeps Press a
+// single instance: the foundation has its own bundled copy, and unipress
+// reaches it via the foundation rather than importing its own (which would
+// create a dual-React-context trap that drops every registration).
+//
+// compileDocument is the high-level "compile this website through this
+// foundation" entry point — it looks up `foundation.outputs[format]`,
+// calls the foundation's getOptions to assemble adapter options, and
+// dispatches. unipress hands it the Website + format + host hints;
+// compileDocument does the rest.
+//
+// React-instance note (gotcha #2): @uniweb/runtime/ssr (built bundle) imports
+// React as an external; the foundation does the same. Both must resolve to the
+// same React instance, otherwise hooks in foundation components throw "Invalid
+// hook call". Inside this monorepo react is hoisted; in a real npm install of
+// unipress, both also resolve from unipress's node_modules.
+
+import { pathToFileURL } from 'node:url'
+import { readFile } from 'node:fs/promises'
+import { initPrerender } from '@uniweb/runtime/ssr'
+import { FoundationResolutionError, CompileError } from './errors.js'
+
+export async function importFoundation(resolvedPath) {
+  try {
+    return await import(pathToFileURL(resolvedPath).href)
+  } catch (err) {
+    throw new FoundationResolutionError(
+      `failed to import foundation at ${resolvedPath}\n` +
+      `cause: ${err.message}\n` +
+      `hint: confirm the foundation was built with @uniweb/build (dist/foundation.js)`
+    )
+  }
+}
+
+export function initOrchestrator({ content, foundation, extensions = [], onProgress } = {}) {
+  return initPrerender(content, foundation, extensions, { onProgress })
+}
+
+// Convenience: import + init in one step. Returns the uniweb instance,
+// or throws (the caller decides whether to surface as fatal or attached
+// to the inspect dump).
+export async function loadAndInit({ content, resolvedPath, extensions = [], onProgress } = {}) {
+  const foundation = await importFoundation(resolvedPath)
+  const uniweb = initOrchestrator({ content, foundation, extensions, onProgress })
+  return { foundation, uniweb }
+}
+
+// Node-side loadAsset for the foundation's compile pipeline.
+//
+// Press's compileDocument threads a `loadAsset(src)` helper into each
+// foundation's getOptions. In a browser host it defaults to fetch; in
+// unipress (Node) we supply an fs-based implementation so config-level
+// assets (cover images, banners, logos in document.yml) load without
+// the foundation needing to branch on environment.
+//
+// Lookup order:
+//   1. data: URL → decode in place.
+//   2. Asset manifest hit (`website.assets[src]`) — the resolved entry
+//      carries an absolute filesystem path the framework's content
+//      collector populated. Read bytes via fs.
+//   3. Absolute filesystem path on disk → read directly.
+//   4. Otherwise: fail loudly. We don't fall back to fetch because
+//      unipress runs offline-by-default and a missing manifest entry
+//      almost always means a misspelled path in document.yml.
+function createNodeLoadAsset(website) {
+  return async function loadAsset(src) {
+    if (!src || typeof src !== 'string') return null
+
+    if (src.startsWith('data:')) {
+      const comma = src.indexOf(',')
+      if (comma === -1) return null
+      const meta = src.slice(5, comma)
+      const data = src.slice(comma + 1)
+      if (meta.includes(';base64')) {
+        const bin = Buffer.from(data, 'base64')
+        return new Uint8Array(bin.buffer, bin.byteOffset, bin.byteLength)
+      }
+      return new TextEncoder().encode(decodeURIComponent(data))
+    }
+
+    const entry = website?.assets?.[src]
+    const path = entry?.resolved || (src.startsWith('/') ? src : null)
+    if (!path) {
+      throw new CompileError(
+        `loadAsset: cannot resolve '${src}' in Node compile context\n` +
+        `hint: config-level asset paths must be discoverable by the framework's ` +
+        `content collector. Confirm the file exists relative to the document directory ` +
+        `(e.g. assets/${src.split('/').pop()}) and that document.yml references it ` +
+        `using the same path.`
+      )
+    }
+
+    try {
+      const buf = await readFile(path)
+      return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
+    } catch (err) {
+      throw new CompileError(
+        `loadAsset: failed to read '${src}' from ${path}\n` +
+        `cause: ${err.message}`
+      )
+    }
+  }
+}
+
+// Compile a populated Website into a Blob, using the foundation's
+// bundled Press via the host-shareable compileDocument re-export.
+// Throws CompileError if compileDocument isn't present — that means
+// the foundation either doesn't depend on @uniweb/press, or was built
+// with a pre-M8a @uniweb/build that only re-exported compileSubtree.
+export async function compileDocumentWithFoundation(foundation, website, options = {}) {
+  if (typeof foundation?.compileDocument !== 'function') {
+    throw new CompileError(
+      `foundation does not expose compileDocument — cannot compile to '${options.format}'\n` +
+      `hint: foundation must import @uniweb/press and be rebuilt with a current @uniweb/build ` +
+      `(@uniweb/build@57498ef or later re-exports compileDocument alongside compileSubtree)`
+    )
+  }
+  try {
+    const loadAsset = createNodeLoadAsset(website)
+    return await foundation.compileDocument(website, { ...options, foundation, loadAsset })
+  } catch (err) {
+    // Wrap Press's errors in CompileError so the CLI's top-level handler
+    // surfaces them with consistent formatting.
+    if (err instanceof CompileError) throw err
+    throw new CompileError(err.message || String(err))
+  }
+}
+
+// Read the foundation's outputs declaration from either the built or
+// source shape. Used by compile.js for pre-compile validation and for
+// reading the default extension per format.
+export function getFoundationOutputs(foundation) {
+  if (!foundation) return null
+  return (
+    foundation.default?.capabilities?.outputs ??
+    foundation.default?.outputs ??
+    foundation.outputs ??
+    null
+  )
+}

package/src/scaffold.js

@@ -0,0 +1,66 @@
+// Scaffold a content directory from a unipress template.
+//
+// Templates live on disk under `framework/unipress/documents/<name>/` and
+// are embedded into the bundle via `src/templates-data.js` (generated by
+// scripts/generate-templates-data.js). This module reads from the embedded
+// map — so scaffolding works identically in Node dev and inside the
+// bun-compiled binary (which has no access to the documents/ path).
+//
+// File entries come in two shapes:
+//   - text files: a plain string. Files with a `.hbs` suffix get
+//     Handlebars-processed (and the suffix stripped); other text files
+//     are copied verbatim.
+//   - binary files (PNG, PDF, fonts, archives, etc.): an object
+//     `{ encoding: 'base64', content: <base64> }`. The generator detects
+//     these by extension. Scaffold decodes and writes the bytes verbatim;
+//     no Handlebars pass.
+//
+// No package.json is written — unipress projects are content-only.
+//
+// Handlebars variables available in `.hbs` files:
+//   title, author, year, date, foundation
+
+import { readdir, mkdir, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import Handlebars from 'handlebars'
+import { TemplateError } from './errors.js'
+import { TEMPLATES } from './templates-data.js'
+
+export async function scaffold({ templateName, targetDir, vars, force = false, onProgress = () => {} }) {
+  const files = TEMPLATES[templateName]
+  if (!files) {
+    throw new TemplateError(
+      `template not found: '${templateName}'\n` +
+      `hint: run 'unipress list-templates' to see available templates`
+    )
+  }
+  if (existsSync(targetDir) && (await readdir(targetDir)).length > 0 && !force) {
+    throw new TemplateError(
+      `target directory is not empty: ${targetDir}\n` +
+      `hint: pick a different directory, or pass --force to overwrite`
+    )
+  }
+  await mkdir(targetDir, { recursive: true })
+
+  for (const [relPath, entry] of Object.entries(files)) {
+    let dstRel = relPath
+    let dstContent
+    let label
+    if (entry !== null && typeof entry === 'object' && entry.encoding === 'base64') {
+      dstContent = Buffer.from(entry.content, 'base64')
+      label = 'extracted'
+    } else if (relPath.endsWith('.hbs')) {
+      dstRel = relPath.slice(0, -'.hbs'.length)
+      dstContent = Handlebars.compile(entry, { noEscape: true })(vars)
+      label = 'rendered'
+    } else {
+      dstContent = entry
+      label = 'copied'
+    }
+    const dstPath = join(targetDir, dstRel)
+    await mkdir(dirname(dstPath), { recursive: true })
+    await writeFile(dstPath, dstContent)
+    onProgress(`${label} ${dstRel}`)
+  }
+}

package/src/sinks/blob.js

@@ -0,0 +1,25 @@
+// Write a compileSubtree Blob to the local filesystem.
+//
+// Today all Press format adapters (docx, xlsx, typst source bundle) return
+// a single Blob. Writing it to disk is one line of glue — the sink lives
+// in its own module because the four-step compile pattern (gather → tree
+// → compile → sink) keeps the sink decoupled, and future hosts (HTTP
+// response, blob storage) slot in here as siblings.
+
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { OutputWriteError } from '../errors.js'
+
+export async function writeBlobToFile(blob, outPath) {
+  const buf = Buffer.from(await blob.arrayBuffer())
+  try {
+    await mkdir(dirname(outPath), { recursive: true })
+    await writeFile(outPath, buf)
+  } catch (err) {
+    throw new OutputWriteError(
+      `failed to write output to ${outPath}\n` +
+      `cause: ${err.message}`
+    )
+  }
+  return { outPath, bytes: buf.length }
+}