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

package/dist/tree-change/apply.js

@@ -0,0 +1,364 @@
+/**
+ * The apply half of the tree-change primitive: carry out a {@link TreePlan} as one
+ * transaction, in a fixed order —
+ *
+ * 1. **Stage** every new entry beside its destination, on the same filesystem (so
+ *    a swap never crosses devices): a `mkdtemp` directory filled by `copyTree`, a
+ *    fresh directory (plain `mkdir`, the caller's mode) filled by the `write`
+ *    callback, or a fresh name for a file or a link. A failure removes
+ *    every staged entry, and every parent directory a create made; no destination
+ *    has changed.
+ * 2. **Park** every entry being replaced or removed: `rename(dest, <staged>.previous)`.
+ *    Every park happens before any swap, so a name is free before anything lands
+ *    on it — on a case-folding filesystem `Old` and `old` are one name. Each
+ *    destination is examined again first: one that is no longer what the plan decided
+ *    on (another writer filled a directory the plan took as empty, or put an entry
+ *    where it found none) is a `destination` fault, class `occupied`, and is left as
+ *    found — the plan is rolled back.
+ * 3. **Swap** every staged entry in: `rename(staged, dest)`.
+ * 4. **`afterSwap()`** — the caller's own writes that must agree with the tree
+ *    (a registry). A throw rolls back every swap.
+ * 5. **Rollback**, when 2–4 throw: in reverse, each swapped entry is moved off its
+ *    destination and its parked entry renamed back, then the parents a create made
+ *    are removed. A parked entry is NEVER deleted on a failure path: if one cannot
+ *    be put back — or a create's new entry cannot be moved off — the error is
+ *    {@link TreeRollbackIncompleteError}, naming each.
+ * 6. **Finalize**: each parked entry is removed, its modes notwithstanding. For a
+ *    replace a refusal is only a warning ({@link TREE_CLEANUP_INCOMPLETE_CODE}): the
+ *    new tree is live. For a remove, removal is the job, so it is a `destination`
+ *    fault naming the parked path — the data is already off the user's path.
+ *
+ * Every rename is {@link renameFileAtomic}'s, retried under win32 on contention.
+ * The primitive's own filesystem faults are classified `destination` (staging sits
+ * beside the user's destination); a `copy` source's read is already classified on
+ * the fill's declared side; a
+ * `write` fill's raw errno is `destination` only when it names a path under the
+ * destination's parent — anything else (an input the callback read) is rethrown
+ * raw, for the verb's boundary to classify.
+ *
+ * A thrown failure is never mutated. What a failure path could not clean up (a
+ * staged entry, a parent, a replaced tree beside a failed remove) is recorded
+ * beside it, off its cause chain: `suppressedFaultsOf(error)`.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fsFaultOf, isAlreadyExistsError, isOccupiedError } from '../errors/errno-table.js';
+import { fsBoundary } from '../errors/fs-boundary.js';
+import { classifyFsFault, isFsFaultError, withFsFault } from '../errors/fs-fault.js';
+import { recordSuppressedFault } from '../errors/suppressed-faults.js';
+import { isVatError } from '../errors/vat-error.js';
+import { forEachInOrder, mapInOrder } from '../in-order.js';
+import { safePath, toForwardSlash } from '../path-core.js';
+import { withoutWin32Namespace } from '../win32-namespace.js';
+import { changedDestinationFault, changedSincePlan, fillFaultIsDestinations, finalizeThrows, madeParentStep, TREE_CLEANUP_INCOMPLETE_CODE } from './apply-decisions.js';
+import { copyTree } from './copy-tree.js';
+import { removeEntry, renameFileAtomic } from './files.js';
+import { sameEntry } from './identity.js';
+import { destinationNow, isActive } from './plan.js';
+import { TreeRollbackIncompleteError } from './rollback-error.js';
+import { PARKED_SUFFIX, stagingName, stagingPrefix } from './staging-names.js';
+export { TREE_CLEANUP_INCOMPLETE_CODE } from './apply-decisions.js';
+/** Suffix of a swapped-in entry moved back off its destination by a rollback. */
+const DISCARD_SUFFIX = '.discard';
+const destOf = (slot) => slot.planned.change.dest;
+const labelOf = (slot) => slot.planned.change.label;
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+/** Run `work` for `slot`, a raw errno classified `destination` with `action`. */
+function onDestination(slot, action, work) {
+    return withFsFault({ side: 'destination', action: `${action} ${labelOf(slot)}`, path: destOf(slot) }, work);
+}
+/**
+ * A `write` fill's failure: a raw errno naming a path under the staged tree — all the
+ * callback may write — is the destination's; anything else, an input the callback read
+ * (a sibling of the destination included), is rethrown as it was, for the verb's
+ * boundary to classify.
+ */
+function writeFillFault(error, slot, staged) {
+    const facts = fsFaultOf(error);
+    if (isVatError(error) || facts === undefined)
+        return error;
+    const ours = fsBoundary({ destination: [staged] });
+    if (!fillFaultIsDestinations(facts, (named) => ours.sideOf(named)))
+        return error;
+    return classifyFsFault(error, { side: 'destination', action: `stage the new ${labelOf(slot)}`, path: destOf(slot) });
+}
+/** The parent of the destination, made when absent; the first directory made is remembered. */
+async function makeParent(slot) {
+    const made = await onDestination(slot, 'make the parent directory of', () => fs.mkdir(path.dirname(destOf(slot)), { recursive: true }));
+    slot.createdParent = made === undefined ? undefined : toForwardSlash(withoutWin32Namespace(made));
+}
+/** How many fresh names a `write` fill tries before an `EEXIST` is the answer (as `mkdtemp` retries its own). */
+const STAGING_NAME_TRIES = 8;
+/** The staged directory beside `dest`: `mkdtemp` for a copy, a plain `mkdir` of a fresh name for a `write` (see {@link stageTree}). */
+async function makeStagedDirectory(dest, from, attempt = 1) {
+    if (from === 'copy')
+        return fs.mkdtemp(stagingPrefix(dest));
+    const name = stagingName(dest);
+    try {
+        await fs.mkdir(name);
+        return name;
+    }
+    catch (error) {
+        // A collision with a leftover of the same random name: draw another, as `mkdtemp` does.
+        if (!isAlreadyExistsError(error) || attempt >= STAGING_NAME_TRIES)
+            throw error;
+        return makeStagedDirectory(dest, from, attempt + 1);
+    }
+}
+/**
+ * Stage a directory tree beside the destination, filled by the copy or the caller's `write`. A copy
+ * stages in a `mkdtemp` directory (the copy gives it its source's mode). A `write` stages in a fresh
+ * name made by a plain `mkdir`, so the tree it becomes gets the mode any directory the caller makes
+ * gets — never a temp directory's 0700 (`dist/skills`, a marketplace). The name is as unique: a
+ * collision is `EEXIST`, never a shared directory.
+ */
+async function stageTree(slot, fill) {
+    const staged = toForwardSlash(await onDestination(slot, 'stage the new', () => makeStagedDirectory(destOf(slot), fill.from)));
+    slot.staged = staged;
+    if (fill.from === 'copy') {
+        await onDestination(slot, 'copy the new', () => copyTree(fill.source, staged, '', { links: fill.links, side: fill.side, onto: 'fresh', ...(fill.filter === undefined ? {} : { filter: fill.filter }) }));
+    }
+    else if (fill.from === 'write') {
+        // `try`/`await`, not `.catch`: a callback that throws synchronously is judged the same way.
+        try {
+            await fill.write(staged);
+        }
+        catch (error) {
+            throw writeFillFault(error, slot, staged);
+        }
+    }
+}
+/** Make the new entry beside the destination. */
+async function stage(slot) {
+    const { change } = slot.planned;
+    if (change.op === 'remove')
+        return;
+    await makeParent(slot);
+    if (change.op === 'replace-file') {
+        const staged = stagingName(change.dest);
+        slot.staged = staged;
+        const { contents } = change;
+        await onDestination(slot, 'stage the new', () => fs.writeFile(staged, typeof contents === 'function' ? contents() : contents, { flag: 'wx' }));
+        return;
+    }
+    if (change.fill.from !== 'link') {
+        await stageTree(slot, change.fill);
+        return;
+    }
+    const staged = stagingName(change.dest);
+    slot.staged = staged;
+    const { target } = change.fill;
+    // `dir`: parity with today's `--dev` lanes, both of which refuse win32 before staging. Should a win32
+    // `--dev` lane ever exist, the repo's precedent is `junction` (dev-tools `link-workspace-packages.ts`),
+    // which needs no symlink privilege.
+    await onDestination(slot, 'stage the link for', () => fs.symlink(target, staged, 'dir'));
+}
+/**
+ * The name `dest` has on disk. On a case-folding filesystem a plan may spell a
+ * destination `plugins/old` while the directory is `plugins/Old`: a rollback must
+ * put it back as `Old`. When the parent lists `dest`'s own name, that is it (two
+ * names one fold apart cannot both exist); otherwise the sibling that is the same
+ * entry, judged by identity, never by comparing names.
+ */
+async function spelledOnDisk(dest) {
+    const parent = path.dirname(dest);
+    const names = await fs.readdir(parent);
+    if (names.includes(toForwardSlash(path.basename(dest))))
+        return dest;
+    const alias = names.find((name) => sameEntry(safePath.join(parent, name), dest) === 'same');
+    return alias === undefined ? dest : safePath.join(parent, alias);
+}
+/**
+ * Refuse a destination that is no longer what the plan decided on (`changedSincePlan`): staging runs
+ * between the plan and the first rename, and a `must-be-free` destination another writer filled
+ * meanwhile must not be parked and deleted, nor a file that appeared at a `create` renamed over.
+ * Asked immediately before the rename it guards; the entry is left exactly as found.
+ */
+function requireAsPlanned(slot) {
+    const changed = changedSincePlan(slot.planned, destinationNow(destOf(slot), slot.planned));
+    if (changed !== undefined)
+        throw changedDestinationFault(slot.planned, changed);
+}
+async function park(slot) {
+    requireAsPlanned(slot);
+    const parked = `${slot.staged ?? stagingName(destOf(slot))}${PARKED_SUFFIX}`;
+    await onDestination(slot, 'move aside the previous', async () => {
+        slot.spelled = await spelledOnDisk(destOf(slot));
+        await renameFileAtomic(destOf(slot), parked);
+    });
+    slot.parked = parked;
+}
+async function swap(slot) {
+    // A destination the plan found absent was never parked: nothing has vouched for it since the plan.
+    if (slot.planned.existing === 'absent')
+        requireAsPlanned(slot);
+    const staged = slot.staged;
+    await onDestination(slot, 'put in place the new', () => renameFileAtomic(staged, destOf(slot)));
+    slot.swapped = true;
+}
+/** Remove `entry`, VAT's own leftover; a refusal is recorded beside `error`, never thrown over it. */
+async function discard(entry, error) {
+    if (entry === undefined)
+        return;
+    try {
+        await removeEntry(entry);
+    }
+    catch (error_) {
+        recordSuppressedFault(error, classifyFsFault(error_, { side: 'destination', action: `remove the staged ${entry}`, path: entry }));
+    }
+}
+/**
+ * Remove, deepest first, the empty parents staging made for `slot`: from the
+ * destination's parent up to the first directory `mkdir` made, never past it — both
+ * in the canonical spelling, bounded by containment, not by comparing strings. A
+ * parent still holding entries (another change's, stranded) is left without a
+ * word; one the OS refuses is recorded beside `error`.
+ */
+function removeMadeParents(slot, error) {
+    if (slot.createdParent === undefined)
+        return Promise.resolve();
+    const top = safePath.resolve(slot.createdParent);
+    const removeFrom = (dir) => {
+        const step = madeParentStep(top, dir);
+        if (step === 'stop')
+            return Promise.resolve();
+        return fs.rmdir(dir).then(() => (step === 'last' ? undefined : removeFrom(safePath.resolve(path.dirname(dir)))), (error_) => {
+            if (isOccupiedError(error_))
+                return;
+            recordSuppressedFault(error, classifyFsFault(error_, { side: 'destination', action: 'remove the directory made for', path: dir }));
+        });
+    };
+    return removeFrom(safePath.resolve(path.dirname(destOf(slot))));
+}
+/** Move a swapped-in entry back off its destination, to be discarded. What could not move is returned. */
+async function unswap(slot) {
+    const discarded = `${slot.staged}${DISCARD_SUFFIX}`;
+    try {
+        await renameFileAtomic(destOf(slot), discarded);
+        slot.staged = discarded;
+        return undefined;
+    }
+    catch (error_) {
+        return { dest: destOf(slot), parked: slot.parked, why: `the new content could not be moved off it: ${messageOf(error_)}` };
+    }
+}
+/** Undo one slot: the new entry off the destination, the previous one back on. What could not be undone is returned. */
+async function restore(slot, error) {
+    const stuck = slot.swapped ? await unswap(slot) : undefined;
+    if (stuck !== undefined)
+        return stuck;
+    await discard(slot.staged, error);
+    if (slot.parked === undefined)
+        return undefined;
+    try {
+        await renameFileAtomic(slot.parked, slot.spelled ?? destOf(slot));
+        return undefined;
+    }
+    catch (error_) {
+        return { dest: destOf(slot), parked: slot.parked, why: messageOf(error_) };
+    }
+}
+/** Remove the parents staging made, for every slot fully undone (newest first). */
+function removeAllMadeParents(slots, error, stranded = []) {
+    return forEachInOrder(slots.toReversed().filter((slot) => !stranded.includes(slot)), (slot) => removeMadeParents(slot, error));
+}
+/** Undo every slot, newest first; the error to throw is `error`, or a rollback-incomplete one carrying it. */
+async function rolledBack(slots, error) {
+    const outcomes = await mapInOrder(slots.toReversed(), async (slot) => ({ slot, stranded: await restore(slot, error) }));
+    const stuck = outcomes.filter((o) => o.stranded !== undefined);
+    await removeAllMadeParents(slots, error, stuck.map((o) => o.slot));
+    return stuck.length === 0 ? error : new TreeRollbackIncompleteError(error, stuck.map((o) => o.stranded));
+}
+/** Remove a parked entry: `undefined` when gone, else the classified fault naming the parked path. */
+async function removeParked(slot) {
+    const parked = slot.parked;
+    try {
+        await removeEntry(parked);
+        return undefined;
+    }
+    catch (error_) {
+        const fault = classifyFsFault(error_, { side: 'destination', action: `remove the previous ${labelOf(slot)}, parked at ${parked}`, path: parked });
+        if (!isFsFaultError(fault))
+            throw error_;
+        return fault;
+    }
+}
+/**
+ * Remove every parked entry. A replace's refusal is a warning; a remove's is thrown
+ * (after every removal was tried), with every other refusal recorded beside it.
+ */
+async function finalize(slots) {
+    const parked = slots.filter((slot) => slot.parked !== undefined);
+    const outcomes = (await mapInOrder(parked, async (slot) => ({ slot, fault: await removeParked(slot) }))).filter((o) => o.fault !== undefined);
+    const thrownAt = finalizeThrows(outcomes.map((o) => ({ op: o.slot.planned.change.op })));
+    const thrown = thrownAt === undefined ? undefined : outcomes[thrownAt];
+    if (thrown !== undefined) {
+        for (const other of outcomes)
+            if (other !== thrown)
+                recordSuppressedFault(thrown.fault, other.fault);
+        throw thrown.fault;
+    }
+    return {
+        warnings: outcomes.map(({ slot, fault }) => ({ code: TREE_CLEANUP_INCOMPLETE_CODE, path: slot.parked, message: messageOf(fault) })),
+    };
+}
+/**
+ * Carry out `plan`: stage, park, swap, `afterSwap`, finalize — or roll back so
+ * every destination is exactly as it was.
+ *
+ * @param plan - What `planTreeChanges` decided; `keep` and `subsumed` changes are not touched
+ * @param options - `afterSwap`, run once the new tree is in place
+ * @returns The warnings of a change that is done: a previous tree left beside a replaced one
+ * @throws the first failure, after the rollback and unchanged: an `FsFaultError` (side
+ *   `destination`, or the fill's declared side for a copy source's read), a `write` fill's own error or raw
+ *   errno, or whatever `afterSwap` threw — with what could not be cleaned up in
+ *   `suppressedFaultsOf(error)`; {@link TreeRollbackIncompleteError} (cause: that
+ *   failure) when the rollback could not undo every change; for a `remove` whose
+ *   parked entry cannot be removed, an `FsFaultError` side `destination` naming it
+ */
+export function applyTreePlan(plan, options = {}) {
+    return applyStages(plan, options);
+}
+/**
+ * {@link applyTreePlan}, for a verb that reports a change it finished even when what it parked could
+ * not then be deleted (an uninstall, a clear): a failure before the commit — every swap made and
+ * `afterSwap` run — rolled back and is thrown, as by `applyTreePlan`; one after it is returned as
+ * `leftover`. The commit is the one line between "nothing finished" and "the change is done".
+ */
+export async function applyTreePlanOrLeftover(plan, options = {}) {
+    let committed = false;
+    try {
+        return await applyStages(plan, {
+            afterSwap: async () => {
+                await options.afterSwap?.();
+                committed = true;
+            },
+        });
+    }
+    catch (error) {
+        if (!committed)
+            throw error;
+        return { warnings: [], leftover: error };
+    }
+}
+async function applyStages(plan, options) {
+    const slots = plan.changes.filter(isActive).map((planned) => ({ planned, createdParent: undefined, staged: undefined, parked: undefined, spelled: undefined, swapped: false }));
+    try {
+        await forEachInOrder(slots, stage);
+    }
+    catch (error) {
+        await forEachInOrder(slots, (slot) => discard(slot.staged, error));
+        await removeAllMadeParents(slots, error);
+        throw error;
+    }
+    try {
+        await forEachInOrder(slots.filter((slot) => slot.planned.existing !== 'absent'), park);
+        await forEachInOrder(slots.filter((slot) => slot.staged !== undefined), swap);
+        await options.afterSwap?.();
+    }
+    catch (error) {
+        throw await rolledBack(slots, error);
+    }
+    return finalize(slots);
+}
+//# sourceMappingURL=apply.js.map

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

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

