@orkestrel/scaffold 0.0.76 → 0.0.78

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

@@ -111,6 +111,29 @@ export declare function computeFileDigest(path: string): string | undefined;
  */
 export declare function computeManifestDigest(entries: readonly ManifestEntry[], roots: readonly string[], surface: readonly SurfaceCollision[]): string;
 
+/**
+ * Decodes exact bytes stated in hexadecimal as strict UTF-8 text.
+ *
+ * @param hex - The exact lowercase hexadecimal bytes to decode.
+ * @returns The decoded text, or `undefined` when the bytes are not valid UTF-8.
+ * @throws Thrown when `hex` is not exact bounded lowercase hexadecimal text; the error is a
+ * `ScaffoldError` coded `INVALID`.
+ *
+ * @remarks
+ * Decoding is strict, so an invalid sequence answers `undefined` rather than
+ * text carrying replacement characters: every caller parses or derives from the
+ * text next, and a lossy decode would hand it bytes the file never held.
+ *
+ * @example
+ * ```ts
+ * import { decodeHexText } from '@orkestrel/scaffold/server'
+ *
+ * decodeHexText('e282ac0a') // '€\n'
+ * decodeHexText('fffe00') // undefined
+ * ```
+ */
+export declare function decodeHexText(hex: string): string | undefined;
+
 /** Holds the repository branch a raw content read addresses when a caller names none. */
 export declare const DEFAULT_BRANCH = "main";
 
@@ -209,8 +232,8 @@ export declare function filesToHost(files: readonly HostFile[], floor: Host): Ho
  *
  * @param hex - The exact lowercase hexadecimal bytes to digest.
  * @returns Sixty-four lowercase hexadecimal digits.
- * @throws `ScaffoldError('INVALID', …)` when `hex` is not exact bounded
- * lowercase hexadecimal text.
+ * @throws Thrown when `hex` is not exact bounded lowercase hexadecimal text; the error is a
+ * `ScaffoldError` coded `INVALID`.
  *
  * @example
  * ```ts
@@ -805,7 +828,7 @@ export declare function listDirectories(root: string): readonly string[];
  * ```ts
  * import { listFiles } from '@orkestrel/scaffold/server'
  *
- * listFiles('./dist/host') // ['AGENTS.md', 'CLAUDE.md', 'LICENSE', …]
+ * listFiles('./dist/host') // ['AGENTS.md', 'LICENSE', 'agents', …]
  * ```
  */
 export declare function listFiles(root: string): readonly string[];
@@ -2050,7 +2073,9 @@ export declare class Materializer implements MaterializerInterface {
             * whichever path the plan reached first. Refusing here fails the build that
             * produced it, where the maintainer can act, and it names every missing path at
             * once. A directory is the same case — declaring an absent directory as an empty
-            * root would create an empty directory in every generated workspace.
+            * root would create an empty directory in every generated workspace. A canon file
+            * member the checkout no longer holds is the one exception: scaffold keeps owning
+            * the path so a target's copy reports foreign, and the stage ships nothing for it.
             *
             * The walk covers `HOST_PATHS`, `CANON_PATHS`, and `REFERENCE_PATHS` together.
             * A plan selects the paths a target receives; the installed package also carries

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

@@ -111,6 +111,29 @@ export declare function computeFileDigest(path: string): string | undefined;
  */
 export declare function computeManifestDigest(entries: readonly ManifestEntry[], roots: readonly string[], surface: readonly SurfaceCollision[]): string;
 
+/**
+ * Decodes exact bytes stated in hexadecimal as strict UTF-8 text.
+ *
+ * @param hex - The exact lowercase hexadecimal bytes to decode.
+ * @returns The decoded text, or `undefined` when the bytes are not valid UTF-8.
+ * @throws Thrown when `hex` is not exact bounded lowercase hexadecimal text; the error is a
+ * `ScaffoldError` coded `INVALID`.
+ *
+ * @remarks
+ * Decoding is strict, so an invalid sequence answers `undefined` rather than
+ * text carrying replacement characters: every caller parses or derives from the
+ * text next, and a lossy decode would hand it bytes the file never held.
+ *
+ * @example
+ * ```ts
+ * import { decodeHexText } from '@orkestrel/scaffold/server'
+ *
+ * decodeHexText('e282ac0a') // '€\n'
+ * decodeHexText('fffe00') // undefined
+ * ```
+ */
+export declare function decodeHexText(hex: string): string | undefined;
+
 /** Holds the repository branch a raw content read addresses when a caller names none. */
 export declare const DEFAULT_BRANCH = "main";
 
@@ -209,8 +232,8 @@ export declare function filesToHost(files: readonly HostFile[], floor: Host): Ho
  *
  * @param hex - The exact lowercase hexadecimal bytes to digest.
  * @returns Sixty-four lowercase hexadecimal digits.
- * @throws `ScaffoldError('INVALID', …)` when `hex` is not exact bounded
- * lowercase hexadecimal text.
+ * @throws Thrown when `hex` is not exact bounded lowercase hexadecimal text; the error is a
+ * `ScaffoldError` coded `INVALID`.
  *
  * @example
  * ```ts
