@orkestrel/scaffold 0.0.99 → 0.0.100

package/dist/host/guides/scaffold.md

@@ -185,7 +185,8 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `SERVICE_TEST_INCLUDE`            | const | Names the include the live-service project covers, which is a directory rather than one proof.         |
 | `SHEET_ENTRY_NAME`                | const | Names the build entry beside each stylesheet marker.                                                   |
 | `SHOWCASE_CONFIG_PATH`            | const | Names the Vite wrapper whose presence makes a workspace `showcase`.                                    |
-| `SHOWCASE_DEV_DEPENDENCIES`       | const | Names the development dependency used only by the optional single-file showcase build.                 |
+| `SHOWCASE_DEV_DEPENDENCIES`       | const | Names the tested dependency pair selected by the optional single-file showcase build.                  |
+| `SHOWCASE_OVERRIDES`              | const | Names the scoped npm override required by the tested showcase plugin.                                  |
 | `SHOWCASE_PAGES_PATH`             | const | Names the physical showcase output directory.                                                          |
 | `SKILLS_CONFIG_PATH`              | const | Names the TypeScript wrapper whose presence makes a workspace `skills`.                                |
 | `SOURCE_BROWSER_DEV_DEPENDENCIES` | const | Lists the development dependencies a published browser `src` environment adds.                         |
@@ -295,6 +296,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `blueprintToHostArtifacts`          | function | Compiles the vendored host artifacts a workspace plans.                                                  |
 | `blueprintToMachinery`              | function | Derives the host-specific machinery a generated root Vite configuration carries.                         |
 | `blueprintToManifest`               | function | Compiles a blueprint into its `package.json` content.                                                    |
+| `blueprintToManifestOverrides`      | function | Projects the scoped npm overrides required by a selected browser showcase.                               |
 | `blueprintToOrchestrationArtifacts` | function | Compiles the blueprint-dependent orchestration artifacts.                                                |
 | `blueprintToQuestions`              | function | Measures a blueprint against every law its own fields decide.                                            |
 | `blueprintToRootTsconfig`           | function | Compiles the root TypeScript configuration for a blueprint.                                              |
@@ -313,6 +315,7 @@ Exported from `@orkestrel/scaffold`, and reachable from
 | `planToFindings`                    | function | Compares a plan against a target's current content.                                                      |
 | `planToHash`                        | function | Computes a plan's content identity.                                                                      |
 | `replaceManifestRanges`             | function | Replaces the runtime and development dependency ranges in package manifest text, and never a peer range. |
+| `replaceManifestOverrides`          | function | Replaces selected npm override leaves while preserving every byte outside the edited path.               |
 | `replaceManifestScripts`            | function | Replaces named script values in package manifest text.                                                   |
 | `replacePlanRanges`                 | function | Replaces dependency ranges in a plan's manifest and recomputes its identity.                             |
 | `srcToEntry`                        | function | Projects a published selection into the manifest's entry fields.                                         |
@@ -1776,15 +1779,34 @@ lookup verdict records why the registry row could not enter a layer.
 
 ## Dependency floors
 
-Every scaffold-owned runtime or development range is a floor: a caret over a whole
+Except for the selected showcase policy, every scaffold-owned runtime or development range is a floor: a caret over a whole
 `major.minor.patch` version. The triple is the newest release the registry served when that floor
 was last raised, so a workspace generated with no network still receives the latest floor scaffold
 knew rather than a bare `major.0.0`. A `Blueprint.peers` row is written during creation into a
 vacant target. After creation, peer declarations and `peerDependenciesMeta` are caller-owned:
 `audit`, `repair`, `catalog`, and `overwrite` do not invent, rewrite, insert, or remove them. Caller
-extras also pass through unchanged. Extras follow `EXTRA_RANGE_PATTERN`; fleet peers follow
+extras pass through unchanged except for the selected showcase pair. Extras follow `EXTRA_RANGE_PATTERN`; fleet peers follow
 `ORKESTREL_RANGE_PATTERN`; foreign peers follow `FLOOR_RANGE_PATTERN`.
 
