@orkestrel/scaffold 0.0.16 → 0.0.17

package/README.md

@@ -1,7 +1,7 @@
 # @orkestrel/scaffold
 
-Blueprint-to-plan package scaffolding, auditing, dependency guide/version
-pulling, and fleet-wide shared-file upkeep for the `@orkestrel` line.
+Blueprint-to-plan package scaffolding, auditing, dependency guide/version pulling,
+complete guide mirroring, and fleet-wide shared-file upkeep for the `@orkestrel` line.
 
 ## Install
 
@@ -27,6 +27,12 @@ flag from the guided flow works standalone:
 
 ```sh
 npx scaffold new mypackage --src core --app core,browser,server --apply
+
+# refresh every published Orkestrel package guide in the current target
+npx scaffold mirror --apply --yes
+
+# the same command from this checkout, after npm run build
+node ./dist/bin/scaffold.js mirror --apply --yes
 ```
 
 In scripts, every verb is dry-run by default and fully non-interactive —
@@ -48,6 +54,7 @@ Node's default roots. `NODE_EXTRA_CA_CERTS` adds custom PEMs in either case.
 ```sh
 scaffold new [name] [--src <list>] [--app <list>] [--deps <list>] [--apply] [--yes] [--json]
 scaffold pull [--apply] [--yes] [--json]
+scaffold mirror [--apply] [--yes] [--json]
 scaffold audit [--live] [--json]
 scaffold repair [--prune] [--apply] [--yes] [--json]
 scaffold fleet [--apply] [--yes] [--json]
@@ -70,6 +77,9 @@ error.
   its plan from your `package.json` and stays clean over the addition.
 - **`pull`** — fetches the latest vendored dependency guides and registry versions
   for an existing package and reports drift.
+- **`mirror`** — discovers the exact published `@orkestrel/*` package set from npm and refreshes
+  every package's GitHub guide in deterministic name order. It never fetches registry versions or
+  overwrites the target package's own guide, and it applies nothing when any guide fetch fails.
 - **`audit`** — a conformance report over the artifacts the plan actually gates: the
   shared host-origin files (presence, or exact bytes once hydrated) AND the generated
   configs/manifest (exact UTF-8 bytes); reports drift as data, findings and all; exits nonzero
@@ -114,7 +124,7 @@ compiler.destroy()
 
 `@orkestrel/scaffold/server` carries the impure API — `createMaterializer`
 (writes a `Plan` to disk) and `createSync` (the only part of the system that
-touches the network, fetching dependency guides and registry versions).
+touches the network, fetching dependency guides, fleet guide mirrors, and registry versions).
 
 The built host uses an exact `{ entries, roots }` manifest. Staging preflights
 containment and portable file-tree collisions, builds in a temporary sibling,

package/dist/bin/scaffold.js

@@ -15,6 +15,7 @@ import { parseArgs } from "node:util";
 var KNOWN_VERBS = Object.freeze([
 	"new",
 	"pull",
+	"mirror",
 	"audit",
 	"repair",
 	"fleet",
@@ -92,6 +93,7 @@ var EXIT_CODES = Object.freeze([
 var VERB_SUMMARY = Object.freeze({
 	new: "scaffold a workspace into ./<name>",
 	pull: "refresh vendored guides/versions, report drift",
+	mirror: "refresh every published Orkestrel package guide",
 	audit: "whole-plan conformance report",
 	repair: "restore host-owned files, plus generated canon with --generated",
 	fleet: "audit/repair every workspace under the cwd's immediate children",
@@ -101,6 +103,7 @@ 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",
+	mirror: "--target . --apply --yes --strict",
 	audit: "--target . --live --generated --from <path> --groups a,b",
 	repair: "--target . --generated --apply --yes --prune --from <path>",
 	fleet: "--generated --apply --yes --prune --from <path>",
@@ -124,6 +127,12 @@ var VERB_FLAG_HELP = Object.freeze({
 		["--yes", "skip the confirmation question"],
 		["--strict", "fail (exit 1) on any drift, even non-fatal"]
 	],
+	mirror: [
+		["--target .", "directory whose guide mirror is refreshed (default: current directory)"],
+		["--apply", "write the refreshed guides (default is a dry run)"],
+		["--yes", "skip the confirmation question"],
+		["--strict", "fail immediately when an upstream guide cannot be fetched"]
+	],
 	audit: [
 		["--target .", "directory to audit (default: current directory)"],
 		["--live", "also check upstream freshness over the network"],
@@ -158,6 +167,7 @@ var VERB_FLAG_HELP = Object.freeze({
 var VERB_DRY_RUN_NOTE = Object.freeze({
 	new: "dry run by default — add --apply to write the files, --yes to skip the question",
 	pull: "dry run by default — add --apply to write the refreshed files, --yes to skip the question",
+	mirror: "dry run by default — add --apply to write every published package guide, --yes to skip the question",
 	audit: "read-only — audit never writes; pass --live to also check upstream freshness",
 	repair: "dry run by default — add --apply to write, --yes to skip the question",
 	fleet: "dry run by default — add --apply to write across every package, --yes to skip the question",
@@ -167,6 +177,7 @@ var VERB_DRY_RUN_NOTE = Object.freeze({
 var VERB_EXAMPLE = Object.freeze({
 	new: "example: scaffold new widget --src core,server --app core,browser --apply",
 	pull: "example: scaffold pull --apply",
+	mirror: "example: scaffold mirror --apply --yes",
 	audit: "example: scaffold audit --live",
 	repair: "example: scaffold repair --apply",
 	fleet: "example: scaffold fleet --apply --yes",
@@ -355,8 +366,8 @@ function repairSuccess(result, removed) {
 	const written = result.written.length + result.copied.length;
 	return `${ACTION_LABEL.written} ${written}, ${ACTION_LABEL.skipped} ${result.skipped.length}, ${ACTION_LABEL.removed} ${removed.length}`;
 }
-/** Render pull freshness as table rows. */
-function pullRows(report) {
+/** Render synchronization freshness as table rows. */
+function syncRows(report) {
 	const guides = report.guides.map((guide) => [
 		guide.name,
 		"guide",
@@ -369,27 +380,28 @@ function pullRows(report) {
 	]);
 	return [...guides, ...versions];
 }
-/** Create pull's terminal table. */
-function pullTable(report) {
+/** Create a synchronization terminal table. */
+function syncTable(report) {
 	return {
 		columns: [
 			{ label: "Name" },
 			{ label: "Kind" },
 			{ label: "Freshness" }
 		],
-		rows: pullRows(report)
+		rows: syncRows(report)
 	};
 }
-/** Render cause notes from non-current pull entries. */
-function pullCauseNotes(report) {
+/** Render cause notes from non-current synchronization entries. */
+function syncCauseNotes(report) {
 	return [...report.guides, ...report.versions].filter((entry) => entry.note !== void 0).map((entry) => `  ${entry.name}: ${FRESHNESS_LABEL[entry.freshness] ?? entry.freshness} — ${entry.note}`);
 }
-/** Render pull's tally. */
-function pullVerdict(report) {
-	return `pull: ${countPart(report.guides.length + report.versions.length, "entry")} — ${countPart(report.failed, "failed")}`;
+/** Render a command-specific synchronization tally. */
+function syncVerdict(report, action) {
+	const count = report.guides.length + report.versions.length;
+	return `${action}: ${String(count)} ${count === 1 ? "entry" : "entries"} — ${String(report.failed)} failed`;
 }
-/** Render pull's success tally. */
-function pullSuccess(count) {
+/** Render a synchronization success tally. */
+function syncSuccess(count) {
 	return `wrote ${countPart(count, "guide")}`;
 }
 /** Render one fleet repository outcome. */
@@ -1117,30 +1129,52 @@ var CLI = class {
 			} catch (error) {
 				this.#error(error, json);
 			}
-			if (!json) {
-				this.#reporter.table(pullTable(report));
-				for (const line of pullCauseNotes(report)) this.#reporter.line(line);
-				this.#reporter.line(pullVerdict(report));
+			await this.#refresh(sync, report, target, values, json, "pull", true);
+		} finally {
+			sync.destroy();
+		}
+	}
+	/** `scaffold mirror` — refresh every published Orkestrel package guide. */
+	async #mirror(values, json) {
+		const target = this.#contain(values.target ?? ".", json);
+		const sync = createSync(values.strict === void 0 ? this.#sync : {
+			...this.#sync,
+			strict: values.strict
+		});
+		try {
+			let report;
+			try {
+				report = await sync.mirror(target);
+			} catch (error) {
+				this.#error(error, json);
 			}
-			const toWrite = [...report.guides, ...report.versions].filter((entry) => entry.freshness !== "current").length;
-			const terminal = createTerminal();
-			const proceed = toWrite > 0 ? await this.#apply(terminal, applyConfirmMessage(toWrite), values, json) : false;
-			if (proceed) {
-				const spinner = this.#spinner("writing mirrors", json);
-				spinner?.start();
-				try {
-					const written = await sync.write(report, target);
-					if (json) this.#write(report);
-					else this.#succeed(spinner, json, pullSuccess(written.length));
-				} catch (error) {
-					this.#reject(spinner, json, error);
-				}
-			} else if (json) this.#write(report);
-			process.exitCode = report.clean ? 0 : proceed ? 0 : 1;
+			await this.#refresh(sync, report, target, values, json, "mirror", report.failed === 0);
 		} finally {
 			sync.destroy();
 		}
 	}
+	async #refresh(sync, report, target, values, json, action, writable) {
+		if (!json) {
+			this.#reporter.table(syncTable(report));
+			for (const line of syncCauseNotes(report)) this.#reporter.line(line);
+			this.#reporter.line(syncVerdict(report, action));
+		}
+		const toWrite = [...report.guides, ...report.versions].filter((entry) => entry.freshness !== "current").length;
+		const terminal = createTerminal();
+		const proceed = writable && toWrite > 0 ? await this.#apply(terminal, applyConfirmMessage(toWrite), values, json) : false;
+		if (proceed) {
+			const spinner = this.#spinner("writing mirrors", json);
+			spinner?.start();
+			try {
+				const written = await sync.write(report, target);
+				if (json) this.#write(report);
+				else this.#succeed(spinner, json, syncSuccess(written.length));
+			} catch (error) {
+				this.#reject(spinner, json, error);
+			}
+		} else if (json) this.#write(report);
+		process.exitCode = report.clean ? 0 : proceed ? 0 : 1;
+	}
 	/** `scaffold audit` — whole-plan conformance report; offers a repair handoff on drift. */
 	async #audit(values, json) {
 		const target = this.#contain(values.target ?? ".", json);
@@ -1602,6 +1636,7 @@ var CLI = class {
 		}
 		if (!isVerb(command)) this.#usage(didYouMean(command), json);
 		if (command !== "catalog" && values.from !== void 0 && values.from.length > 1) this.#usage(`--from may be provided only once for '${command}'`, json);
+		if (command === "mirror" && values.deps !== void 0) this.#usage("--deps is not supported for 'mirror'; use 'pull --deps'", json);
 		if (values.help) {
 			process.stdout.write(`${verbHelp(command)}\n`);
 			process.exitCode = 0;
@@ -1609,6 +1644,7 @@ var CLI = class {
 		}
 		if (command === "new") return this.#new(values, argument, json);
 		if (command === "pull") return this.#pull(values, json);
+		if (command === "mirror") return this.#mirror(values, json);
 		if (command === "audit") return this.#audit(values, json);
 		if (command === "repair") return this.#repair(values, json);
 		if (command === "fleet") return this.#fleet(values, json);