@orkestrel/scaffold 0.0.55 → 0.0.56

package/dist/src/server/index.cjs

@@ -1211,6 +1211,97 @@ function listDirectories(root) {
 	return directories.sort();
 }
 /**
+* Lists the canon paths a target holds, filtered to a plan's groups.
+*
+* @param target - The target directory to inspect.
+* @param groups - The artifact groups the plan covers; a held path whose group
+* is outside them is not listed.
+* @returns Every held canon path as a `/`-separated target-relative path, a
+* directory member expanded to the files beneath it, and `[]` when the target
+* holds none or cannot be resolved.
+* @throws `ScaffoldError('TARGET', …)` when a held canon directory cannot be
+* inventoried; {@link listFiles} states each refusal.
+*
+* @remarks
+* A release stages the canon for reading rather than for a target, so a copy
+* sitting in one is an artifact of a release that vendored it, and reading it
+* here is what lets the deletion verb take it.
+*
+* A directory member is read by file, which is what pairs the paths a plan
+* claims inside the canon with their artifacts and leaves only the rest foreign,
+* with no case for a planned file. The plan's own selection gates the reading,
+* the same rule that decides a vendored path's group, so a scoped audit reports
+* nothing outside its groups. A member that cannot resolve inside the target is
+* not held by it.
+*
+* @example
+* ```ts
+* import { listCanonPaths } from '@orkestrel/scaffold/server'
+*
+* listCanonPaths('vacant', ['orchestration']) // []
+* ```
+*/
+function listCanonPaths(target, groups) {
+	const held = [];
+	for (const member of _src_core.CANON_PATHS) {
+		const full = resolveContainedPath(target, member);
+		if (full === void 0) continue;
+		if (isPhysicalFile(full)) held.push(member);
+		else if (isPhysicalDirectory(full)) for (const name of listFiles(full)) held.push(`${member}/${name}`);
+	}
+	return held.filter((path) => groups.includes((0, _src_core.inferGroup)(path)));
+}
+/**
+* Removes every directory one set of deletions emptied.
+*
+* @param target - The directory the deleted paths are relative to.
+* @param removed - The `/`-separated target-relative paths the deletion took.
+* @returns Every removed directory as a target-relative path, in the order they
+* were taken, and `[]` when the target is absent or nothing it holds was
+* emptied.
+*
+* @remarks
+* A deletion that takes the last file out of a directory leaves the directory
+* standing, and git records no directory, so a swept target keeps the shape of a
+* set it no longer holds while every reading of it reports clean. Only an
+* ancestor of a path this deletion took is a candidate, so nothing the deletion
+* did not reach is inspected, and the target itself is never a candidate.
+*
+* Candidates are taken deepest first, which is what lets a whole chain go: the
+* directory holding nothing but the emptied directory is empty in turn by the
+* time it is read. Each one is resolved through the containment law and left
+* standing when it escapes the target, is not a physical directory, still holds
+* an entry, or refuses removal, and a directory left standing is absent from the
+* answer.
+*
+* @example
+* ```ts
+* import { pruneEmptiedDirectories } from '@orkestrel/scaffold/server'
+*
+* pruneEmptiedDirectories('vacant', ['notes/entry.md']) // []
+* ```
+*/
+function pruneEmptiedDirectories(target, removed) {
+	const candidates = /* @__PURE__ */ new Set();
+	for (const path of removed) {
+		let parent = (0, node_path.dirname)(path);
+		while (parent !== "." && parent !== (0, node_path.dirname)(parent) && !candidates.has(parent)) {
+			candidates.add(parent);
+			parent = (0, node_path.dirname)(parent);
+		}
+	}
+	const ordered = [...candidates].sort((left, right) => (0, _orkestrel_contract.compareValues)(right.split("/").length, left.split("/").length) || (0, _orkestrel_contract.compareValues)(left, right));
+	const pruned = [];
+	for (const candidate of ordered) {
+		const directory = resolveContainedPath(target, candidate);
+		if (directory === void 0 || !isPhysicalDirectory(directory)) continue;
+		const entries = (0, _orkestrel_contract.attempt)(() => (0, node_fs.readdirSync)(directory));
+		if (!entries.success || entries.value.length > 0) continue;
+		if ((0, _orkestrel_contract.attempt)(() => (0, node_fs.rmdirSync)(directory)).success) pruned.push(candidate);
+	}
+	return pruned;
+}
+/**
 * Read one contained file as its exact bytes in lowercase hexadecimal.
 *
 * @param root - The containing host directory.
@@ -1519,8 +1610,11 @@ function readManifestEntry(destination, source) {
 * went missing, names an undeclared path, or leaves a host-owned path absent
 * answers `undefined`. Deferred paths are presence-only and retain the installed
 * floor bytes that their catalog or mirror surface owns; repair never writes
-* those floor bytes. One `Host` can therefore carry live host bytes beside floor
-* bytes without mixing baselines within a surface.
+* those floor bytes. A canon path is read the same way for a different reason:
+* the canon is staged for reading rather than for a target, so every canon
+* destination keeps its floor bytes here, claimed or not, and a fill that carries
+* no row for one is complete rather than spoiled. One `Host` can therefore carry
+* live host bytes beside floor bytes without mixing baselines within a surface.
 *
 * The emitted entries keep the release's own order and its storage and
 * executable declarations, and carry digests recomputed over the bytes the fill
@@ -1532,8 +1626,12 @@ function readManifestEntry(destination, source) {
 * ```ts
 * import { filesToHost } from '@orkestrel/scaffold/server'
 *
-* filesToHost([{ path: 'AGENTS.md', lookup: 'found', hex: '23204167656e74730a' }], floor)
-* // { manifest: { entries: [ … ], roots: [ … ], digest: '…' }, bytes: { 'AGENTS.md': '…' } }
+* // A floor declaring the host-owned `scripts/codex.sh` path and the canon
+* // `AGENTS.md` destination. The script's live bytes are taken; the canon
+* // destination keeps the floor's.
+* filesToHost([{ path: 'scripts/codex.sh', lookup: 'found', hex: '23212f62696e2f73680a' }], floor)
+* // { manifest: { entries: [ … ], roots: [ … ], digest: '…' },
+* //   bytes: { 'scripts/codex.sh': '23212f62696e2f73680a', 'AGENTS.md': floor.bytes['AGENTS.md'] } }
 * ```
 */
 function filesToHost(files, floor) {
@@ -1541,12 +1639,12 @@ function filesToHost(files, floor) {
 	const held = /* @__PURE__ */ new Map();
 	for (const file of files) {
 		if (file.lookup !== "found" || !declared.has(file.path)) return void 0;
-		if (!(0, _src_core.isDeferredPath)(file.path)) held.set(file.path, file.hex);
+		if (!(0, _src_core.isDeferredPath)(file.path) && !(0, _src_core.isCanonPath)(file.path)) held.set(file.path, file.hex);
 	}
 	const entries = [];
 	const bytes = {};
 	for (const entry of floor.manifest.entries) {
-		const hex = (0, _src_core.isDeferredPath)(entry.destination) ? floor.bytes[entry.destination] : held.get(entry.destination);
+		const hex = (0, _src_core.isDeferredPath)(entry.destination) || (0, _src_core.isCanonPath)(entry.destination) ? floor.bytes[entry.destination] : held.get(entry.destination);
 		if (hex === void 0) return void 0;
 		entries.push({
 			storage: entry.storage,
@@ -1677,9 +1775,15 @@ function stageBytes(host, root, destinations) {
 * once. A directory is the same case — declaring an absent directory as an empty
 * root would create an empty directory in every generated workspace.
 *
-* The vendoring deny-list applies to what the walk discovers beneath a vendored
+* The walk covers `HOST_PATHS` and `CANON_PATHS` together, because a release
+* ships both: a target receives the first set, and reads the second one out of
+* the installed package. Everything downstream — the missing-path refusal, the
+* storage collision guard, the sort, the digests, and the root inventory — reads
+* the union, so a canon path is staged under exactly the law a vendored one is.
+*
+* The vendoring deny-list applies to what the walk discovers beneath a staged
 * directory, where a maintainer's local credential can legitimately sit, and
-* such a path is skipped. A path `HOST_PATHS` names itself is curated data
+* such a path is skipped. A path either list names itself is curated data
 * rather than discovery, so it is staged or the stage is refused.
 *
 * @example
@@ -1698,7 +1802,7 @@ function stageHost(checkout, host) {
 	const vendored = [];
 	const roots = [];
 	const missing = [];
-	for (const path of _src_core.HOST_PATHS) {
+	for (const path of [..._src_core.HOST_PATHS, ..._src_core.CANON_PATHS]) {
 		const full = resolveContainedPath(source, path);
 		if (full === void 0) throw new _src_core.ScaffoldError("INVALID", `Vendored path leaves its checkout at ${path}`, {
 			checkout: source,
@@ -2652,7 +2756,8 @@ var Materializer = class Materializer {
 	*
 	* @param plan - The compiled plan to compare.
 	* @param target - The directory to inspect.
-	* @returns One finding per hydrated planned path, plus foreign files beneath owned host roots.
+	* @returns One finding per hydrated planned path, plus the foreign files
+	* beneath owned host roots and inside the instruction canon.
 	* @throws {@link ScaffoldError} coded `INVALID` when an argument is not the
 	* exact shape, `TARGET` when the host or target cannot be read within its
 	* bounds, and `DESTROYED` after teardown.
@@ -2660,8 +2765,16 @@ var Materializer = class Materializer {
 	* @remarks
 	* Host directories expand before the target is read, so this method and
 	* {@link repair} compare the same paths with the same ownership. Foreign
-	* candidates are files beneath those expanded roots only; a root file never
-	* becomes a deletion candidate merely because its group is selected.
+	* candidates are files beneath those expanded roots and files the target holds
+	* at a `CANON_PATHS` member, each in a group the plan selects; a file outside
+	* both populations never becomes a deletion candidate merely because its group
+	* is selected.
+	*
+	* The canon is staged for reading rather than for a target, so a copy of one of
+	* its paths sitting in a target is a superseded artifact and reports foreign. A
+	* path the plan claims inside the canon — the root instruction pointers and the
+	* catalog agent file — pairs with its artifact and is compared like any other
+	* planned path.
 	*/
 	audit(plan, target) {
 		this.#assertAlive();
@@ -2860,9 +2973,20 @@ var Materializer = class Materializer {
 	* recovery mechanism, so a path it cannot restore is not one this verb takes.
 	* A tree carrying uncommitted work is refused whole for the same reason.
 	*
+	* One candidate list carries both foreign populations {@link audit} reports, so
+	* a superseded instruction copy the target holds inside the canon is deleted in
+	* the same transaction as a stray beneath an owned root. Membership decides it,
+	* never byte identity: a copy a release behind no longer matches the bytes the
+	* canon now stages, and matching bytes is exactly how such a copy would be
+	* spared. An untracked leftover is left where it sits and stays a finding, which
+	* is the seam a maintainer keeps a git-ignored file in.
+	*
 	* The whole call refuses when the preview disagrees with the re-derivation on
 	* any foreign finding, including one the deletion itself would skip, because a
 	* preview stale anywhere is stale evidence.
+	*
+	* Every directory the deletions emptied is taken after the commit, so a swept
+	* target does not keep the shape of the set it no longer holds.
 	*/
 	remove(plan, audit, worktree, target) {
 		this.#assertAlive();
@@ -2980,6 +3104,7 @@ var Materializer = class Materializer {
 			});
 			for (const name of listFiles(directory)) paths.add(`${root}/${name}`);
 		}
+		for (const path of listCanonPaths(target, plan.groups)) paths.add(path);
 		return {
 			findings: (0, _src_core.planToFindings)(hydrated, readSnapshot(target, [...paths])),
 			questions: []
@@ -3285,6 +3410,7 @@ var Materializer = class Materializer {
 		});
 		const removed = this.#close(transaction, staged, target);
 		for (const path of removed) this.#emitter.emit("remove", path);
+		pruneEmptiedDirectories(target, removed);
 		return this.#finish({
 			target,
 			written: [],
@@ -4183,6 +4309,7 @@ exports.isUpstreamHooks = isUpstreamHooks;
 exports.isUpstreamOptions = isUpstreamOptions;
 exports.isVacant = isVacant;
 exports.isWorktree = isWorktree;
+exports.listCanonPaths = listCanonPaths;
 exports.listDirectories = listDirectories;
 exports.listFiles = listFiles;
 exports.matchesAnchor = matchesAnchor;
@@ -4194,6 +4321,7 @@ exports.matchesPrecondition = matchesPrecondition;
 exports.matchesProtectedPath = matchesProtectedPath;
 exports.matchesSensitivePath = matchesSensitivePath;
 exports.pathToStorage = pathToStorage;
+exports.pruneEmptiedDirectories = pruneEmptiedDirectories;
 exports.readAnchor = readAnchor;
 exports.readExpectation = readExpectation;
 exports.readFileHex = readFileHex;