@orkestrel/scaffold 0.0.49 → 0.0.50

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

@@ -6,6 +6,7 @@ import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { Guard } from '@orkestrel/contract';
 import { HostFile } from '@orkestrel/scaffold';
+import { ManifestRegionSet } from '@orkestrel/scaffold';
 import { Mirror } from '@orkestrel/scaffold';
 import { Plan } from '@orkestrel/scaffold';
 import { Release } from '@orkestrel/scaffold';
@@ -428,6 +429,24 @@ export declare function isInventory(value: unknown): value is readonly unknown[]
  */
 export declare const isManifestEntry: Guard<ManifestEntry>;
 
+/**
+ * Narrow a value to one {@link ManifestRegionSet}.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import { isManifestRegionSet } from '@orkestrel/scaffold/server'
+ *
+ * isManifestRegionSet({ pins: { runtime: [], development: [] }, scripts: [] }) // true
+ * isManifestRegionSet({ pins: { runtime: [], development: [] } }) // false
+ * ```
+ */
+export declare const isManifestRegionSet: Guard<ManifestRegionSet>;
+
 /**
  * Narrow a value to the materializer's initial listener record.
  *
@@ -1059,24 +1078,30 @@ export declare class Materializer implements MaterializerInterface {
               */
           catalog(entries: readonly CatalogEntry[], target: string): MaterializeResult;
           /**
-           * Rewrite the declared dependency ranges the caller names in the target's manifest.
+           * Rewrite the manifest regions the caller names in the target's manifest.
            *
-           * @param dependencies - The names and ranges the manifest must declare.
+           * @param regions - The dependency ranges and script values the manifest must declare.
            * @param target - The directory to write into.
-           * @returns The manifest path, written when a declared range moved and skipped otherwise.
+           * @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
                * the manifest is unreadable, `WRITE` when the write cannot be staged or
                * committed, and `DESTROYED` after teardown.
                *
                * @remarks
-               * No other part of the manifest is read back out or rewritten, so a consumer's
-               * own description, keywords, scripts, and formatting survive the call. Only a
-               * range already declared is rewritten: inserting a package would mean
-               * re-serializing the whole manifest, which is exactly the edit this verb
-               * promises not to make, so an undeclared name is refused by name instead.
+               * 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.
+               *
+               * The regions refuse differently because their targets differ. A range
+               * the manifest does not declare is the caller's mistake and throws. A script
+               * holding a value the region does not accept is the workspace author's own
+               * chain, so the script region is skipped without a byte moving and the range
+               * region is still written. The advisory channel reports what the maintainer
+               * must paste.
                */
-           declare(dependencies: readonly Dependency[], target: string): MaterializeResult;
+           declare(regions: ManifestRegionSet, target: string): MaterializeResult;
            /**
             * Re-derive and delete the tracked files the plan does not own.
             *
@@ -1213,17 +1238,19 @@ export declare class Materializer implements MaterializerInterface {
                 */
                catalog(entries: readonly CatalogEntry[], target: string): MaterializeResult;
                /**
-                * Rewrite the declared dependency ranges the caller names in the target's manifest.
+                * Rewrite the manifest regions the caller names in the target's manifest.
                 *
-                * @param dependencies - The names and ranges the manifest must declare.
+                * @param regions - The dependency ranges and script values the manifest must declare.
                 * @param target - The directory to write into.
-                * @returns The manifest path, written when a declared range moved and skipped otherwise.
+                * @returns The manifest path, written when a named region moved and skipped otherwise.
                 *
                 * @remarks
-                * No other part of the manifest is read back out or rewritten, so a
-                * consumer's own description, keywords, and scripts survive the call.
+                * 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.
                 */
