@uniweb/unipress 0.2.2

package/src/compile.js

@@ -0,0 +1,165 @@
+// Programmatic entry point for `unipress compile`.
+//
+// Two-step pipeline after content + foundation setup:
+//
+//   1. Load content, resolve the foundation, run initPrerender to
+//      populate the Website graph. (loadContent + resolveFoundation +
+//      loadAndInit — unchanged from M4.)
+//   2. Call foundation.compileDocument(website, { format, foundation,
+//      ...hostHints }) — the foundation looks up outputs[format],
+//      assembles adapter options, gathers blocks, and routes through
+//      the right Press adapter. Returns a Blob.
+//   3. Sink the Blob. Pdf output runs the typst binary on the source
+//      bundle; everything else writes bytes directly.
+//
+// Block gathering, tree building, and adapter-options assembly used to
+// live here (M4–M8a). As of M8a they live inside compileDocument on the
+// Press side, keyed off the foundation's `outputs:` declaration. This
+// module used to maintain PRESS_FORMAT_BY_OUTPUT and EXT_BY_FORMAT
+// tables for the `pdf` → `typst` aliasing and the default filename
+// extension — both are gone. Foundations declare their own aliasing via
+// `outputs[format].via` and default extensions via
+// `outputs[format].extension`.
+//
+// Progress is fanned out through a single `onProgress` callback so
+// verbose output is consistent across the pipeline (load, resolve,
+// init, compile, sink).
+
+import { basename, resolve } from 'node:path'
+import { loadContent } from './content-loader.js'
+import { resolveFoundation } from './foundation-loader.js'
+import { loadAndInit, compileDocumentWithFoundation, getFoundationOutputs } from './orchestrator.js'
+import { loadUnipressConfig } from './config.js'
+import { writeBlobToFile } from './sinks/blob.js'
+import { writePdfViaTypst } from './sinks/typst.js'
+import { DocumentYmlError, CompileError } from './errors.js'
+
+// Sink selection. `pdf` is special-cased because the Press output (via
+// the typst adapter) is a source-bundle zip, not a PDF — unipress
+// finishes the job by running the typst binary. Every other format is a
+// direct byte write.
+function pickSink(format) {
+  if (format === 'pdf') return 'typst'
+  return 'blob'
+}
+
+export async function compile({
+  dir,
+  format: cliFormat = null,
+  foundationRef: cliFoundationRef = null,
+  outPath: cliOutPath = null,
+  typstBinaryPath: cliTypstBinaryPath = null,
+  keepTemp = false,
+  configPath: cliConfigPath = null,
+  onProgress = () => {}
+} = {}) {
+  onProgress('loading content...')
+  const { content, sitePath, configFile } = await loadContent(dir)
+  onProgress(`  ${content.pages.length} page(s) from ${sitePath} (${configFile})`)
+
+  // Load unipress.config.js — from --config, then <dir>/unipress.config.js,
+  // else empty. Relative paths inside the config are resolved against the
+  // config file's own directory (see src/config.js).
+  const { config, configPath } = await loadUnipressConfig({
+    contentDir: sitePath,
+    explicitPath: cliConfigPath
+  })
+  if (configPath) onProgress(`  config: ${configPath}`)
+
+  // Precedence chain: CLI > unipress.config.js > document.yml > defaults.
+  const format = cliFormat ?? config.format ?? content.config?.format ?? null
+  if (!format) {
+    const hints = ['pass --format <fmt>']
+    if (configPath) hints.push(`set format: in ${configPath}`)
+    hints.push(`set format: in ${configFile}`)
+    throw new DocumentYmlError(
+      `no format specified — ${hints.join(' or ')}`
+    )
+  }
+
+  const foundationRef = cliFoundationRef ?? config.foundation ?? null
+  const typstBinaryPath = cliTypstBinaryPath ?? config.typst?.binary ?? null
+  const typstVersion = config.typst?.version ?? null
+
+  onProgress('resolving foundation...')
+  const foundationInfo = await resolveFoundation({
+    // Already merged CLI + config.foundation above; document.yml foundation
+    // is the fallback.
+    cliRef: foundationRef,
+    configRef: content.config?.foundation,
+    anchorDir: sitePath
+  })
+  onProgress(`  ${foundationInfo.ref} → ${foundationInfo.resolvedPath}`)
+
+  onProgress('initializing foundation...')
+  const { foundation, uniweb } = await loadAndInit({
+    content,
+    resolvedPath: foundationInfo.resolvedPath,
+    onProgress: (msg) => onProgress(`  ${msg}`)
+  })
+  const website = uniweb.activeWebsite
+
+  // Validate the format early so users get a helpful "declared outputs:
+  // …" message before anything downstream fails. Press's compileDocument
+  // would throw an equivalent error — we front-load it so the error
+  // class is the one unipress uses for CLI output.
+  const outputs = getFoundationOutputs(foundation)
+  if (!outputs) {
+    throw new CompileError(
+      `foundation declares no outputs — cannot compile.\n` +
+      `hint: foundation's default export must include an outputs: { … } map. ` +
+      `See framework/docs/reference/foundation-config.md#document-outputs.`
+    )
+  }
+  const outputSpec = outputs[format]
+  if (!outputSpec) {
+    const declared = Object.keys(outputs).join(', ') || '(none)'
+    throw new CompileError(
+      `foundation does not declare 'outputs.${format}' — cannot compile.\n` +
+      `available formats: ${declared}`
+    )
+  }
+
+  // Default output filename: `./<dir-basename>.<ext>`. The foundation
+  // declares the extension; fall back to the format name if it didn't.
+  // Precedence: CLI --out > config.out > default.
+  const ext = outputSpec.extension ?? format
+  const outPath = cliOutPath ?? config.out ?? null
+  const finalOutPath = outPath
+    ? resolve(outPath)
+    : resolve(`./${basename(sitePath)}.${ext}`)
+
+  // Host hints for the foundation's getOptions. For pdf, pass
+  // mode: 'sources' so the foundation returns a typst source bundle the
+  // typst sink can then compile locally. Other formats receive no
+  // extra hints for now — foundations decide their own defaults.
+  const hostHints = format === 'pdf' ? { mode: 'sources' } : {}
+
+  onProgress(`compiling to ${format}${outputSpec.via ? ` (via ${outputSpec.via})` : ''}...`)
+  const blob = await compileDocumentWithFoundation(foundation, website, {
+    format,
+    ...hostHints
+  })
+  onProgress(`  blob: ${blob.size} bytes, type=${blob.type || '(none)'}`)
+
+  onProgress(`writing ${finalOutPath}...`)
+  const sink = pickSink(format)
+  const result = sink === 'typst'
+    ? await writePdfViaTypst(blob, finalOutPath, {
+        typstBinaryPath,
+        typstVersion,
+        keepTemp,
+        onProgress: (msg) => onProgress(`  ${msg}`)
+      })
+    : await writeBlobToFile(blob, finalOutPath)
+  onProgress(`  wrote ${result.bytes} bytes`)
+
+  return {
+    outPath: result.outPath,
+    bytes: result.bytes,
+    format,
+    pressFormat: outputSpec.via ?? format,
+    pageCount: website.pages.length,
+    foundation: foundationInfo
+  }
+}

