@vibe-agent-toolkit/utils 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/tree-change/plan.js

@@ -0,0 +1,320 @@
+/**
+ * The plan half of the tree-change primitive: every destructive verb describes
+ * what it wants as {@link TreeChange}s, and {@link planTreeChanges} decides, with
+ * no side effect, what will actually happen to each — before anything is written.
+ *
+ * The decisions, in order:
+ *
+ * 1. **What is there** at each destination (`lstat`; a destination the OS refuses
+ *    to examine throws, classified `destination`; "absent" is believed only when
+ *    the parent's listing agrees).
+ * 2. **Keep.** A `remove` with nothing there, or whose `keepIfSameAs` names an
+ *    entry that is `same` **or `unknown`** to it, is kept, with the reason. Only
+ *    the target's own unexaminability throws, never a sibling's. A `remove` that
+ *    holds a kept entry (or cannot be proven not to) is kept too: a kept entry is
+ *    kept whole, never taken away with a directory above it.
+ * 3. **Aliasing and containment, by identity.** A `remove` that is the same entry
+ *    as a `replace` (`plugins/Old` and `plugins/old` on APFS or NTFS, a link and its
+ *    target), or an earlier `remove`, or lies inside any other change's
+ *    destination, is `subsumed`: that change parks it. `unknown` is never a merge
+ *    and never a refusal — the two changes run as two, and a wrong guess fails the
+ *    apply, which rolls back; refusing would refuse every change on a filesystem
+ *    that reports `ino` 0. Any other two changes still active whose destinations
+ *    are one entry or nest are refused ({@link TREE_DESTS_OVERLAP_CODE}): the
+ *    calling verb's defect, never the user's input.
+ * 4. **Ownership** of whatever is there: `must-be-free` refuses anything but an
+ *    empty directory ({@link TREE_DEST_OCCUPIED_CODE}); `vat-made` refuses what its
+ *    `recognise` disowns ({@link TREE_DEST_NOT_OWNED_CODE}); `force` and
+ *    `vat-state` take anything — except that a `replace-file` never takes a directory
+ *    (or a link to one), under any ownership ({@link TREE_DEST_OCCUPIED_CODE}).
+ * 5. **Holding.** A `copy` source, or a `write` fill's declared `reads`, that is the
+ *    destination or inside it ({@link TREE_DEST_HOLDS_SOURCE_CODE}: the replace
+ *    would delete it — never asked of a destination that is a link, which holds
+ *    nothing: only the link is parked), or that holds the destination
+ *    ({@link TREE_SOURCE_HOLDS_DEST_CODE}: a copy into itself), is refused.
+ * 6. **Readable source.** Every `copy` source is proven readable (the one
+ *    special-file and link policy, `proveTreeReadable`, on the fill's declared `side`).
+ *
+ * Utils names no refusal code: these are library codes, and the CLI's refusal map
+ * decides which refusal each is.
+ */
+import { lstatSync, readdirSync } from 'node:fs';
+import { requireConfirmedAbsent } from '../errors/confirmed-absent.js';
+import { isPathAbsentError } from '../errors/errno-table.js';
+import { classifyFsFault, everywhere, withFsFaultSync } from '../errors/fs-fault.js';
+import { VatError } from '../errors/vat-error.js';
+import { forEachInOrder } from '../in-order.js';
+import { followedStatSync } from '../link-following.js';
+import { relativeEscapesRoot, safePath } from '../path-core.js';
+import { identityOracle } from './identity.js';
+import { proveTreeReadable } from './readable-tree.js';
+/** A destination that must be absent or an empty directory already holds something. */
+export const TREE_DEST_OCCUPIED_CODE = 'TREE_DEST_OCCUPIED';
+/** A destination VAT may replace only when it made it holds something its recogniser disowns. */
+export const TREE_DEST_NOT_OWNED_CODE = 'TREE_DEST_NOT_OWNED';
+/**
+ * Two changes of one plan whose destinations are one entry or nest (other than a remove the other
+ * change takes with it): they cannot be one transaction — the outer park would carry the inner
+ * change's staging away. The calling verb built a plan it must not, so it is VAT's defect.
+ */
+export const TREE_DESTS_OVERLAP_CODE = 'TREE_DESTS_OVERLAP';
+/** A copy's destination lies inside its source: the copy would copy into itself. */
+export const TREE_SOURCE_HOLDS_DEST_CODE = 'TREE_SOURCE_HOLDS_DEST';
+/** A copy's source is its destination or lies inside it: the replace would delete what it copies. */
+export const TREE_DEST_HOLDS_SOURCE_CODE = 'TREE_DEST_HOLDS_SOURCE';
+function refusal(code, message) {
+    return new VatError(code, message);
+}
+/** Why a remove is kept — and the sibling the OS refused to examine, when that is why — or `undefined` when it goes ahead. */
+function keepReason(change, existing, facts) {
+    if (change.op !== 'remove')
+        return undefined;
+    if (existing === 'absent')
+        return { reason: 'nothing there' };
+    const others = change.keepIfSameAs?.() ?? [];
+    // The target's own refusal throws; only an OTHER entry's refusal is `unknown`, a keep.
+    if (others.length > 0)
+        facts.requireExaminable(change.dest);
+    for (const other of others) {
+        const verdict = facts.sameEntry(change.dest, other);
+        if (verdict === 'same')
+            return { reason: `${other} is the same entry` };
+        if (verdict === 'unknown') {
+            const reason = `could not tell whether ${other} is the same entry`;
+            return facts.refusesToExamine(other) ? { reason, unexaminedSibling: other } : { reason };
+        }
+    }
+    return undefined;
+}
+/** The kept entry `planned` (a remove) holds, or may hold: removing it would take that entry with it. */
+function heldKeep(planned, all, facts) {
+    if (planned.action !== 'remove')
+        return undefined;
+    return all.find((other) => other !== planned && other.action === 'keep' && other.existing !== 'absent' && facts.isInside(other.change.dest, planned.change.dest) !== 'outside');
+}
+/**
+ * Keep every remove that holds — or cannot be proven not to hold — a kept entry: a
+ * kept entry is kept whole, never taken away with a directory above it. Repeated until
+ * nothing changes, so a remove holding one that was just kept is kept as well.
+ */
+function keepingHolders(planned, facts) {
+    const next = planned.map((each) => {
+        const held = heldKeep(each, planned, facts);
+        return held === undefined ? each : { ...each, action: 'keep', reason: `holds ${held.change.dest}, which is kept` };
+    });
+    return next.some((each, index) => each !== planned[index]) ? keepingHolders(next, facts) : planned;
+}
+function initialAction(change, existing) {
+    if (change.op === 'remove')
+        return 'remove';
+    return existing === 'absent' ? 'create' : 'replace';
+}
+/** Whether `other` takes `change`'s destination with it: the same entry as a replace or an earlier remove, or an ancestor of it. */
+function subsumes(change, index, other, otherIndex, facts) {
+    if (otherIndex === index || other.action === 'keep' || other.existing === 'absent')
+        return false;
+    const sameAllowed = other.change.op !== 'remove' || otherIndex < index;
+    if (sameAllowed && facts.sameEntry(change.change.dest, other.change.dest) === 'same')
+        return true;
+    return facts.isInside(change.change.dest, other.change.dest) === 'inside';
+}
+function withSubsumption(planned, index, all, facts) {
+    if (planned.action !== 'remove')
+        return planned;
+    const by = all.find((other, otherIndex) => subsumes(planned, index, other, otherIndex, facts));
+    return by === undefined ? planned : { ...planned, action: 'subsumed', reason: `parked by ${by.change.op} ${by.change.label}` };
+}
+/** Whether a planned change touches its destination (`keep` and `subsumed` do not). */
+export const isActive = ({ action }) => action === 'create' || action === 'replace' || action === 'remove';
+/**
+ * Whether `inner`'s destination is `outer`'s or lies under it. Judged by identity where `outer`
+ * exists; an absent destination has no identity, so there it is judged by the spelling.
+ */
+function holds(outer, inner, facts) {
+    if (outer.existing === 'absent')
+        return !relativeEscapesRoot(safePath.relative(outer.change.dest, inner.change.dest));
+    return facts.sameEntry(inner.change.dest, outer.change.dest) === 'same' || facts.isInside(inner.change.dest, outer.change.dest) === 'inside';
+}
+/** Refuse two active changes over one tree: the plan is the calling verb's defect. `unknown` is never proof. */
+function checkOverlap(planned, facts) {
+    const active = planned.filter((each) => isActive(each));
+    for (const [index, first] of active.entries()) {
+        const second = active.slice(index + 1).find((other) => holds(first, other, facts) || holds(other, first, facts));
+        if (second !== undefined) {
+            throw refusal(TREE_DESTS_OVERLAP_CODE, `${first.change.label} (${first.change.dest}) and ${second.change.label} (${second.change.dest}) change one tree; a plan may not overlap its own destinations`);
+        }
+    }
+}
+/**
+ * Refuse a FILE change whose destination is a directory, or a link to one — under every ownership,
+ * `force` included: `--force` means "overwrite the file", and a file landing on a directory's name
+ * would park the whole tree and delete it.
+ */
+function checkFileOverDirectory({ change, existing }, facts) {
+    if (change.op !== 'replace-file')
+        return;
+    const { dest, label } = change;
+    if (existing === 'directory') {
+        throw refusal(TREE_DEST_OCCUPIED_CODE, `${label}: ${dest} is a directory; a file is never written over a directory`);
+    }
+    if (existing === 'link' && facts.linksToDirectory(dest)) {
+        throw refusal(TREE_DEST_OCCUPIED_CODE, `${label}: ${dest} is a link to a directory; a file is never written over a directory`);
+    }
+}
+/** Refuse a destination its ownership does not let this change take. */
+function checkOwnership(planned, facts) {
+    const { change, existing, action } = planned;
+    if (existing === 'absent' || action === 'keep' || action === 'subsumed')
+        return;
+    checkFileOverDirectory(planned, facts);
+    const { ownership, dest, label } = change;
+    // An empty directory is free for a tree that lands in its place, never for a FILE: a file
+    // replacing a directory the user made (a folder they named as an output) is a surprise, not a fill.
+    const freeDirectory = change.op !== 'replace-file' && existing === 'directory' && facts.isEmptyDirectory(dest);
+    // The refusal says what this change would have done to the destination.
+    const verb = change.op === 'remove' ? 'remove' : 'replace';
+    if (ownership.kind === 'must-be-free' && !freeDirectory) {
+        throw refusal(TREE_DEST_OCCUPIED_CODE, `${label}: ${dest} already holds something (a ${existing}); refusing to ${verb} it`);
+    }
+    if (ownership.kind === 'vat-made') {
+        const verdict = ownership.recognise(dest);
+        if (!verdict.owned)
+            throw refusal(TREE_DEST_NOT_OWNED_CODE, `${label}: refusing to ${verb} ${dest}: ${verdict.reason}`);
+    }
+}
+/** The inputs a replace reads, which its destination must neither be, hold, nor lie inside. */
+function readsOf(change) {
+    if (change.op !== 'replace')
+        return [];
+    if (change.fill.from === 'copy')
+        return [change.fill.source];
+    return change.fill.from === 'write' ? change.fill.reads ?? [] : [];
+}
+function checkHolding(planned, facts) {
+    if (planned.action !== 'create' && planned.action !== 'replace')
+        return;
+    const { dest, label } = planned.change;
+    // A destination that is a LINK holds nothing: the replace parks the link itself, never what it points
+    // at — so a source the link leads to (a `--dev` link to the build being installed) is not lost with it.
+    const destHoldsEntries = planned.existing !== 'link';
+    for (const source of readsOf(planned.change)) {
+        if (destHoldsEntries && (facts.sameEntry(source, dest) === 'same' || facts.isInside(source, dest) === 'inside')) {
+            throw refusal(TREE_DEST_HOLDS_SOURCE_CODE, `${label}: ${source} is ${dest} or lies inside it, so replacing ${dest} would delete it`);
+        }
+        if (facts.isInside(dest, source) === 'inside') {
+            throw refusal(TREE_SOURCE_HOLDS_DEST_CODE, `${label}: ${dest} lies inside ${source}, which it is made from`);
+        }
+    }
+}
+function describeChange({ change, action, reason }) {
+    const line = `${action} ${change.label} ${change.dest}`;
+    return reason === undefined ? line : `${line} (${reason})`;
+}
+/**
+ * The pure planner: every decision of {@link planTreeChanges} but the source
+ * proof, made from `facts`.
+ *
+ * @throws VatError coded `TREE_DESTS_OVERLAP` (a defect in the caller's plan), `TREE_DEST_OCCUPIED`,
+ *   `TREE_DEST_NOT_OWNED`, `TREE_DEST_HOLDS_SOURCE` or `TREE_SOURCE_HOLDS_DEST`; whatever `facts` throws
+ */
+export function planFromFacts(changes, facts) {
+    const drafted = changes.map((change) => {
+        const existing = facts.existing(change.dest);
+        const kept = keepReason(change, existing, facts);
+        return kept === undefined ? { change, existing, action: initialAction(change, existing) } : { change, existing, action: 'keep', ...kept };
+    });
+    const kept = keepingHolders(drafted, facts);
+    const planned = kept.map((draft, index) => withSubsumption(draft, index, kept, facts));
+    checkOverlap(planned, facts);
+    for (const each of planned)
+        checkOwnership(each, facts);
+    for (const each of planned)
+        checkHolding(each, facts);
+    return { changes: planned, describe: () => planned.map((each) => describeChange(each)) };
+}
+const EXAMINE_DEST = { side: 'destination', action: 'examine the destination' };
+function kindOf(dest) {
+    let stats;
+    try {
+        stats = lstatSync(dest);
+    }
+    catch (error) {
+        if (!isPathAbsentError(error))
+            throw classifyFsFault(error, { ...EXAMINE_DEST, path: dest });
+        // Absent only when the parent's listing agrees: a refused probe of an entry that is there is a fault.
+        requireConfirmedAbsent(dest, error, { action: EXAMINE_DEST.action, path: dest }, { follows: false, sideOf: everywhere(EXAMINE_DEST.side) });
+        return 'absent';
+    }
+    if (stats.isSymbolicLink())
+        return 'link';
+    if (stats.isDirectory())
+        return 'directory';
+    return stats.isFile() ? 'file' : 'special';
+}
+/** Whether the link at `dest` leads to a directory: a dangling link leads nowhere; a target the OS refuses to examine is a fault. */
+function linksToDirectory(dest) {
+    try {
+        // `dest` is the destination the verb names: the operator's own path, its own link the edge.
+        return followedStatSync(dest, dest)?.isDirectory() ?? false;
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return false;
+        throw classifyFsFault(error, { ...EXAMINE_DEST, path: dest });
+    }
+}
+/**
+ * What is at `dest` NOW, for the apply to hold against what the plan decided
+ * (`changedSincePlan`). The emptiness of a directory is read only where the plan took it as free.
+ *
+ * @throws FsFaultError side `destination` when the OS refuses to examine or list it
+ */
+export function destinationNow(dest, planned) {
+    const kind = kindOf(dest);
+    const askEmpty = kind === 'directory' && planned.existing === 'directory' && planned.change.ownership.kind === 'must-be-free';
+    return { kind, emptyDirectory: askEmpty && withFsFaultSync({ side: 'destination', action: 'list the destination', path: dest }, () => readdirSync(dest).length === 0) };
+}
+/** The live facts of one plan: every identity question asks each entry once, so no two decisions see the filesystem differently. */
+function liveFacts() {
+    const oracle = identityOracle();
+    return {
+        existing: kindOf,
+        isEmptyDirectory: (dest) => withFsFaultSync({ side: 'destination', action: 'list the destination', path: dest }, () => readdirSync(dest).length === 0),
+        linksToDirectory,
+        sameEntry: oracle.sameEntry,
+        isInside: oracle.isInside,
+        requireExaminable: (dest) => {
+            oracle.identities(dest);
+        },
+        refusesToExamine: (entry) => oracle.refuses(entry),
+    };
+}
+/** Prove a copy source readable, as the copy will read it. */
+function proveSource({ change, action }) {
+    if (change.op !== 'replace' || change.fill.from !== 'copy' || (action !== 'create' && action !== 'replace'))
+        return Promise.resolve();
+    const { source, links, side, filter } = change.fill;
+    return proveTreeReadable(source, { links, side, ...(filter === undefined ? {} : { filter }) });
+}
+/**
+ * Decide every change against the filesystem as it is, with no side effect. Each
+ * destination is taken in its canonical spelling (`safePath.resolve`: absolute,
+ * `.`/`..` resolved, forward slashes); `describe()` prints that spelling.
+ * Hand the result to `applyTreePlan`; print `describe()` for a dry run — the two
+ * cannot disagree, because the apply does exactly what the plan says.
+ *
+ * @param changes - What the verb wants, in the order it wants it
+ * @throws VatError coded `TREE_DEST_OCCUPIED`, `TREE_DEST_NOT_OWNED`,
+ *   `TREE_DEST_HOLDS_SOURCE` or `TREE_SOURCE_HOLDS_DEST`; `FsFaultError` side
+ *   `destination` for a destination the OS refuses to examine, on the fill's
+ *   declared side for a copy source it refuses to read
+ */
+export async function planTreeChanges(changes) {
+    // One canonical spelling of every destination (absolute, normalized, forward slashes), which the
+    // plan, the dry run and the apply — down to the parents a create makes and removes — all use.
+    const canonical = changes.map((change) => ({ ...change, dest: safePath.resolve(change.dest) }));
+    const plan = planFromFacts(canonical, liveFacts());
+    await forEachInOrder(plan.changes, proveSource);
+    return plan;
+}
+//# sourceMappingURL=plan.js.map