@@ -805,7 +828,7 @@ export declare function listDirectories(root: string): readonly string[];
  * ```ts
  * import { listFiles } from '@orkestrel/scaffold/server'
  *
- * listFiles('./dist/host') // ['AGENTS.md', 'CLAUDE.md', 'LICENSE', …]
+ * listFiles('./dist/host') // ['AGENTS.md', 'LICENSE', 'agents', …]
  * ```
  */
 export declare function listFiles(root: string): readonly string[];
@@ -2050,7 +2073,9 @@ export declare class Materializer implements MaterializerInterface {
             * whichever path the plan reached first. Refusing here fails the build that
             * produced it, where the maintainer can act, and it names every missing path at
             * once. A directory is the same case — declaring an absent directory as an empty
-            * root would create an empty directory in every generated workspace.
+            * root would create an empty directory in every generated workspace. A canon file
+            * member the checkout no longer holds is the one exception: scaffold keeps owning
+            * the path so a target's copy reports foreign, and the stage ships nothing for it.
             *
             * The walk covers `HOST_PATHS`, `CANON_PATHS`, and `REFERENCE_PATHS` together.
             * A plan selects the paths a target receives; the installed package also carries

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, 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, 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";
@@ -354,8 +354,8 @@ function computeDigest(content) {
 *
 * @param hex - The exact lowercase hexadecimal bytes to digest.
 * @returns Sixty-four lowercase hexadecimal digits.
-* @throws `ScaffoldError('INVALID', …)` when `hex` is not exact bounded
-* lowercase hexadecimal text.
+* @throws Thrown when `hex` is not exact bounded lowercase hexadecimal text; the error is a
+* `ScaffoldError` coded `INVALID`.
 *
 * @example
 * ```ts
@@ -369,6 +369,32 @@ function hexToDigest(hex) {
 	return createHash("sha256").update(Buffer.from(hex, "hex")).digest("hex");
 }
 /**
+* Decodes exact bytes stated in hexadecimal as strict UTF-8 text.
+*
+* @param hex - The exact lowercase hexadecimal bytes to decode.
+* @returns The decoded text, or `undefined` when the bytes are not valid UTF-8.
+* @throws Thrown when `hex` is not exact bounded lowercase hexadecimal text; the error is a
+* `ScaffoldError` coded `INVALID`.
+*
+* @remarks
+* Decoding is strict, so an invalid sequence answers `undefined` rather than
+* text carrying replacement characters: every caller parses or derives from the
+* text next, and a lossy decode would hand it bytes the file never held.
+*
+* @example
+* ```ts
+* import { decodeHexText } from '@orkestrel/scaffold/server'
+*
+* decodeHexText('e282ac0a') // '€\n'
+* decodeHexText('fffe00') // undefined
+* ```
+*/
+function decodeHexText(hex) {
+	if (!isHex(hex)) throw new ScaffoldError("INVALID", "Decode input is not exact hexadecimal bytes", { hex });
+	const decoded = attempt(() => new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(hex, "hex")));
+	return decoded.success ? decoded.value : void 0;
+}
+/**
 * Computes the digest of a vendored host's declared membership.
 *
 * @param entries - The ordered file membership declarations.
@@ -724,7 +750,7 @@ function isVacant(target) {
 * ```ts
 * import { listFiles } from '@orkestrel/scaffold/server'
 *
-* listFiles('./dist/host') // ['AGENTS.md', 'CLAUDE.md', 'LICENSE', …]
+* listFiles('./dist/host') // ['AGENTS.md', 'LICENSE', 'agents', …]
 * ```
 */
 function listFiles(root) {
@@ -1059,9 +1085,7 @@ function readFileHex(root, path, limit = MAX_ARTIFACT_BYTES) {
 */
 function readFileText(root, path, limit = MAX_ARTIFACT_BYTES) {
 	const hex = readFileHex(root, path, limit);
-	if (hex === void 0) return void 0;
-	const decoded = attempt(() => new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(hex, "hex")));
-	return decoded.success ? decoded.value : void 0;
+	return hex === void 0 ? void 0 : decodeHexText(hex);
 }
 /**
 * Reads a target's current bytes at the paths a plan claims.
@@ -1447,7 +1471,9 @@ function stageBytes(host, root, destinations) {
 * whichever path the plan reached first. Refusing here fails the build that
 * produced it, where the maintainer can act, and it names every missing path at
 * once. A directory is the same case — declaring an absent directory as an empty
-* root would create an empty directory in every generated workspace.
+* root would create an empty directory in every generated workspace. A canon file
+* member the checkout no longer holds is the one exception: scaffold keeps owning
+* the path so a target's copy reports foreign, and the stage ships nothing for it.
 *
 * The walk covers `HOST_PATHS`, `CANON_PATHS`, and `REFERENCE_PATHS` together.
 * A plan selects the paths a target receives; the installed package also carries
@@ -1496,7 +1522,7 @@ function stageHost(checkout, host, options) {
 			continue;
 		}
 		if (!isPhysicalDirectory(full)) {
-			missing.push(path);
+			if (!CANON_PATHS.includes(path)) missing.push(path);
 			continue;
 		}
 		roots.push(path);
@@ -3282,7 +3308,7 @@ var Materializer = class {
 				continue;
 			}
 			const expanded = this.#expand(artifact, remaining);
-			for (const one of expanded) remaining -= (one.hex?.length ?? 0) / 2;
+			for (const one of expanded) remaining -= one.origin === "host" ? (one.hex?.length ?? 0) / 2 : computeBytes(one.content);
 			artifacts.push(...expanded);
 		}
 		if (remaining < 0) throw this.#error("TARGET", "The hydrated plan retains more bytes than one plan may.", {
@@ -3444,6 +3470,14 @@ var Materializer = class {
 		};
 	}
 	#hydrated(artifact, path, destination, hex) {
+		if ("pointer" in artifact && artifact.pointer === true) return {
+			path,
+			group: artifact.group,
+			ownership: "content",
+			origin: "computed",
+			...artifact.environment === void 0 ? {} : { environment: artifact.environment },
+			content: this.#point(path, destination, hex)
+		};
 		return {
 			path,
 			group: artifact.group,
@@ -3454,6 +3488,17 @@ var Materializer = class {
 			hex
 		};
 	}
+	#point(path, destination, hex) {
+		const name = path.endsWith("/SKILL.md") ? path.split("/").at(-2) : void 0;
+		const decoded = decodeHexText(hex);
+		const pointer = name === void 0 || decoded === void 0 ? void 0 : renderSkillPointer(decoded, name);
+		if (pointer === void 0) throw this.#error("TARGET", `The vendored skill at ${destination} cannot derive the pointer at ${path}.`, {
+			host: this.#root,
+			source: destination,
+			path
+		});
+		return pointer;
+	}
 	#read(entry, budget) {
 		const held = this.#value?.bytes[entry.destination];
 		if (held === void 0) return this.#readRoot(entry.storage, budget);
@@ -4480,6 +4525,6 @@ var Upstream = class {
 	}
 };
 //#endregion
-export { BRANCH_PATTERN, DEFAULT_BRANCH, DEFAULT_REGISTRY_BASE, DEFAULT_REPOSITORY_BASE, DEFAULT_UPSTREAM_CONCURRENCY, DEFAULT_UPSTREAM_RETRIES, DEFAULT_UPSTREAM_TIMEOUT, 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, ORKESTREL_SCOPE, PACKUMENT_MEDIA_TYPE, RESERVED_SEGMENT_PATTERN, SCAFFOLD_REPOSITORY, UNREADABLE_VERSION_NOTE, 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, listCanonPaths, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, pruneEmptiedDirectories, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, readSurfaceBaseline, readSurfaceCollisions, resolveContainedPath, resolveRealPath, stageBytes, stageHost, stageInventory };
+export { BRANCH_PATTERN, DEFAULT_BRANCH, DEFAULT_REGISTRY_BASE, DEFAULT_REPOSITORY_BASE, DEFAULT_UPSTREAM_CONCURRENCY, DEFAULT_UPSTREAM_RETRIES, DEFAULT_UPSTREAM_TIMEOUT, 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, ORKESTREL_SCOPE, PACKUMENT_MEDIA_TYPE, RESERVED_SEGMENT_PATTERN, SCAFFOLD_REPOSITORY, UNREADABLE_VERSION_NOTE, Upstream, WriteTransaction, computeDigest, computeFileDigest, computeManifestDigest, decodeHexText, 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, listCanonPaths, listDirectories, listFiles, matchesAnchor, matchesExecutablePath, matchesExpectation, matchesGitPath, matchesMissingPath, matchesPrecondition, matchesProtectedPath, matchesSensitivePath, pathToStorage, pruneEmptiedDirectories, readAnchor, readExpectation, readFileHex, readFileText, readHostFloor, readHostManifest, readManifestEntry, readSnapshot, readSurfaceBaseline, readSurfaceCollisions, resolveContainedPath, resolveRealPath, stageBytes, stageHost, stageInventory };
 
 //# sourceMappingURL=index.js.map