package/src/config.js

@@ -0,0 +1,128 @@
+// Load an optional `unipress.config.js` from the content directory (or
+// an explicit --config path). The config is an ordinary ES module that
+// default-exports a settings object — typically written with the
+// `defineUnipressConfig` identity helper for editor autocomplete:
+//
+//   // unipress.config.js
+//   import { defineUnipressConfig } from '@uniweb/unipress'
+//   export default defineUnipressConfig({
+//     out: './dist/book.pdf',
+//     typst: { version: '0.14.2' },
+//   })
+//
+// The precedence chain (plan §9.2):
+//
+//   CLI flags > unipress.config.js > document.yml > foundation defaults
+//
+// This module only loads + validates the config file. Merging into the
+// compile pipeline happens in src/compile.js, which owns the precedence
+// semantics for each field.
+//
+// Path resolution convention (matches Vite / Astro): relative paths in
+// the config object — `out`, `foundation`, `typst.binary` — are
+// resolved against the directory containing the config file, not the
+// cwd or the content directory. Absolute paths are used as-is.
+
+import { existsSync, statSync } from 'node:fs'
+import { resolve, dirname, isAbsolute } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { ConfigValidationError } from './errors.js'
+
+const DEFAULT_CONFIG_NAME = 'unipress.config.js'
+const PATHY_FIELDS = ['out', 'foundation']
+const PATHY_NESTED_FIELDS = [['typst', 'binary']]
+
+export async function loadUnipressConfig({ contentDir, explicitPath = null } = {}) {
+  const configPath = pickConfigPath({ contentDir, explicitPath })
+  if (!configPath) {
+    return { config: {}, configPath: null, source: 'default' }
+  }
+
+  let mod
+  try {
+    mod = await import(pathToFileURL(configPath).href)
+  } catch (err) {
+    throw new ConfigValidationError(
+      `failed to load config file ${configPath}\n` +
+      `cause: ${err.message}\n` +
+      `hint: syntax errors, missing dependencies, and thrown errors surface here`
+    )
+  }
+
+  const raw = mod.default ?? mod.config
+  if (raw == null) {
+    throw new ConfigValidationError(
+      `config file ${configPath} has no default export\n` +
+      `hint: export default { ... }  (or wrap with defineUnipressConfig)`
+    )
+  }
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new ConfigValidationError(
+      `config file ${configPath} must default-export an object (got ${describe(raw)})`
+    )
+  }
+
+  const config = normalizePaths(raw, dirname(configPath))
+  return { config, configPath, source: explicitPath ? 'flag' : 'autodetect' }
+}
+
+// Pick between an explicit --config path and auto-discovery in the
+// content directory. Explicit paths must exist; auto-discovery skips
+// silently when no config file is present.
+function pickConfigPath({ contentDir, explicitPath }) {
+  if (explicitPath) {
+    const abs = isAbsolute(explicitPath)
+      ? explicitPath
+      : resolve(process.cwd(), explicitPath)
+    if (!existsSync(abs)) {
+      throw new ConfigValidationError(
+        `--config path does not exist: ${abs}`
+      )
+    }
+    if (!statSync(abs).isFile()) {
+      throw new ConfigValidationError(
+        `--config path is not a file: ${abs}`
+      )
+    }
+    return abs
+  }
+  if (!contentDir) return null
+  const candidate = resolve(contentDir, DEFAULT_CONFIG_NAME)
+  return existsSync(candidate) ? candidate : null
+}
+
+// Resolve relative paths declared in the config against the config
+// file's own directory. The fields treated as paths are listed
+// explicitly so this doesn't catch arbitrary user strings.
+function normalizePaths(config, configDir) {
+  const out = { ...config }
+  for (const key of PATHY_FIELDS) {
+    if (typeof out[key] === 'string' && !isAbsolute(out[key]) && !looksUrlOrPackage(out[key])) {
+      out[key] = resolve(configDir, out[key])
+    }
+  }
+  for (const [key, subkey] of PATHY_NESTED_FIELDS) {
+    const sub = out[key]
+    if (sub && typeof sub === 'object' && typeof sub[subkey] === 'string' && !isAbsolute(sub[subkey])) {
+      out[key] = { ...sub, [subkey]: resolve(configDir, sub[subkey]) }
+    }
+  }
+  return out
+}
+
+// A value like 'my-foundation' or '@scope/foo' is a package name; a
+// value like 'https://...' is a URL. Don't try to filesystem-resolve
+// those. Everything else with a leading dot / absolute is treated as a
+// path and resolved above.
+function looksUrlOrPackage(value) {
+  if (/^https?:\/\//.test(value)) return true
+  // A path starts with ./, ../, /, or a drive letter.
+  const pathy = /^(\.\.?[/\\]|[/\\]|[A-Za-z]:[/\\])/
+  return !pathy.test(value)
+}
+
+function describe(value) {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'array'
+  return typeof value
+}

package/src/content-loader.js

@@ -0,0 +1,56 @@
+// Load a unipress content directory into a Uniweb content object.
+//
+// Wraps `collectSiteContent`, but tells it which top-level config file to
+// read (document.yml or site.yml).
+//
+// Imports from `@uniweb/build/content` — the sharp/Vite/React-free entry
+// designed for Bun-compiled binaries. `@uniweb/build/site` pulls in the
+// image asset-processor (which eagerly loads sharp's native binding and
+// blows up in a `bun build --compile` binary).
+
+import { existsSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { collectSiteContent } from '@uniweb/build/content'
+import { detectConfigFile, CONFIG_FILE_NAMES } from './document-yml.js'
+import { ContentDirectoryError, DocumentYmlError } from './errors.js'
+
+export async function loadContent(dir, options = {}) {
+  const sitePath = resolve(dir)
+
+  if (!existsSync(sitePath)) {
+    throw new ContentDirectoryError(`content directory does not exist: ${sitePath}`)
+  }
+
+  const configFile = detectConfigFile(sitePath)
+  if (!configFile) {
+    throw new DocumentYmlError(
+      `no ${CONFIG_FILE_NAMES.PRIMARY} (or ${CONFIG_FILE_NAMES.FALLBACK}) found in ${sitePath}`
+    )
+  }
+
+  let content
+  try {
+    content = await collectSiteContent(sitePath, {
+      configFile,
+      foundationPath: options.foundationPath
+    })
+  } catch (err) {
+    // js-yaml throws YAMLException with .mark.line/.column. Wrap it in
+    // DocumentYmlError so the CLI reports it with a location hint
+    // instead of a bare stack trace.
+    if (err?.name === 'YAMLException') {
+      const configPath = join(sitePath, configFile)
+      const line = err?.mark?.line != null ? err.mark.line + 1 : null
+      const col = err?.mark?.column != null ? err.mark.column + 1 : null
+      const loc = line != null ? `${configPath}:${line}${col != null ? `:${col}` : ''}` : configPath
+      throw new DocumentYmlError(
+        `malformed YAML in ${configFile}\n` +
+        `at ${loc}\n` +
+        `cause: ${err.reason || err.message}`
+      )
+    }
+    throw err
+  }
+
+  return { content, configFile, sitePath }
+}

package/src/document-yml.js

@@ -0,0 +1,20 @@
+// Detect which top-level config file a content directory uses.
+//
+// unipress projects use `document.yml`. To smooth migration and to support
+// dogfooding inside uniweb workspaces, `site.yml` is accepted as a fallback
+// and gets the same treatment — `collectSiteContent` reads whichever name
+// we pass via its `configFile` option.
+
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const PRIMARY = 'document.yml'
+const FALLBACK = 'site.yml'
+
+export function detectConfigFile(sitePath) {
+  if (existsSync(join(sitePath, PRIMARY))) return PRIMARY
+  if (existsSync(join(sitePath, FALLBACK))) return FALLBACK
+  return null
+}
+
+export const CONFIG_FILE_NAMES = { PRIMARY, FALLBACK }

package/src/errors.js

@@ -0,0 +1,78 @@
+// Named error classes used across unipress commands.
+//
+// Per the brief (Section 14), every error names what was attempted, what
+// failed, and how to recover. The CLI's top-level handler converts these
+// into `error: ...` lines (and stack traces under --verbose).
+//
+// Error shape:
+//   new <Class>(summary)
+//   new <Class>(summary + '\nhint: ...\ncause: ...')
+//
+// Convention: a single summary line, optionally followed by lines prefixed
+// with `hint:` or `cause:`. `format()` turns that into
+//
+//   error: <summary>
+//       hint: <...>
+//       cause: <...>
+//
+// Keeping the structured data as part of the string (rather than separate
+// fields) lets call sites stay one-argument and still get consistent
+// output.
+
+// Known "structured" prefixes inside a multi-line message. When format()
+// sees these at the start of a continuation line, it preserves them;
+// everything else on continuation lines is indented as-is (for the
+// `at file:line` form and arbitrary continuation context).
+const STRUCTURED_PREFIXES = /^(hint|cause|at)\s*:/
+
+export class UnipressError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = this.constructor.name
+  }
+
+  // Formatted multi-line rendering. The top-level CLI handler calls this
+  // for every UnipressError so output stays consistent regardless of
+  // which pipeline stage threw.
+  format() {
+    const [first, ...rest] = (this.message ?? '').split('\n')
+    const out = [`error: ${first}`]
+    for (const line of rest) {
+      if (!line) continue
+      // Normalize prefixed continuation lines (hint/cause/at) with a
+      // 4-space indent, a 6-character prefix column, and the remainder.
+      // Example: 'hint: rebuild the foundation' -> '    hint: rebuild the foundation'.
+      // Non-prefixed lines get the same 4-space indent (they're
+      // continuation context).
+      out.push(STRUCTURED_PREFIXES.test(line) ? `    ${line}` : `    ${line}`)
+    }
+    return out.join('\n')
+  }
+}
+
+// --- Pipeline stages (present in code today) ---------------------------
+
+export class ContentDirectoryError extends UnipressError {}
+export class DocumentYmlError extends UnipressError {}
+export class ConfigValidationError extends UnipressError {}
+export class FoundationResolutionError extends UnipressError {}
+export class CompileError extends UnipressError {}
+export class OutputWriteError extends UnipressError {}
+export class TypstBinaryError extends UnipressError {}
+
+// --- Pipeline stages (catalog-complete; call sites land with their milestone) ---
+
+// M9-URL will use this for registry fetches.
+export class FoundationFetchError extends UnipressError {}
+
+// Reserved for markdown / frontmatter / collections-JSON parse failures.
+// Today, js-yaml's YAMLException + ENOENT surface through DocumentYmlError
+// (content-loader.js catches them); ContentParseError is the dedicated
+// class when per-file parse errors start needing distinct exit codes or
+// handling (e.g. "build succeeded with 1 page skipped — parse error in
+// pages/foo.md").
+export class ContentParseError extends UnipressError {}
+
+// M9 (unipress create) uses this for missing / malformed template
+// packages.
+export class TemplateError extends UnipressError {}

