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

package/dist/tree-change/files.js

@@ -0,0 +1,423 @@
+/**
+ * The file-level half of the tree-change primitive: the staging names every
+ * change sits beside its destination under, the one rename (retried where Windows
+ * makes a rename race a scanner), the one removal (a read-only tree included), a
+ * whole-file replace that never truncates what it replaces, and a temp directory
+ * that is always disposed of.
+ */
+import { rmSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { requireConfirmedAbsent } from '../errors/confirmed-absent.js';
+import { isAccessRefusedError, isAlreadyExistsError, isPathAbsentError, isRenameContentionError } from '../errors/errno-table.js';
+import { classifyFsFault, everywhere, isFsFaultError, withFsFault } from '../errors/fs-fault.js';
+import { recordSuppressedFault } from '../errors/suppressed-faults.js';
+import { mapWithConcurrency } from '../in-order.js';
+import { realpathNative, requireFollowedStat } from '../link-following.js';
+import { isUnderRoot } from '../path-containment.js';
+import { safePath, toForwardSlash } from '../path-core.js';
+import { normalizedTmpdir } from '../path-utils.js';
+import { entryInTheWayFault, renameRetryDelay, tempDirRefusal } from './apply-decisions.js';
+import { stagingName } from './staging-names.js';
+/** The owner's read, write and search bits: what a directory needs for its entries to be removed. */
+const OWNER_RWX = 0o700;
+export { TEMP_DIR_OUTSIDE_TMPDIR_CODE } from './apply-decisions.js';
+function renameTrying(from, to, attempt) {
+    return fs.rename(from, to).catch(async (error) => {
+        const wait = renameRetryDelay(process.platform, attempt, isRenameContentionError(error));
+        if (wait === undefined)
+            throw error;
+        await delay(wait);
+        return renameTrying(from, to, attempt + 1);
+    });
+}
+/**
+ * Rename `from` to `to` — a file or a whole tree — in one step. Under win32 a
+ * rename the OS refuses with contention (`EPERM`, `EBUSY`, `EACCES`: a scanner,
+ * an indexer, a handle still closing) is retried, up to 6 tries with a backoff of
+ * 50·2ⁿ ms (1.55 s in all); any other errno, and any errno on another platform,
+ * is final.
+ *
+ * @param from - The entry to move
+ * @param to - Its new name, on the same filesystem
+ * @throws the rename's raw errno, for the caller to classify on the side it knows
+ */
+export function renameFileAtomic(from, to) {
+    return renameTrying(from, to, 0);
+}
+/**
+ * Give `dir` the owner's rwx, then list the directories under it (links not followed). A
+ * directory already gone is nothing to grant: `rm`'s recursion removes siblings concurrently and
+ * goes on after it has rejected, so the walk can meet one it has just taken.
+ */
+async function grantOwner(dir) {
+    try {
+        await fs.chmod(dir, OWNER_RWX);
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        return entries.filter((entry) => !entry.isSymbolicLink() && entry.isDirectory()).map((entry) => safePath.join(dir, entry.name));
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return [];
+        throw error;
+    }
+}
+/**
+ * Give every directory of `level` and below the owner's rwx, each before it is listed: one
+ * level at a time, at most `FS_CONCURRENCY` in flight however wide or deep the tree is.
+ */
+async function grantOwnerWalk(level) {
+    if (level.length === 0)
+        return;
+    const next = await mapWithConcurrency(level, grantOwner);
+    await grantOwnerWalk(next.flat());
+}
+/**
+ * Remove `entry` — a tree, a file or a link (never what it points at) — whatever
+ * the modes under it: the root gets the owner's rwx first, and a removal still
+ * refused (`EACCES` / `EPERM`: a read-only directory deeper down refuses the
+ * removal of its entries) is retried once every directory under it has been given
+ * them too. Nothing there is not a failure. A root the OS will not chmod is still
+ * removed when the removal itself is allowed. Done means not there: a removal that
+ * resolved with the entry still present (`rm`'s `force` reading its own listing's
+ * ENOENT as "gone") is run once more, and a plain `rmdir` then throws why it stays.
+ *
+ * @throws the raw errno of the chmod, listing or removal that failed
+ */
+export async function removeEntry(entry) {
+    if (!(await removeOnce(entry)))
+        return;
+    // `rm` with `force` takes an ENOENT from its own listing for "already gone" and resolves with the entry
+    // still there: done is what is not there. Once more; then the non-recursive removal names why it stays.
+    if (!(await present(entry)))
+        return;
+    await removeOnce(entry);
+    if (await present(entry))
+        await fs.rmdir(entry);
+}
+/**
+ * The `lstat` of `entry`, or `undefined` when nothing — a dangling link included — is there. "Nothing
+ * there" is believed only when the parent's listing agrees: an `lstat` answering ENOTDIR for a parked
+ * tree that WAS there read as "already gone", and the run exited 0 with the tree left behind.
+ */
+async function examined(entry) {
+    try {
+        return await fs.lstat(entry);
+    }
+    catch (error) {
+        if (!isPathAbsentError(error))
+            throw error;
+        requireConfirmedAbsent(entry, error, { action: 'remove the entry', path: entry }, { follows: false, sideOf: everywhere('destination') });
+        return undefined;
+    }
+}
+/** Whether anything is at `entry` (see {@link examined}); a refusal is thrown. */
+async function present(entry) {
+    return (await examined(entry)) !== undefined;
+}
+/** One removal pass (see {@link removeEntry}); `false` when nothing was there to remove. */
+async function removeOnce(entry) {
+    const stats = await examined(entry);
+    if (stats === undefined)
+        return false;
+    const directory = stats.isDirectory();
+    // Best effort: a root the OS will not chmod may still be removable, and the walk below asks again.
+    if (directory)
+        await fs.chmod(entry, OWNER_RWX).catch((error_) => error_);
+    try {
+        await fs.rm(entry, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (!directory || !isAccessRefusedError(error))
+            throw error;
+        await grantOwnerWalk([entry]);
+        await fs.rm(entry, { recursive: true, force: true });
+    }
+    return true;
+}
+/** Where a write to `dest` really lands: a link's target (so a dotfiles link stays a link), or `dest` itself. */
+async function writeTarget(dest) {
+    try {
+        // The one native realpath rule (`realpathNative`): an unanswerable volume is asked again by the JS walk.
+        // `dest` is the path the verb itself names — the operator's own, so its own link is the edge.
+        const real = await realpathNative(dest, dest);
+        return { path: real, mode: (await requireFollowedStat(real, real)).mode & 0o7777 };
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return { path: dest, mode: undefined };
+        throw error;
+    }
+}
+/**
+ * Prove an existing file writable as it is, by opening it for writing — no truncation, no
+ * creation — and closing it. A rename over a file needs only its directory's permission, so
+ * without this a file its owner made read-only (or Windows marked read-only) would be replaced
+ * where a write in place is refused. An open, not `access`: on Windows `access` does not consult ACLs.
+ */
+async function proveWritable(file) {
+    const handle = await fs.open(file, 'r+');
+    await handle.close();
+}
+/**
+ * Replace the file `dest` with `contents` in one step: the bytes go to a temp
+ * name beside it, which is then renamed over it ({@link renameFileAtomic}). A
+ * write that fails — a full disk mid-write — leaves `dest` byte-equal and the
+ * temp removed (a temp that will not go is recorded beside the thrown error:
+ * `suppressedFaultsOf`). An existing file keeps its mode, and must be writable as it is: one
+ * a write in place would be refused (a read-only file) is refused before anything is written,
+ * never replaced by the rename. A link is written through, so it stays a link to the replaced file.
+ *
+ * @param dest - The file to replace or create
+ * @param contents - Its new bytes
+ * @throws the raw errno, for the caller to classify on the side it knows
+ */
+export async function replaceFile(dest, contents) {
+    const target = await writeTarget(dest);
+    if (target.mode !== undefined)
+        await proveWritable(target.path);
+    const temp = stagingName(target.path);
+    try {
+        const handle = await fs.open(temp, 'wx');
+        try {
+            await handle.writeFile(contents);
+        }
+        finally {
+            await handle.close();
+        }
+        if (target.mode !== undefined)
+            await fs.chmod(temp, target.mode);
+        await renameFileAtomic(temp, target.path);
+    }
+    catch (error) {
+        await fs.rm(temp, { force: true }).catch((error_) => {
+            recordSuppressedFault(error, classifyFsFault(error_, { side: 'destination', action: 'remove the temporary file', path: temp }));
+        });
+        throw error;
+    }
+}
+/** What is at `path`, never following a link; `undefined` when nothing is. A refusal is thrown raw. */
+async function entryAt(path) {
+    try {
+        return await fs.lstat(path);
+    }
+    catch (error) {
+        if (isPathAbsentError(error))
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * The directory `segments` name under `dir`, each component a REAL directory: made (a plain `mkdir`)
+ * when absent, refused when a link or a file stands there. One component at a time — each must be a
+ * directory before the next is looked at.
+ */
+async function plainDirectoryUnder(dir, segments, writing) {
+    const [segment, ...rest] = segments;
+    if (segment === undefined)
+        return dir;
+    const next = safePath.join(dir, segment);
+    const there = await entryAt(next);
+    if (there === undefined)
+        await fs.mkdir(next);
+    else if (!there.isDirectory())
+        throw entryInTheWayFault(next, writing, undefined);
+    return plainDirectoryUnder(next, rest, writing);
+}
+/** The components of `relative`, a path under a tree's root. A `..` would leave the tree: a defect in the caller. */
+function segmentsUnderRoot(relative) {
+    const segments = toForwardSlash(relative).split('/').filter((segment) => segment.length > 0 && segment !== '.');
+    if (segments.includes('..'))
+        throw new TypeError(`"${relative}" is not a path under the tree's root`);
+    return segments;
+}
+/**
+ * Make the directory `relative` under `root` — a tree VAT is building, which may hold whatever its
+ * source shipped, links included — without ever going through a link: every component must be a real
+ * directory (adopted when there, made by a plain `mkdir` when absent). What a recursive `mkdir`
+ * would do instead is follow a link standing where a component goes, out of the tree.
+ *
+ * @param root - The tree's root, which the caller made
+ * @param relative - The directory, relative to `root`, forward slashes
+ * @param writing - What the directory is for, for a refusal's message
+ * @returns The directory's path
+ * @throws FsFaultError side `source`, origin `content`, class `occupied`, naming the link or file
+ *   standing where a directory goes; any other failure is the raw errno
+ */
+export async function makeDirectoryUnder(root, relative, writing) {
+    return await plainDirectoryUnder(root, segmentsUnderRoot(relative), writing);
+}
+/**
+ * The ONE way VAT makes a file in a tree it is building — a staged tree that may hold whatever its
+ * source shipped, links included — without ever writing over or through what is already there.
+ *
+ * Every directory of `relative` under `root` must be a real directory (a link standing where one goes
+ * would carry the write outside the tree); a missing one is made by a plain `mkdir`. The file itself
+ * is made by `create`, which must be an EXCLUSIVE create (`wx`, which no link satisfies).
+ *
+ * @throws FsFaultError side `source`, origin `content`, class `occupied`, naming the entry in the
+ *   way; any other failure is the raw errno, for the caller's boundary to classify
+ */
+async function createUnder(root, relative, options, create) {
+    const segments = segmentsUnderRoot(relative);
+    const name = segments.at(-1);
+    if (name === undefined)
+        throw new TypeError(`"${relative}" names no file under the tree's root`);
+    const target = safePath.join(await plainDirectoryUnder(root, segments.slice(0, -1), options.writing), name);
+    if (options.existing === 'replace') {
+        const there = await entryAt(target);
+        if (there?.isFile() === true)
+            await fs.unlink(target);
+    }
+    try {
+        return await create(target);
+    }
+    catch (error) {
+        throw isAlreadyExistsError(error) ? entryInTheWayFault(target, options.writing, error) : error;
+    }
+}
+/**
+ * Write a file VAT makes into a tree it is building, never over or through what is already there
+ * (see {@link createUnder}: real directories only, an exclusive create, `existing` deciding the
+ * entry at the file's own name).
+ *
+ * @param root - The tree's root, which the caller made
+ * @param relative - The file, relative to `root`, forward slashes
+ * @param contents - Its bytes
+ * @param options - `existing`, and `writing`: what the file is, for a refusal's message
+ * @throws FsFaultError side `source`, origin `content`, class `occupied`, naming the entry in the
+ *   way; any other failure is the raw errno, for the caller's boundary to classify
+ */
+export async function writeFileUnder(root, relative, contents, options) {
+    await createUnder(root, relative, options, (target) => fs.writeFile(target, contents, { flag: 'wx' }));
+}
+/**
+ * {@link writeFileUnder} for bytes that are streamed: the file is made the same way and handed back
+ * OPEN, for the caller to fill and close. What the copy of one file into such a tree is built on.
+ *
+ * @returns The new file's handle, open for writing; the caller closes it
+ */
+export function openFileUnder(root, relative, options) {
+    return createUnder(root, relative, options, (target) => fs.open(target, 'wx'));
+}
+/** The classified fault disposing of `dir` raised, or `undefined` once it is gone. A non-filesystem error is a defect and propagates. */
+async function disposalFault(dir) {
+    try {
+        await removeEntry(dir);
+        return undefined;
+    }
+    catch (error) {
+        return classifiedDisposalFault(dir, error);
+    }
+}
+/** What a failed disposal of `dir` threw, classified; a non-filesystem error is a defect and is rethrown. */
+function classifiedDisposalFault(dir, error) {
+    // The action names the directory: what is left is all of it, while the errno may name an entry deep inside.
+    const fault = classifyFsFault(error, { side: 'environment', action: `remove the temporary directory ${dir}`, path: dir });
+    if (!isFsFaultError(fault))
+        throw error;
+    return fault;
+}
+/**
+ * Remove a temporary directory, its modes notwithstanding — only one strictly
+ * under the temp directory (`normalizedTmpdir()`): this removal makes a read-only
+ * tree writable before it deletes it, so a wrong argument (an empty string, a
+ * project directory) must be refused before anything is touched. A directory
+ * elsewhere that VAT owns goes through a `remove` plan.
+ *
+ * @param dir - The directory
+ * @returns `undefined` when it is gone (or was never there); otherwise the leftover: the
+ *   classified fault (an `FsFaultError`, side `environment`) whose message names the directory,
+ *   for the caller to report as the one `TREE_CLEANUP_INCOMPLETE` warning beside its work
+ * @throws VatError {@link TEMP_DIR_OUTSIDE_TMPDIR_CODE} — a defect in the caller — for a
+ *   directory not strictly under the temp directory, with nothing removed
+ */
+export async function disposeTempDir(dir) {
+    refuseOutsideTmpdir(dir);
+    return await disposalFault(dir);
+}
+/** How many times {@link disposeTempDirSync} retries a transient refusal (`EBUSY`, `EPERM`, `ENOTEMPTY`, …). */
+const SYNC_DISPOSAL_RETRIES = 4;
+/** The first retry's delay; each further one waits this much longer (Node's linear backoff). */
+const SYNC_DISPOSAL_RETRY_DELAY_MS = 40;
+/**
+ * {@link disposeTempDir}, synchronously — for a process on its way OUT, where no promise will ever
+ * settle: a signal handler about to re-raise, an `exit` listener. Same refusal of any directory not
+ * strictly under the temp directory, same answer.
+ *
+ * ⚠️ No mode repair: it is for a directory the process filled with its own ordinary files. A
+ * SHORT bounded retry ({@link SYNC_DISPOSAL_RETRIES} × {@link SYNC_DISPOSAL_RETRY_DELAY_MS}, linear
+ * backoff, at most ~0.4 s) covers the one transient refusal a dying process meets: on Windows a
+ * child it has just terminated still holds a handle in the directory for a moment, and removal
+ * answers `EBUSY`/`EPERM` until the OS lets go. Anything still there after it is answered as the
+ * leftover fault.
+ *
+ * @param dir - The directory
+ * @returns `undefined` when it is gone (or was never there); otherwise the leftover fault
+ * @throws VatError {@link TEMP_DIR_OUTSIDE_TMPDIR_CODE} — a defect in the caller — for a
+ *   directory not strictly under the temp directory, with nothing removed
+ */
+export function disposeTempDirSync(dir) {
+    refuseOutsideTmpdir(dir);
+    try {
+        rmSync(dir, { recursive: true, force: true, maxRetries: SYNC_DISPOSAL_RETRIES, retryDelay: SYNC_DISPOSAL_RETRY_DELAY_MS });
+        return undefined;
+    }
+    catch (error) {
+        return classifiedDisposalFault(dir, error);
+    }
+}
+/** Refuse (a defect in the caller) a directory to dispose of that is not strictly under the temp directory. */
+function refuseOutsideTmpdir(dir) {
+    const tmp = normalizedTmpdir();
+    const refusal = tempDirRefusal(dir, toForwardSlash(tmp), isUnderRoot(tmp, dir));
+    if (refusal !== undefined)
+        throw refusal;
+}
+/**
+ * Dispose of a temporary directory because the work that owned it failed — for a directory
+ * whose lifetime is not one call (one handed back to the caller on success, removed only on
+ * failure), where {@link withTempDir} cannot hold it. The failure stays the answer: a
+ * disposal fault is recorded beside it (`suppressedFaultsOf`), never thrown in its place.
+ *
+ * @param dir - The directory, strictly under the temp directory
+ * @param failure - What the work threw; the caller rethrows it
+ * @returns `undefined` when the directory went; otherwise the leftover fault, already recorded
+ *   beside `failure` — for a caller that must also say so where no report will carry the failure
+ * @throws VatError {@link TEMP_DIR_OUTSIDE_TMPDIR_CODE} — a defect in the caller — for a
+ *   directory not strictly under the temp directory, with nothing removed
+ */
+export async function disposeTempDirAfterFailure(dir, failure) {
+    refuseOutsideTmpdir(dir);
+    const fault = await disposalFault(dir);
+    if (fault !== undefined)
+        recordSuppressedFault(failure, fault);
+    return fault;
+}
+/**
+ * Run `work` in a fresh directory under the temp dir (`normalizedTmpdir()`), and
+ * dispose of it after, whatever happened.
+ *
+ * The work's error always wins: rethrown unchanged — never wrapped, never given a
+ * cause, never mutated — with a disposal failure recorded beside it
+ * (`suppressedFaultsOf`), so a report still names the directory left behind.
+ * When the work succeeded, nothing is thrown: the value comes back with the
+ * disposal's `leftover` (see {@link TempDirOutcome}), for the caller to report.
+ *
+ * @param prefix - `mkdtemp` prefix, so a leaked directory names its owner
+ * @param work - Given the directory's forward-slash path
+ */
+export async function withTempDir(prefix, work) {
+    const tmp = normalizedTmpdir();
+    const dir = toForwardSlash(await withFsFault({ side: 'environment', action: 'create a temporary directory', path: tmp }, () => fs.mkdtemp(safePath.join(tmp, prefix))));
+    let value;
+    try {
+        value = await work(dir);
+    }
+    catch (error) {
+        await disposeTempDirAfterFailure(dir, error);
+        throw error;
+    }
+    return { value, leftover: await disposalFault(dir) };
+}
+//# sourceMappingURL=files.js.map

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * The two refusals that bound a walk which FOLLOWS links: a link back into the
+ * walk ({@link FollowedWalk}, {@link DirectoryWalkRevisitedError}) and, for a walk
+ * contained to a root, a link out of it ({@link CopyLinkEscapesSourceError}).
+ * `proveTreeReadable` and `copyTree` under `links: 'follow-contained'` hold both;
+ * every other following walk holds a {@link FollowedWalk}.
+ */
+import { type FsSide } from '../errors/fs-fault.js';
+import { VatError } from '../errors/vat-error.js';
+/** The `VatError` code of a {@link DirectoryWalkRevisitedError}. */
+export declare const DIRECTORY_WALK_REVISITED_CODE = "DIRECTORY_WALK_REVISITED";
+/** Thrown when a following walk is led back into a directory it has already entered. */
+export declare class DirectoryWalkRevisitedError extends VatError {
+    constructor(dir: string, enteredAs: string);
+}
+/**
+ * The directories a FOLLOWING walk has entered, by realpath, so a link that
+ * leads back into the walk is refused instead of recursed until
+ * `ENAMETOOLONG`.
+ *
+ * A walk that follows links (`direntKindFollowing`) has no cycle guard by
+ * construction: `scripts/loop -> .` makes a copy create `dest/loop/loop/…`,
+ * writing every file at every level first, and a hashing walk do the same in
+ * memory. Every following walk holds one of these and calls {@link enter}
+ * on every directory it recurses into — the root included. A REVISIT is
+ * refused, not just a cycle: two links to one directory make the walk's
+ * output ambiguous (which spelling is the file's path?), and a refusal that
+ * names both spellings is the answer the author can act on.
+ */
+export declare class FollowedWalk {
+    #private;
+    /**
+     * @param side - The side of the verb the walked tree is on: a refused realpath in {@link enter} is a fault there
+     * @param within - The tree the walk is in (the operator's own input): every link beneath it is read before the kernel resolves it
+     */
+    constructor(side: FsSide, within: string);
+    /**
+     * Record that the walk is entering `dir`. Synchronous on purpose — one
+     * realpath per directory entered is nothing beside the listing itself, and
+     * the sync and async walkers then share one guard.
+     *
+     * @param dir - A directory the walk is about to list, in any spelling
+     * @throws {DirectoryWalkRevisitedError} When its realpath was entered before
+     * @throws FsFaultError on the walk's side (origin `content`) when the OS refuses to resolve it
+     */
+    enter(dir: string): void;
+}
+/** The `VatError` code of a {@link CopyLinkEscapesSourceError}. */
+export declare const COPY_LINK_ESCAPES_SOURCE_CODE = "COPY_LINK_ESCAPES_SOURCE";
+/** Thrown when a link inside a tree walked with `links: 'follow-contained'` points outside it. */
+export declare class CopyLinkEscapesSourceError extends VatError {
+    constructor(link: string, src: string);
+}
+//# sourceMappingURL=followed-walk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"followed-walk.d.ts","sourceRoot":"","sources":["../../src/tree-change/followed-walk.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAIlD,oEAAoE;AACpE,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE,wFAAwF;AACxF,qBAAa,2BAA4B,SAAQ,QAAQ;gBAC3C,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAM3C;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;;IAKvB;;;OAGG;gBACS,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAKxC;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAczB;AAED,mEAAmE;AACnE,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE,kGAAkG;AAClG,qBAAa,0BAA2B,SAAQ,QAAQ;gBAC1C,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM;CAQtC"}

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

@@ -0,0 +1,81 @@
+/**
+ * The two refusals that bound a walk which FOLLOWS links: a link back into the
+ * walk ({@link FollowedWalk}, {@link DirectoryWalkRevisitedError}) and, for a walk
+ * contained to a root, a link out of it ({@link CopyLinkEscapesSourceError}).
+ * `proveTreeReadable` and `copyTree` under `links: 'follow-contained'` hold both;
+ * every other following walk holds a {@link FollowedWalk}.
+ */
+import { classifyFsFault } from '../errors/fs-fault.js';
+import { VatError } from '../errors/vat-error.js';
+import { toForwardSlash } from '../path-core.js';
+import { normalizePath } from '../path-utils.js';
+/** The `VatError` code of a {@link DirectoryWalkRevisitedError}. */
+export const DIRECTORY_WALK_REVISITED_CODE = 'DIRECTORY_WALK_REVISITED';
+/** Thrown when a following walk is led back into a directory it has already entered. */
+export class DirectoryWalkRevisitedError extends VatError {
+    constructor(dir, enteredAs) {
+        super(DIRECTORY_WALK_REVISITED_CODE, `Refusing to enter ${dir}: it is the directory already walked as ${enteredAs} — a symlink leads the walk back into itself.`);
+    }
+}
+/**
+ * The directories a FOLLOWING walk has entered, by realpath, so a link that
+ * leads back into the walk is refused instead of recursed until
+ * `ENAMETOOLONG`.
+ *
+ * A walk that follows links (`direntKindFollowing`) has no cycle guard by
+ * construction: `scripts/loop -> .` makes a copy create `dest/loop/loop/…`,
+ * writing every file at every level first, and a hashing walk do the same in
+ * memory. Every following walk holds one of these and calls {@link enter}
+ * on every directory it recurses into — the root included. A REVISIT is
+ * refused, not just a cycle: two links to one directory make the walk's
+ * output ambiguous (which spelling is the file's path?), and a refusal that
+ * names both spellings is the answer the author can act on.
+ */
+export class FollowedWalk {
+    #entered = new Map();
+    #side;
+    #within;
+    /**
+     * @param side - The side of the verb the walked tree is on: a refused realpath in {@link enter} is a fault there
+     * @param within - The tree the walk is in (the operator's own input): every link beneath it is read before the kernel resolves it
+     */
+    constructor(side, within) {
+        this.#side = side;
+        this.#within = within;
+    }
+    /**
+     * Record that the walk is entering `dir`. Synchronous on purpose — one
+     * realpath per directory entered is nothing beside the listing itself, and
+     * the sync and async walkers then share one guard.
+     *
+     * @param dir - A directory the walk is about to list, in any spelling
+     * @throws {DirectoryWalkRevisitedError} When its realpath was entered before
+     * @throws FsFaultError on the walk's side (origin `content`) when the OS refuses to resolve it
+     */
+    enter(dir) {
+        const real = toForwardSlash(this.#realpath(dir));
+        const before = this.#entered.get(real);
+        if (before !== undefined)
+            throw new DirectoryWalkRevisitedError(dir, before);
+        this.#entered.set(real, dir);
+    }
+    #realpath(dir) {
+        try {
+            return normalizePath(dir, this.#within);
+        }
+        catch (error) {
+            throw classifyFsFault(error, { side: this.#side, origin: 'content', action: `resolve ${dir}`, path: dir });
+        }
+    }
+}
+/** The `VatError` code of a {@link CopyLinkEscapesSourceError}. */
+export const COPY_LINK_ESCAPES_SOURCE_CODE = 'COPY_LINK_ESCAPES_SOURCE';
+/** Thrown when a link inside a tree walked with `links: 'follow-contained'` points outside it. */
+export class CopyLinkEscapesSourceError extends VatError {
+    constructor(link, src) {
+        super(COPY_LINK_ESCAPES_SOURCE_CODE, `Refusing to copy ${link}: it is a symlink to a path outside ${src}. ` +
+            'A copy follows links, so this would ship content the source tree does not own — ' +
+            'replace the link with the files, or point it inside the tree.');
+    }
+}
+//# sourceMappingURL=followed-walk.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"followed-walk.js","sourceRoot":"","sources":["../../src/tree-change/followed-walk.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAe,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,oEAAoE;AACpE,MAAM,CAAC,MAAM,6BAA6B,GAAG,0BAA0B,CAAC;AAExE,wFAAwF;AACxF,MAAM,OAAO,2BAA4B,SAAQ,QAAQ;IACvD,YAAY,GAAW,EAAE,SAAiB;QACxC,KAAK,CACH,6BAA6B,EAC7B,qBAAqB,GAAG,2CAA2C,SAAS,+CAA+C,CAC5H,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,YAAY;IACd,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,KAAK,CAAS;IACd,OAAO,CAAS;IAEzB;;;OAGG;IACH,YAAY,IAAY,EAAE,MAAc;QACtC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,GAAW;QACf,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,2BAA2B,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7E,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,SAAS,CAAC,GAAW;QACnB,IAAI,CAAC;YACH,OAAO,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,eAAe,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;QAC7G,CAAC;IACH,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,CAAC,MAAM,6BAA6B,GAAG,0BAA0B,CAAC;AAExE,kGAAkG;AAClG,MAAM,OAAO,0BAA2B,SAAQ,QAAQ;IACtD,YAAY,IAAY,EAAE,GAAW;QACnC,KAAK,CACH,6BAA6B,EAC7B,oBAAoB,IAAI,uCAAuC,GAAG,IAAI;YACpE,kFAAkF;YAClF,+DAA+D,CAClE,CAAC;IACJ,CAAC;CACF"}

package/dist/tree-change/host-chain.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The link-chain resolver ({@link walkLinkChain}) bound to this host's filesystem: `lstat` and
+ * `readlink`, and nothing that follows a link. Every call VAT makes that FOLLOWS a link — a
+ * `stat`, a `realpath` — reads the chain here first (`link-following.ts`, `assertLocalChain`), so
+ * no lane — a write lane, a read lane, an untrusted tree or the user's own — hands the kernel a
+ * chain whose every text has not been read.
+ */
+import { VatError } from '../errors/vat-error.js';
+import { type ChainRefusal, type ChainRule, type LinkChain, type PlaceKind } from './link-chain.js';
+/**
+ * What stands at `path`, a link there not followed. A probe the OS refuses is thrown raw, for the
+ * caller to classify.
+ *
+ * ⚠️ "Not followed" is `lstat`'s word, and on Windows libuv keeps it only for what it calls a
+ * symbolic link: a junction to a volume (`\??\Volume{…}\`) and a reparse point of another tag
+ * (cloud files, dedup, WCI) are retried as a link-FOLLOWING `stat` and reported as the directory
+ * or file they lead to. Their targets are local — the kernel refuses a remote mount point — so no
+ * credential leaves the host, but the walk reads such a place as a plain directory where the
+ * kernel reparses it.
+ */
+export declare function hostPlaceKind(path: string): PlaceKind;
+/**
+ * Where `path` leads on this host's filesystem, under `rule` ({@link walkLinkChain}).
+ *
+ * @param path - Absolute, or relative to cwd; either separator
+ * @param rule - The flavor (bound from the host at the edge), the tree, and what the chain may do outside it
+ * @throws The raw errno of an `lstat` or `readlink` the OS refused, for the caller to classify
+ */
+export declare function walkHostChain(path: string, rule: ChainRule): LinkChain;
+/**
+ * A path VAT would not resolve: a link on the way to it leads to a network path, or the chain is
+ * longer than any kernel follows. A read lane records it as that one target's fault
+ * (`linkResolutionFault`); a lane that stops classifies it on its own side, like any refusal
+ * (`classifyFsFault`), so a destination's refused chain reads as the destination's.
+ */
+export declare class LinkChainRefusedError extends VatError {
+    /** The path whose resolution was asked. */
+    readonly path: string;
+    /** Why, with the link whose text decided it. */
+    readonly refusal: ChainRefusal;
+    constructor(path: string, refusal: ChainRefusal);
+}
+/** Whether `error` is a {@link LinkChainRefusedError}, by its code (a `dist` copy never `instanceof`-matches a `src` one). */
+export declare function isLinkChainRefusedError(error: unknown): error is VatError & {
+    readonly path: string;
+    readonly refusal: ChainRefusal;
+};
+//# sourceMappingURL=host-chain.d.ts.map

package/dist/tree-change/host-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-chain.d.ts","sourceRoot":"","sources":["../../src/tree-change/host-chain.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAc,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAG9D,OAAO,EAAmB,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAiB,KAAK,SAAS,EAAiB,MAAM,iBAAiB,CAAC;AAEnJ;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CASrD;AAKD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,SAAS,CAEtE;AAkBD;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ;IACjD,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;gBACnB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY;CAKhD;AAED,8HAA8H;AAC9H,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;CAAE,CAErI"}