@orkestrel/scaffold 0.0.1

package/dist/src/server/index.d.cts

@@ -0,0 +1,779 @@
+import { Audit } from '../core/index.ts';
+import { Blueprint } from '../core/index.ts';
+import { CatalogEntry } from '../core/index.ts';
+import { Dependency } from '../core/index.ts';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { GuideSync } from '../core/index.ts';
+import { Plan } from '../core/index.ts';
+import { SyncReport } from '../core/index.ts';
+import { VersionSync } from '../core/index.ts';
+
+/**
+ * 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: '…' }, …]
+ * ```
+ */
+export declare function catalogPackages(roots: readonly string[]): readonly CatalogEntry[];
+
+/**
+ * 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()
+ * ```
+ */
+export declare function createMaterializer(options?: MaterializerOptions): MaterializerInterface;
+
+/**
+ * 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()
+ * ```
+ */
+export declare function createSync(options?: SyncOptions): SyncInterface;
+
+/**
+ * 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'], … }
+ * ```
+ */
+export declare function deriveBlueprint(target: string): Blueprint;
+
+/**
+ * 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']
+ * ```
+ */
+export declare function discoverPackages(root: string): readonly string[];
+
+/**
+ * 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'
+ * ```
+ */
+export declare function hostRoot(): string;
+
+/**
+ * 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')
+ * ```
+ */
+export declare function hydratePlan(plan: Plan, host: string): Plan;
+
+/**
+ * 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`
+ * ```
+ */
+export declare function isManifestEntry(value: unknown): value is ManifestEntry;
+
+/**
+ * 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
+ * ```
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+
+/**
+ * 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
+ * ```
+ */
+export declare function isVacant(target: string): boolean;
+
+/**
+ * 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', …]
+ * ```
+ */
+export declare function listFiles(root: string): readonly string[];
+
+/**
+ * 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'
+ * ```
+ */
+export declare function locateHostSource(manifest: readonly ManifestEntry[] | undefined, source: string, host: string): string | undefined;
+
+/** One entry of the vendored host's `manifest.json` (server). */
+export declare interface ManifestEntry {
+    readonly storage: string;
+    readonly destination: string;
+    readonly executable: boolean;
+}
+
+/**
+ * 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()
+ * ```
+ */
+export declare class Materializer implements MaterializerInterface {
+    #private;
+    constructor(options?: MaterializerOptions);
+    get emitter(): EmitterInterface<MaterializerEventMap>;
+    materialize(plan: Plan, target: string): MaterializeResult;
+    repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
+    prune(target: string): MaterializeResult;
+    destroy(): void;
+}
+
+/** The outcome of one materialization (server). */
+export declare interface MaterializeResult {
+    readonly target: string;
+    readonly written: readonly string[];
+    readonly copied: readonly string[];
+    readonly skipped: readonly string[];
+    readonly removed: readonly string[];
+}
+
+/** `Materializer`'s push observation surface (AGENTS §13, server). */
+export declare type MaterializerEventMap = {
+    readonly copy: readonly [path: string];
+    readonly write: readonly [path: string];
+    readonly remove: readonly [path: string];
+    readonly done: readonly [result: MaterializeResult];
+    readonly error: readonly [error: unknown];
+    readonly destroy: readonly [];
+};
+
+/** The materialization contract (server) — the only impure entity in the package. */
+export declare interface MaterializerInterface {
+    readonly emitter: EmitterInterface<MaterializerEventMap>;
+    materialize(plan: Plan, target: string): MaterializeResult;
+    repair(plan: Plan, audit: Audit, target: string): MaterializeResult;
+    prune(target: string): MaterializeResult;
+    destroy(): void;
+}
+
+/**
+ * Options for `createMaterializer` / the `Materializer` constructor (server).
+ *
+ * @remarks
+ * `host` is the vendored-data root `host`-origin artifacts are copied FROM;
+ * defaults to THIS PACKAGE'S OWN vendored data root (`dist/host`, resolved
+ * from the installed module's own location) — the package vendors its host
+ * data and ships it with itself, so the default host is never the caller's
+ * working directory. A caller-supplied `host` pointing at a raw repo root
+ * (no `manifest.json` alongside it) maps artifact paths 1:1 instead of
+ * through the manifest — the sibling-repo / test-fixture shape.
+ */
+export declare interface MaterializerOptions {
+    readonly host?: string;
+    readonly on?: EmitterHooks<MaterializerEventMap>;
+    readonly error?: EmitterErrorHandler;
+}
+
+/**
+ * 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']
+ * ```
+ */
+export declare const PRUNE_DIRECTORIES: readonly [".claude/agents", "scripts"];
+
+/**
+ * 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']
+ * ```
+ */
+export declare function pruneTargets(target: string, host: string): readonly string[];
+
+/**
+ * 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
+ * ```
+ */
+export declare function readHostManifest(host: string): readonly ManifestEntry[] | undefined;
+
+/**
+ * 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", … }'
+ * ```
+ */
+export declare function readManifest(target: string): string;
+
+/**
+ * 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': '…' }
+ * ```
+ */
+export declare function readTarget(target: string, paths: readonly string[]): Readonly<Record<string, string>>;
+
+/**
+ * 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']]
+ * ```
+ */
+export declare function selectOrkestrelEntries(value: unknown): readonly (readonly [string, string])[];
+
+/**
+ * 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
+ * ```
+ */
+export declare function stageHost(root: string, out: string, paths?: readonly string[]): readonly ManifestEntry[];
+
+/**
+ * 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'
+ * ```
+ */
+export declare function storagePath(path: string): string;
+
+/**
+ * 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()
+ * ```
+ */
+export declare class Sync implements SyncInterface {
+    #private;
+    constructor(options?: SyncOptions);
+    get emitter(): EmitterInterface<SyncEventMap>;
+    guides(deps: readonly Dependency[], current?: Readonly<Record<string, string>>): Promise<readonly GuideSync[]>;
+    versions(deps: readonly Dependency[]): Promise<readonly VersionSync[]>;
+    /**
+     * 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.
+     */
+    catalog(): Promise<readonly CatalogEntry[]>;
+    pull(target: string): Promise<SyncReport>;
+    write(report: SyncReport, target: string): Promise<readonly string[]>;
+    destroy(): void;
+}
+
+/**
+ * `Sync`'s push observation surface (AGENTS §13, server).
+ *
+ * @remarks
+ * `package` fires once per `catalog()` entry processed; its `note` is the
+ * empty string when both the registry packument and the guide fetch
+ * succeeded, else a human-readable explanation of which one degraded (and
+ * why) — the same `''`-means-nothing convention `GuideSync.note` /
+ * `VersionSync.note` use, just non-optional here since every `catalog()`
+ * entry emits exactly once regardless of outcome.
+ */
+export declare type SyncEventMap = {
+    readonly guide: readonly [name: string];
+    readonly version: readonly [name: string];
+    readonly package: readonly [name: string, note: string];
+    readonly write: readonly [path: string];
+    readonly done: readonly [report: SyncReport];
+    readonly error: readonly [error: unknown];
+    readonly destroy: readonly [];
+};
+
+/**
+ * The upstream-synchronization contract (server) — the impure FETCH sibling
+ * of `MaterializerInterface`.
+ */
+export declare interface SyncInterface {
+    readonly emitter: EmitterInterface<SyncEventMap>;
+    guides(deps: readonly Dependency[], current?: Readonly<Record<string, string>>): Promise<readonly GuideSync[]>;
+    versions(deps: readonly Dependency[]): Promise<readonly VersionSync[]>;
+    catalog(): Promise<readonly CatalogEntry[]>;
+    pull(target: string): Promise<SyncReport>;
+    write(report: SyncReport, target: string): Promise<readonly string[]>;
+    destroy(): void;
+}
+
+/**
+ * Options for `createSync` / the `Sync` constructor (server).
+ *
+ * @remarks
+ * The endpoint bases + branch are INJECTABLE — `guides.base` defaults to
+ * `raw.githubusercontent.com`, `guides.branch` to `main`, `registry.base` to
+ * `registry.npmjs.org`, and `guides.timeout` / `registry.timeout` to 10
+ * seconds each. `concurrency` bounds in-flight requests (default 6, never an
+ * unbounded `Promise.all`); `retries` opts into per-request retry on a
+ * transport fault (default 0); `strict` flips a collect-mode failure into a
+ * thrown `ScaffoldError('FETCH', …)` (default `false`). `limit` bounds the
+ * bytes read from a single response body (declared `Content-Length` or
+ * streamed total, whichever trips first) — default 5,242,880 (5 MiB); a body
+ * that would exceed it is a transport fault, handled exactly like any other
+ * (retry-eligible per `retries`, then `failed` / strict `FETCH`). Every fetch
+ * is unauthenticated — no token, no `Authorization` header, anywhere; every
+ * fleet repo is public, so plain reachability is the only signal (a guide
+ * `404` degrades gracefully rather than needing credentials).
+ * `registry.base` also anchors `catalog()`'s org package-list lookup
+ * (`<registry.base>/-/org/orkestrel/package`) and its per-package packument
+ * fetches (`<registry.base>/<name>`) — the same base every other registry
+ * read already uses.
+ */
+export declare interface SyncOptions {
+    readonly guides?: {
+        readonly base?: string;
+        readonly branch?: string;
+        readonly timeout?: number;
+    };
+    readonly registry?: {
+        readonly base?: string;
+        readonly timeout?: number;
+    };
+    readonly concurrency?: number;
+    readonly retries?: number;
+    readonly strict?: boolean;
+    readonly limit?: number;
+    readonly on?: EmitterHooks<SyncEventMap>;
+    readonly error?: EmitterErrorHandler;
+}
+
+/**
+ * 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', … }
+ * ```
+ */
+export declare function vendoredPruneSet(host: string, directory: string): ReadonlySet<string>;
+
+export { }