+A browser application with `showcase: true`, including its Vue face, selects exact
+`vite-plugin-singlefile: 2.3.3`, Vite `^8.3.4` from scaffold's manifest, and the npm override
+`"vite-plugin-singlefile@2.3.3": { "micromatch": "npm:picomatch@2.3.2" }`. This policy applies
+after extras. Online resolution excludes this pair from ordinary foreign-major updates; other
+dependencies retain their usual resolution. Repair preserves each package's runtime or development
+section. Audit reports pin drift and override-only drift. Overwrite lands the pair and override in
+its offline half, including missing planned dependencies, before the catalog read.
+
+`blueprintToManifestOverrides(blueprint: Blueprint): Readonly<Record<string, Readonly<Record<string, string>>>>`
+projects this metadata for a selected showcase and returns an empty map otherwise.
+`replaceManifestOverrides(manifest: string, overrides: Readonly<Record<string, Readonly<Record<string, string>>>>): string | undefined`
+inserts missing ancestors or leaves and replaces stale string leaves without changing unrelated
+bytes. Aligned text is returned unchanged. Invalid JSON, duplicate selected keys, malformed
+ancestors, and non-string owned leaves return `undefined`; repair and overwrite refuse these
+structures before writing configuration. `ManifestRegionSet.overrides` carries the same optional
+map into `Materializer.declare`, independently of the artifact replacements in `Blueprint.overrides`.
+Like other manifest-region writes, repair and overwrite apply this policy with any `--groups`
+selection. `replaceManifestRanges` continues to ignore npm overrides.
+
 The distribution project packs a caller-owned peer beside a co-peer witness that requires an exact
 version. The real npm resolver accepts the preserved range. Its narrowed-range control reports
 `ERESOLVE`.
@@ -1800,7 +1822,7 @@ row entering or leaving the manifest moves a test rather than passing unnoticed.
 of `STYLES_DEV_DEPENDENCIES`, is a seed as well: it carries the `^1.105.1` range the
 `@orkestrel/veneer` checkout declared on 2026-09-30, and that test names it in the seeded set.
 
-A newer major is never crossed for you. `audit` reports one as a non-blocking `dependencies`
+Outside the selected showcase pair, a newer major is never crossed for you. `audit` reports one as a non-blocking `dependencies`
 question, and a person decides whether the generated toolchain supports it. Inside the declared
 major the verbs raise the floor themselves, which is what makes the caret's own width beside the
 point: `^0.64.0` admits no `0.65.0`, and `repair` rewrites the range to `^0.65.0` rather than

package/dist/host/manifest.json

@@ -1042,7 +1042,7 @@
 			"storage": "guides/scaffold.md",
 			"destination": "guides/scaffold.md",
 			"executable": false,
-			"digest": "92391c5adfa7652ce6c4b34b4b78176f152d0c4398f28dc7da04797b64e2e973"
+			"digest": "d0a34d3e2fce85649ad48e6ab59da0a0098bd9945bac33168412410d5f0b8ad4"
 		},
 		{
 			"storage": "guides/sea.md",
@@ -2120,5 +2120,5 @@
 			]
 		}
 	],
-	"digest": "9accd825a5d01bac14b22e69911c94abb361165b21ab9e12dbc899dcc1cbc0cd"
+	"digest": "2eb5a827baa67b121d77f333051acf59bd11b1572c9f26f7364444b1b4d9a9f4"
 }

package/dist/src/core/index.cjs

