@orkestrel/scaffold 0.0.23 → 0.0.25

package/dist/bin/main.js

@@ -0,0 +1,1094 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+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 { BIN_ENTRY_PATH, CATALOG_AGENT_PATH, DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, INTEGRATION_TEST_PATH, MAX_MANIFEST_BYTES, SHOWCASE_CONFIG_PATH, ScaffoldError, blueprintToRootVite, createBlueprint, createCompiler, isScaffoldError, manifestToDependencies, manifestToName, nameToGuide } from "../src/core/index.js";
+import { createMaterializer, createUpstream, isExactCaseFile, isPhysicalDirectory, isRepository, readFileText, readSnapshot, resolveContainedPath } from "../src/server/index.js";
+import { parseArgs } from "node:util";
+//#region src/bin/constants.ts
+/**
+* The name the executable installs as.
+*
+* @remarks
+* `package.json`'s `bin` field is the authority for what the command is called;
+* this is the same word, so every usage line the executable prints is a command
+* a reader can paste back.
+*/
+var EXECUTABLE_NAME = "scaffold";
+/**
+* The five {@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.
+*/
+var VERBS = Object.freeze([
+	"new",
+	"audit",
+	"repair",
+	"catalog",
+	"overwrite"
+]);
+/**
+* What each exit code means, frozen.
+*
+* @remarks
+* Keyed by the three code constants rather than by literals, so the usage block
+* cannot document a code the executable does not return.
+*/
+var EXIT_SUMMARY = Object.freeze({
+	[0]: "clean",
+	[1]: "drift or failure",
+	[2]: "usage error"
+});
+/**
+* The machine-readable code a malformed command line reports.
+*
+* @remarks
+* The executable contributes its own codes to the failure envelope, which is why
+* that envelope's `code` is a plain string rather than a `ScaffoldErrorCode`: a
+* command line that never became a command failed before any coded package
+* operation could.
+*/
+var USAGE_CODE = "USAGE";
+/** The machine-readable code a failure carrying no code of its own reports. */
+var FAILED_CODE = "FAILED";
+/** What the failure envelope says when the raised value carried no message. */
+var FAILED_MESSAGE = "The command failed for an unrecognized reason";
+/**
+* The positional argument `new` alone takes, as usage writes it.
+*
+* @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.
+*/
+var NAME_ARGUMENT = "<name>";
+/**
+* Every option the executable accepts, as `node:util` parses them, frozen.
+*
+* @remarks
+* One table for every verb rather than one per verb, because the verb an option
+* belongs to is a domain fact the command union already fixes: parsing decides
+* only whether the word is an option at all, and {@link VERB_OPTIONS} decides
+* whether this verb takes it. No option declares a default, so the parsed keys
+* are exactly the options the caller supplied, which is what makes an option
+* offered to the wrong verb visible rather than silently absorbed. `from`
+* collects repeats because `catalog` may draw on more than one local source; a
+* verb that takes it once refuses the second.
+*/
+var COMMAND_OPTIONS = Object.freeze({
+	src: Object.freeze({ type: "string" }),
+	app: Object.freeze({ type: "string" }),
+	bin: Object.freeze({ type: "boolean" }),
+	deps: Object.freeze({ type: "string" }),
+	groups: Object.freeze({ type: "string" }),
+	all: Object.freeze({ type: "boolean" }),
+	dirty: Object.freeze({ type: "boolean" }),
+	from: Object.freeze({
+		type: "string",
+		multiple: true
+	}),
+	target: Object.freeze({ type: "string" }),
+	json: Object.freeze({ type: "boolean" })
+});
+/**
+* What each option does, keyed by the token usage prints, frozen.
+*
+* @remarks
+* The key order is the glossary order. A key is the whole displayed token,
+* value placeholder included, because that token is what a reader copies and
+* what {@link VERB_OPTIONS} lists.
+*/
+var OPTION_SUMMARY = Object.freeze({
+	"--src <list>": "the published library environments to build: core, browser, server",
+	"--app <list>": "the private application environments to build: core, browser, server",
+	"--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",
+	"--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",
+	"--json": "emit one machine-readable value instead of a report"
+});
+/**
+* The options each verb takes, in usage order, frozen.
+*
+* @remarks
+* The executable's half of the frozen command union: every option a branch
+* declares is listed against its verb, and every option a branch excludes is
+* absent from it. An option a verb does not list is refused by name rather than
+* parsed and ignored.
+*/
+var VERB_OPTIONS = Object.freeze({
+	new: Object.freeze([
+		"--src <list>",
+		"--app <list>",
+		"--bin",
+		"--deps <list>",
+		"--from <path>",
+		"--target <path>",
+		"--json"
+	]),
+	audit: Object.freeze([
+		"--groups <list>",
+		"--from <path>",
+		"--target <path>",
+		"--json"
+	]),
+	repair: Object.freeze([
+		"--groups <list>",
+		"--from <path>",
+		"--target <path>",
+		"--json"
+	]),
+	catalog: Object.freeze([
+		"--all",
+		"--from <path>",
+		"--target <path>",
+		"--json"
+	]),
+	overwrite: Object.freeze([
+		"--groups <list>",
+		"--dirty",
+		"--from <path>",
+		"--target <path>",
+		"--json"
+	])
+});
+/**
+* What each verb does, in one line, frozen.
+*
+* @remarks
+* Each line names what the verb writes, because authority is the verb's: a
+* reader deciding which one to run is deciding what they are authorizing.
+*/
+var VERB_SUMMARY = Object.freeze({
+	new: "scaffold a workspace",
+	audit: "report how the target compares to its plan, writing nothing",
+	repair: "write each planned path the target is missing or has let drift",
+	catalog: "regenerate the package table and refresh the guide mirrors",
+	overwrite: "do everything repair and catalog do, then delete what the plan does not own and re-declare the dependency ranges"
+});
+//#endregion
+//#region src/bin/errors.ts
+/**
+* The error raised when a command line is not a command.
+*
+* @remarks
+* Distinct from `ScaffoldError` because the two 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
+* mistyped flag as a failed run.
+*
+* It carries no `context`. Everything a caller can act on is in the message,
+* because the reader of a usage error is a person at a terminal rather than a
+* program branching on a cause.
+*
+* @example
+* ```ts
+* import { isUsageError, UsageError } from './errors.js'
+*
+* try {
+* 	throw new UsageError("Unknown command 'pull'.")
+* } catch (error) {
+* 	if (isUsageError(error)) error.code // 'USAGE'
+* }
+* ```
+*/
+var UsageError = class extends Error {
+	code;
+	/**
+	* Construct a usage error.
+	*
+	* @param message - What was wrong with the command line, in one sentence.
+	*/
+	constructor(message) {
+		super(message);
+		this.name = "UsageError";
+		this.code = USAGE_CODE;
+	}
+};
+/**
+* Narrow a caught value to a {@link UsageError}.
+*
+* @param value - The caught value to narrow.
+* @returns `true` when `value` is a {@link UsageError}.
+*
+* @example
+* ```ts
+* import { isUsageError } from './errors.js'
+*
+* isUsageError(new Error('plain')) // false
+* isUsageError(undefined) // false
+* ```
+*/
+function isUsageError(value) {
+	return value instanceof UsageError;
+}
+//#endregion
+//#region src/bin/helpers.ts
+/**
+* Read the option name out of the token usage displays it as.
+*
+* @param option - The displayed token, such as `--from <path>`.
+* @returns The bare name `node:util` parses the option under.
+*
+* @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.
+*
+* @example
+* ```ts
+* import { optionToName } from './helpers.js'
+*
+* optionToName('--from <path>') // 'from'
+* optionToName('--json') // 'json'
+* ```
+*/
+function optionToName(option) {
+	const [token = option] = option.split(" ");
+	return token.startsWith("--") ? token.slice(2) : token;
+}
+/**
+* Render one verb's synopsis.
+*
+* @param verb - The verb to describe.
+* @returns The command line this verb accepts, with every option bracketed.
+*
+* @remarks
+* The synopsis is derived from the verb's own option list rather than stored
+* beside it, so a line that documents an option the verb does not take cannot be
+* written. `new` alone carries the positional argument.
+*
+* @example
+* ```ts
+* import { verbToSyntax } from './helpers.js'
+*
+* verbToSyntax('audit') // 'scaffold audit [--groups <list>] …'
+* ```
+*/
+function verbToSyntax(verb) {
+	return `${EXECUTABLE_NAME} ${verb}${verb === "new" ? ` ${NAME_ARGUMENT}` : ""} ${VERB_OPTIONS[verb].map((option) => `[${option}]`).join(" ")}`;
+}
+/**
+* Render the whole command reference.
+*
+* @returns One line per output call: the synopsis, every verb, the option glossary, and the exit codes.
+*
+* @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.
+*/
+function renderUsage() {
+	const summaries = Object.entries(OPTION_SUMMARY);
+	const column = Math.max(...summaries.map(([option]) => width(option)));
+	return [
+		`${EXECUTABLE_NAME} <verb> [options]`,
+		"",
+		...VERBS.flatMap((verb) => [`  ${verbToSyntax(verb)}`, `      ${VERB_SUMMARY[verb]}`]),
+		"",
+		"options",
+		...summaries.map(([option, summary]) => `  ${align(option, column)}  ${summary}`),
+		"",
+		"exit codes",
+		...Object.entries(EXIT_SUMMARY).map(([code, meaning]) => `  ${code}  ${meaning}`)
+	];
+}
+/**
+* Read one command out of the arguments following the executable's own name.
+*
+* @param argv - The arguments the executable was given.
+* @returns The command the arguments denote.
+* @throws {@link UsageError} when they denote no command.
+*
+* @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
+* 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
+* 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
+* answers it first.
+*
+* @example
+* ```ts
+* import { argvToCommand } from './helpers.js'
+*
+* argvToCommand(['audit', '--json']) // { verb: 'audit', json: true }
+* ```
+*/
+function argvToCommand(argv) {
+	const [head, ...rest] = argv;
+	const verb = VERBS.find((candidate) => candidate === head);
+	if (verb === void 0) throw new UsageError(`${head === void 0 ? "No command given." : `Unknown command '${head}'.`} Run '${EXECUTABLE_NAME} --help' for the command list.`);
+	const parsed = attempt(() => parseArgs({
+		args: rest,
+		options: COMMAND_OPTIONS,
+		allowPositionals: true,
+		strict: true
+	}));
+	if (!parsed.success) {
+		const cause = parsed.error;
+		throw new UsageError(cause instanceof Error ? cause.message : `Could not read the arguments to '${verb}'.`);
+	}
+	const { positionals, values } = parsed.value;
+	const accepted = VERB_OPTIONS[verb].map((option) => optionToName(option));
+	const refused = Object.keys(values).filter((name) => !accepted.includes(name));
+	if (refused.length > 0) throw new UsageError(`'${verb}' does not take ${refused.map((name) => `--${name}`).join(", ")}.`);
+	const [name] = positionals;
+	if (positionals.length > 1) throw new UsageError(`'${verb}' takes at most one argument, and was given ${String(positionals.length)}.`);
+	if (verb !== "new" && name !== void 0) throw new UsageError(`'${verb}' takes no argument, and was given '${name}'.`);
+	const paths = Array.isArray(values.from) ? values.from.filter((value) => typeof value === "string") : [];
+	if (verb !== "catalog" && paths.length > 1) throw new UsageError(`'${verb}' takes --from once, and was given it ${String(paths.length)} times.`);
+	const src = typeof values.src === "string" ? values.src : void 0;
+	const app = typeof values.app === "string" ? values.app : void 0;
+	const bin = values.bin === true;
+	const dependencies = typeof values.deps === "string" ? values.deps : void 0;
+	const target = typeof values.target === "string" ? values.target : void 0;
+	const json = values.json === true;
+	const [from] = paths;
+	const location = target === void 0 ? {} : { target };
+	const source = from === void 0 ? {} : { from };
+	const selection = typeof values.groups === "string" ? { groups: values.groups } : {};
+	switch (verb) {
+		case "new":
+			if (name === void 0) throw new UsageError(`'new' needs the workspace ${NAME_ARGUMENT} it is scaffolding.`);
+			return {
+				verb,
+				name,
+				json,
+				...location,
+				...source,
+				...src === void 0 ? {} : { src },
+				...app === void 0 ? {} : { app },
+				...bin ? { bin } : {},
+				...dependencies === void 0 ? {} : { dependencies }
+			};
+		case "audit": return {
+			verb,
+			json,
+			...location,
+			...source,
+			...selection
+		};
+		case "repair": return {
+			verb,
+			json,
+			...location,
+			...source,
+			...selection
+		};
+		case "catalog": return {
+			verb,
+			json,
+			all: values.all === true,
+			...location,
+			...paths.length === 0 ? {} : { from: paths }
+		};
+		case "overwrite": return {
+			verb,
+			json,
+			dirty: values.dirty === true,
+			...location,
+			...source,
+			...selection
+		};
+	}
+}
+/**
+* Read the exit code an audit reports.
+*
+* @param audit - The comparison of a plan against a target.
+* @returns `EXIT_CLEAN` when the target matched the plan, `EXIT_DRIFT` otherwise.
+*
+* @remarks
+* One rule for every verb that carries an audit, so `audit`, `repair`, and
+* `overwrite` cannot disagree about what a clean run is. A blocking question
+* means the gate refused the blueprint, so the audit says nothing about the
+* target and the run is a failure. A foreign finding counts: the target holds a
+* file the plan does not own, which is a difference from the plan whether or not
+* this verb was allowed to remove it. A non-blocking question rides a complete
+* result and does not.
+*
+* @example
+* ```ts
+* import { auditToExit } from './helpers.js'
+*
+* auditToExit({ findings: [], questions: [] }) // 0
+* ```
+*/
+function auditToExit(audit) {
+	const blocked = audit.questions.some((question) => question.blocking);
+	const drifted = audit.findings.some((finding) => finding.drift !== "aligned");
+	return blocked || drifted ? 1 : 0;
+}
+/**
+* Project a raised value into the machine-readable failure envelope.
+*
+* @param error - The value a command raised.
+* @returns The envelope naming the coded reason and what went wrong.
+*
+* @remarks
+* A `ScaffoldError` and a {@link UsageError} both publish a code, so both are
+* reported under their own. Anything else failed without saying why, and is
+* reported under one code rather than under an invented reading of it; a raised
+* value that is not an `Error` carries no message worth quoting, so the envelope
+* says so instead of stringifying whatever it was.
+*
+* @example
+* ```ts
+* import { errorToEnvelope } from './helpers.js'
+*
+* errorToEnvelope(new Error('boom')) // { error: { code: 'FAILED', message: 'boom' } }
+* ```
+*/
+function errorToEnvelope(error) {
+	if (isUsageError(error) || isScaffoldError(error)) return { error: {
+		code: error.code,
+		message: error.message
+	} };
+	return { error: {
+		code: FAILED_CODE,
+		message: error instanceof Error ? error.message : FAILED_MESSAGE
+	} };
+}
+//#endregion
+//#region src/bin/CLI.ts
+/**
+* The executable: one command line in, one exit code out.
+*
+* @remarks
+* Every destination this class writes to is a handler it was given, and the run
+* ends by returning its code rather than by setting one, so the whole executable
+* is drivable from inside another process. That is what makes proving what a
+* command prints cost a function call: `src/bin/main.ts` is the only module
+* that reads `process.argv` or assigns `process.exitCode`.
+*
+* Every line leaving here is stripped of ANSI escapes and control characters
+* once, on the way out, because a refusal quotes the argument that caused it and
+* that argument came from an untrusted command line. The machine-readable path
+* needs no second pass: `JSON.stringify` escapes a control character into text
+* before it reaches the handler.
+*
+* The collaborators are constructed per run rather than received, because
+* `--from` decides the vendored root the materializer reads and an instance
+* handed in before the command line was parsed could not honour it. The
+* 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.
+*
+* @example
+* ```ts
+* import { CLI } from './CLI.js'
+*
+* const lines: string[] = []
+* const code = await new CLI({ output: (line) => lines.push(line) }).execute(['--help'])
+* code // 0
+* ```
+*/
+var CLI = class CLI {
+	static #stdout = (line) => void process.stdout.write(`${line}\n`);
+	static #stderr = (line) => void process.stderr.write(`${line}\n`);
+	#output;
+	#diagnostic;
+	#upstream;
+	/**
+	* Construct the executable over the two destinations it writes to.
+	*
+	* @param options - The report and diagnostic handlers and the upstream
+	* endpoints; the process streams and the published endpoints when absent.
+	*/
+	constructor(options) {
+		this.#output = options?.output ?? CLI.#stdout;
+		this.#diagnostic = options?.diagnostic ?? CLI.#stderr;
+		this.#upstream = options?.upstream;
+	}
+	/**
+	* Run one command line to completion and report through the configured output.
+	*
+	* @param argv - The arguments following the executable's own name.
+	* @returns The exit code: `0` clean, `1` drift or failure, `2` a usage error.
+	*
+	* @remarks
+	* A request for usage is answered before anything is parsed, because it
+	* replaces the run rather than modifying it, and because `--help` is not an
+	* option any verb takes. Everything after that is one command: read it,
+	* dispatch it, render what it produced, and answer with the code it earned.
+	*
+	* @example
+	* ```ts
+	* import { CLI } from './CLI.js'
+	*
+	* await new CLI().execute(['audit', '--json']) // 0 when the target matches its plan
+	* ```
+	*/
+	async execute(argv) {
+		if (argv.includes("--help")) {
+			for (const line of renderUsage()) this.#say(line);
+			return 0;
+		}
+		const read = attempt(() => argvToCommand(argv));
+		if (!read.success) return this.#refuse(read.error, false);
+		const command = read.value;
+		try {
+			return await this.#dispatch(command);
+		} catch (error) {
+			return this.#refuse(error, command.json === true);
+		}
+	}
+	async #dispatch(command) {
+		switch (command.verb) {
+			case "new": return this.#create(command);
+			case "audit": return this.#inspect(command);
+			case "repair": return this.#restore(command);
+			case "catalog": return this.#refresh(command);
+			case "overwrite": return this.#replace(command);
+		}
+	}
+	async #create(command) {
+		const target = command.target ?? command.name;
+		const blueprint = createBlueprint(command.name, {
+			src: this.#environments(command.src, "src"),
+			app: this.#environments(command.app, "app"),
+			bin: command.bin === true,
+			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 });
+		try {
+			const result = materializer.materialize(plan, target);
+			if (command.json === true) this.#report(result);
+			else {
+				this.#say(`Scaffolded ${blueprint.name} into ${result.target}.`);
+				this.#say(this.#tally(result));
+			}
+			return 0;
+		} finally {
+			materializer.destroy();
+		}
+	}
+	#inspect(command) {
+		const target = command.target ?? ".";
+		const blueprint = this.#derive(target);
+		const question = this.#projectQuestion(target, blueprint);
+		const materializer = createMaterializer(command.from === void 0 ? void 0 : { host: command.from });
+		try {
+			const [measured] = this.#survey(materializer, blueprint, target, this.#groups(command.groups));
+			const audit = question === void 0 ? measured : {
+				...measured,
+				questions: [...measured.questions, question]
+			};
+			if (command.json === true) this.#report(audit);
+			else this.#present(audit);
+			return auditToExit(audit);
+		} finally {
+			materializer.destroy();
+		}
+	}
+	#restore(command) {
+		const target = command.target ?? ".";
+		const groups = this.#groups(command.groups);
+		const blueprint = this.#derive(target);
+		this.#assertProjects(target, blueprint);
+		const materializer = createMaterializer(command.from === void 0 ? void 0 : { host: command.from });
+		try {
+			const [audit, plan] = this.#survey(materializer, blueprint, target, groups);
+			if (plan === void 0) {
+				if (command.json === true) this.#report(audit);
+				else this.#present(audit);
+				return 1;
+			}
+			const result = materializer.repair(plan, audit, target);
+			const [terminal] = this.#survey(materializer, blueprint, target, groups);
+			const outcome = {
+				...result,
+				audit: terminal
+			};
+			if (command.json === true) this.#report(outcome);
+			else {
+				this.#present(terminal);
+				this.#say(this.#tally(result));
+			}
+			return auditToExit(terminal);
+		} finally {
+			materializer.destroy();
+		}
+	}
+	async #refresh(command) {
+		const target = command.target ?? ".";
+		const [host, ...extra] = command.from ?? [];
+		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 });
+		let result;
+		try {
+			result = this.#publish(materializer, target, fetched.entries, fetched.mirrors);
+		} finally {
+			materializer.destroy();
+		}
+		const outcome = {
+			...result,
+			entries: fetched.entries,
+			mirrors: fetched.mirrors,
+			dropped: previous.filter((name) => !fetched.entries.some((entry) => entry.name === name))
+		};
+		if (command.json === true) this.#report(outcome);
+		else this.#recount(outcome);
+		return fetched.mirrors.some((mirror) => mirror.lookup === "failed") ? 1 : 0;
+	}
+	async #replace(command) {
+		const target = command.target ?? ".";
+		const groups = this.#groups(command.groups);
+		const blueprint = this.#derive(target);
+		this.#assertProjects(target, blueprint);
+		const repository = this.#repository(target);
+		if (repository.dirty.length > 0 && command.dirty !== true) throw new ScaffoldError("TARGET", `The target at ${target} carries ${String(repository.dirty.length)} uncommitted change${repository.dirty.length === 1 ? "" : "s"}. Commit them, or pass --dirty to waive the refusal.`, {
+			target,
+			dirty: repository.dirty.length
+		});
+		const materializer = createMaterializer(command.from === void 0 ? void 0 : { host: command.from });
+		try {
+			const [audit, plan] = this.#survey(materializer, blueprint, target, groups);
+			if (plan === void 0) {
+				if (command.json === true) this.#report(audit);
+				else this.#present(audit);
+				return 1;
+			}
+			const repaired = materializer.repair(plan, audit, target);
+			const removed = materializer.remove(audit, command.dirty === true ? {
+				tracked: repository.tracked,
+				dirty: []
+			} : repository, target);
+			const offline = this.#merge(repaired, removed);
+			const online = await this.#reconcile(materializer, target, blueprint.dependencies);
+			const [terminal] = this.#survey(materializer, blueprint, target, groups);
+			const outcome = {
+				...online,
+				...this.#merge(offline, online),
+				audit: terminal
+			};
+			if (command.json === true) this.#report(outcome);
+			else {
+				this.#present(terminal);
+				this.#recount(outcome);
+				if (online.note !== void 0) this.#warn(online.note);
+			}
+			if (online.note !== void 0) return 1;
+			return auditToExit(terminal);
+		} finally {
+			materializer.destroy();
+		}
+	}
+	async #reconcile(materializer, target, declared) {
+		const previous = this.#previous(target);
+		try {
+			const releases = await this.#lookup(declared);
+			const fetched = await this.#fetch(target, false);
+			return {
+				...this.#merge(this.#publish(materializer, target, fetched.entries, fetched.mirrors), materializer.declare(this.#pin(releases), target)),
+				entries: fetched.entries,
+				mirrors: fetched.mirrors,
+				dropped: previous.filter((name) => !fetched.entries.some((entry) => entry.name === name)),
+				releases
+			};
+		} catch (error) {
+			return {
+				target,
+				written: [],
+				skipped: [],
+				removed: [],
+				entries: [],
+				mirrors: [],
+				dropped: [],
+				releases: [],
+				note: `The catalog step did not complete: ${errorToEnvelope(error).error.message}`
+			};
+		}
+	}
+	async #lookup(declared) {
+		const upstream = createUpstream(this.#upstream);
+		try {
+			return await upstream.lookup(declared);
+		} finally {
+			upstream.destroy();
+		}
+	}
+	async #fetch(target, all) {
+		const manifest = this.#manifest(target);
+		const own = manifestToName(manifest);
+		const declared = manifestToDependencies(manifest).map((dependency) => dependency.name);
+		const upstream = createUpstream(this.#upstream);
+		try {
+			const entries = await upstream.catalog();
+			const names = (all ? entries.map((entry) => entry.name) : declared).filter((name) => name !== own);
+			return {
+				entries,
+				mirrors: await upstream.fetch(names, readSnapshot(target, names.map(nameToGuide)))
+			};
+		} finally {
+			upstream.destroy();
+		}
+	}
+	#publish(materializer, target, entries, mirrors) {
+		return this.#merge(materializer.mirror(mirrors, target), materializer.catalog(entries, target));
+	}
+	#pin(releases) {
+		const pinned = [];
+		for (const release of releases) if (release.lookup === "found") pinned.push({
+			name: release.name,
+			range: `^${release.latest}`
+		});
+		return pinned;
+	}
+	#compile(blueprint, groups) {
+		const compiler = createCompiler();
+		try {
+			const scaffolding = compiler.compile(blueprint, groups);
+			if (scaffolding.plan !== void 0) return scaffolding.plan;
+			throw new ScaffoldError("BLOCKED", scaffolding.questions.filter((question) => question.blocking).map((question) => `${question.field}: ${question.message}`).join(" "), { questions: scaffolding.questions.length });
+		} finally {
+			compiler.destroy();
+		}
+	}
+	#survey(materializer, blueprint, target, groups) {
+		const compiler = createCompiler();
+		try {
+			const scaffolding = compiler.compile(blueprint, groups);
+			if (scaffolding.plan === void 0) return [compiler.audit(blueprint, {}, groups), void 0];
+			return [materializer.audit(scaffolding.plan, target), scaffolding.plan];
+		} finally {
+			compiler.destroy();
+		}
+	}
+	#derive(target) {
+		const manifest = this.#manifest(target);
+		const declared = manifestToName(manifest);
+		if (declared === void 0) throw new ScaffoldError("TARGET", `The manifest at ${target} declares no package name.`, { target });
+		const bin = resolveContainedPath(target, BIN_ENTRY_PATH);
+		const integration = resolveContainedPath(target, INTEGRATION_TEST_PATH);
+		const global = resolveContainedPath(target, GLOBAL_SETUP_PATH);
+		const showcase = resolveContainedPath(target, SHOWCASE_CONFIG_PATH);
+		return createBlueprint(declared.slice(declared.lastIndexOf("/") + 1), {
+			src: this.#probe(target, "src"),
+			app: this.#probe(target, "app"),
+			dependencies: manifestToDependencies(manifest),
+			bin: bin !== void 0 && isExactCaseFile(bin),
+			integration: integration !== void 0 && isExactCaseFile(integration),
+			global: global !== void 0 && isExactCaseFile(global),
+			showcase: showcase !== void 0 && isExactCaseFile(showcase)
+		});
+	}
+	#scriptProjects(script) {
+		const tokens = [];
+		let value = "";
+		let resolved = true;
+		let started = false;
+		let quote;
+		for (let index = 0; index < script.length; index += 1) {
+			const character = script[index];
+			if (character === void 0) return void 0;
+			if (quote === void 0) {
+				if (/\s/.test(character)) {
+					if (started) tokens.push({
+						value,
+						resolved
+					});
+					value = "";
+					resolved = true;
+					started = false;
+					continue;
+				}
+				if (";&|()".includes(character)) {
+					if (started) tokens.push({
+						value,
+						resolved
+					});
+					const paired = script[index + 1] === character && (character === "&" || character === "|");
+					tokens.push({
+						value: paired ? `${character}${character}` : character,
+						resolved: true
+					});
+					value = "";
+					resolved = true;
+					started = false;
+					if (paired) index += 1;
+					continue;
+				}
+				if (character === "\"" || character === "'") {
+					quote = character;
+					started = true;
+					continue;
+				}
+				if (character === "\\") {
+					const escaped = script[index + 1];
+					if (escaped === void 0) return void 0;
+					value += escaped;
+					started = true;
+					index += 1;
+					continue;
+				}
+				if (character === "$" || character === "`" || character === "%") resolved = false;
+				value += character;
+				started = true;
+				continue;
+			}
+			if (character === quote) {
+				quote = void 0;
+				continue;
+			}
+			if (character === "\\" && quote === "\"") {
+				const escaped = script[index + 1];
+				if (escaped === void 0) return void 0;
+				value += escaped;
+				index += 1;
+				continue;
+			}
+			if (quote === "\"" && (character === "$" || character === "`" || character === "%")) resolved = false;
+			value += character;
+			started = true;
+		}
+		if (quote !== void 0) return void 0;
+		if (started) tokens.push({
+			value,
+			resolved
+		});
+		const projects = [];
+		for (let index = 0; index < tokens.length; index += 1) {
+			const token = tokens[index];
+			if (token === void 0) return void 0;
+			if (token.value === "--project") {
+				const project = tokens[index + 1];
+				if (project === void 0 || !project.resolved || project.value.length === 0 || [
+					"&&",
+					"||",
+					";",
+					"|",
+					"&",
+					"(",
+					")"
+				].includes(project.value)) return void 0;
+				projects.push(project.value);
+				index += 1;
+				continue;
+			}
+			if (token.value.startsWith("--project=")) {
+				const project = token.value.slice(10);
+				if (!token.resolved || project.length === 0) return void 0;
+				projects.push(project);
+				continue;
+			}
+			if (!token.resolved && token.value.includes("--project")) return void 0;
+		}
+		return projects;
+	}
+	#projectQuestion(target, blueprint, writing = false) {
+		const manifest = this.#manifest(target);
+		const guides = resolveContainedPath(target, GUIDES_TEST_PATH);
+		const planned = blueprintToRootVite(blueprint);
+		const parsed = parseJSON(manifest);
+		const scripts = isRecord(parsed) && isRecord(parsed.scripts) ? parsed.scripts : void 0;
+		const absent = /* @__PURE__ */ new Set();
+		let unresolved = false;
+		if (scripts !== void 0) for (const script of Object.values(scripts)) {
+			if (!isString(script) || !script.includes("vitest")) continue;
+			const projects = this.#scriptProjects(script);
+			if (projects === void 0) {
+				unresolved = true;
+				continue;
+			}
+			for (const project of projects) {
+				const guide = project === "guides" && guides !== void 0 && isExactCaseFile(guides);
+				if (!planned.includes(`name: { label: '${project}',`) || project === "guides" && !guide) absent.add(project);
+			}
+		}
+		if (absent.size === 0 && !unresolved) return void 0;
+		const projects = [...absent].sort();
+		if (unresolved) return {
+			field: "projects",
+			message: `The manifest at ${target} contains a Vitest project expression that cannot be resolved statically.${projects.length === 0 ? "" : ` It also names projects the planned configuration does not register: ${projects.join(", ")}.`} ${writing ? "Replace it with a literal --project value or remove the script before using a scaffold writing verb." : "Replace it with a literal --project value before relying on the planned configuration."}`,
+			blocking: false
+		};
+		return {
+			field: "projects",
+			message: writing ? `The manifest at ${target} names ${projects.length === 1 ? "a Vitest project" : "Vitest projects"} the planned configuration does not register: ${projects.join(", ")}. To continue, remove the ${projects.length === 1 ? "script that names it" : "scripts that name them"} or do not use scaffold writing verbs on a workspace that needs ${projects.length === 1 ? "a custom Vitest project" : "custom Vitest projects"}.` : `The manifest at ${target} names ${projects.length === 1 ? "a Vitest project" : "Vitest projects"} the planned configuration does not register: ${projects.join(", ")}. Add ${projects.length === 1 ? "the project" : "each project"} to vite.config.ts or remove the ${projects.length === 1 ? "script that names it" : "scripts that name them"}.`,
+			blocking: false
+		};
+	}
+	#assertProjects(target, blueprint) {
+		const question = this.#projectQuestion(target, blueprint, true);
+		if (question === void 0) return;
+		throw new ScaffoldError("TARGET", question.message, { target });
+	}
+	#manifest(target) {
+		const manifest = readFileText(target, "package.json", MAX_MANIFEST_BYTES);
+		if (manifest === void 0) throw new ScaffoldError("TARGET", `The target at ${target} carries no readable manifest.`, { target });
+		return manifest;
+	}
+	#probe(target, axis) {
+		return ENVIRONMENTS.filter((environment) => {
+			const full = resolveContainedPath(target, `${axis}/${environment}`);
+			return full !== void 0 && isPhysicalDirectory(full);
+		});
+	}
+	#previous(target) {
+		const text = readFileText(target, CATALOG_AGENT_PATH);
+		if (text === void 0) return [];
+		const names = [];
+		for (const table of createMarkdown(text).filter(isTableNode)) for (const row of table.rows) {
+			const [cell] = row;
+			if (cell === void 0) continue;
+			const name = cell.map(flattenText).join("").trim();
+			if (DEPENDENCY_NAME_PATTERN.test(name)) names.push(name);
+		}
+		return names;
+	}
+	#repository(target) {
+		const tracked = this.#inventory(target, ["ls-files", "-z"]);
+		const dirty = this.#inventory(target, [
+			"status",
+			"--porcelain=v1",
+			"--untracked-files=all",
+			"-z"
+		]).map((record) => record.length > 3 && record[2] === " " ? record.slice(3) : record);
+		const state = {
+			tracked,
+			dirty
+		};
+		if (!isRepository(state)) throw new ScaffoldError("TARGET", `The git state at ${target} is not a readable inventory.`, {
+			target,
+			tracked: tracked.length,
+			dirty: dirty.length
+		});
+		return state;
+	}
+	#inventory(target, args) {
+		const read = attempt(() => execFileSync("git", [...args], {
+			cwd: target,
+			encoding: "utf8",
+			windowsHide: true,
+			maxBuffer: MAX_MANIFEST_BYTES,
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}));
+		if (!read.success) throw new ScaffoldError("TARGET", `The target at ${target} is not a git repository.`, { target });
+		return read.value.split("\0").filter((record) => record.length > 0);
+	}
+	#environments(selection, axis) {
+		if (selection === void 0) return [];
+		const requested = selection.split(",");
+		const refused = requested.filter((name) => !ENVIRONMENTS.some((environment) => environment === name));
+		if (refused.length > 0) throw new UsageError(`'--${axis}' does not take ${refused.join(", ")}. It takes ${ENVIRONMENTS.join(", ")}.`);
+		return ENVIRONMENTS.filter((environment) => requested.includes(environment));
+	}
+	#groups(selection) {
+		if (selection === void 0) return void 0;
+		const requested = selection.split(",");
+		const refused = requested.filter((name) => !GROUPS.some((group) => group === name));
+		if (refused.length > 0) throw new UsageError(`'--groups' does not take ${refused.join(", ")}. It takes ${GROUPS.join(", ")}.`);
+		return GROUPS.filter((group) => requested.includes(group));
+	}
+	#packages(selection) {
+		if (selection === void 0) return [];
+		const requested = selection.split(",");
+		const refused = requested.filter((name) => !DEPENDENCY_NAME_PATTERN.test(name));
+		if (refused.length > 0) throw new UsageError(`'--deps' does not take ${refused.join(", ")}. Every name is a published @orkestrel package.`);
+		return requested;
+	}
+	async #resolve(names) {
+		if (names.length === 0) return [];
+		const upstream = createUpstream(this.#upstream);
+		let releases;
+		try {
+			releases = await upstream.lookup(names.map((name) => ({
+				name,
+				range: "*"
+			})));
+		} finally {
+			upstream.destroy();
+		}
+		const refused = releases.filter((release) => release.lookup !== "found");
+		if (refused.length > 0) throw new ScaffoldError("FETCH", `The registry named no release for ${refused.map((release) => release.name).join(", ")}.`, { names: refused.length });
+		return this.#pin(releases);
+	}
+	#merge(first, second) {
+		return {
+			target: first.target,
+			written: [...first.written, ...second.written],
+			skipped: [...first.skipped, ...second.skipped],
+			removed: [...first.removed, ...second.removed]
+		};
+	}
+	#present(audit) {
+		for (const question of audit.questions) this.#warn(`${question.field}: ${question.message}`);
+		const rows = audit.findings.filter((finding) => finding.drift !== "aligned").map((finding) => [
+			finding.path,
+			finding.group,
+			finding.drift
+		]);
+		if (rows.length > 0) {
+			const table = renderTable({
+				columns: [
+					{ label: "path" },
+					{ label: "group" },
+					{ label: "drift" }
+				],
+				rows
+			});
+			for (const line of table.split("\n")) this.#say(line);
+		}
+		this.#say(`${String(rows.length)} of ${String(audit.findings.length)} planned path${audit.findings.length === 1 ? "" : "s"} differ from the plan.`);
+	}
+	#recount(result) {
+		this.#say(this.#tally(result));
+		this.#say(`${String(result.entries.length)} published, ${String(result.mirrors.filter((mirror) => mirror.lookup === "found").length)} guide${result.mirrors.length === 1 ? "" : "s"} fetched, ${String(result.dropped.length)} no longer listed.`);
+		for (const mirror of result.mirrors) if (mirror.lookup !== "found") this.#warn(`${mirror.name}: ${mirror.note}`);
+	}
+	#tally(result) {
+		return `${String(result.written.length)} written, ${String(result.skipped.length)} unchanged, ${String(result.removed.length)} removed in ${result.target}.`;
+	}
+	#report(value) {
+		this.#say(JSON.stringify(value));
+	}
+	#refuse(error, json) {
+		const envelope = errorToEnvelope(error);
+		if (json) this.#report(envelope);
+		else this.#warn(`${envelope.error.code}: ${envelope.error.message}`);
+		return isUsageError(error) ? 2 : 1;
+	}
+	#say(line) {
+		this.#output(this.#sanitize(line));
+	}
+	#warn(line) {
+		this.#diagnostic(this.#sanitize(line));
+	}
+	#sanitize(line) {
+		return stripControls(strip(line)).split(/\r?\n/).join(" ");
+	}
+};
+//#endregion
+//#region src/bin/main.ts
+process.stdout.on("error", (error) => {
+	if ("code" in error && error.code === "EPIPE") return;
+	throw error;
+});
+process.exitCode = await new CLI().execute(process.argv.slice(2));
+//#endregion
+
+//# sourceMappingURL=main.js.map