-               declare(dependencies: readonly Dependency[], target: string): MaterializeResult;
+               declare(regions: ManifestRegionSet, target: string): MaterializeResult;
                /**
                 * Re-derive and delete the tracked files the plan does not own.
                 *

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

@@ -6,6 +6,7 @@ import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
 import { Guard } from '@orkestrel/contract';
 import { HostFile } from '@orkestrel/scaffold';
+import { ManifestRegionSet } from '@orkestrel/scaffold';
 import { Mirror } from '@orkestrel/scaffold';
 import { Plan } from '@orkestrel/scaffold';
 import { Release } from '@orkestrel/scaffold';
@@ -428,6 +429,24 @@ export declare function isInventory(value: unknown): value is readonly unknown[]
  */
 export declare const isManifestEntry: Guard<ManifestEntry>;
 
+/**
+ * Narrow a value to one {@link ManifestRegionSet}.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import { isManifestRegionSet } from '@orkestrel/scaffold/server'
+ *
+ * isManifestRegionSet({ pins: { runtime: [], development: [] }, scripts: [] }) // true
+ * isManifestRegionSet({ pins: { runtime: [], development: [] } }) // false
+ * ```
+ */
+export declare const isManifestRegionSet: Guard<ManifestRegionSet>;
+
 /**
  * Narrow a value to the materializer's initial listener record.
  *
@@ -1059,24 +1078,30 @@ export declare class Materializer implements MaterializerInterface {
               */
           catalog(entries: readonly CatalogEntry[], target: string): MaterializeResult;
           /**
-           * Rewrite the declared dependency ranges the caller names in the target's manifest.
+           * Rewrite the manifest regions the caller names in the target's manifest.
            *
-           * @param dependencies - The names and ranges the manifest must declare.
+           * @param regions - The dependency ranges and script values the manifest must declare.
            * @param target - The directory to write into.
-           * @returns The manifest path, written when a declared range moved and skipped otherwise.
+           * @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
                * the manifest is unreadable, `WRITE` when the write cannot be staged or
                * committed, and `DESTROYED` after teardown.
                *
                * @remarks
-               * No other part of the manifest is read back out or rewritten, so a consumer's
-               * own description, keywords, scripts, and formatting survive the call. Only a
-               * range already declared is rewritten: inserting a package would mean
-               * re-serializing the whole manifest, which is exactly the edit this verb
-               * promises not to make, so an undeclared name is refused by name instead.
+               * 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.
+               *
+               * The regions refuse differently because their targets differ. A range
+               * the manifest does not declare is the caller's mistake and throws. A script
+               * holding a value the region does not accept is the workspace author's own
+               * chain, so the script region is skipped without a byte moving and the range
+               * region is still written. The advisory channel reports what the maintainer
+               * must paste.
                */
-           declare(dependencies: readonly Dependency[], target: string): MaterializeResult;
+           declare(regions: ManifestRegionSet, target: string): MaterializeResult;
            /**
             * Re-derive and delete the tracked files the plan does not own.
             *
@@ -1213,17 +1238,19 @@ export declare class Materializer implements MaterializerInterface {
                 */
                catalog(entries: readonly CatalogEntry[], target: string): MaterializeResult;
                /**
-                * Rewrite the declared dependency ranges the caller names in the target's manifest.
+                * Rewrite the manifest regions the caller names in the target's manifest.
                 *
-                * @param dependencies - The names and ranges the manifest must declare.
+                * @param regions - The dependency ranges and script values the manifest must declare.
                 * @param target - The directory to write into.
-                * @returns The manifest path, written when a declared range moved and skipped otherwise.
+                * @returns The manifest path, written when a named region moved and skipped otherwise.
                 *
                 * @remarks
-                * No other part of the manifest is read back out or rewritten, so a
-                * consumer's own description, keywords, and scripts survive the call.
+                * 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.
                 */
