@orkestrel/scaffold 0.0.63 → 0.0.65

package/README.md

@@ -1,26 +1,7 @@
 # @orkestrel/scaffold
 
-Compile a workspace specification into an ordered list of files, compare that list to a real
-directory, and write the difference.
-
-Every `@orkestrel` repository shares one toolchain, one set of agent instructions, and one set of
-root dotfiles. Scaffold ships that shared set as data inside the package and gives it verbs: create
-a workspace from it, report how a workspace differs from it, and write the difference back.
-
-The set splits by how a repository meets it. Each target carries its own copy of the paths it
-selects from the vendored set — its licence, its harness permission file, its session-start hooks,
-its policy register, its policy proof, its policy plugin, its configuration leaf and its proof, its
-root dotfiles, and the guide mirrors it starts from, never its own guide — and the verbs write
-them and compare them. A bench probe hook reports whether a bench CLI resolves, and the dependency
-hook installs the lockfile's closure in a remote session; what wires a bench stays in the canon,
-and a session reads it at its primary root. The instruction canon — the coding and
-orchestration contracts, the rules, the skills, the templates, the transport contracts, the agent
-roles, the bench configuration, and the MCP registrations — is published for reading instead, from a
-scaffold checkout sitting beside the repository, or from
-`node_modules/@orkestrel/scaffold/dist/host/` in the installed package. Every target carries the
-`AGENTS.md` and `CLAUDE.md` pointers that name where to read it, and the
-`.claude/agents/orkestrel.md` catalog file the `catalog` verb rewrites. Anything else a target holds
-at a canon path is a superseded copy, and `overwrite` deletes it.
+> A compiler that turns a workspace specification into an ordered list of files, compares that list
+> to a real directory, and writes the difference.
 
 ## Install
 
@@ -28,7 +9,7 @@ at a canon path is a superseded copy, and `overwrite` deletes it.
 npm install --save-dev @orkestrel/scaffold
 ```
 
-The executable needs Node 22.12 or later. Run it without installing anything:
+The executable needs Node 22.18.0 or later. Run it without installing anything:
 
 ```sh
 npx @orkestrel/scaffold --help
@@ -36,73 +17,25 @@ npx @orkestrel/scaffold --help
 
 ## Verbs
 
-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.
+Authority is the verb's: every verb except `audit` writes when it is typed, and no option grants a
+write. The guide's [Command line](guides/scaffold.md#command-line) section specifies each verb, its
+options, its defaults, and the exit codes.
 
-`--target <path>` points any verb at another directory; the working directory is the default.
-`--json` replaces the report with one machine-readable value on standard output.
-
-### `new` — scaffold a workspace
-
-```sh
-npx scaffold new router --src core,server
-```
-
-Writes a complete workspace into `./router`: its manifest, its build configuration, empty barrels
-for each selected environment, its tests, its documentation, the `AGENTS.md` and `CLAUDE.md`
-pointers, and every vendored file. `--app` selects private application environments on an
-independent axis, and `--deps` names `@orkestrel/*` runtime dependencies, each pinned to the
-registry's latest release. `--bin` adds the command-line entry, its test, and its scoped build
-configuration.
-
-### `audit` — report how a target compares to its plan
-
-```sh
-npx scaffold audit --groups configs,orchestration
-```
-
-Writes nothing. Reports one row per path that differs, and exits `1` when anything does. Omit
-`--groups` to cover every group.
-
-### `repair` — write back what drifted
-
-```sh
-npx scaffold repair
-```
-
-Restores each planned path the target is missing or has let drift, then re-audits. A file the
-workspace owns — its source, its own proofs, its README — is written once at creation and is never
-rewritten here. Not everything is owned that way: `tests/distribution.test.ts` is restored when it
-is absent and left alone when the workspace has replaced it, and the manifest's script region is
-rewritten when its chain is the one scaffold generated and refused without a write when it is not.
-
-### `catalog` — refresh the package table and the guide mirrors
-
-```sh
-npx scaffold catalog --all
-```
-
-Reads the organization's published package list, rewrites the marker-bounded table in
-`.claude/agents/orkestrel.md`, and fetches each package's guide into its local mirror. Without
-`--all` it fetches only the guides the target declares as dependencies.
-
-### `overwrite` — repair, catalog, delete, and re-pin
-
-```sh
-npx scaffold overwrite --dirty
-```
-
-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. The deletion covers a stray beneath a vendored directory and a superseded
-instruction copy alike, so one run repairs the pointers and sweeps the canon paths a release moved.
-It needs a git repository, and it refuses a tree carrying uncommitted changes unless `--dirty` waives
-that refusal.
+- `new` writes a whole workspace into a target that holds nothing the plan would collide with.
+- `audit` writes nothing, and reports one row per path that differs.
+- `repair` writes each planned path the target is missing or has let drift, and the manifest's range
+  and script regions.
+- `catalog` rewrites the package table in the target's catalog agent file, and refetches the guide
+  mirrors.
+- `overwrite` does everything `repair` and `catalog` do, then deletes what the plan does not own and
+  re-declares the dependency ranges.
 
 ## Library
 
 The entry points split by host. `@orkestrel/scaffold` is host-independent: it compiles, gates, and
