@orkestrel/scaffold 0.0.1

package/dist/src/server/index.js

@@ -0,0 +1,1572 @@
+import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { flattenText, isBlockquoteNode, isParagraphNode, parseDocument, walkNodes } from "@orkestrel/markdown";
+import { DEFAULT_ENGINES, DEFAULT_VERSION, HOST_PATHS, ScaffoldError, blueprint, devDependenciesFor, manifestToDependencies, rangeToFreshness } from "../core/index.js";
+import { Emitter } from "@orkestrel/emitter";
+//#region src/server/helpers.ts
+/**
+* Locate this MODULE's own installed package root — the nearest ancestor of
+* `import.meta.url` holding a `package.json` — and return its vendored
+* `dist/host` data root. THE single source of truth for the default
+* `Materializer` / `scaffold` bin host: once installed, walking up from the
+* module's own file (not `process.cwd()`, which points at whichever project
+* happens to be running) resolves to `node_modules/@orkestrel/scaffold`, the
+* correct default host — the package ships its vendored data with itself.
+* `dist/host` may not exist yet when this resolves from SOURCE under a test
+* runner; that is fine — existence is checked at the point of use, not here.
+*
+* @returns The absolute vendored `dist/host` path.
+* @throws `ScaffoldError('TARGET', …)` when no ancestor of this module's own
+*   location holds a `package.json`.
+*
+* @example
+* ```ts
+* import { hostRoot } from '@orkestrel/scaffold/server'
+*
+* hostRoot() // '/…/node_modules/@orkestrel/scaffold/dist/host'
+* ```
+*/
+function hostRoot() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (;;) {
+		if (existsSync(join(dir, "package.json"))) return join(dir, "dist", "host");
+		const parent = dirname(dir);
+		if (parent === dir) throw new ScaffoldError("TARGET", "No package root found above the module location", { module: import.meta.url });
+		dir = parent;
+	}
+}
+/**
+* Filter a manifest record's entries down to `@orkestrel/`-prefixed keys with
+* string values — the shared `dependencies` / `peerDependencies` /
+* `devDependencies` reader `deriveBlueprint` uses for every dependency-shaped
+* field.
+*
+* @param value - The candidate manifest field value (e.g. `parsed.dependencies`).
+* @returns The `@orkestrel/`-prefixed `[name, range]` entries; `[]` when
+*   `value` is not a plain object (per `isRecord`).
+*
+* @example
+* ```ts
+* import { selectOrkestrelEntries } from '@orkestrel/scaffold/server'
+*
+* selectOrkestrelEntries({ '@orkestrel/core': '^1.0.0', lodash: '^4.0.0' })
+* // [['@orkestrel/core', '^1.0.0']]
+* ```
+*/
+function selectOrkestrelEntries(value) {
+	if (!isRecord(value)) return [];
+	return Object.entries(value).filter((entry) => typeof entry[1] === "string" && entry[0].startsWith("@orkestrel/"));
+}
+/**
+* Reconstruct a `Blueprint` from an EXISTING repo at `target` — the faithful
+* inverse `audit` / `repair` / `mirror` need to diff a live package against
+* its own would-be scaffold, rather than a fresh, dependency-less stand-in.
+*
+* @param target - The existing package directory to derive a `Blueprint` from.
+* @remarks
+* `name` strips the `@orkestrel/` prefix off `manifest.name` — a non-`@orkestrel`
+* name is a coded `TARGET` failure, since this tool derives only `@orkestrel`
+* packages. `surfaces` is read off the LIVE line: every surface the package
+* carries has a `src/<surface>/` directory, so each of `'core' | 'browser' |
+* 'server'` is included iff that directory exists at `target`; a target with
+* NONE of the three is also a coded `TARGET` failure. `dependencies` /
+* `peers` are the `@orkestrel/`-prefixed entries of `manifest.dependencies` /
+* `manifest.peerDependencies` (a peer flagged `peerDependenciesMeta[name]
+* .optional === true` carries `optional: true`). `extras` is EVERY entry of
+* `manifest.devDependencies` (not only `@orkestrel/`-prefixed ones — an
+* external extra like `zod` must round-trip too), EXCLUDING the generated
+* devDependency baseline (`devDependenciesFor([])`'s keys, which already
+* cover `@orkestrel/guide` and `@orkestrel/scaffold`) every scaffolded
+* package already carries, never a package-specific extra. A devDependency
+* ALSO present in
+* `manifest.peerDependencies` or `manifest.dependencies` (e.g. a peer
+* dev-installed for local testing) is likewise excluded from `extras` — it
+* already surfaces as a `peer`/`dependency` above, and double-counting it as
+* an `extra` would land it in `peers ∩ extras`, a blocking `validateBlueprint`
+* gate. `overrides` is always `[]` — derivation cannot know a caller's
+* template-override intent.
+* @returns The reconstructed `Blueprint`.
+* @throws `ScaffoldError('TARGET', …)` when `target`'s manifest is unreadable
+*   (via `readManifest`), is not valid JSON, its `name` is not `@orkestrel`-
+*   prefixed, or `target` carries none of the three surface directories.
+*
+* @example
+* ```ts
+* import { deriveBlueprint } from '@orkestrel/scaffold/server'
+*
+* deriveBlueprint('./packages/router') // { name: 'router', surfaces: ['core', 'server'], … }
+* ```
+*/
+function deriveBlueprint(target) {
+	const BASELINE_EXTRAS = /* @__PURE__ */ new Set([
+		...Object.keys(devDependenciesFor([])),
+		"@orkestrel/guide",
+		"@orkestrel/scaffold"
+	]);
+	const text = readManifest(target);
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw new ScaffoldError("TARGET", `Manifest at ${target} is not valid JSON`, {
+			target,
+			error
+		});
+	}
+	if (!isRecord(parsed)) throw new ScaffoldError("TARGET", `Manifest at ${target} is not a JSON object`, { target });
+	const rawName = parsed.name;
+	if (typeof rawName !== "string" || !rawName.startsWith("@orkestrel/")) throw new ScaffoldError("TARGET", `Manifest name "${String(rawName)}" is not an @orkestrel package`, {
+		target,
+		name: rawName
+	});
+	const name = rawName.slice(11);
+	const description = typeof parsed.description === "string" ? parsed.description : void 0;
+	const keywords = Array.isArray(parsed.keywords) && parsed.keywords.every((word) => typeof word === "string") ? parsed.keywords : [];
+	const version = typeof parsed.version === "string" ? parsed.version : DEFAULT_VERSION;
+	const engines = isRecord(parsed.engines) && typeof parsed.engines.node === "string" ? parsed.engines.node : DEFAULT_ENGINES;
+	const surfaces = [
+		"core",
+		"browser",
+		"server"
+	].filter((surface) => existsSync(join(target, "src", surface)));
+	if (surfaces.length === 0) throw new ScaffoldError("TARGET", `No surface directory found under ${target}/src`, { target });
+	const dependencies = selectOrkestrelEntries(parsed.dependencies).map(([depName, range]) => ({
+		name: depName,
+		range
+	}));
+	const peersMeta = isRecord(parsed.peerDependenciesMeta) ? parsed.peerDependenciesMeta : void 0;
+	const peers = selectOrkestrelEntries(parsed.peerDependencies).map(([depName, range]) => {
+		const meta = peersMeta !== void 0 ? peersMeta[depName] : void 0;
+		return isRecord(meta) && meta.optional === true ? {
+			name: depName,
+			range,
+			optional: true
+		} : {
+			name: depName,
+			range
+		};
+	});
+	const peerAndDependencyNames = /* @__PURE__ */ new Set([...selectOrkestrelEntries(parsed.peerDependencies).map(([depName]) => depName), ...selectOrkestrelEntries(parsed.dependencies).map(([depName]) => depName)]);
+	const devDependencies = isRecord(parsed.devDependencies) ? parsed.devDependencies : {};
+	return blueprint(name, {
+		description,
+		keywords,
+		surfaces,
+		dependencies,
+		peers,
+		extras: Object.entries(devDependencies).filter((entry) => typeof entry[1] === "string").filter(([depName]) => !BASELINE_EXTRAS.has(depName) && !peerAndDependencyNames.has(depName)).map(([depName, range]) => ({
+			name: depName,
+			range
+		})),
+		version,
+		engines,
+		overrides: []
+	});
+}
+/**
+* Whether a target path is absent, empty, or contains nothing but a `.git`
+* directory — the green-field target law `Materializer.materialize` enforces.
+*
+* @param target - The candidate target directory path.
+* @returns `true` when `target` is safe to materialize a fresh package into.
+*
+* @example
+* ```ts
+* import { isVacant } from '@orkestrel/scaffold/server'
+*
+* isVacant('./packages/router-new') // true — absent, empty, or only a .git dir
+* ```
+*/
+function isVacant(target) {
+	if (!existsSync(target)) return true;
+	if (!statSync(target).isDirectory()) return false;
+	const entries = readdirSync(target);
+	return entries.length === 0 || entries.length === 1 && entries[0] === ".git";
+}
+/**
+* Read a target's current content at a set of relative paths into a
+* `Record<string, string>` — the I/O that feeds the pure `diffPlan`.
+*
+* @param target - The target directory to read from.
+* @param paths - The plan-relative artifact paths to probe.
+* @returns A record keyed by path; a directory entry maps to `''` (presence
+*   only — a `host`-origin directory artifact is audited by presence, never
+*   content), an absent path is OMITTED entirely (never an empty-string
+*   placeholder for a missing file, so `diffPlan` reports it `missing`).
+* @throws `ScaffoldError('TARGET', …)` when an EXISTING path fails to read
+*   (e.g. `EACCES` / `EPERM`) — carries the offending relative `path` (and
+*   the resolved `full` path) in `context`. An absent path is never an
+*   error — it is simply omitted, per the return contract above.
+*
+* @example
+* ```ts
+* import { readTarget } from '@orkestrel/scaffold/server'
+*
+* readTarget('./packages/router', ['package.json', 'src/core/index.ts'])
+* // { 'package.json': '{ "name": … }', 'src/core/index.ts': '…' }
+* ```
+*/
+function readTarget(target, paths) {
+	const current = {};
+	for (const path of paths) {
+		const full = join(target, path);
+		if (!existsSync(full)) continue;
+		try {
+			current[path] = statSync(full).isDirectory() ? "" : readFileSync(full, "utf8");
+		} catch (error) {
+			throw new ScaffoldError("TARGET", `Failed to read target file at ${path}`, {
+				path,
+				full,
+				error
+			});
+		}
+	}
+	return current;
+}
+/**
+* Read `target/package.json` text — the read that feeds `manifestToDependencies`.
+*
+* @param target - The target directory to read the manifest from.
+* @returns The manifest file's raw text.
+* @throws `ScaffoldError('TARGET', …)` when the manifest is absent or
+*   unreadable (e.g. `EACCES` / `EPERM`) — carries the resolved `full` path
+*   in `context`.
+*
+* @example
+* ```ts
+* import { readManifest } from '@orkestrel/scaffold/server'
+*
+* readManifest('./packages/router') // '{ "name": "@orkestrel/router", … }'
+* ```
+*/
+function readManifest(target) {
+	const full = join(target, "package.json");
+	try {
+		return readFileSync(full, "utf8");
+	} catch (error) {
+		throw new ScaffoldError("TARGET", `Failed to read manifest at ${full}`, {
+			target,
+			full,
+			error
+		});
+	}
+}
+/**
+* Whether `value` is a plain object (not `null`, not an array).
+*
+* @param value - The candidate value.
+* @returns `true` when `value` narrows to `Record<string, unknown>`.
+*
+* @example
+* ```ts
+* import { isRecord } from '@orkestrel/scaffold/server'
+*
+* isRecord({ a: 1 }) // true
+* isRecord(null) // false
+* ```
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Whether `value` is a well-formed `host/manifest.json` entry — a string
+* `storage`, a string `destination`, and a boolean `executable`.
+*
+* @param value - The candidate raw manifest entry.
+* @returns `true` when `value` narrows to `ManifestEntry`.
+*
+* @example
+* ```ts
+* import { isManifestEntry } from '@orkestrel/scaffold/server'
+*
+* isManifestEntry({ storage: 'a', destination: 'b', executable: false }) // true
+* isManifestEntry({ storage: 'a', destination: 'b' }) // false — missing `executable`
+* ```
+*/
+function isManifestEntry(value) {
+	if (!isRecord(value)) return false;
+	return typeof value.storage === "string" && typeof value.destination === "string" && typeof value.executable === "boolean";
+}
+/**
+* Read and validate a vendored host root's `manifest.json`, when present.
+*
+* @param host - The host root to probe.
+* @returns The parsed entries, or `undefined` when `host` has no
+*   `manifest.json` — the raw-repo-root fallback (`Materializer` then maps
+*   an artifact's `source` to `host` 1:1, no vendored staging indirection).
+* @throws `ScaffoldError('TARGET', …)` when `manifest.json` exists but is
+*   unreadable, is not valid JSON, or is not an array of `ManifestEntry`.
+*
+* @example
+* ```ts
+* import { readHostManifest } from '@orkestrel/scaffold/server'
+*
+* readHostManifest('./dist/host') // readonly ManifestEntry[] | undefined
+* ```
+*/
+function readHostManifest(host) {
+	const full = join(host, "manifest.json");
+	if (!existsSync(full)) return void 0;
+	let text;
+	try {
+		text = readFileSync(full, "utf8");
+	} catch (error) {
+		throw new ScaffoldError("TARGET", `Failed to read host manifest at ${full}`, {
+			host,
+			full,
+			error
+		});
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		throw new ScaffoldError("TARGET", `Host manifest at ${full} is not valid JSON`, {
+			host,
+			full,
+			error
+		});
+	}
+	if (!Array.isArray(parsed) || !parsed.every(isManifestEntry)) throw new ScaffoldError("TARGET", `Host manifest at ${full} is not an array of manifest entries`, {
+		host,
+		full
+	});
+	return parsed;
+}
+/**
+* Recursively list a directory's files as root-relative paths.
+*
+* @param root - The directory to list.
+* @returns Root-relative file paths (posix-style `/` separators), or `[]`
+*   when `root` is absent.
+*
+* @example
+* ```ts
+* import { listFiles } from '@orkestrel/scaffold/server'
+*
+* listFiles('./dist/host/.claude/agents') // ['scout.md', 'builder.md', …]
+* ```
+*/
+function listFiles(root) {
+	if (!existsSync(root)) return [];
+	const files = [];
+	for (const entry of readdirSync(root, { withFileTypes: true })) {
+		const full = join(root, entry.name);
+		if (entry.isDirectory()) for (const nested of listFiles(full)) files.push(`${entry.name}/${nested}`);
+		else files.push(entry.name);
+	}
+	return files;
+}
+/**
+* Map a repo-relative path to its vendored-host STAGING path, per the
+* dotfile-mapping rule `stageHost` writes into `manifest.json`.
+*
+* @param path - The repo-relative source path (e.g. `.claude/agents/scout.md`).
+* @returns The mapped storage path: a leading-dot TOP-LEVEL FILE maps to
+*   `dotfiles/<name-without-dot>`; a leading-dot DIRECTORY segment loses its
+*   dot wherever it appears; an undotted path is unchanged.
+*
+* @example
+* ```ts
+* import { storagePath } from '@orkestrel/scaffold/server'
+*
+* storagePath('.gitignore') // 'dotfiles/gitignore'
+* storagePath('.claude/agents/scout.md') // 'claude/agents/scout.md'
+* storagePath('.github/workflows/ci.yml') // 'github/workflows/ci.yml'
+* storagePath('AGENTS.md') // 'AGENTS.md'
+* ```
+*/
+function storagePath(path) {
+	const segments = path.split("/");
+	if (segments.length === 1) {
+		const name = segments[0];
+		return name.startsWith(".") ? `dotfiles/${name.slice(1)}` : name;
+	}
+	return segments.map((segment) => segment.startsWith(".") ? segment.slice(1) : segment).join("/");
+}
+/**
+* Stage the vendored host set (byte-preserved copies + `manifest.json`) from
+* a repo root into an output directory — the BUILD-time primitive the
+* `build:host` npm script now calls directly (replacing a standalone build
+* script); `Materializer.materialize` is the RUNTIME reader of what this
+* writes (via `hostRoot` / `readHostManifest`).
+*
+* @param root - The repo root every `paths` entry resolves against.
+* @param out - The output directory to wipe and stage into (typically `dist/host`).
+* @param paths - The repo-relative file/directory entries to stage; defaults
+*   to the package's own vendored set (`HOST_PATHS`) — a caller passes an
+*   explicit list only to stage an arbitrary/test set.
+* @remarks
+* `out` is wiped (`rmSync(out, { recursive: true, force: true })`) BEFORE
+* staging, so a stale file left over from a prior run never lingers. Each
+* `paths` entry is walked to its per-file leaves (a directory recursively,
+* via `listFiles`; a file, itself) and copied byte-for-byte
+* (`copyFileSync`) to `<out>/<storagePath(path)>`. The `executable` flag
+* `entries` reports is derived from the `.sh` suffix on `destination` —
+* deterministic on every build platform (Windows `stat` carries no execute
+* bit); all vendored executables are shell scripts by construction.
+* `manifest.json` is written LAST, as `entries` code-unit sorted by
+* `destination`, tab-indented JSON with a trailing newline.
+* @returns The written manifest's entries (`{ storage, destination, executable }`).
+* @throws `ScaffoldError('TARGET', …)` naming the offending path when a
+*   `paths` entry has no source under `root`, or naming BOTH colliding
+*   destinations when two entries map to the same `storagePath` (the guard
+*   run BEFORE `manifest.json` is written).
+*
+* @example
+* ```ts
+* import { stageHost } from '@orkestrel/scaffold/server'
+*
+* const entries = stageHost(process.cwd(), 'dist/host')
+* entries.length // number of files staged
+* ```
+*/
+function stageHost(root, out, paths = HOST_PATHS) {
+	const destinations = [];
+	for (const path of paths) {
+		const absolute = join(root, path);
+		if (!existsSync(absolute)) throw new ScaffoldError("TARGET", `Missing host source at ${path}`, {
+			path,
+			root
+		});
+		if (statSync(absolute).isDirectory()) for (const nested of listFiles(absolute)) destinations.push(`${path}/${nested}`);
+		else destinations.push(path);
+	}
+	rmSync(out, {
+		recursive: true,
+		force: true
+	});
+	const entries = [];
+	for (const destination of destinations) {
+		const storage = storagePath(destination);
+		const sourceAbsolute = join(root, destination);
+		const destinationAbsolute = join(out, storage);
+		mkdirSync(dirname(destinationAbsolute), { recursive: true });
+		copyFileSync(sourceAbsolute, destinationAbsolute);
+		const executable = destination.endsWith(".sh");
+		entries.push({
+			storage,
+			destination,
+			executable
+		});
+	}
+	entries.sort((a, b) => a.destination < b.destination ? -1 : a.destination > b.destination ? 1 : 0);
+	const byStorage = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const existing = byStorage.get(entry.storage);
+		if (existing !== void 0) throw new ScaffoldError("TARGET", `Storage path collision at "${entry.storage}" — destinations "${existing}" and "${entry.destination}" both map to it`, {
+			storage: entry.storage,
+			destinations: [existing, entry.destination]
+		});
+		byStorage.set(entry.storage, entry.destination);
+	}
+	mkdirSync(out, { recursive: true });
+	writeFileSync(join(out, "manifest.json"), `${JSON.stringify(entries, null, "	")}\n`);
+	return entries;
+}
+/**
+* Resolve the absolute host-storage path for a host-origin artifact's
+* `source`, manifest-aware.
+*
+* @param manifest - The host's parsed `manifest.json` entries, or `undefined`
+*   when the host carries none (raw-repo-root fallback).
+* @param source - The artifact's `source` (or `path`) to resolve.
+* @param host - The resolved host root the path is joined against.
+* @returns `join(host, source)` when `manifest` is `undefined` (no vendored
+*   staging indirection); when `manifest` is present, `join(host,
+*   entries[0].storage)` for the SINGLE manifest entry whose `destination`
+*   equals `source`, or `undefined` when zero or more than one entry matches
+*   (`source` names a directory, or the manifest is ambiguous — no single
+*   storage file to point at).
+*
+* @example
+* ```ts
+* import { locateHostSource } from '@orkestrel/scaffold/server'
+*
+* locateHostSource(undefined, 'package.json', './dist/host') // './dist/host/package.json'
+* locateHostSource([{ storage: 'pkg.tmpl', destination: 'package.json', executable: false }], 'package.json', './dist/host')
+* // './dist/host/pkg.tmpl'
+* ```
+*/
+function locateHostSource(manifest, source, host) {
+	if (manifest === void 0) return join(host, source);
+	const entries = manifest.filter((entry) => entry.destination === source);
+	if (entries.length !== 1) return void 0;
+	return join(host, entries[0].storage);
+}
+/**
+* Rehydrate a `Plan`'s `host`-origin artifacts with their real byte content
+* read from `host` — manifest-aware, via `locateHostSource`.
+*
+* @param plan - The plan to hydrate.
+* @param host - The resolved host root to read from.
+* @returns A new `Plan` whose file-shaped `host` artifacts carry `content`;
+*   `template` / `computed` artifacts and directory-shaped `host` artifacts
+*   (no single storage file to read) pass through untouched.
+* @throws `ScaffoldError('TARGET', …)` when a resolved, existing host source
+*   file fails to read.
+*
+* @example
+* ```ts
+* import { hydratePlan } from '@orkestrel/scaffold/server'
+*
+* const hydrated = hydratePlan(plan, './dist/host')
+* ```
+*/
+function hydratePlan(plan, host) {
+	const manifest = readHostManifest(host);
+	const artifacts = plan.artifacts.map((artifact) => {
+		if (artifact.origin !== "host") return artifact;
+		const source = artifact.source ?? artifact.path;
+		const full = locateHostSource(manifest, source, host);
+		if (full === void 0 || !existsSync(full) || statSync(full).isDirectory()) return artifact;
+		try {
+			return {
+				...artifact,
+				content: readFileSync(full, "utf8")
+			};
+		} catch (error) {
+			throw new ScaffoldError("TARGET", `Failed to read host artifact at ${source}`, {
+				source,
+				full,
+				error
+			});
+		}
+	});
+	return {
+		...plan,
+		artifacts
+	};
+}
+/**
+* The `prune`-owned directories — a hard allowlist; `pruneTargets` (and the
+* `Materializer.prune` that consumes it) never scans anything outside these two.
+*
+* @example
+* ```ts
+* import { PRUNE_DIRECTORIES } from '@orkestrel/scaffold/server'
+*
+* PRUNE_DIRECTORIES // ['.claude/agents', 'scripts']
+* ```
+*/
+var PRUNE_DIRECTORIES = [".claude/agents", "scripts"];
+/**
+* The vendored set of destination-relative paths under `directory` (one of
+* `PRUNE_DIRECTORIES`) that `pruneTargets` must NOT report — read from the
+* manifest's `destination`s when `host` has one, else listed straight off
+* `host/<directory>`.
+*
+* @param host - The vendored host root to establish the allowlist from.
+* @param directory - The prune directory (one of `PRUNE_DIRECTORIES`) to scope the allowlist to.
+* @remarks
+* FAIL CLOSED: before returning any allowlist (even an empty one), the
+* vendored source must be POSITIVELY established, or a caller would treat an
+* unresolved host as "vendors nothing" and report every file under
+* `target/<directory>` as unexpected. A missing `host` root, or (no
+* `manifest.json` AND no `host/<directory>`), is a coded `TARGET` failure —
+* the distinction this guards is missing-host vs genuinely-empty-vendor: a
+* `host` that EXISTS and vendors zero files in `directory` (an existing empty
+* dir, or a manifest with zero entries for it) remains a valid empty allowlist.
+* @returns The allowed destination-relative paths under `directory`.
+* @throws `ScaffoldError('TARGET', …)` when `host` does not exist, or when
+*   `host` has no `manifest.json` and no `host/<directory>` either.
+*
+* @example
+* ```ts
+* import { vendoredPruneSet } from '@orkestrel/scaffold/server'
+*
+* vendoredPruneSet('./dist/host', '.claude/agents') // Set { '.claude/agents/scout.md', … }
+* ```
+*/
+function vendoredPruneSet(host, directory) {
+	if (!existsSync(host)) throw new ScaffoldError("TARGET", `Cannot establish vendored source for prune: host root not found at ${host}`, {
+		host,
+		directory
+	});
+	const manifest = readHostManifest(host);
+	if (manifest !== void 0) return new Set(manifest.filter((entry) => entry.destination.startsWith(`${directory}/`)).map((entry) => entry.destination));
+	const hostDirectory = join(host, directory);
+	if (!existsSync(hostDirectory)) throw new ScaffoldError("TARGET", `Cannot establish vendored source for prune: no manifest.json and no host directory at ${hostDirectory}`, {
+		host,
+		directory
+	});
+	return new Set(listFiles(hostDirectory).map((relative) => `${directory}/${relative}`));
+}
+/**
+* List the repo-relative POSIX paths under `target`'s prune directories
+* (`.claude/agents`, `scripts`) that the vendored `host` allowlist does NOT
+* declare — THE single source of truth for prune drift, consumed by both
+* `Materializer.prune` (which deletes exactly these paths) and the bin's
+* audit/preview UX (which now shows them honestly instead of a
+* structurally-always-zero `audit.foreign`).
+*
+* @param target - The target directory to scan for unexpected files.
+* @param host - The vendored host root the allowlist is derived from.
+* @returns The unexpected relative paths (e.g. `.claude/agents/rogue.md`); `[]`
+*   when a prune directory is absent under `target`, or when none of its
+*   files are unexpected. Pure read — never deletes anything.
+* @throws `ScaffoldError('TARGET', …)` when `host` cannot positively
+*   establish a vendored allowlist for a prune directory that DOES exist
+*   under `target` (see `vendoredPruneSet`'s fail-closed remarks).
+*
+* @example
+* ```ts
+* import { pruneTargets } from '@orkestrel/scaffold/server'
+*
+* pruneTargets('./packages/router', hostRoot()) // ['.claude/agents/rogue.md']
+* ```
+*/
+function pruneTargets(target, host) {
+	const paths = [];
+	for (const directory of PRUNE_DIRECTORIES) {
+		const root = join(target, directory);
+		if (!existsSync(root)) continue;
+		const allowed = vendoredPruneSet(host, directory);
+		for (const relative of listFiles(root)) {
+			const path = `${directory}/${relative}`;
+			if (!allowed.has(path)) paths.push(path);
+		}
+	}
+	return paths;
+}
+/**
+* List a fleet root's `@orkestrel/*` package directories.
+*
+* @param root - The fleet root directory to scan.
+* @returns Absolute, code-unit-sorted paths of `root`'s immediate child
+*   directories whose `package.json` parses and whose `name` starts with
+*   `@orkestrel/`. A child with an unreadable or unparsable `package.json`,
+*   or a non-`@orkestrel` name, is skipped silently — it simply is not a
+*   fleet member.
+*
+* @example
+* ```ts
+* import { discoverPackages } from '@orkestrel/scaffold/server'
+*
+* discoverPackages('./packages') // ['/abs/packages/router', '/abs/packages/budget']
+* ```
+*/
+function discoverPackages(root) {
+	const packages = [];
+	for (const entry of readdirSync(root, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const directory = join(root, entry.name);
+		const manifestPath = join(directory, "package.json");
+		if (!existsSync(manifestPath)) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+		} catch {
+			continue;
+		}
+		if (!isRecord(parsed)) continue;
+		const name = parsed.name;
+		if (typeof name === "string" && name.startsWith("@orkestrel/")) packages.push(directory);
+	}
+	return packages.sort();
+}
+/**
+* Build the fleet package catalog — one `CatalogEntry` per `@orkestrel/*`
+* package discovered under each root, its description drawn from its own
+* guide's FIRST blockquote.
+*
+* @param roots - The fleet root directories to scan (each walked via `discoverPackages`).
+* @remarks
+* Per discovered package directory: `name` / `version` come from its own
+* `package.json`; `description` is the first paragraph of the guide's opening
+* blockquote — the flattened text of the FIRST `ParagraphNode` among the
+* FIRST `BlockquoteNode` found's (depth-first, pre-order, via `walkNodes`)
+* TOP-LEVEL children in its `guides/src/<short>.md` (`<short>` = `name` with
+* the `@orkestrel/` prefix stripped), parsed with `@orkestrel/markdown`'s
+* `parseDocument` — a multi-paragraph blockquote overview yields only its
+* FIRST paragraph, never the whole quote glued together; embedded newlines
+* collapse to single spaces, and surrounding whitespace trims. A
+* missing/unreadable guide, a guide carrying no blockquote, or a blockquote
+* with no top-level paragraph child, yields `description: ''`, never a
+* thrown error. Entries merge across `roots` (a later root's entry for a
+* repeated `name` wins), then code-unit sort by `name`. An unreadable ROOT
+* itself is NOT wrapped here — whatever `discoverPackages` throws for it
+* propagates as-is; the bin layer is responsible for coding that failure
+* `TARGET`.
+* @returns The merged, sorted `CatalogEntry[]`.
+*
+* @example
+* ```ts
+* import { catalogPackages } from '@orkestrel/scaffold/server'
+*
+* catalogPackages(['/repos']) // [{ name: '@orkestrel/contract', version: '0.0.5', description: '…' }, …]
+* ```
+*/
+function catalogPackages(roots) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const root of roots) for (const directory of discoverPackages(root)) {
+		let parsed;
+		try {
+			parsed = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+		} catch {
+			continue;
+		}
+		if (!isRecord(parsed)) continue;
+		const name = parsed.name;
+		if (typeof name !== "string" || !name.startsWith("@orkestrel/")) continue;
+		const version = typeof parsed.version === "string" ? parsed.version : DEFAULT_VERSION;
+		const guidePath = join(directory, "guides", "src", `${name.slice(11)}.md`);
+		let description = "";
+		if (existsSync(guidePath)) try {
+			const document = parseDocument(readFileSync(guidePath, "utf8"));
+			let quote;
+			for (const node of walkNodes(document)) if (isBlockquoteNode(node)) {
+				quote = node;
+				break;
+			}
+			if (quote !== void 0) {
+				const paragraph = quote.children.find((child) => isParagraphNode(child));
+				if (paragraph !== void 0) description = flattenText(paragraph).replace(/\s+/g, " ").trim();
+			}
+		} catch {
+			description = "";
+		}
+		merged.set(name, {
+			name,
+			version,
+			description
+		});
+	}
+	return [...merged.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
+//#endregion
+//#region src/server/Materializer.ts
+/**
+* The materialization entity (server) — the only impure surface in the
+* package, writing a `Plan` to `node:fs` behind an explicit call.
+*
+* @remarks
+* `materialize` is green-field: it refuses any target `isVacant` rejects
+* (`ScaffoldError('TARGET', …)`), then byte-copies each `host` artifact from
+* the `host` root and writes each `template` / `computed` artifact's rendered
+* `content`, failing fast on any write error (`ScaffoldError('WRITE', …)`).
+* `repair` is into-existing: it skips the vacancy check and writes ONLY the
+* `missing` / `stale` artifacts an `Audit` names, leaving `aligned` ones
+* untouched. `prune` deletes stale files under `target/.claude/agents/` and
+* `target/scripts/` that the vendored `host` no longer names — the retired
+* `mirror.sh`/`scaffold.sh` cleanup step, now a method. After `destroy()`
+* every method throws `DESTROYED`; teardown is idempotent, emitter last.
+*
+* @remarks
+* `host`-origin copies are MANIFEST-AWARE: when the resolved `host` root
+* carries a `manifest.json` (this package's own vendored `dist/host`), each
+* artifact's `source` (a destination-relative path) is looked up in the
+* manifest to find its un-dotted STORAGE path plus an `executable` bit
+* (applied via `chmodSync` after the copy) — the vendored-package shape,
+* where storage names avoid leading dots npm would otherwise mangle. When
+* `host` carries no `manifest.json` (a caller-supplied raw repo root, e.g. a
+* sibling checkout or a test fixture), `source` maps to `host` 1:1, exactly
+* as before.
+*
+* @remarks
+* A manifest-present `source` with ZERO matching entries degrades to a stub
+* ONLY when that `source` is a dependency-guide pointer — one that starts
+* with `guides/src/` and ends with `.md` (the `guides/src/<dep>.md` pointer
+* `Compiler` emits for any dependency outside this package's vendored set).
+* That is the ONLY zero-match case that is legitimate: every `HOST_PATHS`
+* source is always staged by `stageHost`, so a non-guide zero-match means a
+* corrupted or truncated `manifest.json`, not an intentionally-unvendored
+* artifact. For a guide pointer, a short stub file is written at the
+* destination and reported exactly like a successful copy, mirroring the
+* READ path (`hydratePlan` leaves such artifacts `content`-undefined, so
+* `diffPlan` audits them by PRESENCE only). For every OTHER zero-match, the
+* fail-closed `ScaffoldError('TARGET', …)` is thrown — degrading an
+* unscoped zero-match would otherwise let a corrupted manifest silently stub
+* an unrecoverable artifact (e.g. `AGENTS.md` — `pull` only ever fetches
+* dependency guides) or write a FILE named `.claude` over what should be a
+* directory artifact. The raw-root fallback (`manifest === undefined`, a
+* caller-supplied `--from`) keeps its own throw regardless: an EXPLICITLY
+* named source failing to resolve is a different, caller-error failure
+* class, not a "not vendored" degrade.
+*
+* @remarks
+* Defense in depth at the filesystem trust boundary: EVERY resolved
+* destination (`materialize` and `repair`, both origins) is asserted to stay
+* within `resolve(target)` before any write, and every `host`-origin copy
+* source is asserted to stay within `resolve(host)` before any read — a
+* traversal segment (`../`) in an artifact's `path` or `source` cannot escape
+* either root, even if a gate upstream (e.g. an ungated `Plan` built by hand)
+* let it through. A destination violation throws `ScaffoldError('WRITE', …)`;
+* a source violation throws `ScaffoldError('TARGET', …)`.
+*
+* @remarks
+* The containment check is REAL-PATH aware, not merely lexical: both the
+* root (`target` / `host`) and the candidate destination/source are resolved
+* through `realpathSync` on their DEEPEST EXISTING ancestor before the prefix
+* comparison, so a symlinked subdirectory planted inside an otherwise
+* legitimate root cannot smuggle a write (or read) outside it — `repair`,
+* which has no `isVacant` gate, is covered exactly like `materialize`. A path
+* segment that does not yet exist on disk (the still-to-be-created file/dir
+* a write is about to create) is rejoined onto the resolved existing
+* ancestor rather than realpath'd itself.
+*
+* @example
+* ```ts
+* import { blueprint, blueprintToPlan } from '@orkestrel/scaffold'
+* import { createMaterializer } from '@orkestrel/scaffold/server'
+*
+* const plan = blueprintToPlan(blueprint('budget', { surfaces: ['core'] }))
+* const materializer = createMaterializer()
+* materializer.materialize(plan, './packages/budget-new')
+* materializer.destroy()
+* ```
+*/
+var Materializer = class Materializer {
+	#emitter;
+	#host;
+	#manifestLoaded = false;
+	#manifestEntries;
+	#destroyed = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#host = options?.host ?? hostRoot();
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	materialize(plan, target) {
+		this.#ensureAlive();
+		if (!isVacant(target)) throw new ScaffoldError("TARGET", "materialize requires a vacant target", { target });
+		const written = [];
+		const copied = [];
+		for (const artifact of plan.artifacts) if (artifact.origin === "host") {
+			this.#copy(artifact, target);
+			copied.push(artifact.path);
+		} else {
+			this.#write(artifact, target);
+			written.push(artifact.path);
+		}
+		const result = {
+			target,
+			written,
+			copied,
+			skipped: [],
+			removed: []
+		};
+		this.#emitter.emit("done", result);
+		return result;
+	}
+	repair(plan, audit, target) {
+		this.#ensureAlive();
+		const drifted = new Map(audit.findings.map((finding) => [finding.path, finding.drift]));
+		const written = [];
+		const copied = [];
+		const skipped = [];
+		for (const artifact of plan.artifacts) {
+			const drift = drifted.get(artifact.path);
+			if (drift !== "missing" && drift !== "stale") {
+				skipped.push(artifact.path);
+				continue;
+			}
+			if (artifact.origin === "host") {
+				this.#copy(artifact, target);
+				copied.push(artifact.path);
+			} else {
+				this.#write(artifact, target);
+				written.push(artifact.path);
+			}
+		}
+		const result = {
+			target,
+			written,
+			copied,
+			skipped,
+			removed: []
+		};
+		this.#emitter.emit("done", result);
+		return result;
+	}
+	prune(target) {
+		this.#ensureAlive();
+		const removed = [];
+		for (const path of pruneTargets(target, this.#host)) {
+			unlinkSync(Materializer.#assertContained(target, path, "WRITE", path));
+			removed.push(path);
+			this.#emitter.emit("remove", path);
+		}
+		const result = {
+			target,
+			written: [],
+			copied: [],
+			skipped: [],
+			removed
+		};
+		this.#emitter.emit("done", result);
+		return result;
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#copy(artifact, target) {
+		const source = artifact.source ?? artifact.path;
+		const manifest = this.#manifest();
+		if (manifest === void 0) {
+			const from = Materializer.#assertContained(this.#host, source, "TARGET", artifact.path);
+			const to = Materializer.#assertContained(target, artifact.path, "WRITE", artifact.path);
+			try {
+				mkdirSync(dirname(to), { recursive: true });
+				cpSync(from, to, { recursive: true });
+			} catch (error) {
+				this.#emitter.emit("error", error);
+				throw new ScaffoldError("WRITE", `Failed to copy host artifact at ${artifact.path}`, {
+					path: artifact.path,
+					error
+				});
+			}
+			this.#emitter.emit("copy", artifact.path);
+			return;
+		}
+		const entries = manifest.filter((entry) => entry.destination === source || entry.destination.startsWith(`${source}/`));
+		if (entries.length === 0) {
+			if (!source.startsWith("guides/src/") || !source.endsWith(".md")) throw new ScaffoldError("TARGET", `Manifest entry for "${source}" is missing — the vendored manifest may be corrupted or truncated`, {
+				target,
+				source
+			});
+			const to = Materializer.#assertContained(target, artifact.path, "WRITE", artifact.path);
+			try {
+				mkdirSync(dirname(to), { recursive: true });
+				writeFileSync(to, Materializer.#stub(source), "utf8");
+			} catch (error) {
+				this.#emitter.emit("error", error);
+				throw new ScaffoldError("WRITE", `Failed to write host artifact stub at ${artifact.path}`, {
+					path: artifact.path,
+					error
+				});
+			}
+			this.#emitter.emit("copy", artifact.path);
+			return;
+		}
+		for (const entry of entries) {
+			const from = Materializer.#assertContained(this.#host, entry.storage, "TARGET", artifact.path);
+			const to = Materializer.#assertContained(target, entry.destination, "WRITE", artifact.path);
+			try {
+				mkdirSync(dirname(to), { recursive: true });
+				cpSync(from, to);
+				if (entry.executable) chmodSync(to, 493);
+			} catch (error) {
+				this.#emitter.emit("error", error);
+				throw new ScaffoldError("WRITE", `Failed to copy host artifact at ${artifact.path}`, {
+					path: artifact.path,
+					error
+				});
+			}
+		}
+		this.#emitter.emit("copy", artifact.path);
+	}
+	#manifest() {
+		if (!this.#manifestLoaded) {
+			this.#manifestEntries = readHostManifest(this.#host);
+			this.#manifestLoaded = true;
+		}
+		return this.#manifestEntries;
+	}
+	#write(artifact, target) {
+		const to = Materializer.#assertContained(target, artifact.path, "WRITE", artifact.path);
+		try {
+			mkdirSync(dirname(to), { recursive: true });
+			writeFileSync(to, artifact.content ?? "", "utf8");
+		} catch (error) {
+			this.#emitter.emit("error", error);
+			throw new ScaffoldError("WRITE", `Failed to write artifact at ${artifact.path}`, {
+				path: artifact.path,
+				error
+			});
+		}
+		this.#emitter.emit("write", artifact.path);
+	}
+	static #assertContained(root, relative, code, path) {
+		const resolvedRoot = Materializer.#resolveReal(resolve(root));
+		const resolvedCandidate = Materializer.#resolveReal(resolve(root, relative));
+		if (resolvedCandidate !== resolvedRoot && !resolvedCandidate.startsWith(resolvedRoot + sep)) throw new ScaffoldError(code, `Artifact path "${path}" escapes the ${code === "WRITE" ? "target" : "host"} root`, {
+			path,
+			root
+		});
+		return resolve(root, relative);
+	}
+	static #stub(source) {
+		return `> Vendored guide for @orkestrel/${source.slice(11, source.length - 3)} — run \`scaffold pull\` to fetch it.\n`;
+	}
+	static #resolveReal(path) {
+		if (existsSync(path)) return realpathSync(path);
+		const parent = dirname(path);
+		if (parent === path) return path;
+		return join(Materializer.#resolveReal(parent), relative(parent, path));
+	}
+	#ensureAlive() {
+		if (this.#destroyed) throw new ScaffoldError("DESTROYED", "Materializer has been destroyed");
+	}
+};
+//#endregion
+//#region src/server/Sync.ts
+/**
+* The upstream-synchronization entity (server) — the impure FETCH sibling of
+* `Materializer`, Promise-based and network-only.
+*
+* @remarks
+* Every method reads upstream over HTTPS with a 10-second per-request
+* `AbortSignal.timeout` and bounded `concurrency` (default 6, never an
+* unbounded `Promise.all`). The default COLLECT posture captures each
+* dependency's `freshness` (`404` → `missing`, transport / other non-2xx →
+* `failed`) into the result; `strict` mode instead throws
+* `ScaffoldError('FETCH', …)` naming the failing URL. `guides`'s optional
+* `current` parameter is a caller-supplied local-mirror content map keyed by
+* dependency NAME (the `diffPlan` caller-supplied-reference pattern): WITH the
+* map, a fetched guide byte-equal to its entry verdicts `current`, anything
+* differing or absent from the map verdicts `behind`; WITHOUT the map, every
+* successful fetch verdicts `behind` (no reference means it needs syncing).
+* `pull` builds that map itself from the TARGET's own `guides/src/<short>.md`
+* mirrors, so its verdicts are target-relative; `write` commits only the
+* `behind` guides (never `current`, `missing`, or `failed`, which carries no
+* trustworthy content) under the same realpath-anchored containment law
+* `Materializer` enforces. After `destroy()` every method throws `DESTROYED`;
+* teardown is idempotent, emitter last.
+*
+* @example
+* ```ts
+* import { createSync } from '@orkestrel/scaffold/server'
+*
+* const sync = createSync()
+* const report = await sync.pull('.')
+* if (report.failed === 0) await sync.write(report, '.')
+* sync.destroy()
+* ```
+*/
+var Sync = class Sync {
+	static #DEFAULT_TIMEOUT = 1e4;
+	static #DEFAULT_CONCURRENCY = 6;
+	static #DEFAULT_LIMIT = 5242880;
+	#emitter;
+	#guidesBase;
+	#branch;
+	#guidesTimeout;
+	#registryBase;
+	#registryTimeout;
+	#concurrency;
+	#retries;
+	#strict;
+	#limit;
+	#destroyed = false;
+	constructor(options) {
+		this.#emitter = new Emitter({
+			on: options?.on,
+			error: options?.error
+		});
+		this.#guidesBase = options?.guides?.base ?? "raw.githubusercontent.com";
+		this.#branch = options?.guides?.branch ?? "main";
+		this.#guidesTimeout = options?.guides?.timeout ?? Sync.#DEFAULT_TIMEOUT;
+		this.#registryBase = options?.registry?.base ?? "registry.npmjs.org";
+		this.#registryTimeout = options?.registry?.timeout ?? Sync.#DEFAULT_TIMEOUT;
+		this.#concurrency = options?.concurrency ?? Sync.#DEFAULT_CONCURRENCY;
+		this.#retries = options?.retries ?? 0;
+		this.#strict = options?.strict ?? false;
+		this.#limit = options?.limit ?? Sync.#DEFAULT_LIMIT;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	async guides(deps, current) {
+		this.#ensureAlive();
+		return Sync.#runPool(deps, this.#concurrency, async (dep) => {
+			const short = Sync.#shortName(dep.name);
+			const url = this.#guideUrl(short);
+			const outcome = await Sync.#fetchText(url, this.#guidesTimeout, this.#retries, this.#limit);
+			const guide = Sync.#toGuideSync(dep.name, short, outcome, current);
+			if (outcome.kind === "failed") this.#emitter.emit("error", outcome.error);
+			this.#emitter.emit("guide", dep.name);
+			if (this.#strict && (guide.freshness === "missing" || guide.freshness === "failed")) throw new ScaffoldError("FETCH", `Failed to fetch guide at ${url}`, {
+				url,
+				name: dep.name
+			});
+			return guide;
+		});
+	}
+	async versions(deps) {
+		this.#ensureAlive();
+		return Sync.#runPool(deps, this.#concurrency, async (dep) => {
+			const url = this.#registryUrl(dep.name);
+			const outcome = await Sync.#fetchText(url, this.#registryTimeout, this.#retries, this.#limit);
+			const version = Sync.#toVersionSync(dep, outcome);
+			if (outcome.kind === "failed") this.#emitter.emit("error", outcome.error);
+			this.#emitter.emit("version", dep.name);
+			if (this.#strict && (version.freshness === "missing" || version.freshness === "failed")) throw new ScaffoldError("FETCH", `Failed to fetch registry version at ${url}`, {
+				url,
+				name: dep.name
+			});
+			return version;
+		});
+	}
+	/**
+	* The fleet package catalog, sourced from the npm registry — the
+	* AUTHORITATIVE enumeration (never a caller-supplied root).
+	*
+	* @returns One {@link CatalogEntry} per `@orkestrel/*` package the registry
+	* lists, code-unit sorted by `name`.
+	* @remarks
+	* Three fetches build each entry: (1) the org's exact package-list
+	* (`-/org/orkestrel/package`) enumerates every published name — an
+	* unreachable or malformed response throws a coded `ScaffoldError('FETCH')`
+	* UNCONDITIONALLY (never gated by `strict`), since without it there is no
+	* catalog to build; (2) each name's own registry packument supplies
+	* `version` (`dist-tags.latest`) and a registry-path `description`
+	* fallback — a failed/malformed packument keeps the entry (degraded:
+	* `version: ''`) rather than dropping it, since the org list already
+	* proved the package exists; (3) each name's own guide
+	* (`guides/src/<short>.md`, same canonical URL as `guides()`, fetched
+	* unauthenticated — every fleet repo is public) supplies the PREFERRED
+	* `description` — its first blockquote's first paragraph — falling back
+	* to the packument description when the guide 404s, faults, or carries no
+	* blockquote; a 404 STAYS LISTED (it is a reachability signal, not an
+	* absence) with a note reading `guide unreachable (HTTP 404 — repo
+	* private or guide missing?)`. Emits `package` once per entry with a
+	* combined human-readable `note` (empty when both fetches succeeded)
+	* alongside the existing `error` events for each degraded sub-fetch.
+	*/
+	async catalog() {
+		this.#ensureAlive();
+		const orgUrl = this.#orgUrl();
+		const orgOutcome = await Sync.#fetchText(orgUrl, this.#registryTimeout, this.#retries, this.#limit);
+		const names = Sync.#toOrgPackages(orgOutcome, orgUrl);
+		return [...await Sync.#runPool(names, this.#concurrency, async (name) => {
+			const packumentOutcome = await Sync.#fetchText(this.#registryUrl(name), this.#registryTimeout, this.#retries, this.#limit);
+			const packument = Sync.#toPackument(packumentOutcome);
+			const short = Sync.#shortName(name);
+			const guideOutcome = await Sync.#fetchText(this.#guideUrl(short), this.#guidesTimeout, this.#retries, this.#limit);
+			const guide = Sync.#toGuideDescription(guideOutcome);
+			if (packumentOutcome.kind === "failed") this.#emitter.emit("error", packumentOutcome.error);
+			if (guideOutcome.kind === "failed") this.#emitter.emit("error", guideOutcome.error);
+			const description = guide.description ?? packument.description;
+			const note = Sync.#combineNote(guide.note, packument.note);
+			this.#emitter.emit("package", name, note);
+			return {
+				name,
+				version: packument.version,
+				description
+			};
+		})].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+	}
+	async pull(target) {
+		this.#ensureAlive();
+		const deps = manifestToDependencies(readManifest(target));
+		const current = {};
+		for (const dep of deps) {
+			const full = join(target, "guides", "src", `${Sync.#shortName(dep.name)}.md`);
+			if (!existsSync(full)) continue;
+			try {
+				current[dep.name] = readFileSync(full, "utf8");
+			} catch {}
+		}
+		const guides = await this.guides(deps, current);
+		const versions = await this.versions(deps);
+		const failed = [...guides, ...versions].filter((entry) => entry.freshness === "missing" || entry.freshness === "failed").length;
+		const report = {
+			target,
+			guides,
+			versions,
+			clean: failed === 0 && guides.every((guide) => guide.freshness === "current") && versions.every((version) => version.freshness === "current"),
+			failed
+		};
+		this.#emitter.emit("done", report);
+		return report;
+	}
+	async write(report, target) {
+		this.#ensureAlive();
+		const written = [];
+		for (const guide of report.guides) {
+			if (guide.freshness !== "behind") continue;
+			const to = Sync.#assertContained(target, guide.path);
+			try {
+				mkdirSync(dirname(to), { recursive: true });
+				writeFileSync(to, guide.content, "utf8");
+			} catch (error) {
+				this.#emitter.emit("error", error);
+				throw new ScaffoldError("WRITE", `Failed to write guide at ${guide.path}`, {
+					path: guide.path,
+					error
+				});
+			}
+			written.push(guide.path);
+			this.#emitter.emit("write", guide.path);
+		}
+		return written;
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#guideUrl(short) {
+		return `${Sync.#normalizeBase(this.#guidesBase)}/orkestrel/${short}/refs/heads/${this.#branch}/guides/src/${short}.md`;
+	}
+	#registryUrl(name) {
+		return `${Sync.#normalizeBase(this.#registryBase)}/${name.replace("/", "%2F")}`;
+	}
+	#orgUrl() {
+		return `${Sync.#normalizeBase(this.#registryBase)}/-/org/orkestrel/package`;
+	}
+	static #normalizeBase(base) {
+		return /^https?:\/\//.test(base) ? base : `https://${base}`;
+	}
+	static #shortName(name) {
+		return name.startsWith("@orkestrel/") ? name.slice(11) : name;
+	}
+	static #isRecord(value) {
+		return typeof value === "object" && value !== null && !Array.isArray(value);
+	}
+	static async #runPool(items, concurrency, worker) {
+		const results = new Array(items.length);
+		const state = {
+			cursor: 0,
+			stopped: false,
+			firstError: void 0
+		};
+		const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => Sync.#drain({
+			items,
+			worker,
+			results,
+			state
+		}));
+		await Promise.allSettled(workers);
+		if (state.firstError !== void 0) throw state.firstError.error;
+		return results;
+	}
+	static async #drain(pool) {
+		for (;;) {
+			if (pool.state.stopped) return;
+			const index = pool.state.cursor;
+			pool.state.cursor += 1;
+			if (index >= pool.items.length) return;
+			try {
+				pool.results[index] = await pool.worker(pool.items[index]);
+			} catch (error) {
+				if (pool.state.firstError === void 0) pool.state.firstError = { error };
+				pool.state.stopped = true;
+				return;
+			}
+		}
+	}
+	static async #fetchText(url, timeout, retries, limit) {
+		let lastError;
+		let lastNote = "";
+		for (let attempt = 0; attempt <= retries; attempt += 1) try {
+			const response = await fetch(url, {
+				signal: AbortSignal.timeout(timeout),
+				redirect: "manual"
+			});
+			if (response.status === 404) return { kind: "missing" };
+			if (response.type === "opaqueredirect" || response.status >= 300 && response.status < 400) {
+				lastNote = "redirected (redirect following is disabled)";
+				lastError = /* @__PURE__ */ new Error(`Redirect blocked for ${url}`);
+				continue;
+			}
+			if (!response.ok) {
+				lastNote = `HTTP ${String(response.status)}`;
+				lastError = /* @__PURE__ */ new Error(`Unexpected HTTP status ${response.status} for ${url}`);
+				continue;
+			}
+			const read = await Sync.#readBounded(response, url, limit);
+			if (!read.ok) {
+				lastError = read.error;
+				lastNote = read.note;
+				continue;
+			}
+			return {
+				kind: "ok",
+				text: read.text
+			};
+		} catch (error) {
+			lastError = error;
+			lastNote = Sync.#transportNote(error);
+		}
+		return {
+			kind: "failed",
+			error: lastError,
+			note: lastNote
+		};
+	}
+	static #transportNote(error) {
+		if (!(error instanceof Error)) return String(error);
+		const code = Sync.#causeCode(error);
+		return code !== void 0 ? `${error.message}: ${code}` : error.message;
+	}
+	static #causeCode(error) {
+		const cause = error.cause;
+		if (typeof cause !== "object" || cause === null) return void 0;
+		if (!("code" in cause)) return void 0;
+		return typeof cause.code === "string" ? cause.code : void 0;
+	}
+	static async #readBounded(response, url, limit) {
+		const declared = response.headers.get("content-length");
+		if (declared !== null) {
+			const declaredBytes = Number(declared);
+			if (Number.isFinite(declaredBytes) && declaredBytes > limit) return {
+				ok: false,
+				error: /* @__PURE__ */ new Error(`Response body for ${url} declares ${String(declaredBytes)} bytes, exceeding the ${String(limit)}-byte limit`),
+				note: `response exceeded limit (${String(limit)} bytes)`
+			};
+		}
+		const body = response.body;
+		if (body === null) return {
+			ok: true,
+			text: ""
+		};
+		const reader = body.getReader();
+		const decoder = new TextDecoder();
+		const chunks = [];
+		let total = 0;
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done) break;
+				total += value.byteLength;
+				if (total > limit) return {
+					ok: false,
+					error: /* @__PURE__ */ new Error(`Response body for ${url} exceeded the ${String(limit)}-byte limit`),
+					note: `response exceeded limit (${String(limit)} bytes)`
+				};
+				chunks.push(decoder.decode(value, { stream: true }));
+			}
+			chunks.push(decoder.decode());
+		} finally {
+			reader.releaseLock();
+		}
+		return {
+			ok: true,
+			text: chunks.join("")
+		};
+	}
+	static #toGuideSync(name, short, outcome, current) {
+		const path = `guides/src/${short}.md`;
+		if (outcome.kind === "missing") return {
+			name,
+			path,
+			content: "",
+			freshness: "missing",
+			note: "HTTP 404"
+		};
+		if (outcome.kind === "failed") return {
+			name,
+			path,
+			content: "",
+			freshness: "failed",
+			note: outcome.note
+		};
+		const freshness = current?.[name] === outcome.text ? "current" : "behind";
+		return {
+			name,
+			path,
+			content: outcome.text,
+			freshness
+		};
+	}
+	static #toVersionSync(dep, outcome) {
+		if (outcome.kind === "missing") return {
+			name: dep.name,
+			range: dep.range,
+			latest: "",
+			freshness: "missing",
+			note: "HTTP 404"
+		};
+		if (outcome.kind === "failed") return {
+			name: dep.name,
+			range: dep.range,
+			latest: "",
+			freshness: "failed",
+			note: outcome.note
+		};
+		const latest = Sync.#parseLatest(outcome.text);
+		if (latest === void 0) return {
+			name: dep.name,
+			range: dep.range,
+			latest: "",
+			freshness: "failed",
+			note: "malformed registry response (missing dist-tags.latest)"
+		};
+		return {
+			name: dep.name,
+			range: dep.range,
+			latest,
+			freshness: rangeToFreshness(dep.range, latest)
+		};
+	}
+	static #toOrgPackages(outcome, url) {
+		if (outcome.kind === "missing" || outcome.kind === "failed") {
+			const note = outcome.kind === "missing" ? "HTTP 404" : outcome.note;
+			throw new ScaffoldError("FETCH", `Failed to fetch the package list at ${url}`, {
+				url,
+				note
+			});
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(outcome.text);
+		} catch {
+			throw new ScaffoldError("FETCH", `Malformed package list response at ${url}`, { url });
+		}
+		if (!Sync.#isRecord(parsed)) throw new ScaffoldError("FETCH", `Malformed package list response at ${url}`, { url });
+		const names = Object.keys(parsed).filter((name) => name.startsWith("@orkestrel/"));
+		if (names.length === 0) throw new ScaffoldError("FETCH", `Malformed package list response at ${url}`, { url });
+		return names;
+	}
+	static #toPackument(outcome) {
+		if (outcome.kind === "missing") return {
+			version: "",
+			description: "",
+			note: "HTTP 404"
+		};
+		if (outcome.kind === "failed") return {
+			version: "",
+			description: "",
+			note: outcome.note
+		};
+		let parsed;
+		try {
+			parsed = JSON.parse(outcome.text);
+		} catch {
+			return {
+				version: "",
+				description: "",
+				note: "malformed registry response (invalid JSON)"
+			};
+		}
+		if (!Sync.#isRecord(parsed)) return {
+			version: "",
+			description: "",
+			note: "malformed registry response (not an object)"
+		};
+		const distTags = parsed["dist-tags"];
+		const version = Sync.#isRecord(distTags) && typeof distTags.latest === "string" ? distTags.latest : "";
+		return {
+			version,
+			description: typeof parsed.description === "string" ? parsed.description : "",
+			note: version === "" ? "malformed registry response (missing dist-tags.latest)" : ""
+		};
+	}
+	static #toGuideDescription(outcome) {
+		if (outcome.kind === "missing") return {
+			description: void 0,
+			note: "guide unreachable (HTTP 404 — repo private or guide missing?)"
+		};
+		if (outcome.kind === "failed") return {
+			description: void 0,
+			note: outcome.note
+		};
+		const description = Sync.#firstBlockquoteParagraph(outcome.text);
+		return description !== void 0 ? {
+			description,
+			note: ""
+		} : {
+			description: void 0,
+			note: "guide has no blockquote description"
+		};
+	}
+	static #firstBlockquoteParagraph(text) {
+		let document;
+		try {
+			document = parseDocument(text);
+		} catch {
+			return;
+		}
+		let quote;
+		for (const node of walkNodes(document)) if (isBlockquoteNode(node)) {
+			quote = node;
+			break;
+		}
+		if (quote === void 0) return void 0;
+		const paragraph = quote.children.find((child) => isParagraphNode(child));
+		if (paragraph === void 0) return void 0;
+		const flattened = flattenText(paragraph).replace(/\s+/g, " ").trim();
+		return flattened.length > 0 ? flattened : void 0;
+	}
+	static #combineNote(guideNote, packumentNote) {
+		const parts = [];
+		if (packumentNote !== "") parts.push(`version unavailable — ${packumentNote}`);
+		if (guideNote !== "") parts.push(`description from registry — ${guideNote}`);
+		return parts.join("; ");
+	}
+	static #parseLatest(text) {
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			return;
+		}
+		if (!Sync.#isRecord(parsed)) return void 0;
+		const distTags = parsed["dist-tags"];
+		if (!Sync.#isRecord(distTags)) return void 0;
+		const latest = distTags.latest;
+		return typeof latest === "string" ? latest : void 0;
+	}
+	static #assertContained(target, relative) {
+		const resolvedRoot = Sync.#resolveReal(resolve(target));
+		const resolvedCandidate = Sync.#resolveReal(resolve(target, relative));
+		if (resolvedCandidate !== resolvedRoot && !resolvedCandidate.startsWith(resolvedRoot + sep)) throw new ScaffoldError("WRITE", `Guide path "${relative}" escapes the target root`, {
+			path: relative,
+			target
+		});
+		return resolve(target, relative);
+	}
+	static #resolveReal(path) {
+		if (existsSync(path)) return realpathSync(path);
+		const parent = dirname(path);
+		if (parent === path) return path;
+		return join(Sync.#resolveReal(parent), relative(parent, path));
+	}
+	#ensureAlive() {
+		if (this.#destroyed) throw new ScaffoldError("DESTROYED", "Sync has been destroyed");
+	}
+};
+//#endregion
+//#region src/server/factories.ts
+/**
+* Create a `MaterializerInterface` (server) — the materialization entity,
+* seeded from `MaterializerOptions`.
+*
+* @param options - Optional `host` root override, emitter hooks, and error handler
+* @returns A {@link MaterializerInterface}
+*
+* @example
+* ```ts
+* import { createMaterializer } from '@orkestrel/scaffold/server'
+*
+* const materializer = createMaterializer()
+* materializer.destroy()
+* ```
+*/
+function createMaterializer(options) {
+	return new Materializer(options);
+}
+/**
+* Create a `SyncInterface` (server) — the upstream-synchronization entity,
+* seeded from `SyncOptions`.
+*
+* @param options - Optional endpoint bases/branch, concurrency, retries, strict, emitter hooks, and error handler
+* @returns A {@link SyncInterface}
+*
+* @example
+* ```ts
+* import { createSync } from '@orkestrel/scaffold/server'
+*
+* const sync = createSync()
+* sync.destroy()
+* ```
+*/
+function createSync(options) {
+	return new Sync(options);
+}
+//#endregion
+export { Materializer, PRUNE_DIRECTORIES, Sync, catalogPackages, createMaterializer, createSync, deriveBlueprint, discoverPackages, hostRoot, hydratePlan, isManifestEntry, isRecord, isVacant, listFiles, locateHostSource, pruneTargets, readHostManifest, readManifest, readTarget, selectOrkestrelEntries, stageHost, storagePath, vendoredPruneSet };
+
+//# sourceMappingURL=index.js.map