-               declare(dependencies: readonly Dependency[], target: string): MaterializeResult;
+               declare(regions: ManifestRegionSet, target: string): MaterializeResult;
                /**
                 * Re-derive and delete the tracked files the plan does not own.
                 *

package/dist/src/server/index.js

@@ -1,5 +1,5 @@
 import { andOf, arrayOf, attempt, boundsOf, holds, isArray, isBoolean, isError, isFunction, isInteger, isRecord, isString, parseJSON, parseJSONAs, parseStringField, recordOf, stringOf, unionOf } from "@orkestrel/contract";
-import { CATALOG_AGENT_PATH, CONTROL_CHARACTER_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, ScaffoldError, WORKSPACE_OWNED_PATHS, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, contentToHex, extractRangeMajor, extractVersion, inferGroup, isAudit, isCatalogEntry, isCollection, isDeferredPath, isDependency, isDependencyName, isHex, isMirror, isPath, isPlan, isSnapshot, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, replaceManifestRanges } from "../core/index.js";
+import { CATALOG_AGENT_PATH, CONTROL_CHARACTER_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, ScaffoldError, WORKSPACE_OWNED_PATHS, bytesToHex, catalogToLayers, cloneValue, compareVersions, computeBytes, contentToHex, extractRangeMajor, extractVersion, inferGroup, isAudit, isCatalogEntry, isCollection, isDeferredPath, isDependency, isDependencyName, isHex, isManifestScript, isMirror, isPath, isPlan, isSnapshot, matchesDriftReachability, matchesRange, nameToGuide, planToFindings, 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";
@@ -291,6 +291,29 @@ var isDependencyNames = andOf(isCollection, arrayOf(isDependencyName));
 var isPaths = andOf(isCollection, arrayOf(isPath));
 /** Narrow a value to a bounded list of declared runtime dependencies. */
 var isDependencies = andOf(isCollection, arrayOf(isDependency));
+/**
+* Narrow a value to one {@link ManifestRegionSet}.
+*
+* @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.
+*
+* @example
+* ```ts
+* import { isManifestRegionSet } from '@orkestrel/scaffold/server'
+*
+* isManifestRegionSet({ pins: { runtime: [], development: [] }, scripts: [] }) // true
+* isManifestRegionSet({ pins: { runtime: [], development: [] } }) // false
+* ```
+*/
+var isManifestRegionSet = recordOf({
+	pins: recordOf({
+		runtime: isDependencies,
+		development: isDependencies
+	}),
+	scripts: andOf(isCollection, arrayOf(isManifestScript))
+});
 /** Narrow a value to a bounded list of fetched guide mirrors. */
 var isMirrors = andOf(isCollection, arrayOf(isMirror));
 /** Narrow a value to a bounded list of fleet catalog rows. */
@@ -2785,26 +2808,32 @@ var Materializer = class Materializer {
 		return this.#rewrite(directory, CATALOG_AGENT_PATH, MAX_ARTIFACT_BYTES, this.#recatalog(accepted));
 	}
 	/**
-	* Rewrite the declared dependency ranges the caller names in the target's manifest.
+	* Rewrite the manifest regions the caller names in the target's manifest.
 	*
-	* @param dependencies - The names and ranges the manifest must declare.
+	* @param regions - The dependency ranges and script values the manifest must declare.
 	* @param target - The directory to write into.
-	* @returns The manifest path, written when a declared range moved and skipped otherwise.
+	* @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
 	* the manifest is unreadable, `WRITE` when the write cannot be staged or
 	* committed, and `DESTROYED` after teardown.
 	*
 	* @remarks
-	* No other part of the manifest is read back out or rewritten, so a consumer's
-	* own description, keywords, scripts, and formatting survive the call. Only a
-	* range already declared is rewritten: inserting a package would mean
-	* re-serializing the whole manifest, which is exactly the edit this verb
-	* promises not to make, so an undeclared name is refused by name instead.
+	* 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.
+	*
+	* The regions refuse differently because their targets differ. A range
+	* the manifest does not declare is the caller's mistake and throws. A script
+	* holding a value the region does not accept is the workspace author's own
+	* chain, so the script region is skipped without a byte moving and the range
+	* region is still written. The advisory channel reports what the maintainer
+	* must paste.
 	*/
