@orkestrel/scaffold 0.0.84 → 0.0.86

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

@@ -550,7 +550,8 @@ export declare const isManifestEntry: Guard<ManifestEntry>;
  * @remarks
  * The whole closed record a manifest-writing method accepts, so a caller
  * naming a region the writer does not carry is refused before any byte moves.
- * Each region is bounded by the same collection law its own list guard applies.
+ * Each region is bounded by the same collection law its own list guard applies,
+ * and `additions` is the one region a caller may omit.
  *
  * @example
  * ```ts
@@ -558,6 +559,11 @@ export declare const isManifestEntry: Guard<ManifestEntry>;
  *
  * isManifestRegionSet({ pins: { runtime: [], development: [] }, scripts: [] }) // true
  * isManifestRegionSet({ pins: { runtime: [], development: [] } }) // false
+ * isManifestRegionSet({
+ *   pins: { runtime: [], development: [] },
+ *   scripts: [],
+ *   additions: { runtime: [], development: [{ name: 'typescript', range: '^6.0.3' }] },
+ * }) // true
  * ```
  */
 export declare const isManifestRegionSet: Guard<ManifestRegionSet>;
@@ -1239,11 +1245,13 @@ export declare class Materializer implements MaterializerInterface {
           /**
            * Rewrites the manifest regions the caller names in the target's manifest.
            *
-           * @param regions - The dependency ranges and script values the manifest must declare.
+           * @param regions - The dependency ranges, script values, and additions the manifest must declare.
            * @param target - The directory to write into.
            * @returns The manifest path, written when a named region moved and skipped otherwise.
            * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
-               * exact shape or names a package the manifest does not declare, `TARGET` when
+               * exact shape, names a range the manifest does not declare, or names an
+               * addition the manifest already declares or whose section is not an object
+               * of version strings, `TARGET` when
                * the manifest is unreadable, `WRITE` when the write cannot be staged or
                * committed, and `DESTROYED` after teardown.
                *
@@ -1251,7 +1259,10 @@ export declare class Materializer implements MaterializerInterface {
                * No other part of the manifest is read back out or rewritten. The method
                * never reads or writes `peerDependencies` or `peerDependenciesMeta`. Only a
                * range already declared in its named writable section is rewritten, so an
-               * undeclared name is refused instead of inserted.
+               * undeclared pin is refused instead of inserted. An undeclared package enters
+               * the manifest only through `additions`, which inserts it into the section its
+               * list names in key order, creating that section when the manifest lacks it,
+               * before the ranges are rewritten.
                *
                * The regions refuse differently because their targets differ. A range
                * the manifest does not declare is the caller's mistake and throws. A script
@@ -1417,7 +1428,7 @@ export declare class Materializer implements MaterializerInterface {
                /**
                 * Rewrites the manifest regions the caller names in the target's manifest.
                 *
-                * @param regions - The dependency ranges and script values the manifest must declare.
+                * @param regions - The dependency ranges, script values, and additions the manifest must declare.
                 * @param target - The directory to write into.
                 * @returns The manifest path, written when a named region moved and skipped otherwise.
                 *
@@ -1425,7 +1436,9 @@ export declare class Materializer implements MaterializerInterface {
                 * No other part of the manifest is read back out or rewritten. The method
                 * never reads or writes `peerDependencies` or `peerDependenciesMeta`. A
                 * script region naming a value the manifest does not accept is skipped
-                * without a byte moving, and the range region is written regardless.
+                * without a byte moving, and the range region is written regardless. An
+                * addition is inserted into the section its list names, which is created when
+                * the manifest lacks it, and one the manifest already declares is refused.
                 */
                declare(regions: ManifestRegionSet, target: string): MaterializeResult;
                /**

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

@@ -550,7 +550,8 @@ export declare const isManifestEntry: Guard<ManifestEntry>;
  * @remarks
  * The whole closed record a manifest-writing method accepts, so a caller
  * naming a region the writer does not carry is refused before any byte moves.
- * Each region is bounded by the same collection law its own list guard applies.
+ * Each region is bounded by the same collection law its own list guard applies,
+ * and `additions` is the one region a caller may omit.
  *
  * @example
  * ```ts
@@ -558,6 +559,11 @@ export declare const isManifestEntry: Guard<ManifestEntry>;
  *
  * isManifestRegionSet({ pins: { runtime: [], development: [] }, scripts: [] }) // true
  * isManifestRegionSet({ pins: { runtime: [], development: [] } }) // false
+ * isManifestRegionSet({
+ *   pins: { runtime: [], development: [] },
+ *   scripts: [],
+ *   additions: { runtime: [], development: [{ name: 'typescript', range: '^6.0.3' }] },
+ * }) // true
  * ```
  */
 export declare const isManifestRegionSet: Guard<ManifestRegionSet>;
@@ -1239,11 +1245,13 @@ export declare class Materializer implements MaterializerInterface {
           /**
            * Rewrites the manifest regions the caller names in the target's manifest.
            *
-           * @param regions - The dependency ranges and script values the manifest must declare.
+           * @param regions - The dependency ranges, script values, and additions the manifest must declare.
            * @param target - The directory to write into.
            * @returns The manifest path, written when a named region moved and skipped otherwise.
            * @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
-               * exact shape or names a package the manifest does not declare, `TARGET` when
+               * exact shape, names a range the manifest does not declare, or names an
+               * addition the manifest already declares or whose section is not an object
+               * of version strings, `TARGET` when
                * the manifest is unreadable, `WRITE` when the write cannot be staged or
                * committed, and `DESTROYED` after teardown.
                *
@@ -1251,7 +1259,10 @@ export declare class Materializer implements MaterializerInterface {
                * No other part of the manifest is read back out or rewritten. The method
                * never reads or writes `peerDependencies` or `peerDependenciesMeta`. Only a
                * range already declared in its named writable section is rewritten, so an
-               * undeclared name is refused instead of inserted.
+               * undeclared pin is refused instead of inserted. An undeclared package enters
+               * the manifest only through `additions`, which inserts it into the section its
+               * list names in key order, creating that section when the manifest lacks it,
+               * before the ranges are rewritten.
                *
                * The regions refuse differently because their targets differ. A range
                * the manifest does not declare is the caller's mistake and throws. A script
@@ -1417,7 +1428,7 @@ export declare class Materializer implements MaterializerInterface {
                /**
                 * Rewrites the manifest regions the caller names in the target's manifest.
                 *
-                * @param regions - The dependency ranges and script values the manifest must declare.
+                * @param regions - The dependency ranges, script values, and additions the manifest must declare.
                 * @param target - The directory to write into.
                 * @returns The manifest path, written when a named region moved and skipped otherwise.
                 *
@@ -1425,7 +1436,9 @@ export declare class Materializer implements MaterializerInterface {
                 * No other part of the manifest is read back out or rewritten. The method
                 * never reads or writes `peerDependencies` or `peerDependenciesMeta`. A
                 * script region naming a value the manifest does not accept is skipped
-                * without a byte moving, and the range region is written regardless.
+                * without a byte moving, and the range region is written regardless. An
+                * addition is inserted into the section its list names, which is created when
+                * the manifest lacks it, and one the manifest already declares is refused.
                 */
                declare(regions: ManifestRegionSet, target: string): MaterializeResult;
                /**

package/dist/src/server/index.js

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { andOf, arrayOf, attempt, boundsOf, compareValues, holds, isArray, isBoolean, isError, isFunction, isInteger, isNumber, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, stringOf, unionOf, whereOf } from "@orkestrel/contract";
-import { CANON_PATHS, CATALOG_AGENT_PATH, CATALOG_CLOSING_MARKER, CATALOG_OPENING_MARKER, CONTROL_CHARACTER_PATTERN, DEPENDENCY_NAME_PATTERN, EXECUTABLE_PATHS, HOST_INVENTORY_PATH, HOST_PATHS, MAX_ARTIFACT_BYTES, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, REFERENCE_PATHS, ScaffoldError, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, contentToHex, extractRangeMajor, extractVersion, inferGroup, isAudit, isCatalogEntry, isCollection, isDependency, isDependencyName, isFloorPath, isHex, isManifestScript, isMirror, isPath, isPlan, isRetainedPath, isSnapshot, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, renderSkillPointer, replaceManifestRanges, replaceManifestScripts } from "../core/index.js";
+import { CANON_PATHS, CATALOG_AGENT_PATH, CATALOG_CLOSING_MARKER, CATALOG_OPENING_MARKER, CONTROL_CHARACTER_PATTERN, DEPENDENCY_NAME_PATTERN, EXECUTABLE_PATHS, HOST_INVENTORY_PATH, HOST_PATHS, MAX_ARTIFACT_BYTES, MAX_COLLECTION_ITEMS, MAX_DEPENDENCY_NAME_LENGTH, MAX_MANIFEST_BYTES, MAX_PATH_LENGTH, MAX_RANGE_LENGTH, MAX_REGISTRY_BYTES, MAX_TOTAL_ARTIFACT_BYTES, MAX_TOTAL_REGISTRY_BYTES, REFERENCE_PATHS, ScaffoldError, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, contentToHex, extractRangeMajor, extractVersion, inferGroup, insertManifestDependencies, isAudit, isCatalogEntry, isCollection, isDependency, isDependencyName, isFloorPath, isHex, isManifestScript, isMirror, isPath, isPlan, isRetainedPath, isSnapshot, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, renderSkillPointer, replaceManifestRanges, replaceManifestScripts } from "../core/index.js";
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, closeSync, constants, copyFileSync, fstatSync, linkSync, lstatSync, mkdirSync, mkdtempSync, openSync, opendirSync, readSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -2144,7 +2144,8 @@ var isDependencies = andOf(isCollection, arrayOf(isDependency));
 * @remarks
 * The whole closed record a manifest-writing method accepts, so a caller
 * naming a region the writer does not carry is refused before any byte moves.
-* Each region is bounded by the same collection law its own list guard applies.
+* Each region is bounded by the same collection law its own list guard applies,
+* and `additions` is the one region a caller may omit.
 *
 * @example
 * ```ts
@@ -2152,6 +2153,11 @@ var isDependencies = andOf(isCollection, arrayOf(isDependency));
 *
 * isManifestRegionSet({ pins: { runtime: [], development: [] }, scripts: [] }) // true
 * isManifestRegionSet({ pins: { runtime: [], development: [] } }) // false
+* isManifestRegionSet({
+*   pins: { runtime: [], development: [] },
+*   scripts: [],
+*   additions: { runtime: [], development: [{ name: 'typescript', range: '^6.0.3' }] },
+* }) // true
 * ```
 */
 var isManifestRegionSet = recordOf({
@@ -2159,8 +2165,12 @@ var isManifestRegionSet = recordOf({
 		runtime: isDependencies,
 		development: isDependencies
 	}),
-	scripts: andOf(isCollection, arrayOf(isManifestScript))
-});
+	scripts: andOf(isCollection, arrayOf(isManifestScript)),
+	additions: recordOf({
+		runtime: isDependencies,
+		development: isDependencies
+	})
+}, ["additions"]);
 /** Narrows a value to a bounded list of fetched guide mirrors. */
 var isMirrors = andOf(isCollection, arrayOf(isMirror));
 /** Narrows a value to a bounded list of fleet catalog rows. */
