@orkestrel/scaffold 0.0.7 → 0.0.9

package/dist/bin/scaffold.js

@@ -2,7 +2,7 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
 import * as tls from "node:tls";
-import { DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, GROUPS, MAX_ARTIFACT_BYTES, NAME_PATTERN, ScaffoldError, blueprint, catalogNames, catalogToBlock, createCompiler, dependency, diffPlan, isScaffoldError, manifestToDependencies, manifestToName, planToSummary } from "../src/core/index.js";
+import { DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, GROUPS, MAX_ARTIFACT_BYTES, NAME_PATTERN, SERVICE_SCRIPT_PATH, ScaffoldError, blueprint, catalogNames, catalogToBlock, createCompiler, dependency, diffPlan, isScaffoldError, manifestToDependencies, manifestToName, planToSummary } from "../src/core/index.js";
 import { WriteTransaction, catalogPackages, commitWriteTransaction, createMaterializer, createSync, deriveBlueprint, digestFile, digestText, discardWriteTransaction, discoverPackages, hostRoot, hydratePlan, isFilesystemPath, isRealDirectory, isTerminalText, isVacant, locateHostSource, parseSyncOptions, pruneTargets, readFileText, readHostManifest, readManifest, readTarget, resolvePhysicalPath, validateWriteDirectories } from "../src/server/index.js";
 import { createReporter, createSpinner, createStyler } from "@orkestrel/console";
 import { createServerSink } from "@orkestrel/console/server";
@@ -49,6 +49,8 @@ var ACTION_LABEL = Object.freeze({
 });
 /** Repair's deliberately limited ownership boundary. */
 var REPAIR_SCOPE = "repair scope: shared host-owned artifacts only — starter and generated files are never touched";
+/** Repair's opt-in generated-canon ownership boundary. */
+var REPAIR_GENERATED_SCOPE = "repair scope: shared host-owned and generated artifacts — starter files and package.json are never touched";
 /** The dry-run note for `new`. */
 var NEW_DRY_RUN_NOTE = "dry run — pass --apply to write";
 /** The fallback message for a malformed command line without an error message. */
@@ -91,7 +93,7 @@ var VERB_SUMMARY = Object.freeze({
 	new: "scaffold a workspace into ./<name>",
 	pull: "refresh vendored guides/versions, report drift",
 	audit: "whole-plan conformance report",
-	repair: "restore the shared host-owned set",
+	repair: "restore host-owned files, plus generated canon with --generated",
 	fleet: "audit/repair every workspace under the cwd's immediate children",
 	catalog: "regenerate the fleet package-catalog table"
 });
