@orkestrel/scaffold 0.0.26 → 0.0.27

package/dist/src/core/index.d.cts

@@ -609,19 +609,61 @@ export declare const CATALOG_AGENT_PATH = ".claude/agents/orkestrel.md";
  * still a row: dropping it would hide a package the organization publishes
  * behind one failed request, and inventing a version would state something
  * upstream never said.
+ *
+ * `dependencies` are the RUNTIME edges the published version declares, which is
+ * what a publish order is computed over: a runtime bump obliges every dependent
+ * to re-pin and republish, while a development bump obliges nothing beyond the
+ * repository that declares it. No layer is recorded here, because a layer is a
+ * deterministic function of these edges across the whole catalog — a stored one
+ * could only disagree with the rows it was derived from. Read it through
+ * {@link catalogToLayers}.
  */
 export declare type CatalogEntry = {
     readonly name: string;
     readonly lookup: 'found';
     readonly version: string;
+    readonly dependencies: readonly Dependency[];
     readonly note?: never;
 } | {
     readonly name: string;
     readonly lookup: 'missing' | 'failed';
     readonly note: string;
     readonly version?: never;
+    readonly dependencies?: never;
 };
 
+/**
+ * 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
+ * ```
+ */
+export declare function catalogToLayers(entries: readonly CatalogEntry[]): ReadonlyArray<readonly string[]>;
+
 /**
  * Snapshot an untrusted value into exact JSON data the caller owns.
  *

package/dist/src/core/index.d.ts

@@ -609,19 +609,61 @@ export declare const CATALOG_AGENT_PATH = ".claude/agents/orkestrel.md";
  * still a row: dropping it would hide a package the organization publishes
  * behind one failed request, and inventing a version would state something
  * upstream never said.
+ *
+ * `dependencies` are the RUNTIME edges the published version declares, which is
+ * what a publish order is computed over: a runtime bump obliges every dependent
+ * to re-pin and republish, while a development bump obliges nothing beyond the
+ * repository that declares it. No layer is recorded here, because a layer is a
+ * deterministic function of these edges across the whole catalog — a stored one
+ * could only disagree with the rows it was derived from. Read it through
+ * {@link catalogToLayers}.
  */
 export declare type CatalogEntry = {
     readonly name: string;
     readonly lookup: 'found';
     readonly version: string;
+    readonly dependencies: readonly Dependency[];
     readonly note?: never;
 } | {
     readonly name: string;
     readonly lookup: 'missing' | 'failed';
     readonly note: string;
     readonly version?: never;
+    readonly dependencies?: never;
 };
 
