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

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"}

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

@@ -0,0 +1,81 @@
+/**
+ * The one walk over a tree that is about to be read whole: `proveTreeReadable`
+ * runs it to prove a source before anything is written, and `copyTree` runs it to
+ * copy that source. One walk, so the proof and the copy can never disagree about
+ * which entries exist, which links are followed, or which entries are refused.
+ *
+ * Every entry is judged by one special-file policy, in this order:
+ *
+ * - A name the caller's `filter` excludes is skipped before anything touches it:
+ *   no `stat`, no `open`, and a directory's subtree is never listed.
+ * - A link under `links: 'preserve'` is handed over as a link; its target is never
+ *   examined.
+ * - A link under `links: 'refuse'` refuses the walk, naming it ({@link linkRefused}): the policy
+ *   of a tree that holds none by construction, so one found there is never followed or copied.
+ * - A link under `links: 'follow-contained'` is answered by its target (`stat`, so
+ *   a dangling link is an absent source). A directory target is entered first, so a
+ *   link back into the walk is named as the loop it is
+ *   ({@link DirectoryWalkRevisitedError}); then a target outside the root is refused
+ *   ({@link CopyLinkEscapesSourceError}).
+ * - A named pipe, socket or device (or a link to one) is refused unopened, as the
+ *   `EFTYPE` errno `refuseSpecialFile` raises.
+ * - A regular file is opened without blocking and judged again by `fstat` on that
+ *   handle, which is the one the visitor reads: a pipe swapped in after the listing
+ *   is refused there, never waited on.
+ *
+ * The ROOT is an entry like any other: it is `lstat`-ed, and a root that is a link is handed over
+ * (`preserve`) or refused (`refuse`) exactly as a link under it would be. Only `follow-contained`
+ * takes a root link for the directory it points at — the root is what containment is judged
+ * against, so it cannot be outside itself.
+ *
+ * Every READ the walk makes (list, `stat`, `open`, `fstat`, `realpath`) that the OS
+ * refuses is a classified fault on the caller's `side`, origin `content`, naming the
+ * entry. What a visitor WRITES is the visitor's: the walk never classifies it.
+ */
+import type { Stats } from 'node:fs';
+import { type FileHandle } from 'node:fs/promises';
+import { type FsSide } from '../errors/fs-fault.js';
+/** How a walk treats a symlink: follow it, contained to the root; keep it as a link; or refuse the tree that holds it. */
+export type LinkPolicy = 'follow-contained' | 'preserve' | 'refuse';
+/** What every walk over a tree is told. */
+export interface TreeWalkOptions {
+    /** `follow-contained`: a link is what it points at, inside the root only. `preserve`: a link is a link. `refuse`: a link refuses the walk. */
+    readonly links: LinkPolicy;
+    /** Keep the entry at this forward-slash path relative to the root; an excluded one is never touched. Omitted: keep everything. */
+    readonly filter?: (relative: string) => boolean;
+}
+/** One entry the walk accepted: where it is, and where it is relative to the root (`''` for the root). */
+interface WalkedEntry {
+    readonly path: string;
+    readonly relative: string;
+}
+/** What the walk hands each accepted entry to. */
+export interface TreeVisitor {
+    /** A directory, before any of its entries. */
+    directory(entry: WalkedEntry, stats: Stats): Promise<void>;
+    /** A regular file, through the handle `fstat` judged; the walk closes it. */
+    file(entry: WalkedEntry, handle: FileHandle, stats: Stats): Promise<void>;
+    /** A link under `links: 'preserve'`, never followed by the walk: the visitor decides what to read of it. */
+    link(entry: WalkedEntry): Promise<void>;
+}
+/**
+ * A refusal by the OS while reading the tree, as a fault on `side` (origin
+ * `content`) naming `entry` when the OS named no path. A coded refusal and a defect
+ * come back as they are. The one classification every read of the tree goes through.
+ */
+export declare function treeReadFault(side: FsSide, entry: string, error: unknown): unknown;
+/** Run one read of the tree; a refusal is rethrown by {@link treeReadFault}. */
+export declare function readingTree<T>(side: FsSide, entry: string, read: () => Promise<T>): Promise<T>;
+/**
+ * Walk the directory `root` under `options`, handing each accepted entry to
+ * `visitor` in listing order, the root first (relative `''`).
+ *
+ * @param root - The directory to walk; one that is not a directory is refused by its listing, and one
+ *   that is a link is judged by `options.links` like any link under it
+ * @param options - The link policy and the filter
+ * @param side - The side every read of the walk is classified on
+ * @param visitor - What to do with each entry
+ */
+export declare function walkTree(root: string, options: TreeWalkOptions, side: FsSide, visitor: TreeVisitor): Promise<void>;
+export {};
+//# sourceMappingURL=tree-walk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tree-walk.d.ts","sourceRoot":"","sources":["../../src/tree-change/tree-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAU,KAAK,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAW,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAiC,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAUnF,0HAA0H;AAC1H,MAAM,MAAM,UAAU,GAAG,kBAAkB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEpE,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,8IAA8I;IAC9I,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,kIAAkI;IAClI,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CACjD;AAED,0GAA0G;AAC1G,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,6EAA6E;IAC7E,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,4GAA4G;IAC5G,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAElF;AAmBD,gFAAgF;AAChF,wBAAsB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMpG;AAkID;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAExH"}

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

