@orkestrel/scaffold 0.0.81 → 0.0.82

package/dist/bin/main.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { align, renderTable, strip, stripControls, width } from "@orkestrel/console";
 import { attempt, isArray, isError, isInstance, 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, JOURNEY_CONFIG_PATH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, SERVICE_SETUP_PATH, SHOWCASE_CONFIG_PATH, SKILLS_CONFIG_PATH, ScaffoldError, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToRootVite, blueprintToScripts, blueprintToTestArtifacts, blueprintToWritableScripts, compareVersions, createBlueprint, extractRangeMajor, extractVersion, isFloorPath, isScaffoldError, manifestToDependencies, manifestToName, nameToGuide, replaceManifestScripts, replacePlanRanges } from "../src/core/index.js";
+import { AXES, BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFORMANCE_TEST_PATH, Compiler, DEPENDENCY_NAME_PATTERN, ENVIRONMENTS, FRAMEWORKS, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HOST_PATHS, INTEGRATION_TEST_PATH, JOURNEY_CONFIG_PATH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, RESERVED_SHEET_NAMES, SERVICE_SETUP_PATH, SHEET_ENTRY_NAME, SHOWCASE_CONFIG_PATH, SHOWCASE_PAGES_PATH, SKILLS_CONFIG_PATH, STYLES_ENTRY_PATH, ScaffoldError, THEMES_BARREL_PATH, THEMES_ENTRY_PATH, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToFaces, blueprintToProjects, blueprintToScripts, blueprintToSheets, blueprintToTestArtifacts, blueprintToWritableScripts, compareVersions, createBlueprint, extractRangeMajor, extractVersion, isFloorPath, isScaffoldError, isSheetName, manifestToDependencies, manifestToName, nameToGuide, parseExtension, replaceManifestScripts, replacePlanRanges } from "../src/core/index.js";
 import { MAX_INVENTORY_PATHS, Materializer, Upstream, filesToHost, isExactCaseFile, isPhysicalDirectory, isWorktree, listFiles, readFileText, readHostFloor, readHostManifest, readSnapshot, resolveContainedPath } from "../src/server/index.js";
 import { createMarkdown, flattenText, isTableNode } from "@orkestrel/markdown";
 import { createSession } from "@orkestrel/process/server";
+import { readdirSync } from "node:fs";
+import { normalize } from "node:path";
 import { parseArgs } from "node:util";
 //#region src/bin/constants.ts
 /**
@@ -82,6 +84,13 @@ var COMMAND_OPTIONS = Object.freeze({
 	src: Object.freeze({ type: "string" }),
 	app: Object.freeze({ type: "string" }),
 	bin: Object.freeze({ type: "boolean" }),
+	styles: Object.freeze({ type: "boolean" }),
+	themes: Object.freeze({ type: "boolean" }),
+	showcase: Object.freeze({ type: "boolean" }),
+	extend: Object.freeze({
+		type: "string",
+		multiple: true
+	}),
 	deps: Object.freeze({ type: "string" }),
 	groups: Object.freeze({ type: "string" }),
 	all: Object.freeze({ type: "boolean" }),
@@ -106,6 +115,10 @@ 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",
+	"--styles": "select the base styles surface",
+	"--themes": "select themes; requires --styles",
+	"--showcase": "select the showcase; requires --app browser",
+	"--extend <list>": "select surface:name extensions on the selected surfaces",
 	"--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 the declared ones alone",
@@ -131,6 +144,10 @@ var VERB_OPTIONS = Object.freeze({
 		"--src <list>",
 		"--app <list>",
 		"--bin",
+		"--styles",
+		"--themes",
+		"--showcase",
+		"--extend <list>",
 		"--deps <list>",
 		"--offline",
 		"--from <path>",
@@ -383,6 +400,9 @@ function argvToCommand(argv) {
 	const target = isString(values.target) ? values.target : void 0;
 	const json = values.json === true;
 	const [from] = paths;
+	const extensions = isArray(values.extend) ? values.extend.filter(isString) : [];
+	if (extensions.length > 1) throw new UsageError("'new' takes --extend once; combine entries in one list.");
+	const [extension] = extensions;
 	const location = target === void 0 ? {} : { target };
 	const source = from === void 0 ? {} : { from };
 	const selection = isString(values.groups) ? { groups: values.groups } : {};
@@ -398,6 +418,10 @@ function argvToCommand(argv) {
 				...src === void 0 ? {} : { src },
 				...app === void 0 ? {} : { app },
 				...bin ? { bin } : {},
+				...values.styles === true ? { styles: true } : {},
+				...values.themes === true ? { themes: true } : {},
+				...values.showcase === true ? { showcase: true } : {},
+				...extension === void 0 ? {} : { extensions: extension },
 				...offline ? { offline } : {},
 				...dependencies === void 0 ? {} : { dependencies }
 			};
@@ -888,6 +912,7 @@ function releasesToPins(releases, declared) {
 * Reads the literal Vitest projects, configuration paths, and npm run scripts a shell command names.
 *
 * @param script - The manifest script text to read.
+* @param wrappers - Planned wrapper paths mapped to the face projects they run.
 * @returns The named projects, configurations, and scripts, or `undefined` when the command
 * cannot be read literally.
 *
@@ -906,7 +931,7 @@ function releasesToPins(releases, declared) {
 * // { projects: ['src:core'], configs: [], scripts: [] }
 * ```
 */