package/src/foundation-fetch.js

@@ -0,0 +1,202 @@
+// URL-based foundation resolution: fetch + cache a built foundation's
+// full dist tree so Node can import it.
+//
+// Cache layout:
+//   <unipress cache>/foundations/<host>/<pathish>/foundation.js
+//   <unipress cache>/foundations/<host>/<pathish>/<chunk>.js
+//   ... etc
+//
+// where <pathish> is the URL's path with leading slashes stripped and
+// the trailing /foundation.js stripped — the same URL always maps to
+// the same cache path.
+//
+// A built foundation is a small entry (`foundation.js`) plus a set of
+// sibling chunks referenced by relative imports (and further chunks
+// dynamically imported from those). `fetchFoundationToCache` walks the
+// import graph: it downloads foundation.js, scans for `./*.js` imports
+// (static and dynamic), fetches each, and recurses. That's enough to
+// cover @uniweb/build's output — all sibling chunks live next to
+// foundation.js. Imports NOT starting with './' are bare specifiers
+// (external like 'react') or absolute URLs and are not part of the
+// fetch graph.
+//
+// Integrity: the fetch is unverified today. Once the Uniweb registry
+// publishes integrity data, the catalog entry can carry an `integrity:`
+// field and this module will verify bytes before caching.
+
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile, symlink } from 'node:fs/promises'
+import { dirname, join, posix, resolve as pathResolve } from 'node:path'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import { FoundationFetchError } from './errors.js'
+import { getCacheDir } from './typst/binary-manager.js'
+
+const require = createRequire(import.meta.url)
+
+// Bare specifiers that the foundation expects to resolve externally
+// (matches DEFAULT_EXTERNALS in @uniweb/build). At import time, Node
+// walks up from the cache dir looking for a node_modules/<name>. The
+// cache dir isn't inside any package tree, so we link unipress's own
+// installations into a co-located node_modules.
+const EXTERNAL_PACKAGES = [
+  'react',
+  'react-dom',
+  'react/jsx-runtime',
+  'react/jsx-dev-runtime',
+  '@uniweb/core',
+]
+
+// Match `./chunk.js` only in actual ESM import positions — `from './x'`,
+// `import './x'`, or `import('./x')`. A broad "match any quoted ./x.js"
+// picks up Node-core strings embedded in bundled commonjs shims.
+const RELATIVE_JS_IMPORT = /(?:from\s*|\bimport\s*\(?\s*)['"](\.\/[^'"]+\.(?:js|mjs|cjs))['"]/g
+
+export function getFoundationCacheDir(url) {
+  let parsed
+  try {
+    parsed = new URL(url)
+  } catch (err) {
+    throw new FoundationFetchError(
+      `foundation URL is not a valid URL: ${url}\n` +
+      `cause: ${err.message}`
+    )
+  }
+  const host = parsed.host.replace(/:/g, '_')
+  let p = parsed.pathname.replace(/^\/+/, '').replace(/\/foundation\.js$/i, '')
+  return join(getCacheDir(), 'foundations', host, p)
+}
+
+export function getFoundationCachePath(url) {
+  return join(getFoundationCacheDir(url), 'foundation.js')
+}
+
+export async function fetchFoundationToCache(url, { onProgress = () => {} } = {}) {
+  const cacheDir = getFoundationCacheDir(url)
+  const entryPath = join(cacheDir, 'foundation.js')
+  if (existsSync(entryPath)) {
+    onProgress(`using cached foundation: ${entryPath}`)
+    return entryPath
+  }
+  onProgress(`downloading foundation graph from ${url}`)
+  await mkdir(cacheDir, { recursive: true })
+
+  // Directory URL the individual chunk files live under. Works whether
+  // the input URL ends in /foundation.js or at the containing directory.
+  const urlObj = new URL(url)
+  const pathname = urlObj.pathname.replace(/\/foundation\.js$/i, '/')
+  urlObj.pathname = pathname.endsWith('/') ? pathname : pathname + '/'
+  const baseUrl = urlObj.toString()
+
+  const fetched = new Set()
+  const queue = ['foundation.js']
+  while (queue.length > 0) {
+    const rel = queue.shift()
+    if (fetched.has(rel)) continue
+    fetched.add(rel)
+
+    const fullUrl = new URL(rel, baseUrl).toString()
+    const buf = await fetchOne(fullUrl)
+    const localPath = join(cacheDir, rel)
+    await mkdir(dirname(localPath), { recursive: true })
+    await writeFile(localPath, buf)
+    onProgress(`  ${buf.length} bytes: ${rel}`)
+
+    // Scan text for relative imports and enqueue.
+    const text = buf.toString('utf8')
+    for (const match of text.matchAll(RELATIVE_JS_IMPORT)) {
+      const discovered = normaliseRelative(rel, match[1])
+      if (!fetched.has(discovered)) queue.push(discovered)
+    }
+  }
+  await linkExternals(cacheDir, onProgress)
+  onProgress(`foundation cached at ${cacheDir} (${fetched.size} file(s))`)
+  return entryPath
+}
+
+// Make unipress's own copies of the externalized packages reachable
+// from the cache dir. Node's ESM loader walks up from the importing
+// file looking for `node_modules/<name>` — by placing a node_modules
+// directory next to the cached foundation.js with symlinks to each
+// external's package directory, bare imports inside the foundation
+// resolve to unipress's already-installed copies. This keeps a single
+// React instance (unipress's) across host and foundation.
+async function linkExternals(cacheDir, onProgress) {
+  const nmDir = join(cacheDir, 'node_modules')
+  await mkdir(nmDir, { recursive: true })
+  // Collapse subpath specifiers (react/jsx-runtime → react) to the
+  // package-root specifier we actually link. Deduped.
+  const rootSpecs = new Set()
+  for (const spec of EXTERNAL_PACKAGES) {
+    rootSpecs.add(spec.startsWith('@')
+      ? spec.split('/').slice(0, 2).join('/')  // '@scope/name'
+      : spec.split('/')[0])                     // 'name'
+  }
+  for (const name of rootSpecs) {
+    const dest = name.startsWith('@')
+      ? join(nmDir, ...name.split('/'))         // node_modules/@scope/name
+      : join(nmDir, name)                       // node_modules/name
+    if (existsSync(dest)) continue
+    try {
+      const pkgDir = findPackageRoot(name)
+      if (!pkgDir) {
+        onProgress(`  warn: cannot find '${name}' in unipress deps — foundation may fail to import`)
+        continue
+      }
+      await mkdir(dirname(dest), { recursive: true })
+      await symlink(pkgDir, dest, 'dir')
+      onProgress(`  linked ${name} → ${pkgDir}`)
+    } catch (err) {
+      onProgress(`  warn: linking ${name} failed: ${err.message}`)
+    }
+  }
+}
+
+function findPackageRoot(name) {
+  try {
+    // Resolve the package's `package.json` to find its root.
+    const pkgJson = require.resolve(`${name}/package.json`)
+    return dirname(pkgJson)
+  } catch {
+    // Fallback: resolve a default export and strip back.
+    try {
+      const entry = require.resolve(name)
+      let dir = dirname(entry)
+      while (dir !== dirname(dir)) {
+        if (existsSync(join(dir, 'package.json'))) {
+          const pkg = JSON.parse(require('fs').readFileSync(join(dir, 'package.json'), 'utf8'))
+          if (pkg.name === name || pkg.name === name.split('/')[0]) return dir
+        }
+        dir = dirname(dir)
+      }
+    } catch {}
+    return null
+  }
+}
+
+function normaliseRelative(fromRel, toRel) {
+  // Resolve `toRel` against `fromRel`'s directory using POSIX semantics
+  // (URLs and ESM paths are POSIX-style regardless of host OS).
+  const fromDir = posix.dirname(fromRel)
+  return posix.normalize(posix.join(fromDir, toRel)).replace(/^\.\//, '')
+}
+
+async function fetchOne(url) {
+  let res
+  try {
+    res = await fetch(url)
+  } catch (err) {
+    throw new FoundationFetchError(
+      `could not fetch ${url}\n` +
+      `cause: ${err.message}\n` +
+      `hint: is the registry reachable? (for localhost URLs, is unicloud running?)`
+    )
+  }
+  if (!res.ok) {
+    throw new FoundationFetchError(
+      `fetch failed (${res.status} ${res.statusText}): ${url}\n` +
+      `hint: check the foundation is published at that version`
+    )
+  }
+  return Buffer.from(await res.arrayBuffer())
+}