-compares.
+compares. `@orkestrel/scaffold/server` is Node-only and holds everything that touches the filesystem
+or the 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 { Compiler, createBlueprint } from '@orkestrel/scaffold'
@@ -115,26 +48,8 @@ scaffolding.questions // the advice the compile could not settle
 compiler.destroy()
 ```
 
-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: `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 { Materializer } from '@orkestrel/scaffold/server'
-
-declare const plan: Plan
-
-const materializer = new Materializer()
-const result = materializer.materialize(plan, './packages/router')
-
-result.written // every path created
-materializer.destroy()
-```
+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.
 
 ## Guide
 
@@ -143,6 +58,16 @@ vendored data root, and the generated file set.
 
 ## Notes
 
+The `scaffold new` command generates a workspace that declares an npm floor of 11.6.0 in its
+`devEngines` record. An npm at 10.9.0 or later and earlier than 11.6.0 refuses the `npm install`
+command there with the `EBADDEVENGINES` code, before resolving the dependency graph.
+npm 10.5.0 and npm 10.8.3, the releases measured earlier than 10.9.0, ignore the record and fail
+inside dependency resolution instead.
+No Node release the executable supports bundles an npm earlier than 10.9.0. Read the ambient
+version with the `npm --version` command. Raise it with the `npm install --global npm@11.6.0`
+command before the first install.
+These readings come from a Linux host, on 2026-09-13.
+
 On Windows, run the executable as `npx scaffold …` or `node ./dist/bin/main.js …`. PowerShell
 mangles npm's `--` passthrough, so avoid `npm run scaffold -- …` there.
 

package/dist/bin/main.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { align, renderTable, strip, stripControls, width } from "@orkestrel/console";
 import { attempt, isError, isRecord, isString, parseJSON } from "@orkestrel/contract";
-import { BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFORMANCE_TEST_PATH, Compiler, DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, MAX_MANIFEST_BYTES, SERVICE_SETUP_PATH, SHOWCASE_CONFIG_PATH, ScaffoldError, blueprintToDevDependencies, blueprintToRootVite, blueprintToScripts, blueprintToTestArtifacts, blueprintToWritableScripts, compareVersions, createBlueprint, extractRangeMajor, extractVersion, isFloorPath, isScaffoldError, manifestToDependencies, manifestToName, nameToGuide, replaceManifestScripts, replacePlanRanges } from "../src/core/index.js";
-import { Materializer, Upstream, filesToHost, isExactCaseFile, isPhysicalDirectory, isWorktree, listFiles, readFileText, readHostFloor, readSnapshot, resolveContainedPath } from "../src/server/index.js";
+import { BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFORMANCE_TEST_PATH, Compiler, DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, SERVICE_SETUP_PATH, SHOWCASE_CONFIG_PATH, ScaffoldError, blueprintToDevDependencies, blueprintToRootVite, blueprintToScripts, blueprintToTestArtifacts, blueprintToWritableScripts, compareVersions, createBlueprint, extractRangeMajor, extractVersion, isFloorPath, isScaffoldError, manifestToDependencies, manifestToName, nameToGuide, replaceManifestScripts, replacePlanRanges } from "../src/core/index.js";
+import { MAX_INVENTORY_PATHS, Materializer, Upstream, filesToHost, isExactCaseFile, isPhysicalDirectory, isWorktree, listFiles, readFileText, readHostFloor, readSnapshot, resolveContainedPath } from "../src/server/index.js";
 import { createMarkdown, flattenText, isTableNode } from "@orkestrel/markdown";
-import { executeSync } from "@orkestrel/process/server";
+import { createSession } from "@orkestrel/process/server";
 import { parseArgs } from "node:util";
 //#region src/bin/constants.ts
 /**
@@ -1033,40 +1033,108 @@ function catalogToNames(target) {
 	return names;
 }
 /**
+* Collects the complete NUL-delimited records from one raw git output chunk.
+*
+* @param records - The complete records retained in arrival order.
+* @param pending - The mutable cell carrying the unfinished record between chunks.
+* @param decoder - The streaming UTF-8 decoder shared by the query.
+* @param controller - The query controller aborted on a bound refusal.
+* @param target - The repository the query addresses.
+* @param chunk - The next owned output bytes.
+* @returns Nothing.
+*/
+function collectGitRecords(records, pending, decoder, controller, target, chunk) {
+	if (controller.signal.aborted) return;
+	const parts = `${pending[0] ?? ""}${decoder.decode(chunk, { stream: true })}`.split("\0");
+	pending[0] = parts.pop() ?? "";
+	for (const record of parts) {
+		if (record.length === 0) continue;
+		if (records.length >= MAX_INVENTORY_PATHS) {
+			refuseGitRecords(controller, target, `The git query for target at ${target} exceeded the working-tree inventory limit.`);
+			return;
+		}
+		records.push(record);
+	}
+	if ((pending[0] ?? "").length > MAX_PATH_LENGTH + 3) refuseGitRecords(controller, target, `The git query for target at ${target} returned an unfinished record beyond the supported path limit.`);
+}
+/**
+* Aborts a git query with its first target refusal.
+*
+* @param controller - The query controller whose reason retains the refusal.
+* @param target - The repository the query addresses.
+* @param message - The refusal message.
+* @returns Nothing.
+*/
+function refuseGitRecords(controller, target, message) {
+	if (!controller.signal.aborted) controller.abort(new ScaffoldError("TARGET", message, { target }));
+}
+/**
 * Reads one git query as its NUL-separated records.
 *
 * @param target - The repository the query runs in.
 * @param args - The git arguments, without the program name.
 * @returns The non-empty records git wrote, in git's own order.
-* @throws `ScaffoldError('TARGET', …)` when the query fails, which is what a
-* directory that is not a git repository answers with.
+* @throws `ScaffoldError('TARGET', …)` when the query fails or its output is
+* incomplete or outside the working-tree inventory bounds.
 *
 * @remarks
 * Git is asked rather than reimplemented, because the tracked set and the dirty
-* set are git's own answers and nothing else can give them. `executeSync`
-* resolves the bare `git` name against `PATH` and `PATHEXT` on Windows, never
-* through a shell, so the query runs without an extension of its own. A failed
-* run resolves instead of throwing there, so git's own refusal is buffered into
-* the result rather than written onto a stream nobody chose.
+* set are git's own answers and nothing else can give them. The raw session
+* streams complete NUL-delimited records without retaining the whole query as a
+* manifest-sized text buffer. Its initial hooks are installed before the eager
+* spawn, so no output or child fault can precede its observer.
 *
 * @example
 * ```ts
 * import { readGitRecords } from './helpers.js'
 *