@@ -0,0 +1,212 @@
+/**
+ * The one walk over a tree that is about to be read whole: `proveTreeReadable`
+ * runs it to prove a source before anything is written, and `copyTree` runs it to
+ * copy that source. One walk, so the proof and the copy can never disagree about
+ * which entries exist, which links are followed, or which entries are refused.
+ *
+ * Every entry is judged by one special-file policy, in this order:
+ *
+ * - A name the caller's `filter` excludes is skipped before anything touches it:
+ *   no `stat`, no `open`, and a directory's subtree is never listed.
+ * - A link under `links: 'preserve'` is handed over as a link; its target is never
+ *   examined.
+ * - A link under `links: 'refuse'` refuses the walk, naming it ({@link linkRefused}): the policy
+ *   of a tree that holds none by construction, so one found there is never followed or copied.
+ * - A link under `links: 'follow-contained'` is answered by its target (`stat`, so
+ *   a dangling link is an absent source). A directory target is entered first, so a
+ *   link back into the walk is named as the loop it is
+ *   ({@link DirectoryWalkRevisitedError}); then a target outside the root is refused
+ *   ({@link CopyLinkEscapesSourceError}).
+ * - A named pipe, socket or device (or a link to one) is refused unopened, as the
+ *   `EFTYPE` errno `refuseSpecialFile` raises.
+ * - A regular file is opened without blocking and judged again by `fstat` on that
+ *   handle, which is the one the visitor reads: a pipe swapped in after the listing
+ *   is refused there, never waited on.
+ *
+ * The ROOT is an entry like any other: it is `lstat`-ed, and a root that is a link is handed over
+ * (`preserve`) or refused (`refuse`) exactly as a link under it would be. Only `follow-contained`
+ * takes a root link for the directory it points at — the root is what containment is judged
+ * against, so it cannot be outside itself.
+ *
+ * Every READ the walk makes (list, `stat`, `open`, `fstat`, `realpath`) that the OS
+ * refuses is a classified fault on the caller's `side`, origin `content`, naming the
+ * entry. What a visitor WRITES is the visitor's: the walk never classifies it.
+ */
+import fs from 'node:fs/promises';
+import { classifyFsFault, FsFaultError } from '../errors/fs-fault.js';
+import { forEachInOrder } from '../in-order.js';
+import { requireFollowedStat } from '../link-following.js';
+import { isUnderRoot } from '../path-containment.js';
+import { safePath } from '../path-core.js';
+import { refuseSpecialFile } from '../special-file.js';
+import { openForReading } from '../text-file.js';
+import { CopyLinkEscapesSourceError, FollowedWalk } from './followed-walk.js';
+/**
+ * A refusal by the OS while reading the tree, as a fault on `side` (origin
+ * `content`) naming `entry` when the OS named no path. A coded refusal and a defect
+ * come back as they are. The one classification every read of the tree goes through.
+ */
+export function treeReadFault(side, entry, error) {
+    return classifyFsFault(error, { side, origin: 'content', action: `read ${entry}`, path: entry });
+}
+/**
+ * The refusal of a link in a tree walked with `links: 'refuse'`: a `wrong-type` fault on `side`
+ * (origin `content`) naming the link, under the errno a special file is refused with — an entry
+ * of a kind the read does not take — so the one refusal table decides what the caller publishes.
+ */
+function linkRefused(side, link) {
+    return new FsFaultError({
+        side,
+        faultClass: 'wrong-type',
+        errno: 'EFTYPE',
+        path: link,
+        origin: 'content',
+        action: `read ${link}: it is a symbolic link, and this tree may hold none`,
+        cause: undefined,
+    });
+}
+/** Run one read of the tree; a refusal is rethrown by {@link treeReadFault}. */
+export async function readingTree(side, entry, read) {
+    try {
+        return await read();
+    }
+    catch (error) {
+        throw treeReadFault(side, entry, error);
+    }
+}
+/** {@link readingTree}, synchronously: the walk guard and the containment check resolve real paths. */
+function readingTreeSync(side, entry, read) {
+    try {
+        return read();
+    }
+    catch (error) {
+        throw treeReadFault(side, entry, error);
+    }
+}
+/**
+ * Open `path` without blocking and judge it by `fstat` on that handle; hand the
+ * handle to `use` and close it after. A special file is refused (`EFTYPE`) and its
+ * handle closed before `use` runs. When `use` fails, ITS error is the one reported:
+ * the handle is still released, but a close that also fails must not replace a
+ * write the visitor failed (a source fault hiding a destination one).
+ */
+async function withRegularFile(side, path, use) {
+    const handle = await readingTree(side, path, () => openForReading(path));
+    try {
+        const stats = await readingTree(side, path, () => handle.stat());
+        await use(handle, stats);
+    }
+    catch (error) {
+        await Promise.allSettled([handle.close()]);
+        throw error;
+    }
+    // Closing the source's handle is a read of the source: a refused close is the source's fault too.
+    await readingTree(side, path, () => handle.close());
+}
+/** One walk: its root, its policy, the guard a following walk holds, and the visitor. */
+class TreeWalk {
+    #root;
+    #options;
+    #side;
+    #visitor;
+    #guard;
+    constructor(root, options, side, visitor) {
+        this.#root = root;
+        this.#options = options;
+        this.#side = side;
+        this.#visitor = visitor;
+        this.#guard = options.links === 'follow-contained' ? new FollowedWalk(side, root) : undefined;
+    }
+    /**
+     * Walk from the root: judged by `lstat`, as every entry under it is by its listing. A root that is
+     * a link is the policy's to decide — except under `follow-contained`, where the root is the
+     * directory it points at.
+     */
+    async root(entry) {
+        if (this.#options.links !== 'follow-contained') {
+            const stats = await readingTree(this.#side, entry.path, () => fs.lstat(entry.path));
+            if (stats.isSymbolicLink()) {
+                await this.#link(entry);
+                return;
+            }
+        }
+        await this.directory(entry);
+    }
+    /** Enter the directory `entry` and visit it and everything under it, in listing order. */
+    async directory(entry) {
+        // Listed first: a root that is not a directory is refused by the listing (`ENOTDIR`), never opened.
+        const listing = await this.#list(entry.path);
+        const stats = await readingTree(this.#side, entry.path, () => requireFollowedStat(entry.path, this.#root));
+        this.#enter(entry.path);
+        await this.#visitDirectory(entry, listing, stats);
+    }
+    #list(dir) {
+        return readingTree(this.#side, dir, () => fs.readdir(dir, { withFileTypes: true }));
+    }
+    /** Visit an entered directory, then its entries in order: the guard must see each directory entered before the walk recurses, and the first refusal names the first offending entry in listing order. */
+    async #visitDirectory(entry, listing, stats) {
+        await this.#visitor.directory(entry, stats);
+        await forEachInOrder(listing, (dirent) => this.#entry(entry, dirent));
+    }
+    async #entry(parent, dirent) {
+        const entry = {
+            path: safePath.join(parent.path, dirent.name),
+            relative: parent.relative === '' ? dirent.name : `${parent.relative}/${dirent.name}`,
+        };
+        if (this.#options.filter !== undefined && !this.#options.filter(entry.relative))
+            return;
+        if (dirent.isSymbolicLink()) {
+            await this.#link(entry);
+            return;
+        }
+        if (dirent.isDirectory()) {
+            await this.directory(entry);
+            return;
+        }
+        await this.#nonDirectory(entry, dirent);
+    }
+    async #link(entry) {
+        if (this.#options.links === 'preserve') {
+            await this.#visitor.link(entry);
+            return;
+        }
+        if (this.#options.links === 'refuse')
+            throw linkRefused(this.#side, entry.path);
+        const target = await readingTree(this.#side, entry.path, () => requireFollowedStat(entry.path, this.#root));
+        // Revisit first, so a link back into the tree is named as the loop it is; then
+        // containment, so a link out is named as the escape it is.
+        if (target.isDirectory())
+            this.#enter(entry.path);
+        const contained = readingTreeSync(this.#side, entry.path, () => isUnderRoot(this.#root, entry.path));
+        if (contained !== 'inside')
+            throw new CopyLinkEscapesSourceError(entry.path, this.#root);
+        if (target.isDirectory()) {
+            await this.#visitDirectory(entry, await this.#list(entry.path), target);
+            return;
+        }
+        await this.#nonDirectory(entry, target);
+    }
+    /** A file by its listing or its link's target: a special one is refused unopened, a regular one opened. */
+    async #nonDirectory(entry, kind) {
+        readingTreeSync(this.#side, entry.path, () => refuseSpecialFile(kind, entry.path));
+        await withRegularFile(this.#side, entry.path, (handle, stats) => this.#visitor.file(entry, handle, stats));
+    }
+    #enter(dir) {
+        const guard = this.#guard;
+        guard?.enter(dir);
+    }
+}
+/**
+ * Walk the directory `root` under `options`, handing each accepted entry to
+ * `visitor` in listing order, the root first (relative `''`).
+ *
+ * @param root - The directory to walk; one that is not a directory is refused by its listing, and one
+ *   that is a link is judged by `options.links` like any link under it
+ * @param options - The link policy and the filter
+ * @param side - The side every read of the walk is classified on
+ * @param visitor - What to do with each entry
+ */
+export async function walkTree(root, options, side, visitor) {
+    await new TreeWalk(root, options, side, visitor).root({ path: root, relative: '' });
+}
+//# sourceMappingURL=tree-walk.js.map

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

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

package/dist/win32-namespace.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The win32 namespace prefix Node may report a path with. A leaf that imports NOTHING, so the
+ * errno table — itself a leaf, for the reason its header gives — can read every errno's path
+ * through it, once.
+ *
+ * Module-internal to `utils`: no barrel and no subpath re-exports it; its two callers are the
+ * errno table and the tree-change apply.
+ */
+/**
+ * A path without the win32 namespace prefix Node may report it with. Under win32 Node hands the OS
+ * a namespaced path (`\\?\C:\…`, `\\?\UNC\server\share\…`) and reports some paths back in
+ * that form — the first directory a recursive `mkdir` made, an errno's `path` and `dest`. Held
+ * against a plain `C:\…` path such a report reads as another root, and displayed it names
+ * `//?/C:/…`. Pure and the same on every host; every other path is returned as it is.
+ *
+ * @param reported - A native path, as Node reported it
+ * @returns The path in the spelling the caller's own paths have (native separators kept)
+ *
+ * @example
+ * withoutWin32Namespace('\\\\?\\C:\\a') // 'C:\\a'
+ * withoutWin32Namespace('\\\\?\\UNC\\host\\share') // '\\\\host\\share'
+ */
+export declare function withoutWin32Namespace(reported: string): string;
+//# sourceMappingURL=win32-namespace.d.ts.map

package/dist/win32-namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"win32-namespace.d.ts","sourceRoot":"","sources":["../src/win32-namespace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI9D"}

package/dist/win32-namespace.js

@@ -0,0 +1,31 @@
+/**
+ * The win32 namespace prefix Node may report a path with. A leaf that imports NOTHING, so the
+ * errno table — itself a leaf, for the reason its header gives — can read every errno's path
+ * through it, once.
+ *
+ * Module-internal to `utils`: no barrel and no subpath re-exports it; its two callers are the
+ * errno table and the tree-change apply.
+ */
+const WIN32_NAMESPACE = String.raw `\\?` + '\\';
+const WIN32_UNC_NAMESPACE = `${WIN32_NAMESPACE}UNC\\`;
+/**
+ * A path without the win32 namespace prefix Node may report it with. Under win32 Node hands the OS
+ * a namespaced path (`\\?\C:\…`, `\\?\UNC\server\share\…`) and reports some paths back in
+ * that form — the first directory a recursive `mkdir` made, an errno's `path` and `dest`. Held
+ * against a plain `C:\…` path such a report reads as another root, and displayed it names
+ * `//?/C:/…`. Pure and the same on every host; every other path is returned as it is.
+ *
+ * @param reported - A native path, as Node reported it
+ * @returns The path in the spelling the caller's own paths have (native separators kept)
+ *
+ * @example
+ * withoutWin32Namespace('\\\\?\\C:\\a') // 'C:\\a'
+ * withoutWin32Namespace('\\\\?\\UNC\\host\\share') // '\\\\host\\share'
+ */
+export function withoutWin32Namespace(reported) {
+    // Matched on the NATIVE spelling, before any separator conversion: the prefix exists only there.
+    if (reported.startsWith(WIN32_UNC_NAMESPACE))
+        return `\\\\${reported.slice(WIN32_UNC_NAMESPACE.length)}`;
+    return reported.startsWith(WIN32_NAMESPACE) ? reported.slice(WIN32_NAMESPACE.length) : reported;
+}
+//# sourceMappingURL=win32-namespace.js.map

package/dist/win32-namespace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"win32-namespace.js","sourceRoot":"","sources":["../src/win32-namespace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAA,KAAK,GAAG,IAAI,CAAC;AAC/C,MAAM,mBAAmB,GAAG,GAAG,eAAe,OAAO,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,iGAAiG;IACjG,IAAI,QAAQ,CAAC,UAAU,CAAC,mBAAmB,CAAC;QAAE,OAAO,OAAO,QAAQ,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,CAAC;IACzG,OAAO,QAAQ,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAClG,CAAC"}

package/dist/yaml/surgical-yaml.d.ts

@@ -22,6 +22,14 @@
  *
  * No filesystem access — these are pure string transforms.
  */
+/**
+ * The code {@link updateYamlIn} throws when the INPUT document cannot take the
+ * edit — it is not YAML, or the path lands on a collection or runs through a
+ * scalar. The input's shape, not a defect: a caller editing an adopter's file
+ * reports it as that file's problem. Its other throws (an empty path, a failed
+ * post-condition) stay uncoded — they are the caller's or this module's bug.
+ */
+export declare const YAML_EDIT_INPUT_REFUSED_CODE = "YAML_EDIT_INPUT_REFUSED";
 /** A path into a YAML document: map keys (strings) and/or sequence indices. */
 export type YamlPath = (string | number)[];
 /** A scalar value this module knows how to serialize as a single YAML token. */
@@ -42,9 +50,10 @@ export type YamlScalarValue = string | number | boolean | null;
  * @param path - Key/index path to the scalar to set.
  * @param value - The scalar value to write (string, number, boolean, or null).
  * @returns The updated document text.
- * @throws If `text` is not valid YAML, if `path` is empty, or if `path` resolves
- *   to a collection that would be clobbered by a scalar (or an intermediate
- *   ancestor is a scalar that cannot hold a child).
+ * @throws A `VatError` coded {@link YAML_EDIT_INPUT_REFUSED_CODE} if `text` is
+ *   not valid YAML, or `path` resolves to a collection that would be clobbered
+ *   by a scalar (or an intermediate ancestor is a scalar that cannot hold a
+ *   child); a plain `Error` if `path` is empty.
  *
  * @example
  * updateYamlIn('model: haiku   # note\n', ['model'], 'opus')

package/dist/yaml/surgical-yaml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surgical-yaml.d.ts","sourceRoot":"","sources":["../../src/yaml/surgical-yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAcH,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;AAE3C,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAK/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CA2BzF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,QAAQ,EAAE,GACvB,IAAI,CAYN"}
+{"version":3,"file":"surgical-yaml.d.ts","sourceRoot":"","sources":["../../src/yaml/surgical-yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAgBH;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,4BAA4B,CAAC;AAEtE,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;AAE3C,gFAAgF;AAChF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAK/D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CA4BzF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,QAAQ,EAAE,GACvB,IAAI,CAYN"}