@@ -3152,11 +3162,13 @@ var Materializer = class {
 	/**
 	* Rewrites the manifest regions the caller names in the target's manifest.
 	*
-	* @param regions - The dependency ranges and script values the manifest must declare.
+	* @param regions - The dependency ranges, script values, and additions the manifest must declare.
 	* @param target - The directory to write into.
 	* @returns The manifest path, written when a named region moved and skipped otherwise.
 	* @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
-	* exact shape or names a package the manifest does not declare, `TARGET` when
+	* exact shape, names a range the manifest does not declare, or names an
+	* addition the manifest already declares or whose section is not an object
+	* of version strings, `TARGET` when
 	* the manifest is unreadable, `WRITE` when the write cannot be staged or
 	* committed, and `DESTROYED` after teardown.
 	*
@@ -3164,7 +3176,10 @@ var Materializer = class {
 	* No other part of the manifest is read back out or rewritten. The method
 	* never reads or writes `peerDependencies` or `peerDependenciesMeta`. Only a
 	* range already declared in its named writable section is rewritten, so an
-	* undeclared name is refused instead of inserted.
+	* undeclared pin is refused instead of inserted. An undeclared package enters
+	* the manifest only through `additions`, which inserts it into the section its
+	* list names in key order, creating that section when the manifest lacks it,
+	* before the ranges are rewritten.
 	*
 	* The regions refuse differently because their targets differ. A range
 	* the manifest does not declare is the caller's mistake and throws. A script
@@ -3768,7 +3783,16 @@ var Materializer = class {
 	}
 	#redeclare(regions) {
 		return (text) => {
-			const manifest = replaceManifestRanges(text, regions.pins);
+			const additions = regions.additions ?? {
+				runtime: [],
+				development: []
+			};
+			const declared = insertManifestDependencies(text, additions);
+			if (declared === void 0) {
+				const names = [...additions.runtime, ...additions.development].map(({ name }) => name);
+				throw this.#error("INVALID", `The manifest cannot declare ${names.join(", ")}: it already declares one of them, or the section that receives them is not an object of version strings.`, { names: names.length });
+			}
+			const manifest = replaceManifestRanges(declared, regions.pins);
 			if (manifest === void 0) {
 				const missing = [...regions.pins.runtime, ...regions.pins.development].find((dependency) => !text.includes(JSON.stringify(dependency.name)));
 				throw this.#error("INVALID", `The manifest does not declare ${missing?.name ?? "a requested package"}, so its range cannot be rewritten.`, missing === void 0 ? void 0 : { name: missing.name });