package/dist/tree-change/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/tree-change/plan.ts"],"names":[],"mappings":"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"}

package/dist/tree-change/readable-tree.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The readable-tree proof: before a verb writes anything for a tree it is about to
+ * read whole, it proves every entry readable, so an unreadable input is refused as
+ * the input it is rather than surfacing half-way through as an output failure.
+ */
+import type { FsSide } from '../errors/fs-fault.js';
+import { type TreeWalkOptions } from './tree-walk.js';
+/** What {@link proveTreeReadable} is told: the walk's link policy and filter, and the side its faults are on. */
+export interface ProveTreeReadableOptions extends TreeWalkOptions {
+    /**
+     * The side of the verb the tree is on: an input (`source`), VAT's staging
+     * (`environment`), or a copy already made into user state (`destination`).
+     */
+    readonly side: FsSide;
+}
+/**
+ * Prove the directory `root` readable: every directory listed, every regular file
+ * opened without blocking and judged by `fstat` on that handle, each entry held to
+ * the one special-file and link policy `copyTree` copies by (see `tree-walk.ts`).
+ * A root that is not a directory is refused by its listing (`ENOTDIR`), as
+ * `copyTree` refuses it. Each file is opened, never `access`ed: on Windows `access`
+ * does not consult ACLs.
+ *
+ * @param root - The directory the caller is about to read
+ * @param options - `links` and `filter` as the read will use them, and the `side` the tree is on
+ * @throws FsFaultError on `options.side` (origin `content`) naming the first entry
+ *   the OS refused, in listing order — a named pipe, socket or device as class
+ *   `wrong-type`; `CopyLinkEscapesSourceError` / `DirectoryWalkRevisitedError` for
+ *   a link out of, or back into, a `follow-contained` tree
+ */
+export declare function proveTreeReadable(root: string, options: ProveTreeReadableOptions): Promise<void>;
+/**
+ * Read a regular file whole, through a handle opened without blocking and judged
+ * by `fstat` on that handle: a named pipe, socket or device is refused before a
+ * byte is read, never waited on.
+ *
+ * @param path - The file to read
+ * @returns Its bytes
+ * @throws an `EFTYPE` errno for a special file, `EISDIR` for a directory, and
+ *   whatever `open` / `read` throw otherwise — raw, for the caller to classify on
+ *   the side it knows the file is on
+ */
+export declare function readRegularFile(path: string): Promise<Buffer>;
+//# sourceMappingURL=readable-tree.d.ts.map