@@ -4,7 +4,7 @@ let _orkestrel_template = require("@orkestrel/template");
 let _orkestrel_emitter = require("@orkestrel/emitter");
 var package_default = {
 	name: "@orkestrel/scaffold",
-	version: "0.0.99",
+	version: "0.0.100",
 	description: "Scaffold workspaces with commands: new, audit, repair, catalog, and overwrite.",
 	keywords: [
 		"audit",
@@ -710,7 +710,7 @@ var APP_BROWSER_DEV_DEPENDENCIES = Object.freeze({
 	"@orkestrel/html": package_default.devDependencies["@orkestrel/html"]
 });
 /**
-* Names the development dependency used only by the optional single-file showcase build.
+* Names the tested dependency pair selected by the optional single-file showcase build.
 *
 * @example
 * ```ts
@@ -719,7 +719,12 @@ var APP_BROWSER_DEV_DEPENDENCIES = Object.freeze({
 * SHOWCASE_DEV_DEPENDENCIES['vite-plugin-singlefile'] // the showcase plugin range
 * ```
 */
-var SHOWCASE_DEV_DEPENDENCIES = Object.freeze({ "vite-plugin-singlefile": "^2.3.3" });
+var SHOWCASE_DEV_DEPENDENCIES = Object.freeze({
+	"vite-plugin-singlefile": "2.3.3",
+	vite: package_default.devDependencies.vite
+});
+/** Names the scoped npm override required by the tested showcase plugin. */
+var SHOWCASE_OVERRIDES = Object.freeze({ [`vite-plugin-singlefile@${SHOWCASE_DEV_DEPENDENCIES["vite-plugin-singlefile"]}`]: Object.freeze({ micromatch: "npm:picomatch@2.3.2" }) });
 /** Lists the development dependencies a private server application adds. */
 var APP_SERVER_DEV_DEPENDENCIES = Object.freeze({
 	"@orkestrel/emitter": package_default.dependencies["@orkestrel/emitter"],
@@ -5765,16 +5770,106 @@ function blueprintToDevDependencies(blueprint) {
 		...blueprint.src.includes("browser") || blueprint.setup.includes("browser") || sheets ? SOURCE_BROWSER_DEV_DEPENDENCIES : {},
 		...blueprint.app.length > 0 ? APP_DEV_DEPENDENCIES : {},
 		...blueprint.app.includes("browser") ? APP_BROWSER_DEV_DEPENDENCIES : {},
-		...blueprint.showcase && blueprint.app.includes("browser") ? SHOWCASE_DEV_DEPENDENCIES : {},
 		...blueprint.app.includes("server") ? APP_SERVER_DEV_DEPENDENCIES : {}
 	};
 	for (const framework of blueprintToMachinery(blueprint).frameworks) Object.assign(merged, FRAMEWORK_MATRIX[framework].dependencies);
 	for (const extra of blueprint.extras) merged[extra.name] = extra.range;
+	if (blueprint.showcase && blueprint.app.includes("browser")) Object.assign(merged, SHOWCASE_DEV_DEPENDENCIES);
 	for (const peer of blueprint.peers) if (!Object.hasOwn(merged, peer.name)) merged[peer.name] = peer.range;
 	const runtime = new Set(blueprint.dependencies.map((dependency) => dependency.name));
 	return Object.fromEntries(Object.entries(merged).filter(([name]) => name !== own && !runtime.has(name)).sort(([left], [right]) => (0, _orkestrel_contract.compareValues)(left, right)));
 }
 /**
+* Projects the scoped npm overrides required by a selected browser showcase.
+*
+* @param blueprint - The workspace specification.
+* @returns The showcase override map, or an empty map for other workspaces.
+* @example
+* ```ts
+* import { blueprintToManifestOverrides, createBlueprint } from '@orkestrel/scaffold'
+* blueprintToManifestOverrides(createBlueprint('desk', { app: ['browser'], showcase: true }))
+* // { 'vite-plugin-singlefile@2.3.3': { micromatch: 'npm:picomatch@2.3.2' } }
+* ```
+*/
+function blueprintToManifestOverrides(blueprint) {
+	return blueprint.showcase && blueprint.app.includes("browser") ? SHOWCASE_OVERRIDES : {};
+}
+/**
+* Replaces selected npm override leaves while preserving every byte outside the edited path.
+*
+* @param manifest - The JSON package manifest text.
+* @param overrides - The scoped selectors and string leaves to write.
+* @returns The aligned text, or `undefined` for invalid JSON, duplicate selected keys, malformed ancestors, or non-string owned leaves.
+* @remarks
+* Absent ancestors and leaves are inserted. Aligned strings retain their original spelling.
+* Unrelated overrides remain caller-owned. Artifact replacements in `Blueprint.overrides` are independent.
+* @example
+* ```ts
+* import { replaceManifestOverrides } from '@orkestrel/scaffold'
+* replaceManifestOverrides('{}', { 'plugin@1.0.0': { child: '2.0.0' } })
+* // '{"overrides":{"plugin@1.0.0":{"child":"2.0.0"}}}'
+* ```
+*/
+function replaceManifestOverrides(manifest, overrides) {
+	if (!(0, _orkestrel_contract.isRecord)((0, _orkestrel_contract.parseJSON)(manifest))) return void 0;
+	let compiled = manifest;
+	for (const [selector, children] of Object.entries(overrides)) for (const [child, range] of Object.entries(children)) {
+		const path = [
+			"overrides",
+			selector,
+			child
+		];
+		let open = compiled.indexOf("{");
+		for (let level = 0; level < path.length; level += 1) {
+			const key = path[level];
+			let depth = 0;
+			let close = -1;
+			let start = -1;
+			let end = -1;
+			let count = 0;
+			for (const token of compiled.slice(open).matchAll(/"(?:\\[\s\S]|[^"\\])*"|[{}[\]]/gu)) {
+				const position = open + token.index;
+				const text = token[0];
+				if (text === "{" || text === "[") depth += 1;
+				else if (text === "}" || text === "]") {
+					depth -= 1;
+					if (depth === 1 && start >= 0 && end < 0) end = position + 1;
+					if (depth === 0) {
+						close = position;
+						break;
+					}
+				} else if (depth === 1) {
+					if (position === start) end = position + text.length;
+					let colon = position + text.length;
+					while (/\s/u.test(compiled.charAt(colon))) colon += 1;
+					if (compiled.charAt(colon) !== ":" || (0, _orkestrel_contract.parseJSON)(text) !== key) continue;
+					count += 1;
+					start = colon + 1;
+					while (/\s/u.test(compiled.charAt(start))) start += 1;
+					end = -1;
+				}
+			}
+			if (close < 0 || count > 1) return void 0;
+			if (count === 0) {
+				let insertion = JSON.stringify(range);
+				for (const name of path.slice(level).reverse()) insertion = `{${JSON.stringify(name)}:${insertion}}`;
+				let tail = close - 1;
+				while (tail > open && /\s/u.test(compiled.charAt(tail))) tail -= 1;
+				compiled = compiled.slice(0, tail + 1) + (tail === open ? "" : ",") + insertion.slice(1, -1) + compiled.slice(tail + 1);
+				break;
+			}
+			if (level < path.length - 1) {
+				if (compiled.charAt(start) !== "{") return void 0;
+				open = start;
+			} else {
+				if (compiled.charAt(start) !== "\"" || end < 0) return void 0;
+				if ((0, _orkestrel_contract.parseJSON)(compiled.slice(start, end)) !== range) compiled = compiled.slice(0, start) + JSON.stringify(range) + compiled.slice(end);
+			}
+		}
+	}
+	return compiled;
+}
+/**
 * Projects a blueprint into the scripts its manifest declares.
 *
 * @param blueprint - The workspace specification.
@@ -6107,6 +6202,7 @@ function blueprintToManifest(blueprint) {
 		scripts: blueprintToScripts(blueprint),
 		dependencies,
 		devDependencies: blueprintToDevDependencies(blueprint),
+		...Object.keys(blueprintToManifestOverrides(blueprint)).length > 0 ? { overrides: blueprintToManifestOverrides(blueprint) } : {},
 		...Object.keys(peerDependencies).length > 0 ? { peerDependencies } : {},
 		...Object.keys(peerDependenciesMeta).length > 0 ? { peerDependenciesMeta } : {},
 		devEngines: WORKSPACE_DEV_ENGINES,
@@ -8778,6 +8874,7 @@ exports.SERVICE_TEST_INCLUDE = SERVICE_TEST_INCLUDE;
 exports.SHEET_ENTRY_NAME = SHEET_ENTRY_NAME;
 exports.SHOWCASE_CONFIG_PATH = SHOWCASE_CONFIG_PATH;
 exports.SHOWCASE_DEV_DEPENDENCIES = SHOWCASE_DEV_DEPENDENCIES;
+exports.SHOWCASE_OVERRIDES = SHOWCASE_OVERRIDES;
 exports.SHOWCASE_PAGES_PATH = SHOWCASE_PAGES_PATH;
 exports.SKILLS_CONFIG_PATH = SKILLS_CONFIG_PATH;
 exports.SOURCE_BROWSER_DEV_DEPENDENCIES = SOURCE_BROWSER_DEV_DEPENDENCIES;
@@ -8806,6 +8903,7 @@ exports.blueprintToGuideArtifacts = blueprintToGuideArtifacts;
 exports.blueprintToHostArtifacts = blueprintToHostArtifacts;
 exports.blueprintToMachinery = blueprintToMachinery;
 exports.blueprintToManifest = blueprintToManifest;
+exports.blueprintToManifestOverrides = blueprintToManifestOverrides;
 exports.blueprintToOptimizedDependencies = blueprintToOptimizedDependencies;
 exports.blueprintToOrchestrationArtifacts = blueprintToOrchestrationArtifacts;
 exports.blueprintToProjects = blueprintToProjects;
@@ -8882,6 +8980,7 @@ exports.planToFindings = planToFindings;
 exports.planToHash = planToHash;
 exports.planToSummary = planToSummary;
 exports.renderSkillPointer = renderSkillPointer;
+exports.replaceManifestOverrides = replaceManifestOverrides;
 exports.replaceManifestRanges = replaceManifestRanges;
 exports.replaceManifestScripts = replaceManifestScripts;
 exports.replacePlanRanges = replacePlanRanges;