package/dist/tree-change/copy-decisions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The decisions of a tree copy that touch no filesystem: what it does about an entry already at a
+ * name it is about to create, when two names are one, and the refusal two source entries with one
+ * destination name get. `copy-tree.ts` is the half that makes the calls.
+ */
+import { FsFaultError } from '../errors/fs-fault.js';
+/**
+ * What a tree copy does about an entry ALREADY at a name it is about to create, below its root:
+ * - `fresh`: the destination is new (a staged tree): anything there is refused (`EEXIST`), never adopted.
+ * - `merge`: the destination is the caller's own output written again (a build directory): a real
+ *   directory is adopted; a file or a link is REMOVED and made anew — never written through.
+ *
+ * Under both, an entry the copy itself made is never taken for one that was "already there": two
+ * source names that are one name at the destination are refused ({@link aliasFault}).
+ */
+export type CopyOnto = 'fresh' | 'merge';
+/** One entry the walk hands the copy: where it is, and where it is relative to the root (forward slashes). */
+export interface CopiedEntry {
+    readonly path: string;
+    readonly relative: string;
+}
+/** The directory, relative to the root, that `relative` is in (`''`: the root). */
+export declare const parentOf: (relative: string) => string;
+/** The entry name of `relative`. */
+export declare const nameOf: (relative: string) => string;
+/**
+ * Whether two entry names are one name on a filesystem that folds letter case or Unicode form
+ * (APFS, NTFS, exFAT, SMB). Asked only AFTER the OS answered `EEXIST` for the second of them, to say
+ * which earlier entry it collided with: it names the pair, it never decides that there is one.
+ */
+export declare function sameNameWhereFolded(a: string, b: string): boolean;
+/**
+ * Whether a sibling this copy made, whose name folds to the name that just answered `EEXIST`, is the
+ * entry it collided with — asked only when identity did not find one that is.
+ *
+ * It is not when the OS proved them TWO entries: both are there, each with an identity, none shared.
+ * That is a tree that keeps the two names apart (case-sensitive), and what stands at the colliding
+ * name was there before this copy — a `merge`'s previous output, to take over as any other.
+ *
+ * @param sameness - What identity answered for the sibling's copy against the colliding name
+ * @param collidingPresent - Whether the colliding name holds an entry the copy can examine
+ */
+export declare function foldedNameIsTwin(sameness: 'same' | 'different' | 'unknown', collidingPresent: boolean): boolean;
+/**
+ * What a copy does at a name that already holds an entry it did not make.
+ *
+ * @param onto - The copy's mode
+ * @param kind - What the copy is about to make there
+ * @param thereIsDirectory - Whether the entry there is a real directory (not a link to one); read only under `merge`
+ * @returns `refuse` (rethrow the `EEXIST`), `adopt` (keep the directory), or `replace` (remove the file or link, make it anew)
+ */
+export declare function mayTakeOver(onto: CopyOnto, kind: 'directory' | 'leaf', thereIsDirectory: boolean): 'refuse' | 'adopt' | 'replace';
+/**
+ * Two source entries that are ONE name where the copy goes: the source's own layout cannot be
+ * copied there. A `source` fault (origin `content`) whatever side the tree is read on, naming both.
+ */
+export declare function aliasFault(first: CopiedEntry, second: CopiedEntry, cause: unknown): FsFaultError;
+//# sourceMappingURL=copy-decisions.d.ts.map

