@orkestrel/scaffold 0.0.21 → 0.0.23

package/dist/src/server/index.cjs

@@ -256,7 +256,7 @@ function isManifestEntry(value) {
 * Narrow a value to one exact complete vendored-host manifest.
 *
 * @param value - The candidate manifest value.
-* @returns `true` only for an exact `{ entries, roots }` record with safe paths.
+* @returns `true` only for an exact `{ entries, roots, digest }` record with safe paths.
 */
 function isHostManifest(value) {
 	const result = (0, _orkestrel_contract.attempt)(() => {
@@ -264,7 +264,8 @@ function isHostManifest(value) {
 		const keys = Reflect.ownKeys(value);
 		const entries = Reflect.getOwnPropertyDescriptor(value, "entries");
 		const roots = Reflect.getOwnPropertyDescriptor(value, "roots");
-		return keys.length === 2 && keys.every((key) => key === "entries" || key === "roots") && entries !== void 0 && Reflect.has(entries, "value") && roots !== void 0 && Reflect.has(roots, "value") && (0, _src_core.isDenseDataArray)(entries.value, 4096, isManifestEntry) && (0, _src_core.isDenseDataArray)(roots.value, 4096, isPortablePath);
+		const digest = Reflect.getOwnPropertyDescriptor(value, "digest");
+		return keys.length === 3 && keys.every((key) => key === "entries" || key === "roots" || key === "digest") && entries !== void 0 && Reflect.has(entries, "value") && roots !== void 0 && Reflect.has(roots, "value") && digest !== void 0 && Reflect.has(digest, "value") && (0, _src_core.isDenseDataArray)(entries.value, 4096, isManifestEntry) && (0, _src_core.isDenseDataArray)(roots.value, 4096, isPortablePath) && typeof digest.value === "string" && WRITE_DIGEST_PATTERN.test(digest.value);
 	});
 	return result.success && result.value;
 }
@@ -939,6 +940,19 @@ function digestText(value) {
 	return (0, node_crypto.createHash)("sha256").update(value, "utf8").digest("hex");
 }
 /**
+* Digest the exact declared membership of a vendored host manifest.
+*
+* @param entries - The ordered file membership declarations.
+* @param roots - The ordered directory membership declarations.
+* @returns A SHA-256 digest independent of the manifest's stored digest field.
+*/
+function digestHostManifest(entries, roots) {
+	return digestText((0, _src_core.stableStringify)({
+		entries,
+		roots
+	}));
+}
+/**
 * Render the local pointer written when an upstream dependency guide is not vendored yet.
 *
 * @param source - The canonical `guides/src/<name>.md` source path.
@@ -1772,9 +1786,10 @@ function selectOrkestrelEntries(value) {
 * and the name satisfies `isWorkspaceName`; every other name is a coded
 * `TARGET` failure. `src` is derived from `src/<environment>/` and `app` from
 * `app/<environment>/`; a target with no environment on either axis is also a coded
-* `TARGET` failure. The `bin`, `integration`, and `service` facts probe physical
-* directories at `src/bin`, `tests/integration`, and `tests/service`, respectively,
-* while `global` probes the physical exact-case `tests/setupGlobal.ts` file and `showcase`
+* `TARGET` failure. The `bin` and `integration` facts probe physical
+* directories at `src/bin` and `tests/integration`. `services` is the sorted
+* set of direct vendor directories under `tests/service` that contain a test
+* at any depth, while `global` probes the physical exact-case `tests/setupGlobal.ts` file and `showcase`
 * probes the physical exact-case `configs/app/vite.showcase.config.ts` regular file; none is
 * inferred from the workspace name. `dependencies` /
 * `peers` are the `@orkestrel/`-prefixed entries of `manifest.dependencies` /
@@ -1794,8 +1809,8 @@ function selectOrkestrelEntries(value) {
 * @throws `ScaffoldError('TARGET', …)` when `target`'s manifest is unreadable
 *   (via `readManifest`), is not valid JSON, its name is unsafe for its
 *   publication mode, or `target` carries no source or application environment.
-* @throws `ScaffoldError('TARGET', …)` when `tests/service` exists without the
-*   physical companion files `tests/setupService.ts` and `scripts/service.sh`.
+* @throws `ScaffoldError('INVALID', …)` when service tests use the retired flat
+*   layout, a vendor directory has no test, or a service companion is missing.
 *
 * @example
 * ```ts
@@ -1835,22 +1850,46 @@ function deriveBlueprint(target) {
 	const engines = typeof rawNode === "string" ? rawNode : _src_core.DEFAULT_ENGINES;
 	const bin = isRealDirectory((0, node_path.join)(target, "src", "bin"));
 	const integration = isRealDirectory((0, node_path.join)(target, "tests", "integration"));
-	const service = isRealDirectory((0, node_path.join)(target, "tests", "service"));
+	const serviceRoot = (0, node_path.join)(target, "tests", "service");
+	const services = [];
+	if ((0, node_fs.existsSync)(serviceRoot)) {
+		if (!isRealDirectory(serviceRoot)) throw new _src_core.ScaffoldError("INVALID", `Service root at ${serviceRoot} must be a physical directory`, {
+			target,
+			path: "tests/service"
+		});
+		const serviceEntries = (0, node_fs.readdirSync)(serviceRoot, { withFileTypes: true });
+		const flat = serviceEntries.filter((entry) => entry.name.endsWith(".test.ts") && !entry.isDirectory()).map((entry) => entry.name).sort();
+		if (flat.length > 0) throw new _src_core.ScaffoldError("INVALID", `Flat service tests are not supported; move ${flat.join(", ")} into tests/service/<vendor>/`, {
+			target,
+			paths: flat.map((path) => `tests/service/${path}`)
+		});
+		for (const entry of serviceEntries) {
+			const vendor = (0, node_path.join)(serviceRoot, entry.name);
+			if (!isRealDirectory(vendor)) continue;
+			if (!(0, _src_core.isWorkspaceName)(entry.name)) throw new _src_core.ScaffoldError("INVALID", `Service vendor directory "${entry.name}" must use a bounded lowercase name`, {
+				target,
+				path: `tests/service/${entry.name}`
+			});
+			if (listFiles(vendor).filter((path) => path.endsWith(".test.ts")).length === 0) throw new _src_core.ScaffoldError("INVALID", `Service vendor "${entry.name}" contains no test; add tests/service/${entry.name}/**/*.test.ts or remove the directory`, {
+				target,
+				service: entry.name
+			});
+			const setup = `tests/service/${entry.name}/setup.ts`;
+			if (!isRealFile((0, node_path.join)(target, setup))) throw new _src_core.ScaffoldError("INVALID", `Service vendor "${entry.name}" is missing ${setup}; add a readiness module that probes and warms the vendor and throws when unavailable`, {
+				target,
+				service: entry.name,
+				missing: setup
+			});
+			services.push(entry.name);
+		}
+		services.sort();
+	}
 	const showcaseRoot = (0, node_path.join)(target, (0, node_path.dirname)(_src_core.SHOWCASE_CONFIG_PATH));
 	const showcaseEntries = (0, _orkestrel_contract.attempt)(() => (0, node_fs.readdirSync)(showcaseRoot));
 	const showcase = showcaseEntries.success && showcaseEntries.value.includes((0, node_path.basename)(_src_core.SHOWCASE_CONFIG_PATH)) && isRealFile((0, node_path.join)(target, _src_core.SHOWCASE_CONFIG_PATH));
 	const tests = (0, node_path.join)(target, (0, node_path.dirname)(_src_core.GLOBAL_SETUP_PATH));
 	const entries = (0, _orkestrel_contract.attempt)(() => (0, node_fs.readdirSync)(tests));
 	const global = entries.success && entries.value.includes((0, node_path.basename)(_src_core.GLOBAL_SETUP_PATH)) && isRealFile((0, node_path.join)(target, _src_core.GLOBAL_SETUP_PATH));
-	if (service) {
-		const missing = [];
-		if (!isRealFile((0, node_path.join)(target, "tests", "setupService.ts"))) missing.push("tests/setupService.ts");
-		if (!isRealFile((0, node_path.join)(target, _src_core.SERVICE_SCRIPT_PATH))) missing.push(_src_core.SERVICE_SCRIPT_PATH);
-		if (missing.length > 0) throw new _src_core.ScaffoldError("TARGET", `Service tests under ${target} are missing ${missing.join(" and ")}`, {
-			target,
-			missing
-		});
-	}
 	const rawDependencies = (0, _src_core.ownDataValue)(parsed, "dependencies");
 	const rawPeerDependencies = (0, _src_core.ownDataValue)(parsed, "peerDependencies");
 	const dependencies = selectOrkestrelEntries(rawDependencies).map(([depName, range]) => ({
@@ -1879,7 +1918,7 @@ function deriveBlueprint(target) {
 		extras: [],
 		bin,
 		integration,
-		service,
+		services,
 		global,
 		showcase
 	}))));
@@ -1902,7 +1941,7 @@ function deriveBlueprint(target) {
 		overrides: [],
 		bin,
 		integration,
-		service,
+		services,
 		global,
 		showcase
 	});
@@ -2026,8 +2065,9 @@ function readManifest(target) {
 *   `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, malformed, collision-prone, root-incomplete, or does not map
-*   bijectively and case-exactly onto real contained storage files.
+*   unreadable, malformed, membership-corrupted, collision-prone,
+*   root-incomplete, or does not map bijectively and case-exactly onto real
+*   contained storage files.
 *
 * @example
 * ```ts
@@ -2051,6 +2091,10 @@ function readHostManifest(host) {
 		host,
 		full
 	});
+	if (manifest.digest !== digestHostManifest(manifest.entries, manifest.roots)) throw new _src_core.ScaffoldError("TARGET", `Host manifest membership at ${full} is corrupted`, {
+		host,
+		full
+	});
 	const destinationConflict = (0, _src_core.findFileConflict)(manifest.entries.map((entry) => entry.destination));
 	if (destinationConflict !== void 0) throw new _src_core.ScaffoldError("TARGET", `Host manifest destination collision between "${destinationConflict[0]}" and "${destinationConflict[1]}"`, {
 		host,
@@ -2527,7 +2571,8 @@ function stageHost(root, out, paths = _src_core.HOST_PATHS) {
 	if (rootConflict !== void 0) throw new _src_core.ScaffoldError("TARGET", `Directory collision between "${rootConflict[0]}" and "${rootConflict[1]}"`, { paths: rootConflict });
 	const manifest = {
 		entries,
-		roots: uniqueRoots
+		roots: uniqueRoots,
+		digest: digestHostManifest(entries, uniqueRoots)
 	};
 	const parent = (0, node_path.dirname)((0, node_path.resolve)(out));
 	const name = (0, node_path.basename)((0, node_path.resolve)(out));
@@ -2626,6 +2671,7 @@ function stageHost(root, out, paths = _src_core.HOST_PATHS) {
 *   {
 *     entries: [{ storage: 'pkg.tmpl', destination: 'package.json', executable: false }],
 *     roots: [],
+*     digest: '3b52f19450237ea4cfb39bc7a77b1e5094b52a8ff1fc9c02fd68b13ad088aa0f',
 *   },
 *   'package.json',
 *   './dist/host',
@@ -2738,7 +2784,8 @@ function hydratePlan(plan, host) {
 			});
 			if (entries.length === 0) {
 				if (source.startsWith("guides/src/") && source.endsWith(".md")) {
-					artifacts.push(artifact);
+					const { hex: _hex, ...presenceOwned } = artifact;
+					artifacts.push(presenceOwned);
 					continue;
 				}
 				throw new _src_core.ScaffoldError("TARGET", `Host manifest does not declare ${source}`, {
@@ -3081,9 +3128,10 @@ function catalogPackages(roots, limit = MAX_HOST_ENTRIES) {
 * (`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. Hydrated directory-shaped host entries are expanded into
+* `repair` is into-existing: it skips the vacancy check and writes `missing`
+* artifacts an `Audit` names. `stale` artifacts are report-only unless its
+* `replace` switch is true, because byte replacement discards local changes.
+* Hydrated directory-shaped host entries are expanded into
 * file-shaped artifacts, so canonical skills and agent configuration are
 * audited and repaired file by file. `prune` deletes stale files under
 * `target/.claude/agents/`, `target/.codex/agents/`, and `target/scripts/`
@@ -3114,9 +3162,10 @@ function catalogPackages(roots, limit = MAX_HOST_ENTRIES) {
 * 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
+* destination and reported exactly like a successful copy. The READ path
+* leaves that intentional pointer without canonical bytes, so `diffPlan`
+* treats it as presence-owned rather than inventing a byte match.
+* 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
@@ -3190,16 +3239,16 @@ var Materializer = class {
 		this.#emitter.emit("done", result);
 		return result;
 	}
-	repair(plan, audit, target) {
+	repair(plan, audit, target, replace = false) {
 		this.#ensureAlive();
 		const context = this.#prepare(plan, target, plan, false);
 		if (!(0, _src_core.hasOnlyDataProperties)(audit) || !(0, _src_core.hasValidAuditBytes)(audit)) throw new _src_core.ScaffoldError("INVALID", "repair requires a bounded audit snapshot");
 		const preview = (0, _orkestrel_contract.attempt)(() => structuredClone(audit));
 		if (!preview.success || !Array.isArray(preview.value.findings)) throw new _src_core.ScaffoldError("INVALID", "repair requires a structurally valid audit", { ...preview.success ? {} : { error: preview.error } });
-		const drifted = new Set(preview.value.findings.filter((finding) => finding.drift === "missing" || finding.drift === "stale").map((finding) => finding.path));
+		const selectedPaths = new Set(preview.value.findings.filter((finding) => finding.drift === "missing" || replace === true && finding.drift === "stale").map((finding) => finding.path));
 		const selected = {
 			...context,
-			artifacts: context.artifacts.filter((artifact) => drifted.has(artifact.path))
+			artifacts: context.artifacts.filter((artifact) => selectedPaths.has(artifact.path))
 		};
 		const prepared = this.#prepare(selected, target, context);
 		const preparedByPath = new Map(prepared.artifacts.map((artifact) => [artifact.path, artifact]));
@@ -3223,7 +3272,7 @@ var Materializer = class {
 			throw new _src_core.ScaffoldError("INVALID", `Repair precondition is missing at ${artifact.path}`, { path: artifact.path });
 		});
 		const skipped = [];
-		for (const artifact of context.artifacts) if (!drifted.has(artifact.path)) skipped.push(artifact.path);
+		for (const artifact of context.artifacts) if (!selectedPaths.has(artifact.path)) skipped.push(artifact.path);
 		const { written, copied } = this.#apply(prepared, target, preconditions);
 		const result = {
 			target,
@@ -4190,6 +4239,7 @@ exports.createWriteDirectory = createWriteDirectory;
 exports.deriveBlueprint = deriveBlueprint;
 exports.digestFile = digestFile;
 exports.digestHex = digestHex;
+exports.digestHostManifest = digestHostManifest;
 exports.digestText = digestText;
 exports.discardWriteTransaction = discardWriteTransaction;
 exports.discoverPackages = discoverPackages;