@@ -99,9 +101,9 @@ var VERB_SUMMARY = Object.freeze({
 var VERB_FLAGS = Object.freeze({
 	new: "--src a,b --app a,b --deps x,y --apply --yes --target <path> --from <path>",
 	pull: "--target . --deps x,y --apply --yes --strict",
-	audit: "--target . --live --from <path> --groups a,b",
-	repair: "--target . --apply --yes --prune --from <path>",
-	fleet: "--apply --yes --prune --from <path>",
+	audit: "--target . --live --generated --from <path> --groups a,b",
+	repair: "--target . --generated --apply --yes --prune --from <path>",
+	fleet: "--generated --apply --yes --prune --from <path>",
 	catalog: "--from <path> ... --target <repo> --offline --apply --yes"
 });
 /** Plain-language command flag descriptions. */
@@ -125,17 +127,20 @@ var VERB_FLAG_HELP = Object.freeze({
 	audit: [
 		["--target .", "directory to audit (default: current directory)"],
 		["--live", "also check upstream freshness over the network"],
+		["--generated", "include generated canon if the repair hand-off is accepted"],
 		["--from <path>", "read the template from a local path instead of the bundled one"],
 		["--groups a,b", "limit the audit to these artifact groups"]
 	],
 	repair: [
 		["--target .", "directory to repair (default: current directory)"],
+		["--generated", "also restore generated canon except package.json"],
 		["--apply", "write the fixes (default is a dry run)"],
 		["--yes", "skip the confirmation question"],
 		["--prune", "also DELETE unexpected files under .claude/agents, .codex/agents, and scripts"],
 		["--from <path>", "read the template from a local path instead of the bundled one"]
 	],
 	fleet: [
+		["--generated", "also restore generated canon except package.json in every package"],
 		["--apply", "write fixes across every package (default is a dry run)"],
 		["--yes", "skip the confirmation question"],
 		["--prune", "also DELETE unexpected files under .claude/agents, .codex/agents, and scripts, per package"],
@@ -322,15 +327,28 @@ function auditTable(audit, plan) {
 		rows: findingRows(audit.findings, plan)
 	};
 }
-/** Render drift outside repair's ownership boundary. */
-function scopeNote(count) {
+/**
+* Render drift outside repair's selected ownership boundary.
+*
+* @param count - The number of findings outside the selected scope.
+* @param generated - Whether generated canon was included in the repair scope.
+* @returns The scope guidance line, or `undefined` when no findings remain outside scope.
+*/
+function scopeNote(count, generated) {
 	if (count === 0) return void 0;
-	return `note: ${countPart(count, "finding")} outside repair's scope — run 'audit' for the list; generated files are yours to edit`;
+	return generated ? `note: ${countPart(count, "finding")} outside host-owned and generated repair scope — run 'audit' for the list; starter files and package.json remain protected` : `note: ${countPart(count, "finding")} outside host-owned repair scope — run 'audit' for the list`;
 }
-/** Render repair's dry-run verdict. */
-function repairVerdict(audit) {
-	if (audit.clean) return `repair: ${countPart(audit.findings.length, "host-owned artifact")} aligned — nothing to write`;
-	return `repair: ${bucketText(audit)} — pass --apply to write`;
+/**
+* Render repair's dry-run verdict.
+*
+* @param audit - The audit over the selected repair plan.
+* @param generated - Whether generated canon was included in the repair scope.
+* @returns The scope-aware clean or drifted verdict.
+*/
+function repairVerdict(audit, generated) {
+	const scope = generated ? "host-owned and generated" : "host-owned";
+	if (audit.clean) return `repair: ${countPart(audit.findings.length, `${scope} artifact`)} aligned — nothing to write`;
+	return `repair: ${scope}: ${bucketText(audit)} — pass --apply to write`;
 }
 /** Render repair's materialization tally. */
 function repairSuccess(result, removed) {
@@ -537,7 +555,28 @@ function unresolvedVersion(names) {
 }
 /** Render drift that belongs to generated artifacts. */
 function generatedNote(count) {
-	return `${countPart(count, "finding")} in generated files — these are regenerated, not hand-edited; repair does not touch them`;
+	return `${countPart(count, "finding")} in generated files — these are regenerated, not hand-edited; run 'scaffold repair --generated' to restore them`;
+}
+/**
+* Render honest repair guidance for computed and protected manifest drift.
+*
+* @param findings - The audit findings to classify.
+* @param plan - The plan that owns each computed artifact.
+* @returns One line for repairable computed drift and one for protected manifest drift when present.
+*/
+function renderComputedNotes(findings, plan) {
+	const origins = new Map(plan.artifacts.map((artifact) => [artifact.path, artifact.origin]));
+	let computed = 0;
+	let manifest = 0;
+	for (const finding of findings) {
+		if (finding.drift === "aligned" || origins.get(finding.path) !== "computed") continue;
+		if (finding.path === "package.json") manifest += 1;
+		else computed += 1;
+	}
+	const notes = [];
+	if (computed > 0) notes.push(generatedNote(computed));
+	if (manifest > 0) notes.push(`${countPart(manifest, "finding")} in package.json — repair does not rewrite protected publication metadata; review and edit it directly`);
+	return notes;
 }
 /** Render live dependency freshness tallies. */
 function auditLiveNote(current, behind, failed) {
@@ -604,6 +643,10 @@ function parseArguments(argv) {
 				type: "boolean",
 				default: false
 			},
+			generated: {
+				type: "boolean",
+				default: false
+			},
 			strict: {
 				type: "boolean",
 				default: false
@@ -766,17 +809,22 @@ var CLI = class {
 			compiler.destroy();
 		}
 	}
+	#prunePaths(target, host, service) {
+		const seam = service ? SERVICE_SCRIPT_PATH : void 0;
+		return pruneTargets(target, host).filter((path) => path !== seam);
+	}
 	/**
-	* Merge a `pruneTargets` scan into `audit` as `foreign` findings — pure
+	* Merge the physical prune scan into `audit` as `foreign` findings — pure
 	* object-spread composition in the BIN only (`src/core`'s `diffPlan` is never
-	* modified/reimplemented). Every unexpected path becomes one
-	* `'orchestration'`-group `foreign` finding (the `Group` every `PRUNE_DIRECTORIES`
-	* entry—`.claude/agents`, `.codex/agents`, `scripts`—belongs to); any scan hit makes the
-	* merged audit unclean, so an "unexpected file" is honestly counted as drift
-	* (exit 1) instead of the structurally-always-zero `diffPlan.foreign`.
+	* modified/reimplemented). Every unexpected path except the declared service
+	* workspace's exact `SERVICE_SCRIPT_PATH` becomes one `'orchestration'`-group
+	* `foreign` finding (the `Group` every `PRUNE_DIRECTORIES` entry—`.claude/agents`,
+	* `.codex/agents`, `scripts`—belongs to); any scan hit makes the merged audit
+	* unclean, so an "unexpected file" is honestly counted as drift (exit 1)
+	* instead of the structurally-always-zero `diffPlan.foreign`.
 	*/
-	#scan(audit, target, host) {
-		const paths = pruneTargets(target, host);
+	#scan(audit, target, host, service) {
+		const paths = this.#prunePaths(target, host, service);
 		if (paths.length === 0) return audit;
 		const findings = paths.map((path) => ({
 			path,
@@ -795,8 +843,8 @@ var CLI = class {
 	* When fail-closed allowlist discovery raises a coded `TARGET` failure, retain
 	* the existing findings and mark the audit incomplete instead of crashing.
 	*/
-	#scanSafe(audit, target, host) {
-		const scanned = attempt(() => this.#scan(audit, target, host));
+	#scanSafe(audit, target, host, service) {
+		const scanned = attempt(() => this.#scan(audit, target, host, service));
 		if (scanned.success) return {
 			audit: scanned.value,
 			skipped: false
@@ -817,9 +865,9 @@ var CLI = class {
 		throw scanned.error;
 	}
 	/**
-	* `repair`'s own scope is host-only, but the caller compiles the FULL plan anyway — diff it too
-	* (cheap, local, no network) so a clean host verdict can point at drift OUTSIDE repair's reach.
-	* The count feeds the shared `scopeNote` renderer.
+	* `repair` scopes to host-owned artifacts by default and optionally generated canon, but the
+	* caller compiles the full plan anyway. Diff it too so a clean scoped verdict can point at drift
+	* outside the selected boundary. The count feeds the shared `scopeNote` renderer.
 	*/
 	#outside(compiled, target) {
 		const full = diffPlan(compiled, readTarget(target, compiled.artifacts.map((artifact) => artifact.path)));
@@ -1093,7 +1141,7 @@ var CLI = class {
 			...diffPlan(plan, readTarget(target, artifactPaths)),
 			questions
 		};
-		const scanned = this.#scanSafe(rawAudit, target, host);
+		const scanned = this.#scanSafe(rawAudit, target, host, spec.service);
 		const audit = scanned.audit;
 		let drifted = !audit.clean;
 		let live;
@@ -1134,7 +1182,6 @@ var CLI = class {
 		if (!audit.clean) {
 			const split = partitionFindings(audit.findings, plan);
 			const ownedCount = split.owned.drifted + split.owned.missing;
-			const computedCount = split.generated.drifted + split.generated.missing;
 			const pruneRequested = values.prune === true;
 			const offerHandoff = this.#tty && (ownedCount > 0 || audit.foreign > 0 && pruneRequested);
 			let handoffAccepted = false;
@@ -1148,19 +1195,19 @@ var CLI = class {
 				if (handoffAccepted) {
 					await this.#repair(values, false);
 					const rawFinal = diffPlan(plan, readTarget(target, artifactPaths));
-					const finalScanned = this.#scanSafe(rawFinal, target, host);
+					const finalScanned = this.#scanSafe(rawFinal, target, host, spec.service);
 					process.exitCode = finalScanned.audit.clean ? 0 : 1;
 					return;
 				}
 			}
 			if (!handoffAccepted) {
 				if (audit.foreign > 0 && !pruneRequested) this.#reporter.line(FOREIGN_HINT);
-				if (computedCount > 0) this.#reporter.line(generatedNote(computedCount));
+				for (const note of renderComputedNotes(audit.findings, plan)) this.#reporter.line(note);
 			}
 		}
 		process.exitCode = drifted ? 1 : 0;
 	}
-	/** `scaffold repair` — restore the shared host-owned set for one target. */
+	/** `scaffold repair` — restore host-owned files and optionally generated canon for one target. */
 	async #repair(values, json) {
 		const target = this.#contain(values.target ?? ".", json);
 		let spec;
@@ -1170,13 +1217,14 @@ var CLI = class {
 			this.#error(error, json);
 		}
 		const [compiled] = this.#compile(spec, json);
+		const generated = values.generated === true;
 		const scoped = {
 			...compiled,
 			blueprint: {
 				...compiled.blueprint,
 				overrides: []
 			},
-			artifacts: compiled.artifacts.filter((artifact) => artifact.origin === "host")
+			artifacts: compiled.artifacts.filter((artifact) => artifact.origin === "host" || generated && artifact.origin === "computed" && artifact.path !== "package.json")
 		};
 		const host = values.from?.[0] ?? hostRoot();
 		let plan;
@@ -1192,23 +1240,23 @@ var CLI = class {
 			this.#error(error, json);
 		}
 		if (!json) {
-			this.#reporter.line(REPAIR_SCOPE);
+			this.#reporter.line(generated ? REPAIR_GENERATED_SCOPE : REPAIR_SCOPE);
 			this.#reporter.section("Audit");
 			this.#reporter.table(auditTable(audit, plan));
 		}
-		const prunePaths = values.prune ? pruneTargets(target, host) : [];
+		const prunePaths = values.prune ? this.#prunePaths(target, host, spec.service) : [];
 		const pruneSnapshot = readTarget(target, prunePaths);
 		if (audit.clean && prunePaths.length === 0) {
 			if (json) this.#write(audit);
 			else {
-				this.#reporter.line(repairVerdict(audit));
-				const note = scopeNote(this.#outside(compiled, target));
+				this.#reporter.line(repairVerdict(audit, generated));
+				const note = scopeNote(this.#outside(compiled, target), generated);
 				if (note !== void 0) this.#reporter.line(note);
 			}
 			process.exitCode = 0;
 			return;
 		}
-		if (!json) this.#reporter.line(repairVerdict(audit));
+		if (!json) this.#reporter.line(repairVerdict(audit, generated));
 		const terminal = createTerminal();
 		let proceed = true;
 		if (!audit.clean) proceed = await this.#apply(terminal, applyConfirmMessage(audit.drifted + audit.missing + audit.foreign), values, json);
@@ -1241,6 +1289,7 @@ var CLI = class {
 	/** `scaffold fleet` — audit/repair every `@orkestrel` package beneath the current directory's immediate children. */
 	async #fleet(values, json) {
 		const root = this.#contain(".", json);
+		const generated = values.generated === true;
 		const packages = discoverPackages(root);
 		if (packages.length === 0) this.#fail(`no @orkestrel packages under "${root}" — fleet scans the immediate children of the current directory; stand in the folder that contains your checkouts (cd ..), or use 'repair' to true up just this repo.`, json);
 		const host = values.from?.[0] ?? hostRoot();
@@ -1262,7 +1311,7 @@ var CLI = class {
 							...scaffolding.plan.blueprint,
 							overrides: []
 						},
-						artifacts: scaffolding.plan.artifacts.filter((artifact) => artifact.origin === "host")
+						artifacts: scaffolding.plan.artifacts.filter((artifact) => artifact.origin === "host" || generated && artifact.origin === "computed" && artifact.path !== "package.json")
 					};
 					questions = scaffolding.questions;
 				} finally {
@@ -1273,7 +1322,7 @@ var CLI = class {
 					...diffPlan(plan, readTarget(directory, plan.artifacts.map((artifact) => artifact.path))),
 					questions
 				};
-				const audit = this.#scan(rawAudit, directory, host);
+				const audit = this.#scan(rawAudit, directory, host, plan.blueprint.service);
 				repos.push({
 					name,
 					directory,
@@ -1313,7 +1362,7 @@ var CLI = class {
 		const terminal = createTerminal();
 		const proceed = await this.#apply(terminal, applyConfirmMessage(fileCount, dirty.length), values, json);
 		const pruneSets = proceed && values.prune ? new Map(dirty.map((repo) => {
-			const paths = pruneTargets(repo.directory, host);
+			const paths = this.#prunePaths(repo.directory, host, repo.plan.blueprint.service);
 			return [repo.name, readTarget(repo.directory, paths)];
 		})) : /* @__PURE__ */ new Map();
 		const prunePaths = dirty.flatMap((repo) => Object.keys(pruneSets.get(repo.name) ?? {}).map((path) => `${repo.name}/${path}`));
@@ -1336,7 +1385,7 @@ var CLI = class {
 				if (doPrune) materializer.prune(repo.directory, pruneSets.get(repo.name) ?? {});
 				const paths = repo.plan.artifacts.map((artifact) => artifact.path);
 				const rawFinal = diffPlan(repo.plan, readTarget(repo.directory, paths));
-				const finalAudit = this.#scan(rawFinal, repo.directory, host);
+				const finalAudit = this.#scan(rawFinal, repo.directory, host, repo.plan.blueprint.service);
 				if (!finalAudit.clean) drifted += 1;
 				entries.push(fleetEntryOf(repo.name, finalAudit, false));
 				if (!json) this.#reporter.line(fleetRepoLine(repo.name, {