@orkestrel/scaffold 0.0.77 → 0.0.78

package/dist/src/server/index.cjs

@@ -355,8 +355,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
@@ -370,6 +370,32 @@ function hexToDigest(hex) {
 	return (0, node_crypto.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 (!(0, _src_core.isHex)(hex)) throw new _src_core.ScaffoldError("INVALID", "Decode input is not exact hexadecimal bytes", { hex });
+	const decoded = (0, _orkestrel_contract.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.
@@ -725,7 +751,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) {
@@ -1060,9 +1086,7 @@ function readFileHex(root, path, limit = _src_core.MAX_ARTIFACT_BYTES) {
 */
 function readFileText(root, path, limit = _src_core.MAX_ARTIFACT_BYTES) {
 	const hex = readFileHex(root, path, limit);
-	if (hex === void 0) return void 0;
-	const decoded = (0, _orkestrel_contract.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.
@@ -1448,7 +1472,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
@@ -1497,7 +1523,7 @@ function stageHost(checkout, host, options) {
 			continue;
 		}
 		if (!isPhysicalDirectory(full)) {
-			missing.push(path);
+			if (!_src_core.CANON_PATHS.includes(path)) missing.push(path);
 			continue;
 		}
 		roots.push(path);
@@ -3283,7 +3309,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 : (0, _src_core.computeBytes)(one.content);
 			artifacts.push(...expanded);
 		}
 		if (remaining < 0) throw this.#error("TARGET", "The hydrated plan retains more bytes than one plan may.", {
@@ -3445,6 +3471,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,
@@ -3455,6 +3489,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 : (0, _src_core.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);
@@ -4511,6 +4556,7 @@ exports.WriteTransaction = WriteTransaction;
 exports.computeDigest = computeDigest;
 exports.computeFileDigest = computeFileDigest;
 exports.computeManifestDigest = computeManifestDigest;
+exports.decodeHexText = decodeHexText;
 exports.filesToHost = filesToHost;
 exports.hexToDigest = hexToDigest;
 exports.isBranch = isBranch;