@orkestrel/scaffold 0.0.25 → 0.0.26

package/dist/src/server/index.cjs

@@ -131,12 +131,23 @@ var MANIFEST_NAME = "manifest.json";
 * the byte ceiling. The character ceiling is read first so an oversized string is
 * refused before it is split.
 *
+* The two spellings of an empty segment are answered differently. A trailing
+* separator terminates a directory rather than opening a segment, and every
+* supported filesystem and every Node path API reads `project/` and `project` as
+* one location, so it is admitted. A doubled separator is a genuine empty
+* segment, so `project//src` is refused. Nothing normalizes the argument first —
+* every server entry point guards the caller's text and resolves it afterwards —
+* so a directory taken from a shell completion arrives carrying the separator the
+* shell appended and names the directory it appears to name.
+*
 * @example
 * ```ts
 * import { isFilesystemPath } from '@orkestrel/scaffold/server'
 *
 * isFilesystemPath('C:/Users/sample/project') // true
 * isFilesystemPath('../sibling') // true
+* isFilesystemPath('project/') // true
+* isFilesystemPath('project//src') // false
 * isFilesystemPath('project/nul') // false
 * ```
 */
@@ -145,7 +156,8 @@ function isFilesystemPath(value) {
 		if (!(0, _orkestrel_contract.isString)(value) || value.length === 0 || value.length > _src_core.MAX_PATH_LENGTH) return false;
 		if (_src_core.CONTROL_CHARACTER_PATTERN.test(value)) return false;
 		const normalized = value.replaceAll("\\", "/");
-		const segments = (normalized.startsWith("//") ? normalized.slice(2) : normalized.startsWith("/") ? normalized.slice(1) : normalized).split("/");
+		const rooted = normalized.startsWith("//") ? normalized.slice(2) : normalized.startsWith("/") ? normalized.slice(1) : normalized;
+		const segments = (rooted.endsWith("/") ? rooted.slice(0, -1) : rooted).split("/");
 		if (segments.length > 64) return false;
 		for (const [index, segment] of segments.entries()) {
 			if (segment === "." || segment === "..") continue;
@@ -510,6 +522,32 @@ function matchesSensitivePath(path) {
 	return /(?:^|\/)(?:(?:\.ssh|\.aws|\.azure|\.docker|\.kube|\.gnupg|\.env(?:\.[^/]*)?)(?:\/|$)|(?:\.npmrc|\.pypirc|\.netrc|\.git-credentials|settings\.local\.json|auth\.json|credentials(?:\.json)?|application_default_credentials\.json|id_rsa|id_ed25519|kubeconfig)$|\.config\/(?:gh|gcloud)(?:\/|$)|\.local\/share\/keyrings(?:\/|$)|[^/]*service-account[^/]*\.json$|[^/]*\.(?:jks|key|p12|pem|pfx|pkcs12)$)/i.test(normalized);
 }
 /**
+* Test whether a vendored path is one a target receives executable.
+*
+* @param path - The target-relative path to classify; either separator is read.
+* @returns `true` when the path is declared in {@link EXECUTABLE_PATHS}.
+*
+* @remarks
+* The declaration is the whole answer, and deliberately so. Reading the staging
+* host's mode instead makes the manifest depend on where the package was built:
+* Windows carries no executable bit, so a host staged there declares every entry
+* non-executable and every target it later fills receives hooks at `0644`. One
+* checkout stages one manifest on every host because this predicate never
+* consults the filesystem.
+*
+* @example
+* ```ts
+* import { matchesExecutablePath } from '@orkestrel/scaffold/server'
+*
+* matchesExecutablePath('scripts/codex.sh') // true
+* matchesExecutablePath('scripts\\deps.sh') // true
+* matchesExecutablePath('AGENTS.md') // false
+* ```
+*/
+function matchesExecutablePath(path) {
+	return _src_core.EXECUTABLE_PATHS.includes(path.replaceAll("\\", "/"));
+}
+/**
 * Project a target-relative path to the storage name a vendored host holds it under.
 *
 * @param path - The target-relative path the file is written to.
@@ -728,9 +766,10 @@ function computeFileDigest(path) {
 * Resolve a path through the real filesystem, keeping the part that does not exist yet.
 *
 * @param path - The absolute or relative host path to resolve.
-* @returns The path with its existing prefix resolved through every link, or
-* `undefined` when the text is not a host path, no bounded existing ancestor
-* resolves, or an ancestor cannot be read.
+* @returns The lexical resolution of `path`, with its existing prefix then
+* resolved through every link, or `undefined` when the text is not a host path,
+* no bounded existing ancestor resolves, a link target cannot be read, a link
+* target carries a `..` segment, or an ancestor cannot be read.
 *
 * @remarks
 * A containment decision has to be made about a destination that does not exist
@@ -740,6 +779,30 @@ function computeFileDigest(path) {
 * it. The climb is bounded by the path-depth ceiling, so an adversarial path
 * cannot make it walk indefinitely.
 *
+* The caller's own text is collapsed first, which is what `resolve` does with a
+* `..` the caller wrote: it cancels the segment before it as text, before any
+* link in that segment is read. So `<root>/hop/..` answers `<root>` even where
+* `hop` links elsewhere, rather than the directory holding what `hop` points at.
+* The collapse only ever shortens the caller's path, so nothing reaches outside
+* it by this; the answer is that lexical location resolved through links, not
+* the physical location the links lead to. {@link resolveContainedPath} passes
+* its `root` through here, so a root written with a parent segment is contained
+* against its collapsed spelling.
+*
+* `realpath` answers `ENOENT` both for a name that is not there and for a link
+* whose target is not there. The name is therefore inspected without following
+* it: a dangling link redirects the walk to its target, while a genuinely absent
+* name is retained as one segment of the unresolved suffix. A dangling link
+* target containing a `..` segment is refused. Resolving that target as one
+* lexical string could discard a preceding link before the filesystem gives
+* `..` its physical meaning.
+*
+* That target is split on both separators on every host, which is the reading
+* `isPath` already gives a planned path. A POSIX filename legally containing a
+* backslash is therefore refused with it: `weird\..\name` is one name to the
+* host and three segments here. The package keeps one separator law rather than
+* a host-dependent second one, and this is the conservative side of it.
+*
 * @example
 * ```ts
 * import { resolveRealPath } from '@orkestrel/scaffold/server'
@@ -759,6 +822,16 @@ function resolveRealPath(path) {
 			return physical;
 		}
 		if (!matchesMissingPath(real.error)) return void 0;
+		const status = (0, _orkestrel_contract.attempt)(() => (0, node_fs.lstatSync)(current));
+		if (status.success) {
+			if (!status.value.isSymbolicLink()) return void 0;
+			const target = (0, _orkestrel_contract.attempt)(() => (0, node_fs.readlinkSync)(current));
+			if (!target.success) return void 0;
+			if (target.value.split(/[\\/]/u).includes("..")) return void 0;
+			current = (0, node_path.resolve)((0, node_path.dirname)(current), target.value);
+			continue;
+		}
+		if (!matchesMissingPath(status.error)) return void 0;
 		const parent = (0, node_path.dirname)(current);
 		if (parent === current) return void 0;
 		pending.unshift((0, node_path.relative)(parent, current));
@@ -775,20 +848,31 @@ function resolveRealPath(path) {
 *
 * @remarks
 * The containment law, and the one door every read in this module goes through.
-* Both sides are resolved through the real filesystem before they are compared,
-* so a link planted inside the root cannot smuggle a destination out of it; the
-* answer is then the lexical join, so the caller operates on the path it named
-* rather than on a resolved form the target may not recognize.
+* Both sides are resolved through the real filesystem before they are compared.
+* A dangling link is followed only when its raw target contains no parent
+* traversal. The answer is then the lexical join of `root` and `path` — an
+* absolute path under `root`, not a root-relative one — so the caller operates
+* on the path it named rather than on a resolved form the target may not
+* recognize. A `root` written with a parent segment is collapsed by that
+* resolution before anything is read, so containment is measured against the
+* directory the caller's text names.
 *
 * Comparison is exact text, which fails closed on a case-insensitive
 * filesystem: a root and a path spelled with different case resolve to
 * different strings there and are refused, never wrongly admitted.
 *
+* The answer describes the namespace this call read. The contract excludes a
+* concurrent rename or link swap during the call or before the caller finishes
+* using the returned path. This helper returns a string, not a filesystem
+* handle, so it cannot bind its containment check to a later operation. A caller
+* that admits hostile concurrent namespace mutation needs a handle-bound
+* operation instead.
+*
 * @example
 * ```ts
 * import { resolveContainedPath } from '@orkestrel/scaffold/server'
 *
-* resolveContainedPath('/tmp/project', 'guides/router.md') // '/tmp/project/guides/router.md'
+* resolveContainedPath('/tmp/project', 'guides/router.md')?.endsWith('router.md') // true
 * resolveContainedPath('/tmp/project', '../secrets') // undefined
 * ```
 */
@@ -865,7 +949,7 @@ function isVacant(target) {
 * ```ts
 * import { listFiles } from '@orkestrel/scaffold/server'
 *
-* listFiles('./dist/host') // ['AGENTS.md', 'claude/rules/names.md', …]
+* listFiles('./dist/host') // ['AGENTS.md', 'CLAUDE.md', 'LICENSE', …]
 * ```
 */
 function listFiles(root) {
@@ -1239,14 +1323,14 @@ function readHostManifest(host) {
 *
 * @remarks
 * The one place the three declared fields are decided together, because they are
-* three readings of one file: {@link pathToStorage} decides where it is stored,
-* the destination is the path it answers for, and the executable bit is read
-* from the source's own mode.
+* three readings of one path: {@link pathToStorage} decides where it is stored,
+* the destination is the path it answers for, and {@link matchesExecutablePath}
+* decides whether a target receives it executable.
 *
-* That mode is the honest limit of this reading. A Windows host reports no
-* executable bit at all, so a host staged there declares every entry
-* non-executable and a consumer receives scripts without it. Staging on a POSIX
-* host is what carries the bit through.
+* The bit is read from that declaration rather than from the source's mode, so
+* the entry does not depend on where the package was staged. A Windows host
+* reports no executable bit at all, and reading the mode there declared every
+* entry non-executable and shipped consumers hooks they could not run.
 *
 * @example
 * ```ts
@@ -1263,7 +1347,7 @@ function readManifestEntry(destination, source) {
 	return {
 		storage: pathToStorage(destination),
 		destination,
-		executable: (status.value.mode & 73) !== 0
+		executable: matchesExecutablePath(destination)
 	};
 }
 /**
@@ -1433,8 +1517,8 @@ function stageHost(checkout, host) {
 * @remarks
 * Device and inode rather than the path, because the path is the thing that can
 * be swapped underneath a write. An anchor captured before a mutation and
-* checked again after it is what proves the directory written into is the
-* directory that was inspected.
+* checked again after it proves the directory written into sits where the
+* inspected one sat, not that it is the one that was inspected.
 *
 * @example
 * ```ts
@@ -1460,9 +1544,13 @@ function readAnchor(path) {
 * device and inode.
 *
 * @remarks
-* The check a write repeats between steps. A directory replaced by another
-* directory of the same name answers `false` here, which is the case a path
-* comparison alone cannot see.
+* This binds location rather than history. `true` means the path still resolves
+* to the same physical directory on the same device, so the next write lands
+* where the last one did. A path now holding nothing, a file, or a symlink
+* answers `false`; a directory swapped in by `rename` also answers `false`
+* because the replacement carries its own inode. A directory deleted and made
+* again under the same name can receive the old inode back and answers `true`,
+* which nothing here detects.
 *
 * @example
 * ```ts
@@ -1608,6 +1696,12 @@ function matchesPrecondition(precondition) {
 * - **No partly written destination.** Every file is written whole into the
 *   private root and digested there before commit, so a destination never
 *   receives bytes that were still being produced.
+* - **Containment, not continuity, of the directories it creates.** Every
+*   ancestor is re-read between `mkdir` calls and again before the first
+*   promotion, so an ancestor that became a file, a symlink, a directory
+*   elsewhere, or nothing is refused. An ancestor deleted and recreated under
+*   the same name can receive its old inode back and is indistinguishable here
+*   from one that never moved.
 * - **No crash atomicity across destinations.** A process killed between two
 *   promotions leaves the target holding some new files and some old ones, and
 *   leaves the private root behind. Nothing here is a journal, and the private
@@ -1702,7 +1796,7 @@ var WriteTransaction = class {
 		this.#stage = (0, node_path.join)(this.#root, "stage");
 		this.#backup = (0, node_path.join)(this.#root, "backup");
 		const opened = (0, _orkestrel_contract.attempt)(() => {
-			this.#created.push(...this.#establish(parent).created);
+			this.#establish(parent);
 			for (const directory of [
 				this.#root,
 				this.#stage,
@@ -1794,7 +1888,7 @@ var WriteTransaction = class {
 		const staged = this.#stagePath(path);
 		const copied = (0, _orkestrel_contract.attempt)(() => {
 			(0, node_fs.copyFileSync)(source, staged, node_fs.constants.COPYFILE_EXCL);
-			if (executable) (0, node_fs.chmodSync)(staged, 493);
+			(0, node_fs.chmodSync)(staged, executable ? 493 : 420);
 		});
 		if (!copied.success) throw new _src_core.ScaffoldError("WRITE", `The staged copy at ${path} could not be made.`, {
 			path,
@@ -1826,8 +1920,12 @@ var WriteTransaction = class {
 	directory(path) {
 		this.#assertOpen();
 		if (this.#expectation(path).shape === "file") throw new _src_core.ScaffoldError("TARGET", `The destination at ${path} holds a file.`, { path });
-		const result = this.#establish(this.#resolve(this.#target, path));
-		this.#created.push(...result.created);
+		const established = (0, _orkestrel_contract.attempt)(() => this.#establish(this.#resolve(this.#target, path)));
+		if (!established.success) throw new _src_core.ScaffoldError("WRITE", `The directory at ${path} could not be established.`, {
+			path,
+			error: established.error
+		});
+		const result = established.value;
 		if (result.created.length > 0 && !this.#established.includes(path)) this.#established.push(path);
 		return result;
 	}
@@ -1871,14 +1969,8 @@ var WriteTransaction = class {
 		const taken = [];
 		const applied = (0, _orkestrel_contract.attempt)(() => {
 			this.#preflight();
-			for (const path of this.#staged) {
-				this.#promote(path);
-				promoted.push(path);
-			}
-			for (const path of this.#taken) {
-				this.#take(path);
-				taken.push(path);
-			}
+			for (const path of this.#staged) this.#promote(path, promoted);
+			for (const path of this.#taken) this.#take(path, taken);
 		});
 		this.#open = false;
 		if (!applied.success) {
@@ -1978,9 +2070,11 @@ var WriteTransaction = class {
 				ancestor: anchor.path
 			});
 			(0, node_fs.mkdirSync)(segment);
+			this.#created.push(segment);
 			const established = readAnchor(segment);
 			if (established === void 0) throw new _src_core.ScaffoldError("WRITE", `The directory at ${segment} changed while writing.`, { path: destination });
 			anchor = established;
+			this.#created[this.#created.length - 1] = established;
 			created.push(established);
 		}
 		return {
@@ -1989,10 +2083,16 @@ var WriteTransaction = class {
 		};
 	}
 	#preflight() {
-		for (const anchor of this.#created) if (!matchesAnchor(anchor)) throw new _src_core.ScaffoldError("WRITE", `The directory at ${anchor.path} changed while writing.`, {
-			target: this.#target,
-			path: anchor.path
-		});
+		for (const anchor of this.#created) {
+			if (typeof anchor === "string") throw new _src_core.ScaffoldError("WRITE", `The directory at ${anchor} changed while writing.`, {
+				target: this.#target,
+				path: anchor
+			});
+			if (!matchesAnchor(anchor)) throw new _src_core.ScaffoldError("WRITE", `The directory at ${anchor.path} changed while writing.`, {
+				target: this.#target,
+				path: anchor.path
+			});
+		}
 		for (const path of [...this.#staged, ...this.#taken]) if (!matchesExpectation(this.#expectation(path))) throw new _src_core.ScaffoldError("WRITE", `The destination at ${path} moved while writing.`, {
 			target: this.#target,
 			path
@@ -2002,24 +2102,26 @@ var WriteTransaction = class {
 			path
 		});
 	}
-	#promote(path) {
+	#promote(path, promoted) {
 		const expectation = this.#expectation(path);
 		if (!matchesExpectation(expectation)) throw new _src_core.ScaffoldError("WRITE", `The destination at ${path} moved while writing.`, { path });
 		const staged = this.#resolve(this.#stage, path);
-		if (expectation.shape === "absent") this.#created.push(...this.#establish((0, node_path.dirname)(expectation.path)).created);
+		if (expectation.shape === "absent") this.#establish((0, node_path.dirname)(expectation.path));
 		else {
 			const backup = this.#resolve(this.#backup, path);
 			(0, node_fs.mkdirSync)((0, node_path.dirname)(backup), { recursive: true });
 			(0, node_fs.linkSync)(expectation.path, backup);
 		}
 		(0, node_fs.renameSync)(staged, expectation.path);
+		promoted.push(path);
 	}
-	#take(path) {
+	#take(path, taken) {
 		const expectation = this.#expectation(path);
 		if (!matchesExpectation(expectation)) throw new _src_core.ScaffoldError("WRITE", `The destination at ${path} moved while writing.`, { path });
 		const backup = this.#resolve(this.#backup, path);
 		(0, node_fs.mkdirSync)((0, node_path.dirname)(backup), { recursive: true });
 		(0, node_fs.renameSync)(expectation.path, backup);
+		taken.push(path);
 	}
 	#recover(promoted, taken) {
 		const residue = [];
@@ -2045,8 +2147,9 @@ var WriteTransaction = class {
 			}));
 			if (!cleared.success) residue.push(cleared.error);
 		}
-		for (const anchor of [...this.#created].reverse()) {
-			const removed = (0, _orkestrel_contract.attempt)(() => (0, node_fs.rmdirSync)(anchor.path));
+		for (const created of [...this.#created].reverse()) {
+			const path = typeof created === "string" ? created : created.path;
+			const removed = (0, _orkestrel_contract.attempt)(() => (0, node_fs.rmdirSync)(path));
 			if (!removed.success && !matchesMissingPath(removed.error)) residue.push(removed.error);
 		}
 		return residue;
@@ -2223,10 +2326,13 @@ var Materializer = class Materializer {
 	* The audit is a preview, not an instruction. The plan is hydrated and
 	* compared against the target again here, and the verdicts that produces must
 	* match the ones the audit carried for every path the plan owns; anything else
-	* means the target moved, and the whole call is refused. A missing destination
-	* is restored whatever its ownership; a stale one is replaced only where the
-	* artifact claims its bytes, which is what leaves a presence-owned file a
-	* consumer has edited exactly as it is.
+	* means the target moved, and the whole call is refused. The audit is checked
+	* for agreement rather than for plausibility, so a verdict the comparison could
+	* not have produced — a birth-owned path reported stale, which the `Finding`
+	* shape admits — disagrees with the derived one and is refused. A missing
+	* destination is restored whatever its ownership; a stale one is replaced only
+	* where the artifact claims its bytes, which is what leaves a presence-owned
+	* file a consumer has edited exactly as it is.
 	*/
 	repair(plan, audit, target) {
 		this.#assertAlive();
@@ -2599,6 +2705,12 @@ var Materializer = class Materializer {
 				path: finding.path
 			});
 			if (other.drift === finding.drift && other.observed === finding.observed) continue;
+			if (!(0, _src_core.matchesDriftReachability)(finding.ownership, other)) throw this.#error("TARGET", `The path ${finding.path} carries an audit verdict this plan could not produce.`, {
+				target,
+				path: finding.path,
+				ownership: finding.ownership,
+				drift: other.drift
+			});
 			throw this.#error("TARGET", `The path ${finding.path} moved since its audit.`, {
 				target,
 				path: finding.path
@@ -2847,6 +2959,7 @@ var Upstream = class Upstream {
 	static #defaultBudget = 16777216;
 	static #scope = "orkestrel";
 	static #unreadable = "the answer carries no readable latest version";
+	static #packument = "application/vnd.npm.install-v1+json";
 	#emitter;
 	#guideBase;
 	#guideBranch;
@@ -3039,7 +3152,7 @@ var Upstream = class Upstream {
 		return parsed.href.replace(/\/+$/u, "");
 	}
 	async #release(dependency, allowance) {
-		const outcome = await this.#read(this.#registryURL(dependency.name), this.#registryTimeout, allowance);
+		const outcome = await this.#read(this.#registryURL(dependency.name), this.#registryTimeout, allowance, Upstream.#packument);
 		const latest = outcome.lookup === "found" ? this.#latest(outcome.content) : void 0;
 		const release = latest === void 0 ? {
 			name: dependency.name,
@@ -3076,7 +3189,7 @@ var Upstream = class Upstream {
 		return mirror;
 	}
 	async #entry(name, allowance) {
-		const outcome = await this.#read(this.#registryURL(name), this.#registryTimeout, allowance);
+		const outcome = await this.#read(this.#registryURL(name), this.#registryTimeout, allowance, Upstream.#packument);
 		const version = outcome.lookup === "found" ? this.#latest(outcome.content) : void 0;
 		if (version !== void 0) return {
 			name,
@@ -3120,11 +3233,11 @@ var Upstream = class Upstream {
 		const repository = encodeURIComponent(name.slice(name.lastIndexOf("/") + 1));
 		return `${this.#guideBase}/${Upstream.#scope}/${repository}/refs/heads/${branch}/${(0, _src_core.nameToGuide)(name)}`;
 	}
-	async #read(url, timeout, allowance) {
+	async #read(url, timeout, allowance, accept) {
 		let note = "";
 		for (let attempt = 0; attempt <= this.#retries; attempt += 1) {
 			this.#assertAlive();
-			const outcome = await this.#request(url, timeout, allowance);
+			const outcome = await this.#request(url, timeout, allowance, accept);
 			if (outcome.lookup !== "failed") return outcome;
 			note = outcome.note;
 		}
@@ -3138,7 +3251,7 @@ var Upstream = class Upstream {
 			note
 		};
 	}
-	async #request(url, timeout, allowance) {
+	async #request(url, timeout, allowance, accept) {
 		if (allowance.remaining <= 0) return {
 			lookup: "failed",
 			content: "",
@@ -3147,7 +3260,8 @@ var Upstream = class Upstream {
 		try {
 			const response = await fetch(url, {
 				signal: AbortSignal.any([this.#controller.signal, AbortSignal.timeout(timeout)]),
-				redirect: "manual"
+				redirect: "manual",
+				...accept === void 0 ? {} : { headers: { accept } }
 			});
 			if (response.status === 404) {
 				await response.body?.cancel();
@@ -3184,21 +3298,11 @@ var Upstream = class Upstream {
 		}
 	}
 	async #body(response, allowance) {
-		const declared = response.headers.get("content-length");
-		const stated = declared === null ? void 0 : Number(declared);
-		if (stated !== void 0 && Number.isFinite(stated) && (stated > this.#limit || stated > allowance.remaining)) {
-			await response.body?.cancel();
-			return {
-				lookup: "failed",
-				content: "",
-				note: `the response declares ${String(stated)} bytes, past the ${String(Math.min(this.#limit, allowance.remaining))}-byte allowance`
-			};
-		}
 		const body = response.body;
 		if (body === null) return {
-			lookup: "found",
+			lookup: "failed",
 			content: "",
-			note: ""
+			note: `HTTP ${String(response.status)}, and the answer carries no body`
 		};
 		const reader = body.getReader();
 		const decoder = new TextDecoder("utf-8", { fatal: true });
@@ -3379,6 +3483,7 @@ exports.isVacant = isVacant;
 exports.listDirectories = listDirectories;
 exports.listFiles = listFiles;
 exports.matchesAnchor = matchesAnchor;
+exports.matchesExecutablePath = matchesExecutablePath;
 exports.matchesExpectation = matchesExpectation;
 exports.matchesGitPath = matchesGitPath;
 exports.matchesMissingPath = matchesMissingPath;