-function scriptToInvocations(script) {
+function scriptToInvocations(script, wrappers = /* @__PURE__ */ new Map()) {
 	const tokens = [];
 	let value = "";
 	let resolved = true;
@@ -983,9 +1008,19 @@ function scriptToInvocations(script) {
 	const projects = [];
 	const configs = [];
 	const scripts = [];
+	const configurations = new Map([...wrappers].map(([path, project]) => [normalize(path), project]));
+	let testing = false;
 	for (let index = 0; index < tokens.length; index += 1) {
 		const token = tokens[index];
 		if (token === void 0) return void 0;
+		if (index === 0 || [
+			"&&",
+			"||",
+			";",
+			"|",
+			"&",
+			"("
+		].includes(tokens[index - 1]?.value ?? "")) testing = token.resolved && token.value === "vitest" && tokens[index + 1]?.value === "run";
 		if (token.value === "npm" && tokens[index + 1]?.value === "run") {
 			const name = tokens[index + 2];
 			if (name === void 0 || !name.resolved || name.value.length === 0 || [
@@ -1012,14 +1047,20 @@ function scriptToInvocations(script) {
 				"(",
 				")"
 			].includes(project.value)) return void 0;
-			(token.value === "--project" ? projects : configs).push(project.value);
+			const names = token.value === "--project" ? projects : configs;
+			names.push(project.value);
+			const face = testing && names === configs ? configurations.get(normalize(project.value)) : void 0;
+			if (face !== void 0) projects.push(face);
 			index += 1;
 			continue;
 		}
 		if (token.value.startsWith("--project=") || token.value.startsWith("--config=")) {
 			const project = token.value.slice(token.value.indexOf("=") + 1);
 			if (!token.resolved || project.length === 0) return void 0;
-			(token.value.startsWith("--project=") ? projects : configs).push(project);
+			const names = token.value.startsWith("--project=") ? projects : configs;
+			names.push(project);
+			const face = testing && names === configs ? configurations.get(normalize(project)) : void 0;
+			if (face !== void 0) projects.push(face);
 			continue;
 		}
 		if (!token.resolved && /--project|--config/.test(token.value)) return void 0;
@@ -1055,6 +1096,96 @@ function targetToEnvironments(target, axis) {
 	});
 }
 /**
+* Reads the styles, themes, and showcase markers a target physically holds.
+* @param target - The target directory.
+* @returns The independent structural facts, false when their markers are absent.
+*/
+function targetToFacts(target) {
+	const styles = resolveContainedPath(target, STYLES_ENTRY_PATH);
+	const themes = resolveContainedPath(target, THEMES_ENTRY_PATH);
+	const barrel = resolveContainedPath(target, THEMES_BARREL_PATH);
+	const wrapper = resolveContainedPath(target, SHOWCASE_CONFIG_PATH);
+	const pages = resolveContainedPath(target, SHOWCASE_PAGES_PATH);
+	return {
+		styles: styles !== void 0 && isExactCaseFile(styles),
+		themes: themes !== void 0 && isExactCaseFile(themes) && barrel !== void 0 && isExactCaseFile(barrel),
+		showcase: wrapper !== void 0 && isExactCaseFile(wrapper) || pages !== void 0 && isPhysicalDirectory(pages)
+	};
+}
+/**
+* Reads browser faces and named sheet marker pairs from a target.
+* @param target - The target directory.
+* @returns Browser extensions in framework order followed by sheets in code-unit order.
+* @throws `ScaffoldError` when sheet markers name an invalid or case-colliding face, or the directory cannot be read.
+*/
+function targetToExtensions(target) {
+	const extensions = [];
+	for (const name of FRAMEWORKS) {
+		const axes = AXES.filter((axis) => {
+			const path = resolveContainedPath(target, `${axis}/${name}`);
+			return path !== void 0 && isPhysicalDirectory(path);
+		});
+		if (axes.length > 0) extensions.push({
+			surface: "browser",
+			name,
+			axes
+		});
+	}
+	const source = resolveContainedPath(target, "src");
+	if (source === void 0 || !isPhysicalDirectory(source)) return extensions;
+	const entries = readdirSync(source, { withFileTypes: true });
+	if (entries.length > MAX_INVENTORY_PATHS) throw new ScaffoldError("TARGET", "The source directory exceeds the inventory limit.");
+	const names = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		if (!entry.isDirectory() || RESERVED_SHEET_NAMES.includes(entry.name)) continue;
+		const sheet = resolveContainedPath(target, `src/${entry.name}/index.scss`);
+		const marker = resolveContainedPath(target, `src/${entry.name}/${SHEET_ENTRY_NAME}`);
+		if (sheet === void 0 || marker === void 0 || !isExactCaseFile(sheet) || !isExactCaseFile(marker)) continue;
+		const folded = entry.name.toLowerCase();
+		if (seen.has(folded)) throw new ScaffoldError("TARGET", `Case-colliding sheet face '${entry.name}'.`);
+		seen.add(folded);
+		names.push(entry.name);
+	}
+	for (const name of names.sort()) {
+		if (!isSheetName(name)) throw new ScaffoldError("TARGET", `Invalid sheet face '${name}'.`);
+		extensions.push({
+			surface: "styles",
+			name
+		});
+	}
+	return extensions;
+}
+/**
+* Reads a creation extension list and assigns its selected browser axes.
+* @param selection - The comma-separated `surface:name` entries, or no selection.
+* @param axes - The axes selecting a browser environment.
+* @param styles - If `true`, admits stylesheet extensions; if `false`, refuses them.
+* @returns The validated extensions in selection order.
+* @throws `UsageError` when an entry is malformed, repeated, unsupported, or lacks its surface.
+*/
+function selectionToExtensions(selection, axes, styles) {
+	if (selection === void 0) return [];
+	const extensions = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of selection.split(",")) {
+		const extension = parseExtension(entry);
+		if (extension === void 0 || seen.has(entry)) throw new UsageError(`'--extend' refuses '${entry}': use distinct supported surface:name entries.`);
+		seen.add(entry);
+		if (extension.surface === "browser") {
+			if (axes.length === 0) throw new UsageError("A browser extension requires browser in --src or --app.");
+			extensions.push({
+				...extension,
+				axes
+			});
+		} else {
+			if (!styles) throw new UsageError("A styles extension requires --styles.");
+			extensions.push(extension);
+		}
+	}
+	return extensions;
+}
+/**
 * Reads the packages a target's catalog table listed before this run.
 *
 * @param target - The target or raw checkout directory, or a verified value host.
@@ -1396,9 +1527,17 @@ var CLI = class {
 	async #create(command) {
 		const target = command.target ?? command.name;
 		const app = selectionToEnvironments(command.app, "app");
+		const src = selectionToEnvironments(command.src, "src");
+		if (command.themes === true && command.styles !== true) throw new UsageError("--themes requires --styles.");
+		if (command.showcase === true && !app.includes("browser")) throw new UsageError("--showcase requires --app browser.");
+		const axes = AXES.filter((axis) => (axis === "src" ? src : app).includes("browser"));
 		const blueprint = createBlueprint(command.name, {
-			src: selectionToEnvironments(command.src, "src"),
+			src,
 			app,
+			extensions: selectionToExtensions(command.extensions, axes, command.styles === true),
+			styles: command.styles === true,
+			themes: command.themes === true,
+			showcase: command.showcase === true,
 			journey: app.includes("browser"),
 			bin: command.bin === true,
 			setup: [],
@@ -1900,16 +2039,17 @@ var CLI = class {
 		const conformance = resolveContainedPath(target, CONFORMANCE_TEST_PATH);
 		const service = resolveContainedPath(target, SERVICE_SETUP_PATH);
 		const global = resolveContainedPath(target, GLOBAL_SETUP_PATH);
-		const showcase = resolveContainedPath(target, SHOWCASE_CONFIG_PATH);
 		const journey = resolveContainedPath(target, JOURNEY_CONFIG_PATH);
 		const skills = resolveContainedPath(target, SKILLS_CONFIG_PATH);
 		const setup = /* @__PURE__ */ new Set();
 		if (tests !== void 0) for (const path of listFiles(tests)) {
 			if (path.includes("/") || !path.startsWith("setup") || !path.endsWith(".test.ts")) continue;
 			const proof = resolveContainedPath(tests, path);
-			if (proof !== void 0 && isExactCaseFile(proof)) setup.add(path === "setupBrowser.test.ts" ? "browser" : "node");
+			if (proof !== void 0 && isExactCaseFile(proof)) setup.add(path === "setupBrowser.test.ts" || path === "setupStyles.test.ts" ? "browser" : "node");
 		}
 		return createBlueprint(declared.slice(declared.lastIndexOf("/") + 1), {
+			...targetToFacts(target),
+			extensions: targetToExtensions(target),
 			src: targetToEnvironments(target, "src"),
 			app: targetToEnvironments(target, "app"),
 			dependencies: manifestToDependencies(manifest).runtime,
@@ -1920,7 +2060,6 @@ var CLI = class {
 			conformance: conformance !== void 0 && isExactCaseFile(conformance),
 			service: service !== void 0 && isExactCaseFile(service),
 			global: global !== void 0 && isExactCaseFile(global),
-			showcase: showcase !== void 0 && isExactCaseFile(showcase),
 			journey: journey !== void 0 && isExactCaseFile(journey),
 			skills: skills !== void 0 && isExactCaseFile(skills)
 		});
@@ -1929,7 +2068,7 @@ var CLI = class {
 		const text = this.#manifest(target);
 		const writable = writing ? manifestToWritableScripts(text, blueprint) : blueprintToWritableScripts(blueprint);
 		const manifest = replaceManifestScripts(text, writable) ?? text;
-		const planned = blueprintToRootVite(blueprint);
+		const planned = new Set(blueprintToProjects(blueprint));
 		const parsed = parseJSON(manifest);
 		const scripts = isRecord(parsed) && isRecord(parsed.scripts) ? parsed.scripts : {};
 		const gates = !isRecord(parsed) || parsed.private !== true ? ["test", "prepublishOnly"] : ["test"];
@@ -1943,7 +2082,7 @@ var CLI = class {
 				unresolved = true;
 				continue;
 			}
-			for (const project of invoked.projects) if (!planned.includes(`name: { label: '${project}',`)) absent.add(project);
+			for (const project of invoked.projects) if (!planned.has(project)) absent.add(project);
 		}
 		const projects = [...absent].sort();
 		if (unresolved) return {
@@ -1991,6 +2130,14 @@ var CLI = class {
 				if (command !== void 0) expectedLines.set(project, `"${direct}": ${JSON.stringify(command)},`);
 			}
 		}
+		const faces = /* @__PURE__ */ new Set([...blueprintToSheets(blueprint).map((name) => `src:${name}`), ...blueprintToFaces(blueprint).flatMap(({ name, axes }) => axes.map((axis) => `${axis}:${name}`))]);
+		const wrappers = /* @__PURE__ */ new Map();
+		for (const artifact of blueprintToConfigArtifacts(blueprint)) {
+			const match = /^configs\/(src|app)\/vite\.([^.]+)\.config\.ts$/u.exec(artifact.path);
+			if (match === null) continue;
+			const project = `${match[1]}:${match[2]}`;
+			if (faces.has(project)) wrappers.set(artifact.path, project);
+		}
 		const reachable = /* @__PURE__ */ new Set();
 		const chains = /* @__PURE__ */ new Map();
 		for (const gate of gates) {
@@ -2003,7 +2150,7 @@ var CLI = class {
 				visited.add(name);
 				const script = scripts[name];
 				if (!isString(script)) continue;
-				const invoked = scriptToInvocations(script);
+				const invoked = scriptToInvocations(script, wrappers);
 				if (invoked === void 0) {
 					unresolved = true;
 					continue;
@@ -2102,7 +2249,7 @@ var CLI = class {
 			if (proofs.has(`${path.slice(0, -3)}.test.ts`)) return false;
 			if (resolveContainedPath(tests, path) === void 0) return false;
 			const content = (readFileText(tests, path) ?? "").trim();
-			return content !== "" && content !== (seeds.get(`tests/${path}`) ?? "");
+			return /^export /m.test(content) && content !== (seeds.get(`tests/${path}`) ?? "");
 		}).sort();
 		if (modules.length === 0) return void 0;
 		const single = modules.length === 1;
@@ -2118,6 +2265,13 @@ var CLI = class {
 	}
 	#targetQuestions(target, blueprint, groups, writing = false) {
 		const questions = [];
+		const browser = resolveContainedPath(target, "app/browser");
+		if (browser !== void 0 && listFiles(browser).some((path) => path.endsWith(".vue"))) questions.push({
+			field: "extensions",
+			message: "Move Vue components from app/browser to app/vue before regenerating this workspace.",
+			blocking: writing,
+			groups: []
+		});
 		if (!writing) {
 			const script = this.#scriptQuestion(target, blueprint);
 			if (script !== void 0) questions.push(script);
@@ -2130,7 +2284,7 @@ var CLI = class {
 			const setup = this.#setupQuestion(target, blueprint);
 			if (setup !== void 0) questions.push(setup);
 		}
-		return questions.filter((question) => groups === void 0 || question.groups.some((group) => groups.includes(group))).map(({ field, message, blocking, candidates }) => ({
+		return questions.filter((question) => question.blocking || groups === void 0 || question.groups.some((group) => groups.includes(group))).map(({ field, message, blocking, candidates }) => ({
 			field,
 			message,
 			blocking,