package/dist/tree-change/readable-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readable-tree.d.ts","sourceRoot":"","sources":["../../src/tree-change/readable-tree.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGpD,OAAO,EAAoB,KAAK,eAAe,EAAY,MAAM,gBAAgB,CAAC;AAElF,iHAAiH;AACjH,MAAM,WAAW,wBAAyB,SAAQ,eAAe;IAC/D;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtG;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnE"}

package/dist/tree-change/readable-tree.js

@@ -0,0 +1,52 @@
+/**
+ * The readable-tree proof: before a verb writes anything for a tree it is about to
+ * read whole, it proves every entry readable, so an unreadable input is refused as
+ * the input it is rather than surfacing half-way through as an output failure.
+ */
+import { openForReading } from '../text-file.js';
+import { walkTree } from './tree-walk.js';
+/** Proving reads nothing past the open: the open, the `fstat` and the listing are the proof. */
+const PROVE = {
+    directory: () => Promise.resolve(),
+    file: () => Promise.resolve(),
+    link: () => Promise.resolve(),
+};
+/**
+ * Prove the directory `root` readable: every directory listed, every regular file
+ * opened without blocking and judged by `fstat` on that handle, each entry held to
+ * the one special-file and link policy `copyTree` copies by (see `tree-walk.ts`).
+ * A root that is not a directory is refused by its listing (`ENOTDIR`), as
+ * `copyTree` refuses it. Each file is opened, never `access`ed: on Windows `access`
+ * does not consult ACLs.
+ *
+ * @param root - The directory the caller is about to read
+ * @param options - `links` and `filter` as the read will use them, and the `side` the tree is on
+ * @throws FsFaultError on `options.side` (origin `content`) naming the first entry
+ *   the OS refused, in listing order — a named pipe, socket or device as class
+ *   `wrong-type`; `CopyLinkEscapesSourceError` / `DirectoryWalkRevisitedError` for
+ *   a link out of, or back into, a `follow-contained` tree
+ */
+export async function proveTreeReadable(root, options) {
+    await walkTree(root, options, options.side, PROVE);
+}
+/**
+ * Read a regular file whole, through a handle opened without blocking and judged
+ * by `fstat` on that handle: a named pipe, socket or device is refused before a
+ * byte is read, never waited on.
+ *
+ * @param path - The file to read
+ * @returns Its bytes
+ * @throws an `EFTYPE` errno for a special file, `EISDIR` for a directory, and
+ *   whatever `open` / `read` throw otherwise — raw, for the caller to classify on
+ *   the side it knows the file is on
+ */
+export async function readRegularFile(path) {
+    const handle = await openForReading(path);
+    try {
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+//# sourceMappingURL=readable-tree.js.map

package/dist/tree-change/readable-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readable-tree.js","sourceRoot":"","sources":["../../src/tree-change/readable-tree.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAA0C,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAWlF,gGAAgG;AAChG,MAAM,KAAK,GAAgB;IACzB,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE;IAClC,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE;IAC7B,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY,EAAE,OAAiC;IACrF,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY;IAChD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC;QACH,OAAO,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/tree-change/rollback-error.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The one shape of a change that failed and could not be fully undone. Pure: it only words
+ * what the rollback found.
+ */
+import { VatError } from '../errors/vat-error.js';
+/** A failed change that could not be fully undone: a previous entry not back at its destination, or a new one not off it. */
+export declare const TREE_ROLLBACK_INCOMPLETE_CODE = "TREE_ROLLBACK_INCOMPLETE";
+/** One destination a rollback could not restore: where its previous entry is, if it had one, and why. */
+export interface TreeRollbackStranded {
+    readonly dest: string;
+    readonly parked: string | undefined;
+    readonly why: string;
+}
+/**
+ * A change failed, and the rollback could not undo all of it: each previous entry
+ * not back at its destination is under its parked name, never deleted; a create's
+ * new entry — or a rewritten file's new content — may still be at its destination.
+ * `cause` is the failure that started the rollback. The one shape of
+ * {@link TREE_ROLLBACK_INCOMPLETE_CODE}: a caller that undoes writes of its own (a
+ * registry edit run as `afterSwap`) throws it too, its entries with no `parked`.
+ */
+export declare class TreeRollbackIncompleteError extends VatError {
+    /** Where each previous entry that is not at its destination now is. */
+    readonly parked: readonly string[];
+    /** Every destination the rollback could not restore. */
+    readonly stranded: readonly TreeRollbackStranded[];
+    constructor(original: unknown, stranded: readonly TreeRollbackStranded[]);
+}
+//# sourceMappingURL=rollback-error.d.ts.map

package/dist/tree-change/rollback-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback-error.d.ts","sourceRoot":"","sources":["../../src/tree-change/rollback-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,6HAA6H;AAC7H,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE,yGAAyG;AACzG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;GAOG;AACH,qBAAa,2BAA4B,SAAQ,QAAQ;IACvD,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;gBAEvC,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,oBAAoB,EAAE;CAMzE"}

package/dist/tree-change/rollback-error.js

@@ -0,0 +1,31 @@
+/**
+ * The one shape of a change that failed and could not be fully undone. Pure: it only words
+ * what the rollback found.
+ */
+import { VatError } from '../errors/vat-error.js';
+/** A failed change that could not be fully undone: a previous entry not back at its destination, or a new one not off it. */
+export const TREE_ROLLBACK_INCOMPLETE_CODE = 'TREE_ROLLBACK_INCOMPLETE';
+function strandedSentence({ dest, parked, why }) {
+    return parked === undefined ? `the new content at ${dest} could not be undone (${why})` : `the previous content of ${dest} is at ${parked} (${why})`;
+}
+/**
+ * A change failed, and the rollback could not undo all of it: each previous entry
+ * not back at its destination is under its parked name, never deleted; a create's
+ * new entry — or a rewritten file's new content — may still be at its destination.
+ * `cause` is the failure that started the rollback. The one shape of
+ * {@link TREE_ROLLBACK_INCOMPLETE_CODE}: a caller that undoes writes of its own (a
+ * registry edit run as `afterSwap`) throws it too, its entries with no `parked`.
+ */
+export class TreeRollbackIncompleteError extends VatError {
+    /** Where each previous entry that is not at its destination now is. */
+    parked;
+    /** Every destination the rollback could not restore. */
+    stranded;
+    constructor(original, stranded) {
+        const where = stranded.map((s) => strandedSentence(s)).join('; ');
+        super(TREE_ROLLBACK_INCOMPLETE_CODE, `${original instanceof Error ? original.message : String(original)}; and the change could not be undone: ${where}`, { cause: original });
+        this.parked = stranded.flatMap((s) => (s.parked === undefined ? [] : [s.parked]));
+        this.stranded = stranded;
+    }
+}
+//# sourceMappingURL=rollback-error.js.map

package/dist/tree-change/rollback-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback-error.js","sourceRoot":"","sources":["../../src/tree-change/rollback-error.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,6HAA6H;AAC7H,MAAM,CAAC,MAAM,6BAA6B,GAAG,0BAA0B,CAAC;AASxE,SAAS,gBAAgB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAwB;IACnE,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,sBAAsB,IAAI,yBAAyB,GAAG,GAAG,CAAC,CAAC,CAAC,2BAA2B,IAAI,UAAU,MAAM,KAAK,GAAG,GAAG,CAAC;AACvJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,2BAA4B,SAAQ,QAAQ;IACvD,uEAAuE;IAC9D,MAAM,CAAoB;IACnC,wDAAwD;IAC/C,QAAQ,CAAkC;IAEnD,YAAY,QAAiB,EAAE,QAAyC;QACtE,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClE,KAAK,CAAC,6BAA6B,EAAE,GAAG,QAAQ,YAAY,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,yCAAyC,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC9K,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAClF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF"}

package/dist/tree-change/staging-names.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The names the tree-change primitive gives what it stages, parks and discards beside a
+ * destination, and the two questions a listing asks of a name. Pure: no filesystem call.
+ */
+/** What a previous entry is renamed to while its replacement goes in: `<staged>.previous`. */
+export declare const PARKED_SUFFIX = ".previous";
+/**
+ * Whether a directory entry is the primitive's own: a staged tree, a parked
+ * previous one, or a discarded one, left beside a destination by a crash or by a
+ * removal the OS refused (`.<base>.vat-staged-<random>[.previous]`). A listing of
+ * the directory a change sits in must never read one as a sibling it holds.
+ *
+ * @param name - A directory entry's name
+ */
+export declare function isTreeChangeResidue(name: string): boolean;
+/**
+ * Whether a directory entry is a PARKED previous entry: the one residue that is safe to sweep, since a
+ * staged entry may be another process's change still in flight.
+ *
+ * @param name - A directory entry's name
+ */
+export declare function isParkedTreeEntry(name: string): boolean;
+/** The `mkdtemp` prefix of a staged tree beside `dest`. */
+export declare function stagingPrefix(dest: string): string;
+/** A fresh staging name beside `dest`, for an entry `mkdtemp` does not make: a file, a link, or a `write` fill's directory (made with the caller's mode). */
+export declare function stagingName(dest: string): string;
+//# sourceMappingURL=staging-names.d.ts.map

package/dist/tree-change/staging-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging-names.d.ts","sourceRoot":"","sources":["../../src/tree-change/staging-names.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,8FAA8F;AAC9F,eAAO,MAAM,aAAa,cAAc,CAAC;AAEzC;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,6JAA6J;AAC7J,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/tree-change/staging-names.js

@@ -0,0 +1,40 @@
+/**
+ * The names the tree-change primitive gives what it stages, parks and discards beside a
+ * destination, and the two questions a listing asks of a name. Pure: no filesystem call.
+ */
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { safePath } from '../path-core.js';
+/** Every staged, parked or discarded entry is named `.<base>.vat-staged-<random>[suffix]` beside the destination. */
+const STAGED_INFIX = '.vat-staged-';
+/** What a previous entry is renamed to while its replacement goes in: `<staged>.previous`. */
+export const PARKED_SUFFIX = '.previous';
+/**
+ * Whether a directory entry is the primitive's own: a staged tree, a parked
+ * previous one, or a discarded one, left beside a destination by a crash or by a
+ * removal the OS refused (`.<base>.vat-staged-<random>[.previous]`). A listing of
+ * the directory a change sits in must never read one as a sibling it holds.
+ *
+ * @param name - A directory entry's name
+ */
+export function isTreeChangeResidue(name) {
+    return name.startsWith('.') && name.includes(STAGED_INFIX);
+}
+/**
+ * Whether a directory entry is a PARKED previous entry: the one residue that is safe to sweep, since a
+ * staged entry may be another process's change still in flight.
+ *
+ * @param name - A directory entry's name
+ */
+export function isParkedTreeEntry(name) {
+    return isTreeChangeResidue(name) && name.endsWith(PARKED_SUFFIX);
+}
+/** The `mkdtemp` prefix of a staged tree beside `dest`. */
+export function stagingPrefix(dest) {
+    return safePath.join(path.dirname(dest), `.${path.basename(dest)}${STAGED_INFIX}`);
+}
+/** A fresh staging name beside `dest`, for an entry `mkdtemp` does not make: a file, a link, or a `write` fill's directory (made with the caller's mode). */
+export function stagingName(dest) {
+    return `${stagingPrefix(dest)}${randomBytes(4).toString('hex')}`;
+}
+//# sourceMappingURL=staging-names.js.map

package/dist/tree-change/staging-names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staging-names.js","sourceRoot":"","sources":["../../src/tree-change/staging-names.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3C,qHAAqH;AACrH,MAAM,YAAY,GAAG,cAAc,CAAC;AAEpC,8FAA8F;AAC9F,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,mBAAmB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;AACnE,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,YAAY,EAAE,CAAC,CAAC;AACrF,CAAC;AAED,6JAA6J;AAC7J,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;AACnE,CAAC"}