-* readGitRecords('./packages/router', ['ls-files', '-z']) // ['package.json', 'src/core/index.ts']
+* await readGitRecords('./packages/router', ['ls-files', '-z']) // ['package.json', 'src/core/index.ts']
 * ```
 */
-function readGitRecords(target, args) {
-	const result = executeSync({
-		file: "git",
-		arguments: [...args]
-	}, {
-		workspace: target,
-		limit: MAX_MANIFEST_BYTES,
-		strict: false
-	});
-	if (result.failed) throw new ScaffoldError("TARGET", `The target at ${target} is not a git repository.`, { target });
-	return result.stdout.split("\0").filter((record) => record.length > 0);
+async function readGitRecords(target, args) {
+	const records = [];
+	const pending = [""];
+	const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+	const controller = new AbortController();
+	let session;
+	try {
+		session = createSession({
+			command: {
+				file: "git",
+				arguments: [
+					"-C",
+					target,
+					...args
+				]
+			},
+			workspace: ".",
+			signal: controller.signal,
+			on: {
+				stdout: collectGitRecords.bind(void 0, records, pending, decoder, controller, target),
+				error: refuseGitRecords.bind(void 0, controller, target, `The git query for target at ${target} failed before it completed.`)
+			},
+			error: refuseGitRecords.bind(void 0, controller, target, `The git query for target at ${target} failed while reading its output.`)
+		});
+		const exit = await session.exit;
+		pending[0] = `${pending[0] ?? ""}${decoder.decode()}`;
+		if (controller.signal.aborted) throw controller.signal.reason;
+		if (exit.signal !== null) throw new ScaffoldError("TARGET", `The git query for target at ${target} ended from signal ${exit.signal}.`, {
+			target,
+			signal: exit.signal
+		});
+		if (exit.code !== 0) throw new ScaffoldError("TARGET", `The git query for target at ${target} failed with exit code ${String(exit.code)}.`, {
+			target,
+			code: exit.code
+		});
+		if (!exit.drained) throw new ScaffoldError("TARGET", `The git query for target at ${target} ended before its output drained.`, { target });
+		if ((pending[0] ?? "").length > 0) throw new ScaffoldError("TARGET", `The git query for target at ${target} returned an incomplete record.`, { target });
+		return records;
+	} catch (error) {
+		if (isScaffoldError(error)) throw error;
+		throw new ScaffoldError("TARGET", `The git query for target at ${target} could not start.`, { target });
+	} finally {
+		if (session !== void 0) await session.destroy();
+	}
 }
 /**
 * Reads the environments a comma-separated selection names.
@@ -1446,7 +1514,7 @@ var CLI = class {
 		const groups = selectionToGroups(command.groups);
 		const blueprint = this.#derive(target);
 		this.#assertTarget(target, blueprint, groups);
-		const worktree = this.#worktree(target);
+		const worktree = await this.#worktree(target);
 		if (worktree.dirty.length > 0 && command.dirty !== true) throw new ScaffoldError("TARGET", `The target at ${target} carries ${String(worktree.dirty.length)} uncommitted change${worktree.dirty.length === 1 ? "" : "s"}. Commit them, or pass --dirty to waive the refusal.`, {
 			target,
 			dirty: worktree.dirty.length
@@ -1971,14 +2039,14 @@ var CLI = class {
 		if (manifest === void 0) throw new ScaffoldError("TARGET", `The target at ${target} carries no readable manifest.`, { target });
 		return manifest;
 	}
-	#worktree(target) {
-		const tracked = readGitRecords(target, ["ls-files", "-z"]);
-		const dirty = readGitRecords(target, [
+	async #worktree(target) {
+		const tracked = await readGitRecords(target, ["ls-files", "-z"]);
+		const dirty = (await readGitRecords(target, [
 			"status",
 			"--porcelain=v1",
 			"--untracked-files=all",
 			"-z"
-		]).map((record) => record.length > 3 && record[2] === " " ? record.slice(3) : record);
+		])).map((record) => record.length > 3 && record[2] === " " ? record.slice(3) : record);
 		const state = {
 			tracked,
 			dirty