package/dist/tree-change/copy-decisions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy-decisions.d.ts","sourceRoot":"","sources":["../../src/tree-change/copy-decisions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAEzC,8GAA8G;AAC9G,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,mFAAmF;AACnF,eAAO,MAAM,QAAQ,GAAI,UAAU,MAAM,KAAG,MAAsF,CAAC;AAEnI,oCAAoC;AACpC,eAAO,MAAM,MAAM,GAAI,UAAU,MAAM,KAAG,MAAuD,CAAC;AAKlG;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,EAAE,gBAAgB,EAAE,OAAO,GAAG,OAAO,CAE/G;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,EAAE,gBAAgB,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAKjI;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,GAAG,YAAY,CAUhG"}

package/dist/tree-change/copy-decisions.js

@@ -0,0 +1,66 @@
+/**
+ * The decisions of a tree copy that touch no filesystem: what it does about an entry already at a
+ * name it is about to create, when two names are one, and the refusal two source entries with one
+ * destination name get. `copy-tree.ts` is the half that makes the calls.
+ */
+import { FsFaultError } from '../errors/fs-fault.js';
+/** The directory, relative to the root, that `relative` is in (`''`: the root). */
+export const parentOf = (relative) => (relative.includes('/') ? relative.slice(0, relative.lastIndexOf('/')) : '');
+/** The entry name of `relative`. */
+export const nameOf = (relative) => relative.slice(relative.lastIndexOf('/') + 1);
+/** A name as a case- and normalisation-insensitive filesystem compares it, near enough to find a pair to name. */
+const folded = (name) => name.normalize('NFKD').toLowerCase();
+/**
+ * Whether two entry names are one name on a filesystem that folds letter case or Unicode form
+ * (APFS, NTFS, exFAT, SMB). Asked only AFTER the OS answered `EEXIST` for the second of them, to say
+ * which earlier entry it collided with: it names the pair, it never decides that there is one.
+ */
+export function sameNameWhereFolded(a, b) {
+    return folded(a) === folded(b);
+}
+/**
+ * Whether a sibling this copy made, whose name folds to the name that just answered `EEXIST`, is the
+ * entry it collided with — asked only when identity did not find one that is.
+ *
+ * It is not when the OS proved them TWO entries: both are there, each with an identity, none shared.
+ * That is a tree that keeps the two names apart (case-sensitive), and what stands at the colliding
+ * name was there before this copy — a `merge`'s previous output, to take over as any other.
+ *
+ * @param sameness - What identity answered for the sibling's copy against the colliding name
+ * @param collidingPresent - Whether the colliding name holds an entry the copy can examine
+ */
+export function foldedNameIsTwin(sameness, collidingPresent) {
+    return !(sameness === 'different' && collidingPresent);
+}
+/**
+ * What a copy does at a name that already holds an entry it did not make.
+ *
+ * @param onto - The copy's mode
+ * @param kind - What the copy is about to make there
+ * @param thereIsDirectory - Whether the entry there is a real directory (not a link to one); read only under `merge`
+ * @returns `refuse` (rethrow the `EEXIST`), `adopt` (keep the directory), or `replace` (remove the file or link, make it anew)
+ */
+export function mayTakeOver(onto, kind, thereIsDirectory) {
+    if (onto === 'fresh')
+        return 'refuse';
+    // A merge never swaps one kind for the other: a directory is not deleted for a file, nor a file for a directory.
+    if (thereIsDirectory !== (kind === 'directory'))
+        return 'refuse';
+    return kind === 'directory' ? 'adopt' : 'replace';
+}
+/**
+ * Two source entries that are ONE name where the copy goes: the source's own layout cannot be
+ * copied there. A `source` fault (origin `content`) whatever side the tree is read on, naming both.
+ */
+export function aliasFault(first, second, cause) {
+    return new FsFaultError({
+        side: 'source',
+        faultClass: 'occupied',
+        errno: 'EEXIST',
+        path: second.path,
+        origin: 'content',
+        action: `copy both ${first.path} and ${second.path}: where the copy goes their two names are one name (they differ only in letter case or Unicode form), so one would overwrite the other`,
+        cause,
+    });
+}
+//# sourceMappingURL=copy-decisions.js.map

