@orkestrel/scaffold 0.0.26 → 0.0.28

package/dist/src/core/index.cjs

@@ -201,6 +201,12 @@ var GLOBAL_SETUP_PATH = "tests/setupGlobal.ts";
 var GUIDES_TEST_PATH = "tests/guides.test.ts";
 /** The installed-package proof whose presence makes a workspace `integration`. */
 var INTEGRATION_TEST_PATH = "tests/integration.test.ts";
+/** The official-tooling drift proof whose presence makes a workspace `conformance`. */
+var CONFORMANCE_TEST_PATH = "tests/conformance.test.ts";
+/** The live-service readiness module whose presence makes a workspace `service`. */
+var SERVICE_SETUP_PATH = "tests/setupService.ts";
+/** The include the live-service project covers, which is a directory rather than one proof. */
+var SERVICE_TEST_INCLUDE = "tests/service/**/*.test.ts";
 /** The Vite wrapper whose presence makes a workspace `showcase`. */
 var SHOWCASE_CONFIG_PATH = "configs/app/vite.showcase.config.ts";
 /** The bare workspace name syntax: lowercase alphanumeric with hyphens, letter first. */
@@ -283,8 +289,8 @@ var DEFAULT_ENGINES = `>=${MINIMUM_NODE_VERSION}`;
 /** The tooling versions scaffold and every generated workspace share. */
 var BASE_DEV_DEPENDENCIES = Object.freeze({
 	"@microsoft/api-extractor": "^7.58.12",
-	"@orkestrel/guide": "^0.0.9",
-	"@orkestrel/scaffold": "^0.0.26",
+	"@orkestrel/guide": "^0.0.10",
+	"@orkestrel/scaffold": "^0.0.28",
 	"@types/node": "^26.2.0",
 	oxfmt: "^0.62.0",
 	oxlint: "^1.77.0",
@@ -299,11 +305,11 @@ var SOURCE_BROWSER_DEV_DEPENDENCIES = Object.freeze({
 	playwright: "^1.62.1"
 });
 /** The development dependency every private `app` environment adds. */
-var APP_DEV_DEPENDENCIES = Object.freeze({ "@orkestrel/contract": "^0.0.10" });
+var APP_DEV_DEPENDENCIES = Object.freeze({ "@orkestrel/contract": "^0.0.11" });
 /** The development dependencies a private Vue browser application adds. */
 var APP_BROWSER_DEV_DEPENDENCIES = Object.freeze({
 	...SOURCE_BROWSER_DEV_DEPENDENCIES,
-	"@orkestrel/html": "^0.0.2",
+	"@orkestrel/html": "^0.0.3",
 	"@vitejs/plugin-vue": "^6.0.8",
 	vue: "^3.5.40",
 	"vue-tsc": "^3.3.7"
@@ -321,10 +327,10 @@ var APP_BROWSER_DEV_DEPENDENCIES = Object.freeze({
 var SHOWCASE_DEV_DEPENDENCIES = Object.freeze({ "vite-plugin-singlefile": "^2.3.3" });
 /** The development dependencies a private server application adds. */
 var APP_SERVER_DEV_DEPENDENCIES = Object.freeze({
-	"@orkestrel/emitter": "^0.0.5",
-	"@orkestrel/middleware": "^0.0.9",
-	"@orkestrel/router": "^0.0.8",
-	"@orkestrel/server": "^0.0.10"
+	"@orkestrel/emitter": "^0.0.6",
+	"@orkestrel/middleware": "^0.0.10",
+	"@orkestrel/router": "^0.0.9",
+	"@orkestrel/server": "^0.0.11"
 });
 //#endregion
 //#region src/core/templates.ts
@@ -676,6 +682,44 @@ export function appBrowser(...options: never[]): UserConfig {
 		},
 		options ?? {},
 	)
+`,
+		conformance: `// Where this package drifts from the official tooling it stays compatible with.
+// The subject is this package, so the proof is hermetic and stays in \`npm test\`.
+export const conformance = (options?: UserConfig): UserConfig =>
+	mergeConfig(
+		{
+			resolve,
+			test: {
+				name: { label: 'conformance', color: 'magenta' },
+				include: ['${CONFORMANCE_TEST_PATH}'],
+				setupFiles: ['./tests/setup.ts'],
+				environment: 'node',
+				browser: { enabled: false },
+			},
+		},
+		options ?? {},
+	)
+`,
+		service: `// The live external services this package drives. It starts nothing itself:
+// \`scripts/service.sh\` provisions, \`tests/setupService.ts\` proves readiness, and
+// the project stays out of \`npm test\` because a real service answers it.
+export const service = (options?: UserConfig): UserConfig =>
+	mergeConfig(
+		{
+			resolve,
+			test: {
+				name: { label: 'service', color: 'red' },
+				include: ['${SERVICE_TEST_INCLUDE}'],
+				setupFiles: ['./tests/setup.ts', './tests/setupService.ts'],
+				environment: 'node',
+				browser: { enabled: false },
+				testTimeout: 120_000,
+				hookTimeout: 120_000,
+				fileParallelism: false,
+			},
+		},
+		options ?? {},
+	)
 `,
 		probe: `// A workbench, not a proof. No gate selects this project.
 export const probe = (options?: UserConfig): UserConfig =>
@@ -1150,7 +1194,7 @@ npm test
 set -eu
 
 printf '%s\\n' \\
-{{services}}
+{{vendors}}
 ` })
 });
 //#endregion
@@ -1437,7 +1481,9 @@ var isBlueprint = (0, _orkestrel_contract.recordOf)({
 	overrides: (0, _orkestrel_contract.andOf)(isCollection, (0, _orkestrel_contract.arrayOf)(isOverride)),
 	bin: _orkestrel_contract.isBoolean,
 	integration: _orkestrel_contract.isBoolean,
-	services: (0, _orkestrel_contract.andOf)(isCollection, (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)),
+	conformance: _orkestrel_contract.isBoolean,
+	service: _orkestrel_contract.isBoolean,
+	vendors: (0, _orkestrel_contract.andOf)(isCollection, (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)),
 	global: _orkestrel_contract.isBoolean,
 	showcase: _orkestrel_contract.isBoolean
 }, ["description"]);
@@ -1591,7 +1637,8 @@ var isMirror = (0, _orkestrel_contract.unionOf)((0, _orkestrel_contract.recordOf
 var isCatalogEntry = (0, _orkestrel_contract.unionOf)((0, _orkestrel_contract.recordOf)({
 	name: isDependencyName,
 	lookup: (0, _orkestrel_contract.literalOf)("found"),
-	version: _orkestrel_contract.isString
+	version: _orkestrel_contract.isString,
+	dependencies: (0, _orkestrel_contract.andOf)(isCollection, (0, _orkestrel_contract.arrayOf)(isDependency))
 }), (0, _orkestrel_contract.recordOf)({
 	name: isDependencyName,
 	lookup: (0, _orkestrel_contract.literalOf)("missing", "failed"),
@@ -2164,6 +2211,54 @@ function matchesDriftReachability(ownership, finding) {
 	return finding.drift === "stale" && ownership === "content";
 }
 /**
+* Project a catalog into the layers it publishes in.
+*
+* @param entries - The catalog rows to order.
+* @returns One layer per round, each holding the names publishable together,
+* sorted within the layer; a name whose edges never resolve is omitted.
+*
+* @remarks
+* A layer is a deterministic function of the catalog's own edges, so it is
+* computed here rather than stored on a row that could disagree with them.
+* Only RUNTIME edges between catalogued packages count: a development
+* dependency reaches no consumer, so it constrains nothing about publish order,
+* and an edge leaving the fleet is a package this catalog does not publish.
+*
+* The order matters because these packages are `0.0.x`, where a caret pins one
+* exact release. Publishing a dependent before its dependency leaves the
+* dependent pinned to the older release, and two ranges that disagree install
+* two copies of one package that the compiler reads as two distinct types.
+*
+* A cycle cannot be published in rounds, so its members are omitted rather than
+* placed in an order that would be wrong. An absent name is the report: compare
+* the returned names against the catalog to find one.
+*
+* @example
+* ```ts
+* import { catalogToLayers } from '@orkestrel/scaffold'
+*
+* catalogToLayers(entries)[0] // the names that depend on nothing in the fleet
+* ```
+*/
+function catalogToLayers(entries) {
+	const published = new Set(entries.filter((entry) => entry.lookup === "found").map((entry) => entry.name));
+	const pending = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		if (entry.lookup !== "found") continue;
+		const edges = entry.dependencies.map((dependency) => dependency.name);
+		pending.set(entry.name, new Set(edges.filter((name) => published.has(name))));
+	}
+	const layers = [];
+	while (pending.size > 0) {
+		const ready = [...pending].filter(([, edges]) => edges.size === 0).map(([name]) => name);
+		if (ready.length === 0) break;
+		for (const name of ready) pending.delete(name);
+		for (const edges of pending.values()) for (const name of ready) edges.delete(name);
+		layers.push(ready.sort());
+	}
+	return layers;
+}
+/**
 * Project a plan into its tally by artifact origin.
 *
 * @param plan - The plan to summarize.
@@ -2624,8 +2719,14 @@ function blueprintToDevDependencies(blueprint) {
 * to the axes the blueprint declares: a check and a test script per declared
 * environment, an aggregate over each axis, the policy and configuration
 * proofs every workspace can pass before it has a public API, and one build per
-* target that actually builds. The isolated installed-package integration
-* proof stays out of `test` and runs from `prepublishOnly` instead.
+* target that actually builds.
+*
+* A proof leaves `test` when a real service or a real install answers it. The
+* installed-package integration proof and the live-service proof therefore run
+* from `prepublishOnly` instead. The conformance proof stays in `test`, because
+* it measures this package against official tooling and drives nothing external:
+* a conformance run may start a server, but it starts its own and reaches it
+* over loopback, so the run stays hermetic.
 *
 * The configuration paths interpolated here are the same ones `SRC_MATRIX` and
 * `APP_MATRIX` list as each environment's configuration files, so a rename in
@@ -2672,7 +2773,8 @@ function blueprintToScripts(blueprint) {
 		...compiles ? ["npm run test:src"] : [],
 		...blueprint.app.length > 0 ? ["npm run test:app"] : [],
 		"npm run test:policy",
-		"npm run test:config"
+		"npm run test:config",
+		...blueprint.conformance ? ["npm run test:conformance"] : []
 	].join(" && ");
 	if (compiles) {
 		scripts["test:src"] = [
@@ -2689,8 +2791,10 @@ function blueprintToScripts(blueprint) {
 	}
 	scripts["test:policy"] = `${vitest} --project policy`;
 	scripts["test:config"] = `${vitest} --project config`;
+	if (blueprint.conformance) scripts["test:conformance"] = `${vitest} --project conformance`;
 	scripts["test:probe"] = "vitest run --config vite.config.ts --no-cache --reporter=verbose --project probe";
 	if (integrates) scripts["test:integration"] = `${vitest} --project integration`;
+	if (blueprint.service) scripts["test:service"] = `${vitest} --project service`;
 	scripts.build = [
 		"npm run clean",
 		...compiles ? ["npm run build:src"] : [],
@@ -2720,7 +2824,11 @@ function blueprintToScripts(blueprint) {
 		scripts.serve = "node dist/app/server/main.cjs";
 		scripts["serve:build"] = "npm run build:app:server && npm run serve";
 	}
-	scripts.prepublishOnly = ["npm run format:check && npm run lint:check && npm run check && npm run build && npm test", ...integrates ? ["npm run test:integration"] : []].join(" && ");
+	scripts.prepublishOnly = [
+		"npm run format:check && npm run lint:check && npm run check && npm run build && npm test",
+		...integrates ? ["npm run test:integration"] : [],
+		...blueprint.service ? ["npm run test:service"] : []
+	].join(" && ");
 	return scripts;
 }
 /**
@@ -3002,6 +3110,14 @@ export function appShowcase(...options: never[]): UserConfig {
 	projects.push("config");
 	factories.push(CONFIG_TEMPLATES.factories.guides);
 	projects.push(`...(isExactCaseFile(resolveWorkspacePath('${GUIDES_TEST_PATH}')) ? [guides] : [])`);
+	if (blueprint.conformance) {
+		factories.push(CONFIG_TEMPLATES.factories.conformance);
+		projects.push("conformance");
+	}
+	if (blueprint.service) {
+		factories.push(CONFIG_TEMPLATES.factories.service);
+		projects.push("service");
+	}
 	if (blueprint.src.length > 0 && blueprint.integration) {
 		factories.push((0, _orkestrel_template.fillTemplate)(CONFIG_TEMPLATES.factories.integration, { global: blueprint.global ? "				globalSetup: ['./tests/setupGlobal.ts'],\n" : "" }));
 		projects.push("integration");
@@ -3222,6 +3338,12 @@ function blueprintToSourceArtifacts(blueprint) {
 * workspace and therefore follows the `src` axis as well as its structural
 * flag.
 *
+* The conformance proof is not emitted either, for the reason the guide proof
+* is not: it names an official artifact only the package knows, so a generated
+* placeholder would read as a proof while measuring nothing. `service` emits its
+* readiness setup alone, because the root configuration names that module by
+* path.
+*
 * @example
 * ```ts
 * import { blueprintToTestArtifacts, createBlueprint } from '@orkestrel/scaffold'
@@ -3255,6 +3377,13 @@ function blueprintToTestArtifacts(blueprint) {
 		environment: "server",
 		content: ARTIFACT_TEMPLATES.tests.setup
 	});
+	if (blueprint.service) artifacts.push({
+		path: SERVICE_SETUP_PATH,
+		group: "tests",
+		ownership: "birth",
+		origin: "template",
+		content: ARTIFACT_TEMPLATES.tests.setup
+	});
 	if (blueprint.global) artifacts.push({
 		path: GLOBAL_SETUP_PATH,
 		group: "tests",
@@ -3368,22 +3497,22 @@ function blueprintToDocumentArtifacts(blueprint) {
 * Compile the blueprint-dependent orchestration artifacts.
 *
 * @param blueprint - The workspace specification.
-* @returns A service inventory script when services are declared, otherwise none.
+* @returns A vendor inventory script when vendors are declared, otherwise none.
 *
 * @remarks
-* A service name does not describe startup, readiness, or cleanup. The script
+* A vendor name does not describe startup, readiness, or cleanup. The script
 * therefore records only the declared inventory and does not invent a service
 * runner or test project.
 */
 function blueprintToOrchestrationArtifacts(blueprint) {
-	if (blueprint.services.length === 0) return [];
-	const services = blueprint.services.map((service, index) => `\t'${service}'${index === blueprint.services.length - 1 ? "" : " \\"}`).join("\n");
+	if (blueprint.vendors.length === 0) return [];
+	const vendors = blueprint.vendors.map((vendor, index) => `\t'${vendor}'${index === blueprint.vendors.length - 1 ? "" : " \\"}`).join("\n");
 	return [{
 		path: SERVICE_SCRIPT_PATH,
 		group: "orchestration",
 		ownership: "birth",
 		origin: "template",
-		content: (0, _orkestrel_template.fillTemplate)(ARTIFACT_TEMPLATES.orchestration.service, { services })
+		content: (0, _orkestrel_template.fillTemplate)(ARTIFACT_TEMPLATES.orchestration.service, { vendors })
 	}];
 }
 /**
@@ -3739,19 +3868,19 @@ function blueprintToQuestions(blueprint) {
 		message: "integration projects a published src, and this workspace declares none, so it emits nothing.",
 		blocking: false
 	});
-	const services = /* @__PURE__ */ new Set();
-	for (const service of blueprint.services) {
-		if (!NAME_PATTERN.test(service)) questions.push({
-			field: "services",
-			message: `${service} is not a lowercase alphanumeric service name starting with a letter.`,
+	const vendors = /* @__PURE__ */ new Set();
+	for (const vendor of blueprint.vendors) {
+		if (!NAME_PATTERN.test(vendor)) questions.push({
+			field: "vendors",
+			message: `${vendor} is not a lowercase alphanumeric vendor name starting with a letter.`,
 			blocking: true
 		});
-		else if (services.has(service)) questions.push({
-			field: "services",
-			message: `${service} is declared more than once on services.`,
+		else if (vendors.has(vendor)) questions.push({
+			field: "vendors",
+			message: `${vendor} is declared more than once on vendors.`,
 			blocking: true
 		});
-		services.add(service);
+		vendors.add(vendor);
 	}
 	if (blueprint.showcase && !blueprint.app.includes("browser")) questions.push({
 		field: "showcase",
@@ -4219,8 +4348,8 @@ var Compiler = class {
 * blueprint.
 *
 * @remarks
-* A blueprint is a closed record of sixteen fields, and most of them have one
-* sensible starting value: an empty list, a cleared flag, `DEFAULT_VERSION`, and
+* A blueprint is a closed record, and most of its fields have one sensible
+* starting value: an empty list, a cleared flag, `DEFAULT_VERSION`, and
 * `DEFAULT_ENGINES`. Filling them here is what lets a caller state only what its
 * workspace actually declares.
 *
@@ -4261,7 +4390,9 @@ function createBlueprint(name, input) {
 		overrides: input?.overrides ?? [],
 		bin: input?.bin ?? false,
 		integration: input?.integration ?? false,
-		services: input?.services ?? [],
+		conformance: input?.conformance ?? false,
+		service: input?.service ?? false,
+		vendors: input?.vendors ?? [],
 		global: input?.global ?? false,
 		showcase: input?.showcase ?? false
 	}));
@@ -4298,6 +4429,7 @@ exports.BIN_CONFIGS = BIN_CONFIGS;
 exports.BIN_ENTRY_PATH = BIN_ENTRY_PATH;
 exports.CATALOG_AGENT_PATH = CATALOG_AGENT_PATH;
 exports.CONFIG_TEMPLATES = CONFIG_TEMPLATES;
+exports.CONFORMANCE_TEST_PATH = CONFORMANCE_TEST_PATH;
 exports.CONTROL_CHARACTER_PATTERN = CONTROL_CHARACTER_PATTERN;
 exports.Compiler = Compiler;
 exports.DEFAULT_ENGINES = DEFAULT_ENGINES;
@@ -4331,6 +4463,8 @@ exports.ORCHESTRATION_PATH_NAMES = ORCHESTRATION_PATH_NAMES;
 exports.ORCHESTRATION_PATH_PREFIXES = ORCHESTRATION_PATH_PREFIXES;
 exports.ORKESTREL_RANGE_PATTERN = ORKESTREL_RANGE_PATTERN;
 exports.SERVICE_SCRIPT_PATH = SERVICE_SCRIPT_PATH;
+exports.SERVICE_SETUP_PATH = SERVICE_SETUP_PATH;
+exports.SERVICE_TEST_INCLUDE = SERVICE_TEST_INCLUDE;
 exports.SHOWCASE_CONFIG_PATH = SHOWCASE_CONFIG_PATH;
 exports.SHOWCASE_DEV_DEPENDENCIES = SHOWCASE_DEV_DEPENDENCIES;
 exports.SOURCE_BROWSER_DEV_DEPENDENCIES = SOURCE_BROWSER_DEV_DEPENDENCIES;
@@ -4355,6 +4489,7 @@ exports.blueprintToScripts = blueprintToScripts;
 exports.blueprintToSourceArtifacts = blueprintToSourceArtifacts;
 exports.blueprintToTestArtifacts = blueprintToTestArtifacts;
 exports.bytesToHex = bytesToHex;
+exports.catalogToLayers = catalogToLayers;
 exports.cloneValue = cloneValue;
 exports.compareVersions = compareVersions;
 exports.computeBytes = computeBytes;