+/**
+ * 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
+ * ```
+ */
+export declare function catalogToLayers(entries: readonly CatalogEntry[]): ReadonlyArray<readonly string[]>;
+
 /**
  * Snapshot an untrusted value into exact JSON data the caller owns.
  *

package/dist/src/core/index.js

@@ -282,8 +282,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.27",
 	"@types/node": "^26.2.0",
 	oxfmt: "^0.62.0",
 	oxlint: "^1.77.0",
@@ -298,11 +298,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"
@@ -320,10 +320,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
@@ -1590,7 +1590,8 @@ var isMirror = unionOf(recordOf({
 var isCatalogEntry = unionOf(recordOf({
 	name: isDependencyName,
 	lookup: literalOf("found"),
-	version: isString
+	version: isString,
+	dependencies: andOf(isCollection, arrayOf(isDependency))
 }), recordOf({
 	name: isDependencyName,
 	lookup: literalOf("missing", "failed"),
@@ -2163,6 +2164,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.
@@ -4287,6 +4336,6 @@ function createCompiler(options) {
 	return new Compiler(options);
 }
 //#endregion
-export { APP_BROWSER_DEV_DEPENDENCIES, APP_DEV_DEPENDENCIES, APP_MATRIX, APP_SERVER_DEV_DEPENDENCIES, ARTIFACT_TEMPLATES, BASE_DEV_DEPENDENCIES, BIN_CONFIGS, BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFIG_TEMPLATES, CONTROL_CHARACTER_PATTERN, Compiler, DEFAULT_ENGINES, DEFAULT_VERSION, DEPENDENCY_NAME_PATTERN, ENGINES_PATTERN, ENVIRONMENTS, EXECUTABLE_PATHS, EXTRA_NAME_PATTERN, EXTRA_RANGE_PATTERN, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HEX_PATTERN, HOST_PATHS, INTEGRATION_TEST_PATH, INVALID_PATH_CHARACTER_PATTERN, MAX_ARTIFACT_BYTES, MAX_ARTIFACT_HEX_LENGTH, MAX_AUDIT_FINDINGS, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_NAME_LENGTH, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_TOTAL_ARTIFACT_BYTES, MINIMUM_NODE_VERSION, NAME_PATTERN, ORCHESTRATION_PATH_NAMES, ORCHESTRATION_PATH_PREFIXES, ORKESTREL_RANGE_PATTERN, SERVICE_SCRIPT_PATH, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SOURCE_BROWSER_DEV_DEPENDENCIES, SRC_MATRIX, ScaffoldError, VERSION_PATTERN, applyOverrides, artifactToFinding, artifactToHex, artifactsToQuestions, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToDocumentArtifacts, blueprintToGuideArtifacts, blueprintToMachinery, blueprintToManifest, blueprintToOrchestrationArtifacts, blueprintToQuestions, blueprintToRootTsconfig, blueprintToRootVite, blueprintToScripts, blueprintToSourceArtifacts, blueprintToTestArtifacts, bytesToHex, cloneValue, compareVersions, computeBytes, computeHash, contentToHex, createBlueprint, createCompiler, dependenciesToQuestions, extractVersion, inferDrift, inferGroup, isArtifact, isAudit, isBlueprint, isCatalogEntry, isCollection, isCompilerHooks, isCompilerOptions, isContent, isDependency, isDependencyName, isEnvironment, isFinding, isGroup, isGroups, isHex, isMirror, isOverride, isPath, isPlan, isQuestion, isScaffoldError, isSnapshot, manifestToDependencies, manifestToName, matchesDriftReachability, matchesEngines, matchesOrchestrationPath, matchesRange, nameToGuide, nameToHostArtifacts, overridesToQuestions, parseBlueprint, parseCompilerOptions, parseGroups, parseSnapshot, pathToCondition, planToFindings, planToHash, planToSummary, selectGroups, selectHostPaths, serializeTypeScriptString, srcToEntry, srcToExports, srcToRoot };
+export { APP_BROWSER_DEV_DEPENDENCIES, APP_DEV_DEPENDENCIES, APP_MATRIX, APP_SERVER_DEV_DEPENDENCIES, ARTIFACT_TEMPLATES, BASE_DEV_DEPENDENCIES, BIN_CONFIGS, BIN_ENTRY_PATH, CATALOG_AGENT_PATH, CONFIG_TEMPLATES, CONTROL_CHARACTER_PATTERN, Compiler, DEFAULT_ENGINES, DEFAULT_VERSION, DEPENDENCY_NAME_PATTERN, ENGINES_PATTERN, ENVIRONMENTS, EXECUTABLE_PATHS, EXTRA_NAME_PATTERN, EXTRA_RANGE_PATTERN, GLOBAL_SETUP_PATH, GROUPS, GUIDES_TEST_PATH, HEX_PATTERN, HOST_PATHS, INTEGRATION_TEST_PATH, INVALID_PATH_CHARACTER_PATTERN, MAX_ARTIFACT_BYTES, MAX_ARTIFACT_HEX_LENGTH, MAX_AUDIT_FINDINGS, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_NAME_LENGTH, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_TOTAL_ARTIFACT_BYTES, MINIMUM_NODE_VERSION, NAME_PATTERN, ORCHESTRATION_PATH_NAMES, ORCHESTRATION_PATH_PREFIXES, ORKESTREL_RANGE_PATTERN, SERVICE_SCRIPT_PATH, SHOWCASE_CONFIG_PATH, SHOWCASE_DEV_DEPENDENCIES, SOURCE_BROWSER_DEV_DEPENDENCIES, SRC_MATRIX, ScaffoldError, VERSION_PATTERN, applyOverrides, artifactToFinding, artifactToHex, artifactsToQuestions, blueprintToConfigArtifacts, blueprintToDevDependencies, blueprintToDocumentArtifacts, blueprintToGuideArtifacts, blueprintToMachinery, blueprintToManifest, blueprintToOrchestrationArtifacts, blueprintToQuestions, blueprintToRootTsconfig, blueprintToRootVite, blueprintToScripts, blueprintToSourceArtifacts, blueprintToTestArtifacts, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, computeHash, contentToHex, createBlueprint, createCompiler, dependenciesToQuestions, extractVersion, inferDrift, inferGroup, isArtifact, isAudit, isBlueprint, isCatalogEntry, isCollection, isCompilerHooks, isCompilerOptions, isContent, isDependency, isDependencyName, isEnvironment, isFinding, isGroup, isGroups, isHex, isMirror, isOverride, isPath, isPlan, isQuestion, isScaffoldError, isSnapshot, manifestToDependencies, manifestToName, matchesDriftReachability, matchesEngines, matchesOrchestrationPath, matchesRange, nameToGuide, nameToHostArtifacts, overridesToQuestions, parseBlueprint, parseCompilerOptions, parseGroups, parseSnapshot, pathToCondition, planToFindings, planToHash, planToSummary, selectGroups, selectHostPaths, serializeTypeScriptString, srcToEntry, srcToExports, srcToRoot };
 
 //# sourceMappingURL=index.js.map