package/dist/tree-change/copy-decisions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy-decisions.js","sourceRoot":"","sources":["../../src/tree-change/copy-decisions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAmBrD,mFAAmF;AACnF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAEnI,oCAAoC;AACpC,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAElG,kHAAkH;AAClH,MAAM,MAAM,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;AAE9E;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAS,EAAE,CAAS;IACtD,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAA0C,EAAE,gBAAyB;IACpG,OAAO,CAAC,CAAC,QAAQ,KAAK,WAAW,IAAI,gBAAgB,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,IAAc,EAAE,IAA0B,EAAE,gBAAyB;IAC/F,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,QAAQ,CAAC;IACtC,iHAAiH;IACjH,IAAI,gBAAgB,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC;QAAE,OAAO,QAAQ,CAAC;IACjE,OAAO,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAkB,EAAE,MAAmB,EAAE,KAAc;IAChF,OAAO,IAAI,YAAY,CAAC;QACtB,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE,UAAU;QACtB,KAAK,EAAE,QAAQ;QACf,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,SAAS;QACjB,MAAM,EAAE,aAAa,KAAK,CAAC,IAAI,QAAQ,MAAM,CAAC,IAAI,wIAAwI;QAC1L,KAAK;KACN,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,125 @@
+/**
+ * `copyTree`: copy a directory tree by the same walk `proveTreeReadable` proves it
+ * with, reading each file from the very handle the walk judged a regular file.
+ */
+import { type FsSide } from '../errors/fs-fault.js';
+import { type CopyOnto } from './copy-decisions.js';
+import { type FileUnderOptions } from './files.js';
+import type { ProveTreeReadableOptions } from './readable-tree.js';
+import { type TreeVisitor } from './tree-walk.js';
+/** Where a tree copy goes: `relative` (forward slashes; `''` for the root itself) under `root`. */
+interface CopyDestination {
+    /**
+     * A directory that is the CALLER's: one it made, or one its user named. Made with its parents
+     * when absent — whatever stands above it is the caller's too, a link in the user's own layout
+     * (`~/.claude` kept in a dotfiles repository) included — and adopted when a real directory. A link
+     * or a file AT its name is never adopted ({@link claimRoot}).
+     */
+    readonly root: string;
+    /**
+     * Where under `root` the copy goes. Everything between the two is inside a tree that may hold
+     * what an earlier copy kept — links included — so each component must be a real directory
+     * (`makeDirectoryUnder`): a link or a file standing there refuses the copy, naming it.
+     */
+    readonly relative: string;
+}
+/** What {@link copyTree} is told: the walk, the side its reads are on, and what it does about what is already there. */
+export interface CopyTreeOptions extends ProveTreeReadableOptions {
+    /** Required: only the caller knows whether its destination is new ({@link CopyOnto}). */
+    readonly onto: CopyOnto;
+}
+/**
+ * The visitor that writes the copy of each entry the walk accepts under `dest`; every read of the
+ * copied tree is on `side`.
+ *
+ * Every create below the root is EXCLUSIVE and never follows a link: a file is opened `wx`, a
+ * directory made by a plain `mkdir`, a link made only where nothing is. So a create that finds
+ * something answers `EEXIST`, and what happens then is decided in this order:
+ *
+ * 1. The entry there is one THIS copy made — the same entry by identity, or (where the OS will not
+ *    say) a sibling whose name is the same once case and Unicode form are folded: two source names,
+ *    one destination name. Refused as the source's layout (`aliasFault`), under either mode.
+ * 2. `fresh`: refused as it is (`EEXIST`), for the caller's boundary to classify.
+ * 3. `merge`: a real directory is adopted; a file or a link is removed (the link, never its target)
+ *    and the entry made anew; anything else — a directory where a file goes, a link where a
+ *    directory goes — is refused as it is (`mayTakeOver`).
+ *
+ * Where the copy goes is made by {@link claimDestination}: the root is the caller's (made with its
+ * parents when absent, adopted when a real directory, refused `EEXIST` when a link or a file — a link
+ * taken for it would put the whole copy where it points), and every directory from the root down to
+ * the copy is a real one or is refused as the layout of the tree it is in.
+ *
+ * Exported for `copyTree` and for the suite that hands it two entries by name — a real alias needs
+ * a case-sensitive source and a case-folding destination, which no one temp directory offers.
+ */
+export declare function copyVisitor(where: CopyDestination, copied: string, side: FsSide, onto: CopyOnto): TreeVisitor;
+/**
+ * Copy the directory `source` to `relative` under `root` ({@link CopyDestination}).
+ *
+ * `root` is a directory the caller made or its user named: created, with its parents, when absent;
+ * adopted when a real directory; refused, `EEXIST`, when a link or a file stands there. `relative`
+ * is `''` for a copy onto `root` itself. A copy that goes INSIDE a tree — a pool skill into a staged
+ * plugin that earlier copies filled, links kept — names that tree's root and where under it, and
+ * every directory between the two must then be a real one (made when absent): a link or a file
+ * there is a `source` fault (origin `content`, class `occupied`) naming it, never followed. So a
+ * caller cannot reach through a link by how deep its destination is: the only directory taken on
+ * trust is the one it declares as `root`.
+ *
+ * Entries are walked, and refused, exactly as `proveTreeReadable` proves them (see
+ * `tree-walk.ts`): a `follow-contained` link is copied as what it points at, inside
+ * the source only; a `preserve` link is copied as a link, its target string
+ * verbatim and never followed — its chain is read by text alone to give the copy its `file`/`dir`
+ * type, and one through a network or device path is refused (a `refused` fault on `options.side`)
+ * before anything is made; an entry `filter` excludes is never touched; a named
+ * pipe, socket or device is refused unopened. Each file is copied from the handle
+ * `fstat` judged, with its mode. Each directory takes its source's mode with the
+ * owner's rwx kept (`| 0o700`): a read-only source must not become a copy nothing
+ * can fill or remove.
+ *
+ * Below the copy's own directory nothing already there is ever adopted or written through, and two source
+ * entries that are one name there are refused as the source's layout (a `source` fault
+ * naming both): see {@link copyVisitor} and `options.onto`.
+ *
+ * The copy names no side for what it WRITES: a failure writing the copy is the raw
+ * errno, for the caller's boundary to classify — a link this host cannot create, and an
+ * `EEXIST` for something already at a name of a `fresh` destination, included. What it READS is on the side the caller names, as the proof's reads
+ * are: a refusal is a classified fault on `options.side` (origin `content`) naming
+ * the entry. Only the caller knows whether the tree is an input (`source`), VAT's
+ * staging (`environment`) or a copy already made into user state (`destination`).
+ *
+ * @param source - The directory to copy
+ * @param root - The directory the caller made or owns, which the copy goes into or under
+ * @param relative - Where under `root` the copy goes, forward slashes; `''` for `root` itself
+ * @param options - `links`, `filter` and `side`, exactly as `proveTreeReadable` was given them, and `onto`
+ */
+export declare function copyTree(source: string, root: string, relative: string, options: CopyTreeOptions): Promise<void>;
+/** What {@link copyRegularFile} is told: the file it reads, and (as `writeFileUnder` is) the entry already where the copy goes. */
+export interface CopyRegularFileOptions extends FileUnderOptions {
+    /** The side of the verb the file is on, as for {@link copyTree}. */
+    readonly side: FsSide;
+    /** What the file is, for a refused read's message: `read <reading>` (`linked file docs/a.md`). */
+    readonly reading: string;
+}
+/**
+ * Copy ONE regular file to `relative` under `root`, as {@link copyTree} copies a file: 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), its bytes copied from that very handle, its mode
+ * carried over.
+ *
+ * The copy is made as `writeFileUnder` makes a file — it is the same primitive: every directory of
+ * `relative` must be a real directory (made by a plain `mkdir` when absent), the file is created
+ * exclusively, and its bytes and mode go to that handle. So it never writes through a link, at the
+ * file's name or on the way to it; `options.existing` decides a regular file already there.
+ *
+ * Every read is a classified fault on `options.side` (origin `content`), naming what was read. An
+ * entry in the copy's way is a `source` fault (origin `content`, class `occupied`) naming it; any
+ * other failure writing is the raw errno, for the caller's boundary to classify.
+ *
+ * @param source - The file to copy
+ * @param root - The root of the tree the copy goes into, which the caller made
+ * @param relative - Where the copy goes, relative to `root`, forward slashes
+ * @param options - The side `source` is on and what it is; `existing` and `writing`, for the copy
+ */
+export declare function copyRegularFile(source: string, root: string, relative: string, options: CopyRegularFileOptions): Promise<void>;
+export {};
+//# sourceMappingURL=copy-tree.d.ts.map