-	declare(dependencies, target) {
+	declare(regions, target) {
 		this.#assertAlive();
-		const accepted = this.#accept(dependencies, isDependencies, "dependencies");
+		const accepted = this.#accept(regions, isManifestRegionSet, "regions");
 		const directory = this.#accept(target, isFilesystemPath, "target");
 		return this.#rewrite(directory, "package.json", MAX_MANIFEST_BYTES, this.#redeclare(accepted));
 	}
@@ -3341,12 +3370,14 @@ var Materializer = class Materializer {
 	#cell(note) {
 		return note.replaceAll("|", "\\|").replaceAll(/\s+/gu, " ").trim();
 	}
-	#redeclare(dependencies) {
+	#redeclare(regions) {
 		return (text) => {
-			const manifest = replaceManifestRanges(text, dependencies);
-			if (manifest !== void 0) return manifest;
-			const missing = dependencies.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 });
+			const manifest = replaceManifestRanges(text, 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 });
+			}
+			return replaceManifestScripts(manifest, regions.scripts) ?? manifest;
 		};
 	}
 	#finish(result) {
@@ -4105,6 +4136,6 @@ var Upstream = class Upstream {
 	}
 };
 //#endregion
-export { BRANCH_PATTERN, DIGEST_PATTERN, DRIVE_PATTERN, INVALID_SEGMENT_CHARACTER_PATTERN, MANIFEST_NAME, MAX_BRANCH_LENGTH, MAX_ENDPOINT_LENGTH, MAX_INVENTORY_PATHS, MAX_PATH_DEPTH, MAX_PATH_SEGMENT_BYTES, MAX_UPSTREAM_CONCURRENCY, MAX_UPSTREAM_RETRIES, MAX_UPSTREAM_TIMEOUT, Materializer, RESERVED_SEGMENT_PATTERN, Upstream, WriteTransaction, computeDigest, computeFileDigest, computeManifestDigest, filesToHost, hexToDigest, isBranch, isCatalogEntries, isDependencies, isDependencyNames, isDigest, isEndpoint, isExactCaseFile, isFilesystemPath, isHost, isHostManifest, isInventory, isManifestEntry, isMaterializerHooks, isMaterializerOptions, isMirrors, isPaths, isPhysicalDirectory, isPhysicalFile, isTimeout, isUpstreamHooks, isUpstreamOptions, isVacant, isWorktree, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, resolveContainedPath, resolveRealPath, stageBytes, stageHost, stageInventory };
+export { BRANCH_PATTERN, DIGEST_PATTERN, DRIVE_PATTERN, INVALID_SEGMENT_CHARACTER_PATTERN, MANIFEST_NAME, MAX_BRANCH_LENGTH, MAX_ENDPOINT_LENGTH, MAX_INVENTORY_PATHS, MAX_PATH_DEPTH, MAX_PATH_SEGMENT_BYTES, MAX_UPSTREAM_CONCURRENCY, MAX_UPSTREAM_RETRIES, MAX_UPSTREAM_TIMEOUT, Materializer, RESERVED_SEGMENT_PATTERN, Upstream, WriteTransaction, computeDigest, computeFileDigest, computeManifestDigest, filesToHost, hexToDigest, isBranch, isCatalogEntries, isDependencies, isDependencyNames, isDigest, isEndpoint, isExactCaseFile, isFilesystemPath, isHost, isHostManifest, isInventory, isManifestEntry, isManifestRegionSet, isMaterializerHooks, isMaterializerOptions, isMirrors, isPaths, isPhysicalDirectory, isPhysicalFile, isTimeout, isUpstreamHooks, isUpstreamOptions, isVacant, isWorktree, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, resolveContainedPath, resolveRealPath, stageBytes, stageHost, stageInventory };
 
 //# sourceMappingURL=index.js.map