@orkestrel/scaffold 0.0.84 → 0.0.86

package/README.md

@@ -27,8 +27,8 @@ options, its defaults, and the exit codes.
   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.
+- `overwrite` does everything `repair` and `catalog` do, then deletes what the plan does not own,
+  re-declares the dependency ranges, and declares each planned dependency the manifest lacks.
 
 ## Library
 

package/dist/agents/skills/orkestrel-publish/scripts/wave.js

@@ -89,9 +89,23 @@ function readReleases(text) {
 function describeCommand(file, args) {
     return [file === process.execPath ? 'node' : file, ...args].join(' ');
 }
+// A JSON verb writes its refusal envelope or its partial-run note on stdout, so the stderr tail
+// alone reads empty for exactly the failures the operator needs named.
 function describeFailure(result) {
     if (result.status === 0)
         return undefined;
+    const value = readJsonObject(result.stdout);
+    const error = value?.error;
+    if (typeof error === 'object' && error !== null && !Array.isArray(error)) {
+        const envelope = Object.fromEntries(Object.entries(error));
+        const code = readString(envelope, 'code');
+        const message = readString(envelope, 'message');
+        if (code !== undefined && message !== undefined)
+            return `${code}: ${message}`;
+    }
+    const note = readString(value, 'note');
+    if (note !== undefined)
+        return note;
     return result.stderr
         .trim()
         .split(/\r\n|\n/)
@@ -214,12 +228,12 @@ function runCommit(runner) {
 function runOverwrite(runner, scaffoldFile, scaffoldPrefix, offline) {
     const written = runStep(runner, 'overwrite', scaffoldFile, [...scaffoldPrefix, 'overwrite', '--json', ...offline], runner.target);
     if (runner.offline && written !== undefined && written.status === 1) {
-        const note = readString(readJsonObject(written.stdout) ?? {}, 'note');
+        const note = readString(readJsonObject(written.stdout), 'note');
         if (note !== undefined && note.includes(OFFLINE_REFUSAL)) {
             replaceLastStep(runner, 0, 'offline overwrite skipped the catalog step by design');
         }
         else {
-            replaceLastStep(runner, 1, note ?? describeFailure(written));
+            replaceLastStep(runner, 1, describeFailure(written));
         }
     }
     if (!failed(runner)) {

package/dist/bin/main.js

@@ -10,7 +10,7 @@ import { normalize } from "node:path";
 import { parseArgs } from "node:util";
 var package_default = {
 	name: "@orkestrel/scaffold",
-	version: "0.0.84",
+	version: "0.0.86",
 	description: "Scaffold workspaces with commands: new, audit, repair, catalog, and overwrite.",
 	keywords: [
 		"audit",
@@ -322,8 +322,25 @@ var VERB_SUMMARY = Object.freeze({
 	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"
+	overwrite: "do everything repair and catalog do, then delete what the plan does not own, re-declare the dependency ranges, and declare each planned dependency the manifest lacks"
 });
+/**
+* Matches a module specifier that names a built sheet's CSS as raw text.
+*
+* @remarks
+* The planned sheet test is the one birth-owned test whose text imports a built
+* sheet, so this is what tells it apart from a face's entry test at the same
+* `tests/src/<face>/index.test.ts` shape.
+*/
+var SHEET_IMPORT_PATTERN = /from\s+(['"])[^'"]*dist\/src\/[^'"]+\.css\?raw\1/u;
+/**
+* Matches each import declaration whose module specifier is root-relative, capturing the specifier.
+*
+* @remarks
+* A root-relative specifier opens with one `/`. Oxlint's `import/no-absolute-path` rule
+* refuses it, while a protocol-relative `//` specifier is outside this pattern.
+*/
+var ROOT_IMPORT_PATTERN = /^\s*import\s[^'"]*?(['"])(\/(?!\/)[^'"]*)\1/gmu;
 //#endregion
 //#region src/bin/errors.ts
 /**
@@ -653,6 +670,89 @@ function manifestToWritableDependencies(manifest, blueprint) {
 	};
 }
 /**
+* Reads the planned dependencies a target manifest declares in neither writable section.
+*
+* @param manifest - The target manifest text.
+* @param blueprint - The workspace shape that supplies the planned dependencies.
+* @returns The undeclared planned dependencies at their planned ranges, in name order, each in
+* the list naming the section the plan assigns it.
+*
+* @remarks
+* The plan declares its tooling under `devDependencies`, so every row lands in `development` and
+* `runtime` stays empty: the blueprint's runtime packages are read from the manifest's own
+* `dependencies`, so none of them is ever missing. A planned package either section declares is
+* present, whatever its range. A manifest that is not an object, or whose sections are not
+* objects, yields what its readable sections leave undeclared, and the caller's refusal of that
+* malformed shape decides whether a write may follow.
+*
+* @example
+* ```ts
+* import { createBlueprint } from '@src/core'
+* import { manifestToAdditions } from './helpers.js'
+*
+* const blueprint = createBlueprint('sample', { src: ['core'] })
+* manifestToAdditions('{"devDependencies": {}}', blueprint).development.some(
+*   ({ name }) => name === 'typescript',
+* ) // true
+* ```
+*/
+function manifestToAdditions(manifest, blueprint) {
+	const parsed = parseJSON(manifest);
+	const runtime = isRecord(parsed) && isRecord(parsed.dependencies) ? parsed.dependencies : {};
+	const development = isRecord(parsed) && isRecord(parsed.devDependencies) ? parsed.devDependencies : {};
+	return {
+		runtime: [],
+		development: Object.entries(blueprintToDevDependencies(blueprint)).filter(([name]) => !Object.hasOwn(runtime, name) && !Object.hasOwn(development, name)).map(([name, range]) => ({
+			name,
+			range
+		}))
+	};
+}
+/**
+* Reads the root-relative imports a target keeps in a planned birth-owned sheet test.
+*
+* @param artifact - The planned artifact at the path the target holds.
+* @param present - The text the target holds at that path.
+* @returns A non-blocking `tests` question naming the file and each root-relative specifier beside
+* the relative specifier to write, or `undefined` when the artifact is not a birth-owned sheet
+* test or the text imports nothing by a root-relative specifier.
+*
+* @remarks
+* Birth ownership never rewrites a present file, so a target born before the sheet test imported
+* the built sheet by a relative path keeps the root-relative import, and the content-owned lint
+* configuration refuses it. The relative specifier climbs one `../` per directory of the
+* artifact's path to the workspace root, which is the specifier the planned test itself imports.
+*
+* @example
+* ```ts
+* import { sheetTestToQuestion } from './helpers.js'
+*
+* const artifact = {
+*   path: 'tests/src/styles/index.test.ts',
+*   group: 'tests',
+*   ownership: 'birth',
+*   origin: 'template',
+*   content: "import sheet from '../../../dist/src/styles/index.css?raw'\n",
+* } as const
+* sheetTestToQuestion(artifact, "import sheet from '/dist/src/styles/index.css?raw'\n")?.field // 'tests'
+* sheetTestToQuestion(artifact, artifact.content) // undefined
+* ```
+*/
+function sheetTestToQuestion(artifact, present) {
+	if (artifact.origin === "host" || artifact.ownership !== "birth") return void 0;
+	if (!SHEET_IMPORT_PATTERN.test(artifact.content)) return void 0;
+	const root = "../".repeat(artifact.path.split("/").length - 1);
+	const replacements = [...present.matchAll(ROOT_IMPORT_PATTERN)].map((match) => `'${match[2] ?? ""}' with '${root}${(match[2] ?? "").slice(1)}'`);
+	if (replacements.length === 0) return void 0;
+	const single = replacements.length === 1;
+	return {
+		field: "tests",
+		message: `The birth-owned sheet test ${artifact.path} imports by ${single ? "a root-relative specifier" : "root-relative specifiers"}, which oxlint's import/no-absolute-path rule refuses under --deny-warnings. Replace ${replacements.join(" and ")}. Scaffold does not rewrite a birth-owned file.`,
+		blocking: false,
+		groups: ["tests"]
+	};
+}
+/**
 * Reads the manifest scripts a writing verb may write.
 *
 * @param manifest - The target manifest text.
@@ -1517,11 +1617,14 @@ function selectionToPackages(selection) {
 *
 * @param first - The earlier result, which fixes the reported target.
 * @param second - The later result.
-* @returns One result carrying both path lists, first's paths ahead of second's.
+* @returns One result carrying both path lists, first's paths ahead of second's, each list
+* naming a path once.
 *
 * @remarks
-* Written and skipped never overlap across the calls a verb makes, because each
-* call answers for its own paths.
+* Two calls can answer for one path: `overwrite` declares a missing dependency
+* and later rewrites the ranges in the same manifest, so each list keeps a path's
+* first entry. A path one call skipped and another wrote stays in both lists, as
+* the manifest a repair skips by birth and its range write rewrites does.
 *
 * @example
 * ```ts
@@ -1536,9 +1639,9 @@ function selectionToPackages(selection) {
 function mergeResults(first, second) {
 	return {
 		target: first.target,
-		written: [...first.written, ...second.written],
-		skipped: [...first.skipped, ...second.skipped],
-		removed: [...first.removed, ...second.removed]
+		written: [.../* @__PURE__ */ new Set([...first.written, ...second.written])],
+		skipped: [.../* @__PURE__ */ new Set([...first.skipped, ...second.skipped])],
+		removed: [.../* @__PURE__ */ new Set([...first.removed, ...second.removed])]
 	};
 }
 /**
@@ -1845,7 +1948,7 @@ var CLI = class {
 		const target = command.target ?? ".";
 		const groups = selectionToGroups(command.groups);
 		const blueprint = this.#derive(target);
-		this.#assertTarget(target, blueprint, groups);
+		this.#assertTarget(target, blueprint, groups, true);
 		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,
@@ -1866,23 +1969,42 @@ var CLI = class {
 				pins: manifestToWritableDependencies(this.#manifest(target), blueprint),
 				scripts: manifestToWritableScripts(this.#manifest(target), blueprint)
 			};
-			const local = mergeResults(host.materializer.repair(plan, audit, target), host.materializer.remove(plan, audit, command.dirty === true ? {
+			const additions = manifestToAdditions(this.#manifest(target), blueprint);
+			const repaired = host.materializer.repair(plan, audit, target);
+			const added = additions.runtime.length === 0 && additions.development.length === 0 ? void 0 : host.materializer.declare({
+				pins: {
+					runtime: [],
+					development: []
+				},
+				scripts: [],
+				additions
+			}, target);
+			const removed = host.materializer.remove(plan, audit, command.dirty === true ? {
 				tracked: worktree.tracked,
 				dirty: []
-			} : worktree, target));
+			} : worktree, target);
+			const local = mergeResults(added === void 0 ? repaired : mergeResults(repaired, added), removed);
 			const remainder = command.offline === true ? await this.#declare(host.materializer, target, declared, host.baseline) : await this.#reconcile(host.materializer, target, declared, host.baseline, host.forced);
 			const [measured] = this.#survey(host.materializer, blueprint, target, groups);
 			const terminal = this.#appendQuestions(measured, target, blueprint, groups);
 			const outcome = {
 				...remainder,
 				...mergeResults(local, remainder),
-				audit: terminal
+				audit: terminal,
+				additions
 			};
 			if (command.json === true) this.#report(outcome);
 			else {
 				this.#present(terminal);
 				this.#reportReplacements(audit, terminal);
 				this.#recount(outcome);
+				for (const { section, dependencies } of [{
+					section: "dependencies",
+					dependencies: additions.runtime
+				}, {
+					section: "devDependencies",
+					dependencies: additions.development
+				}]) for (const { name, range } of dependencies) this.#say(`Declared ${JSON.stringify(name)}: ${JSON.stringify(range)} in ${section}. Run npm install to install it.`);
 				if (remainder.note !== void 0) this.#warn(remainder.note);
 			}
 			if (remainder.note !== void 0) return 1;
@@ -2341,9 +2463,32 @@ var CLI = class {
 			groups: ["manifest"]
 		};
 	}
-	#dependencyQuestion(target, blueprint, writing = false) {
+	#dependencyQuestion(target, blueprint, writing = false, declaring = false) {
 		const parsed = parseJSON(this.#manifest(target));
 		if (!isRecord(parsed)) return void 0;
+		const dependencies = isRecord(parsed.dependencies) ? parsed.dependencies : {};
+		const development = isRecord(parsed.devDependencies) ? parsed.devDependencies : {};
+		const missing = Object.entries(blueprintToDevDependencies(blueprint)).filter(([name]) => !Object.hasOwn(dependencies, name) && !Object.hasOwn(development, name)).sort(([left], [right]) => left.localeCompare(right));
+		const names = missing.map(([name]) => name);
+		if (declaring && missing.length > 0) {
+			const planned = `${names.length === 1 ? "the planned dependency" : "the planned dependencies"} ${names.join(", ")}`;
+			if (parsed.devDependencies !== void 0 && !isRecord(parsed.devDependencies)) return {
+				field: "dependencies",
+				message: `The manifest at ${target} declares devDependencies as a value that is not an object, so overwrite cannot declare ${planned} in it. Replace it with an object in package.json before running overwrite.`,
+				blocking: true,
+				groups: ["configs", "tests"]
+			};
+			const entries = Object.entries(development).filter(([, value]) => !isString(value)).map(([name]) => JSON.stringify(name));
+			if (entries.length > 0) {
+				const single = entries.length === 1;
+				return {
+					field: "dependencies",
+					message: `The manifest at ${target} declares the devDependencies ${single ? "entry" : "entries"} ${entries.join(", ")} as ${single ? "a value that is not a version string" : "values that are not version strings"}, so overwrite cannot declare ${planned} beside ${single ? "it" : "them"}. Replace ${single ? "it with a version range" : "them with version ranges"} in package.json before running overwrite.`,
+					blocking: true,
+					groups: ["configs", "tests"]
+				};
+			}
+		}
 		const malformed = ["dependencies", "devDependencies"].filter((section) => parsed[section] !== void 0 && !isRecord(parsed[section]));
 		if (malformed.length > 0) return {
 			field: "dependencies",
@@ -2351,11 +2496,7 @@ var CLI = class {
 			blocking: false,
 			groups: ["configs", "tests"]
 		};
-		const dependencies = isRecord(parsed.dependencies) ? parsed.dependencies : {};
-		const development = isRecord(parsed.devDependencies) ? parsed.devDependencies : {};
-		const missing = Object.entries(blueprintToDevDependencies(blueprint)).filter(([name]) => !Object.hasOwn(dependencies, name) && !Object.hasOwn(development, name)).sort(([left], [right]) => left.localeCompare(right));
-		if (missing.length === 0) return void 0;
-		const names = missing.map(([name]) => name);
+		if (missing.length === 0 || declaring) return void 0;
 		const lines = missing.map(([name, range]) => `${JSON.stringify(name)}: ${JSON.stringify(range)},`);
 		return {
 			field: "dependencies",
@@ -2390,7 +2531,15 @@ var CLI = class {
 			groups: ["tests"]
 		};
 	}
-	#targetQuestions(target, blueprint, groups, writing = false) {
+	#sheetQuestions(target, blueprint) {
+		return blueprintToTestArtifacts(blueprint).flatMap((artifact) => {
+			const path = resolveContainedPath(target, artifact.path);
+			if (path === void 0 || !isExactCaseFile(path)) return [];
+			const question = sheetTestToQuestion(artifact, readFileText(target, artifact.path) ?? "");
+			return question === void 0 ? [] : [question];
+		});
+	}
+	#targetQuestions(target, blueprint, groups, writing = false, declaring = false) {
 		const questions = [];
 		const browser = resolveContainedPath(target, "app/browser");
 		if (browser !== void 0 && listFiles(browser).some((path) => path.endsWith(".vue"))) questions.push({
@@ -2405,11 +2554,12 @@ var CLI = class {
 		}
 		const project = this.#projectQuestion(target, blueprint, writing);
 		if (project !== void 0) questions.push(project);
-		const dependency = this.#dependencyQuestion(target, blueprint, writing);
+		const dependency = this.#dependencyQuestion(target, blueprint, writing, declaring);
 		if (dependency !== void 0) questions.push(dependency);
 		if (!writing) {
 			const setup = this.#setupQuestion(target, blueprint);
 			if (setup !== void 0) questions.push(setup);
+			questions.push(...this.#sheetQuestions(target, blueprint));
 		}
 		return questions.filter((question) => question.blocking || groups === void 0 || question.groups.some((group) => groups.includes(group))).map(({ field, message, blocking, candidates }) => ({
 			field,
@@ -2425,9 +2575,9 @@ var CLI = class {
 			questions: [...audit.questions, ...questions]
 		};
 	}
-	#assertTarget(target, blueprint, groups) {
+	#assertTarget(target, blueprint, groups, declaring = false) {
 		if (manifestToName(this.#manifest(target)) === PACKAGE_NAME) throw new ScaffoldError("TARGET", `The target at ${target} is the ${PACKAGE_NAME} package, whose canon the vendored host is staged from. Run repair and overwrite against a workspace that consumes it.`, { target });
-		const questions = this.#targetQuestions(target, blueprint, groups, true);
+		const questions = this.#targetQuestions(target, blueprint, groups, true, declaring);
 		if (questions.length === 0) return;
 		throw new ScaffoldError("TARGET", questions.map((question) => question.message).join(" "), { target });
 	}