@orkestrel/scaffold 0.0.44 → 0.0.45

package/README.md

@@ -13,7 +13,7 @@ a workspace from it, report how a workspace differs from it, and write the diffe
 npm install --save-dev @orkestrel/scaffold
 ```
 
-The executable needs Node 22.12 or newer. Run it without installing anything:
+The executable needs Node 22.12 or later. Run it without installing anything:
 
 ```sh
 npx @orkestrel/scaffold --help
@@ -21,7 +21,7 @@ npx @orkestrel/scaffold --help
 
 ## Verbs
 
-Five verbs. Authority is the verb's: every verb except `audit` writes when it is typed, and no
+Authority is the verb's: every verb except `audit` writes when it is typed, and no
 option grants a write. Exit codes are `0` clean, `1` drift or failure, and `2` usage error.
 
 `--target <path>` points any verb at another directory; the working directory is the default.
@@ -74,20 +74,20 @@ Reads the organization's published package list, rewrites the marker-bounded tab
 npx scaffold overwrite --dirty
 ```
 
-Everything `repair` and `catalog` do, plus the two steps only this verb carries: it deletes tracked
+Everything `repair` and `catalog` do, plus the steps only this verb carries: it deletes tracked
 files the plan does not own, and it rewrites the `@orkestrel/*` ranges in the manifest to the
 registry's latest releases. It needs a git repository, and it refuses a tree carrying uncommitted
 changes unless `--dirty` waives that refusal.
 
 ## Library
 
-Two entry points, split by host. `@orkestrel/scaffold` is host-independent: it compiles, gates, and
+The entry points split by host. `@orkestrel/scaffold` is host-independent: it compiles, gates, and
 compares.
 
 ```ts
-import { createBlueprint, createCompiler } from '@orkestrel/scaffold'
+import { Compiler, createBlueprint } from '@orkestrel/scaffold'
 
-const compiler = createCompiler()
+const compiler = new Compiler()
 const scaffolding = compiler.compile(createBlueprint('router', { src: ['core', 'server'] }))
 
 scaffolding.plan?.artifacts // every planned file, in group order
@@ -95,21 +95,21 @@ scaffolding.questions // the advice the compile could not settle
 compiler.destroy()
 ```
 
-A plan says the workspace can be built. It does not say the workspace should be created: a caller
+A plan says the workspace can be built. It does not decide whether to create it: a caller
 creating a fresh workspace refuses on any question beside the plan, blocking or not, exactly as
 `new` does. [`guides/scaffold.md`](guides/scaffold.md) states that rule and what it covers.
 
 `@orkestrel/scaffold/server` is Node-only and holds everything that touches the filesystem or the
-network: `createMaterializer` writes a plan into a target, `createUpstream` reads the registry and
+network: `Materializer` writes a plan into a target, `Upstream` reads the registry and
 the guide host, and `WriteTransaction` stages and swaps a set of files with rollback.
 
 ```ts
 import type { Plan } from '@orkestrel/scaffold'
-import { createMaterializer } from '@orkestrel/scaffold/server'
+import { Materializer } from '@orkestrel/scaffold/server'
 
 declare const plan: Plan
 
-const materializer = createMaterializer()
+const materializer = new Materializer()
 const result = materializer.materialize(plan, './packages/router')
 
 result.written // every path created

package/dist/bin/main.js

@@ -2,9 +2,9 @@
 import { align, renderTable, strip, stripControls, width } from "@orkestrel/console";
 import { attempt, isRecord, isString, parseJSON } from "@orkestrel/contract";
 import { createMarkdown, flattenText, isTableNode } from "@orkestrel/markdown";
-import { runSync } from "@orkestrel/process/server";
-import { BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFORMANCE_TEST_PATH, DEPENDENCY_NAME_PATTERN, DISTRIBUTION_TEST_PATH, ENVIRONMENTS, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, INTEGRATION_TEST_PATH, MAX_MANIFEST_BYTES, SERVICE_SETUP_PATH, SHOWCASE_CONFIG_PATH, ScaffoldError, blueprintToDevDependencies, blueprintToRootVite, blueprintToScripts, createBlueprint, createCompiler, isScaffoldError, manifestToDependencies, manifestToName, nameToGuide } from "../src/core/index.js";
-import { createMaterializer, createUpstream, isExactCaseFile, isPhysicalDirectory, isRepository, listFiles, readFileText, readSnapshot, resolveContainedPath } from "../src/server/index.js";
+import { executeSync } from "@orkestrel/process/server";
+import { BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFORMANCE_TEST_PATH, Compiler, DEPENDENCY_NAME_PATTERN, DISTRIBUTION_TEST_PATH, ENVIRONMENTS, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, INTEGRATION_TEST_PATH, MAX_MANIFEST_BYTES, SERVICE_SETUP_PATH, SHOWCASE_CONFIG_PATH, ScaffoldError, blueprintToDevDependencies, blueprintToRootVite, blueprintToScripts, createBlueprint, isScaffoldError, manifestToDependencies, manifestToName, nameToGuide } from "../src/core/index.js";
+import { Materializer, Upstream, isExactCaseFile, isPhysicalDirectory, isRepository, listFiles, readFileText, readSnapshot, resolveContainedPath } from "../src/server/index.js";
 import { parseArgs } from "node:util";
 //#region src/bin/constants.ts
 /**
@@ -17,12 +17,12 @@ import { parseArgs } from "node:util";
 */
 var EXECUTABLE_NAME = "scaffold";
 /**
-* The five {@link Verb} values in usage order, frozen.
+* The {@link Verb} values in usage order, frozen.
 *
 * @remarks
 * The order the type declares them in, which is also the order usage lists them:
 * the verb that creates a workspace, then the one that only reads it, then the
-* three that write to one that already exists, widest last.
+* ones that write to one that already exists, widest last.
 */
 var VERBS = Object.freeze([
 	"new",
@@ -35,7 +35,7 @@ var VERBS = Object.freeze([
 * What each exit code means, frozen.
 *
 * @remarks
-* Keyed by the three code constants rather than by literals, so the usage block
+* Keyed by the code constants rather than by literals, so the usage block
 * cannot document a code the executable does not return.
 */
 var EXIT_SUMMARY = Object.freeze({
@@ -62,7 +62,7 @@ var FAILED_MESSAGE = "The command failed for an unrecognized reason";
 *
 * @remarks
 * The workspace name is the only positional argument any verb takes, so it is
-* one value rather than a per-verb table with four holes in it.
+* one value rather than a per-verb table with holes in it.
 */
 var NAME_ARGUMENT = "<name>";
 /**
@@ -107,7 +107,7 @@ var OPTION_SUMMARY = Object.freeze({
 	"--bin": "scaffold a command-line executable at src/bin/main.ts",
 	"--deps <list>": "the @orkestrel/* packages the workspace depends on",
 	"--groups <list>": "the artifact groups to cover; every group when absent",
-	"--all": "fetch a guide for every package the organization publishes, not just the declared ones",
+	"--all": "fetch a guide for every package the organization publishes, not the declared ones alone",
 	"--dirty": "delete from a tree carrying uncommitted changes",
 	"--from <path>": "read the data root from a local path instead of the bundled one; catalog alone accepts it more than once",
 	"--target <path>": "the directory the verb operates on; the working directory when absent",
@@ -178,7 +178,7 @@ var VERB_SUMMARY = Object.freeze({
 * The error raised when a command line is not a command.
 *
 * @remarks
-* Distinct from `ScaffoldError` because the two answer different questions and
+* Distinct from `ScaffoldError` because they answer different questions and
 * exit differently: a `ScaffoldError` says the package could not serve a
 * well-formed request and exits `1`, while this says there was no request to
 * serve and exits `2`. Folding a usage error into `INVALID` would report a
@@ -240,7 +240,7 @@ function isUsageError(value) {
 * @remarks
 * One token serves both readers: a person reads the value placeholder and the
 * parser reads the name in front of it. Deriving the name means a documented
-* option and an accepted option cannot be two different lists.
+* option and an accepted option cannot be separate lists.
 *
 * @example
 * ```ts
@@ -283,9 +283,9 @@ function verbToSyntax(verb) {
 * @remarks
 * Returned as lines because the executable writes through a handler that takes
 * one line, so the caller never has to split a block back apart. The glossary is
-* printed once for every verb rather than repeated per verb, since seven of the
-* nine options are shared and a reader comparing two verbs wants the difference,
-* not the repetition.
+* printed once for every verb rather than repeated per verb, because
+* `--from <path>`, `--target <path>`, and `--json` are shared by every verb and
+* a reader comparing two verbs wants the difference, not the repetition.
 */
 function renderUsage() {
 	const summaries = Object.entries(OPTION_SUMMARY);
@@ -312,10 +312,10 @@ function renderUsage() {
 * @remarks
 * The one place untrusted argument text becomes a domain value, and it stays one
 * function because the command union admits no partial command to hand on: every
-* refusal has to happen before the value exists. It refuses in four ways, each
+* refusal has to happen before the value exists. It refuses in these ways, each
 * naming what was wrong — a word that is not a verb, a word that is not an
 * option, an option this verb does not take, and an argument this verb does not
-* take. `node:util` decides the second and this decides the rest, so an unknown
+* take. `node:util` decides the unknown option and this decides the rest, so an unknown
 * option is reported by the parser that found it rather than re-derived here.
 *
 * A request for usage is not a command and never reaches this: the caller
@@ -441,7 +441,7 @@ function auditToExit(audit) {
 *
 * @remarks
 * A blocking question means the gate produced no plan, so the target was not
-* compared and no finding count is reported. Otherwise the three grounds
+* compared and no finding count is reported. Otherwise the grounds
 * describe what this run did. `bytes` means content-owned
 * bytes were observed, `existence` means presence or absence alone decided the
 * finding, and `nothing` means a birth-owned path was not examined. Foreign
@@ -524,8 +524,8 @@ function errorToEnvelope(error) {
 * upstream reader is built the same way but from the options, because no
 * command line names an endpoint: a terminal caller means the published
 * registry and the published guide host, and only the process driving the
-* executable can mean anything else. That is the seam that makes the three
-* verbs which read the network provable without one.
+* executable can mean anything else. That is the seam that makes the verbs
+* which read the network provable without one.
 *
 * @example
 * ```ts
@@ -543,7 +543,7 @@ var CLI = class CLI {
 	#diagnostic;
 	#upstream;
 	/**
-	* Construct the executable over the two destinations it writes to.
+	* Construct the executable over the destinations it writes to.
 	*
 	* @param options - The report and diagnostic handlers and the upstream
 	* endpoints; the process streams and the published endpoints when absent.
@@ -605,7 +605,7 @@ var CLI = class CLI {
 			dependencies: await this.#resolve(this.#packages(command.dependencies))
 		});
 		const plan = this.#compile(blueprint);
-		const materializer = createMaterializer(command.from === void 0 ? void 0 : { host: command.from });
+		const materializer = new Materializer(command.from === void 0 ? void 0 : { host: command.from });
 		try {
 			const result = materializer.materialize(plan, target);
 			if (command.json === true) this.#report(result);
@@ -622,7 +622,7 @@ var CLI = class CLI {
 		const target = command.target ?? ".";
 		const blueprint = this.#derive(target);
 		const questions = this.#targetQuestions(target, blueprint);
-		const materializer = createMaterializer(command.from === void 0 ? void 0 : { host: command.from });
+		const materializer = new Materializer(command.from === void 0 ? void 0 : { host: command.from });
 		try {
 			const [measured] = this.#survey(materializer, blueprint, target, this.#groups(command.groups));
 			const audit = questions.length === 0 ? measured : {
@@ -641,7 +641,7 @@ var CLI = class CLI {
 		const groups = this.#groups(command.groups);
 		const blueprint = this.#derive(target);
 		this.#assertTarget(target, blueprint);
-		const materializer = createMaterializer(command.from === void 0 ? void 0 : { host: command.from });
+		const materializer = new Materializer(command.from === void 0 ? void 0 : { host: command.from });
 		try {
 			const [audit, plan] = this.#survey(materializer, blueprint, target, groups);
 			if (plan === void 0) {
@@ -672,7 +672,7 @@ var CLI = class CLI {
 		if (extra.length > 0) this.#warn(`Read the data root from ${String(host)}. The other ${String(extra.length)} local root${extra.length === 1 ? "" : "s"} named by --from reach nothing this run does.`);
 		const previous = this.#previous(target);
 		const fetched = await this.#fetch(target, command.all === true);
-		const materializer = createMaterializer(host === void 0 ? void 0 : { host });
+		const materializer = new Materializer(host === void 0 ? void 0 : { host });
 		let result;
 		try {
 			result = this.#publish(materializer, target, fetched.entries, fetched.mirrors);
@@ -699,7 +699,7 @@ var CLI = class CLI {
 			target,
 			dirty: repository.dirty.length
 		});
-		const materializer = createMaterializer(command.from === void 0 ? void 0 : { host: command.from });
+		const materializer = new Materializer(command.from === void 0 ? void 0 : { host: command.from });
 		try {
 			const [audit, plan] = this.#survey(materializer, blueprint, target, groups);
 			if (plan === void 0) {
@@ -708,7 +708,7 @@ var CLI = class CLI {
 				return 1;
 			}
 			const repaired = materializer.repair(plan, audit, target);
-			const removed = materializer.remove(audit, command.dirty === true ? {
+			const removed = materializer.remove(plan, audit, command.dirty === true ? {
 				tracked: repository.tracked,
 				dirty: []
 			} : repository, target);
@@ -760,7 +760,7 @@ var CLI = class CLI {
 		}
 	}
 	async #lookup(declared) {
-		const upstream = createUpstream(this.#upstream);
+		const upstream = new Upstream(this.#upstream);
 		try {
 			return await upstream.lookup(declared);
 		} finally {
@@ -771,7 +771,7 @@ var CLI = class CLI {
 		const manifest = this.#manifest(target);
 		const own = manifestToName(manifest);
 		const declared = manifestToDependencies(manifest).map((dependency) => dependency.name);
-		const upstream = createUpstream(this.#upstream);
+		const upstream = new Upstream(this.#upstream);
 		try {
 			const entries = await upstream.catalog();
 			const names = (all ? entries.map((entry) => entry.name) : declared).filter((name) => name !== own);
@@ -795,7 +795,7 @@ var CLI = class CLI {
 		return pinned;
 	}
 	#compile(blueprint, groups) {
-		const compiler = createCompiler();
+		const compiler = new Compiler();
 		try {
 			const scaffolding = compiler.compile(blueprint, groups);
 			if (scaffolding.plan !== void 0 && scaffolding.questions.length === 0) return scaffolding.plan;
@@ -805,7 +805,7 @@ var CLI = class CLI {
 		}
 	}
 	#survey(materializer, blueprint, target, groups) {
-		const compiler = createCompiler();
+		const compiler = new Compiler();
 		try {
 			const scaffolding = compiler.compile(blueprint, groups);
 			if (scaffolding.plan === void 0) return [compiler.audit(blueprint, {}, groups), void 0];
@@ -1133,7 +1133,7 @@ var CLI = class CLI {
 		return state;
 	}
 	#inventory(target, args) {
-		const result = runSync({
+		const result = executeSync({
 			file: "git",
 			arguments: [...args]
 		}, {
@@ -1167,7 +1167,7 @@ var CLI = class CLI {
 	}
 	async #resolve(names) {
 		if (names.length === 0) return [];
-		const upstream = createUpstream(this.#upstream);
+		const upstream = new Upstream(this.#upstream);
 		let releases;
 		try {
 			releases = await upstream.lookup(names.map((name) => ({