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

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

@@ -0,0 +1 @@
+{"version":3,"file":"copy-tree.d.ts","sourceRoot":"","sources":["../../src/tree-change/copy-tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAKrE,OAAO,EAAgC,KAAK,QAAQ,EAAwE,MAAM,qBAAqB,CAAC;AACxJ,OAAO,EAAE,KAAK,gBAAgB,EAAqC,MAAM,YAAY,CAAC;AAEtF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAA8B,KAAK,WAAW,EAAY,MAAM,gBAAgB,CAAC;AAqDxF,mGAAmG;AACnG,UAAU,eAAe;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AA+BD,wHAAwH;AACxH,MAAM,WAAW,eAAgB,SAAQ,wBAAwB;IAC/D,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,WAAW,CAgE7G;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtH;AAED,mIAAmI;AACnI,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBpI"}

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

@@ -0,0 +1,279 @@
+/**
+ * `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 fs from 'node:fs/promises';
+import { isAlreadyExistsError, isPathAbsentError } from '../errors/errno-table.js';
+import { classifyFsFault } from '../errors/fs-fault.js';
+import { linkCopyType } from '../link-following.js';
+import { safePath } from '../path-core.js';
+import { openForReading } from '../text-file.js';
+import { aliasFault, foldedNameIsTwin, mayTakeOver, nameOf, parentOf, sameNameWhereFolded } from './copy-decisions.js';
+import { makeDirectoryUnder, openFileUnder } from './files.js';
+import { sameEntry } from './identity.js';
+import { readingTree, treeReadFault, walkTree } from './tree-walk.js';
+/** The owner's read, write and search bits, kept on every copied directory so its owner can always fill and remove it. */
+const OWNER_RWX = 0o700;
+/** The bytes of an open file being copied; a read failure is `readFault`'s. A write failure never reaches this catch: the writer's loop ends the generator with `return()`, not `throw()`. */
+async function* sourceBytes(source, readFault) {
+    try {
+        yield* source.createReadStream({ autoClose: false, start: 0 });
+    }
+    catch (error) {
+        throw readFault(error);
+    }
+}
+/**
+ * Copy the bytes of an open file — one already judged a regular file on that very handle — into
+ * `claimed`, a file this copy has just made exclusively (opened `wx`), and carry its permission bits
+ * over, so a script stays executable — never its setuid, setgid or sticky bit. The ONE file copy of the tree copy and the
+ * single-file copy: bytes and mode both go to that very handle, never to a path, so nothing swapped
+ * in after the claim — a link least of all — is written or chmod-ed through. Closes `claimed`.
+ */
+async function copyOpenFileInto(handle, claimed, mode, readFault) {
+    try {
+        // On the handle, not through a stream of it: a stream owns the handle it writes and closes it
+        // with itself, before the mode could be set on it.
+        await claimed.writeFile(sourceBytes(handle, readFault));
+        // The permission bits only: setuid, setgid and sticky never travel with a copy.
+        await claimed.chmod(mode & 0o777);
+    }
+    catch (error) {
+        // The copy's own failure is the answer: a close refused after it is not a second one.
+        await claimed.close().catch(() => undefined);
+        throw error;
+    }
+    await claimed.close();
+}
+/**
+ * Make the root of a copy: with its parents when nothing is there, adopted when a real directory
+ * is. A link there — to a directory included — or a file is never adopted: the plain `mkdir` is the
+ * OS's own `EEXIST` for it, raw, as for any entry of a `fresh` destination.
+ */
+async function claimRoot(into) {
+    const there = await fs.lstat(into).catch((error) => {
+        if (isPathAbsentError(error))
+            return undefined;
+        throw error;
+    });
+    if (there === undefined)
+        await fs.mkdir(into, { recursive: true });
+    else if (!there.isDirectory())
+        await fs.mkdir(into);
+}
+/**
+ * Make the directory a copy goes into ({@link CopyDestination}): the root as the caller's, every
+ * component under it as a real directory or not at all.
+ *
+ * @param copied - What is copied, for a refusal's message
+ * @returns The directory's path
+ */
+async function claimDestination(into, copied) {
+    await claimRoot(into.root);
+    return into.relative === '' ? into.root : await makeDirectoryUnder(into.root, into.relative, `the copy of ${copied}`);
+}
+/**
+ * Make the directory a copy's own entry goes IN, for a source that is not a directory at all — a
+ * root that is a link, kept as one (`links: 'preserve'`): the destination root's parents as the
+ * caller's, every component under the root as a real directory or not at all.
+ *
+ * @param copied - What is copied, for a refusal's message
+ */
+async function claimParentOfDestination(into, copied) {
+    if (into.relative === '') {
+        await fs.mkdir(parentOf(into.root), { recursive: true });
+        return;
+    }
+    await claimRoot(into.root);
+    const parent = parentOf(into.relative);
+    if (parent !== '')
+        await makeDirectoryUnder(into.root, parent, `the copy of ${copied}`);
+}
+/**
+ * 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 function copyVisitor(where, copied, side, onto) {
+    const dest = where.relative === '' ? where.root : safePath.join(where.root, where.relative);
+    const target = (relative) => (relative === '' ? dest : safePath.join(dest, relative));
+    /** What this copy made, by the directory (relative to the root) it made it in. */
+    const made = new Map();
+    const madeIn = (parent) => {
+        const list = made.get(parent) ?? [];
+        made.set(parent, list);
+        return list;
+    };
+    const twinOf = async (entry, into) => {
+        const siblings = madeIn(parentOf(entry.relative));
+        const byIdentity = siblings.find((each) => sameEntry(target(each.relative), into) === 'same');
+        if (byIdentity !== undefined)
+            return byIdentity;
+        const byName = siblings.find((each) => sameNameWhereFolded(nameOf(each.relative), nameOf(entry.relative)));
+        if (byName === undefined)
+            return undefined;
+        // Absent or unexaminable alike: then the collision is all there is to go on, and the name decides.
+        const present = await fs.lstat(into).then(() => true, () => false);
+        return foldedNameIsTwin(sameEntry(target(byName.relative), into), present) ? byName : undefined;
+    };
+    /**
+     * Claim `entry`'s place by `claim` — an exclusive create, and nothing else, so it can be asked
+     * twice — and hand back what it made (`undefined`: a directory a merge adopted).
+     */
+    const create = async (entry, kind, claim) => {
+        const into = target(entry.relative);
+        const claimed = await claim(into).catch(async (error) => {
+            if (!isAlreadyExistsError(error))
+                throw error;
+            const twin = await twinOf(entry, into);
+            if (twin !== undefined)
+                throw aliasFault(twin, entry, error);
+            const takeOver = mayTakeOver(onto, kind, onto === 'merge' ? (await fs.lstat(into)).isDirectory() : false);
+            if (takeOver === 'refuse')
+                throw error;
+            if (takeOver === 'adopt')
+                return undefined;
+            await fs.unlink(into);
+            return claim(into);
+        });
+        madeIn(parentOf(entry.relative)).push(entry);
+        return claimed;
+    };
+    return {
+        async directory(entry, stats) {
+            const into = target(entry.relative);
+            if (entry.relative === '')
+                await claimDestination(where, copied);
+            else
+                await create(entry, 'directory', (path) => fs.mkdir(path));
+            await fs.chmod(into, (stats.mode & 0o7777) | OWNER_RWX);
+        },
+        async file(entry, handle, stats) {
+            const claimed = await create(entry, 'leaf', (into) => fs.open(into, 'wx'));
+            if (claimed !== undefined)
+                await copyOpenFileInto(handle, claimed, stats.mode, (error) => treeReadFault(side, entry.path, error));
+        },
+        async link(entry) {
+            const linkTarget = await readingTree(side, entry.path, () => fs.readlink(entry.path));
+            // Typed from the chain read by its text, before anything is made: an untyped `symlink` has
+            // Node on Windows ask the kernel to follow the target to pick `file` or `dir`, so a network or
+            // device text — at any hop — is refused here, on the copied tree's side, never handed on.
+            const type = await readingTree(side, entry.path, () => Promise.resolve().then(() => linkCopyType(entry.path, copied)));
+            // The source itself is a link: there is no copied directory to hold it, so its place is made first.
+            if (entry.relative === '')
+                await claimParentOfDestination(where, copied);
+            // Verbatim. A host that cannot make the link (Windows without the privilege: EPERM; a
+            // filesystem with none: ENOTSUP) raises the raw errno, a write like any other, for the
+            // caller's boundary to classify.
+            await create(entry, 'leaf', (into) => fs.symlink(linkTarget, into, type));
+        },
+    };
+}
+/**
+ * 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 async function copyTree(source, root, relative, options) {
+    await walkTree(source, options, options.side, copyVisitor({ root, relative }, source, options.side, options.onto));
+}
+/**
+ * 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 async function copyRegularFile(source, root, relative, options) {
+    // Every read — the open, the `fstat`, the stream, the close — names what was read, on its side.
+    const readFault = (error) => classifyFsFault(error, { side: options.side, origin: 'content', action: `read ${options.reading}`, path: source });
+    const reading = async (read) => {
+        try {
+            return await read();
+        }
+        catch (error) {
+            throw readFault(error);
+        }
+    };
+    const handle = await reading(() => openForReading(source));
+    try {
+        const stats = await reading(() => handle.stat());
+        // Only once the source is open and judged: a `replace` removes nothing for a copy that cannot be read.
+        const claimed = await openFileUnder(root, relative, options);
+        await copyOpenFileInto(handle, claimed, stats.mode, readFault);
+    }
+    catch (error) {
+        // The copy's own failure is the answer: a close refused after it is not a second one.
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+    // The close is a read of the source, too: a refusal of it is on the source's side.
+    await reading(() => handle.close());
+}
+//# sourceMappingURL=copy-tree.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"copy-tree.js","sourceRoot":"","sources":["../../src/tree-change/copy-tree.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAuB,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,eAAe,EAAe,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAmC,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AACxJ,OAAO,EAAyB,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAoB,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAExF,0HAA0H;AAC1H,MAAM,SAAS,GAAG,KAAK,CAAC;AAKxB,8LAA8L;AAC9L,KAAK,SAAS,CAAC,CAAC,WAAW,CAAC,MAAkB,EAAE,SAAoB;IAClE,IAAI,CAAC;QACH,KAAK,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAA0B,CAAC;IAC1F,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,gBAAgB,CAAC,MAAkB,EAAE,OAAmB,EAAE,IAAY,EAAE,SAAoB;IACzG,IAAI,CAAC;QACH,8FAA8F;QAC9F,mDAAmD;QACnD,MAAM,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;QACxD,gFAAgF;QAChF,MAAM,OAAO,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,sFAAsF;QACtF,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC7C,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,SAAS,CAAC,IAAY;IACnC,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC1D,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC/C,MAAM,KAAK,CAAC;IACd,CAAC,CAAC,CAAC;IACH,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;SAC9D,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;QAAE,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAmBD;;;;;;GAMG;AACH,KAAK,UAAU,gBAAgB,CAAC,IAAqB,EAAE,MAAc;IACnE,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,IAAI,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,kBAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,eAAe,MAAM,EAAE,CAAC,CAAC;AACxH,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,wBAAwB,CAAC,IAAqB,EAAE,MAAc;IAC3E,IAAI,IAAI,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QACzB,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACzD,OAAO;IACT,CAAC;IACD,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,EAAE;QAAE,MAAM,kBAAkB,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,MAAM,EAAE,CAAC,CAAC;AAC1F,CAAC;AAQD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,WAAW,CAAC,KAAsB,EAAE,MAAc,EAAE,IAAY,EAAE,IAAc;IAC9F,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC5F,MAAM,MAAM,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC,CAAC,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IACtG,kFAAkF;IAClF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC9C,MAAM,MAAM,GAAG,CAAC,MAAc,EAAiB,EAAE;QAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACpC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,KAAK,EAAE,KAAkB,EAAE,IAAY,EAAoC,EAAE;QAC1F,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;QAClD,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC;QAC9F,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,UAAU,CAAC;QAChD,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC3G,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC3C,mGAAmG;QACnG,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;QACnE,OAAO,gBAAgB,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAClG,CAAC,CAAC;IACF;;;OAGG;IACH,MAAM,MAAM,GAAG,KAAK,EAAK,KAAkB,EAAE,IAA0B,EAAE,KAAmC,EAA0B,EAAE;QACtI,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAc,EAA0B,EAAE;YACvF,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC;gBAAE,MAAM,KAAK,CAAC;YAC9C,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YACvC,IAAI,IAAI,KAAK,SAAS;gBAAE,MAAM,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;YAC7D,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YAC1G,IAAI,QAAQ,KAAK,QAAQ;gBAAE,MAAM,KAAK,CAAC;YACvC,IAAI,QAAQ,KAAK,OAAO;gBAAE,OAAO,SAAS,CAAC;YAC3C,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACtB,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7C,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IACF,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK;YAC1B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YACpC,IAAI,KAAK,CAAC,QAAQ,KAAK,EAAE;gBAAE,MAAM,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;;gBAC5D,MAAM,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YAChE,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;QAC1D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK;YAC7B,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YAC3E,IAAI,OAAO,KAAK,SAAS;gBAAE,MAAM,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAC,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QACnI,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAK;YACd,MAAM,UAAU,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YACtF,2FAA2F;YAC3F,+FAA+F;YAC/F,0FAA0F;YAC1F,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;YACvH,oGAAoG;YACpG,IAAI,KAAK,CAAC,QAAQ,KAAK,EAAE;gBAAE,MAAM,wBAAwB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YACzE,sFAAsF;YACtF,uFAAuF;YACvF,iCAAiC;YACjC,MAAM,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC5E,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,MAAc,EAAE,IAAY,EAAE,QAAgB,EAAE,OAAwB;IACrG,MAAM,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AACrH,CAAC;AAUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAc,EAAE,IAAY,EAAE,QAAgB,EAAE,OAA+B;IACnH,gGAAgG;IAChG,MAAM,SAAS,GAAc,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3J,MAAM,OAAO,GAAG,KAAK,EAAK,IAAsB,EAAc,EAAE;QAC9D,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;IACH,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3D,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QACjD,uGAAuG;QACvG,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC7D,MAAM,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,sFAAsF;QACtF,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC5C,MAAM,KAAK,CAAC;IACd,CAAC;IACD,mFAAmF;IACnF,MAAM,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;AACtC,CAAC"}

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

@@ -0,0 +1,167 @@
+/**
+ * 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 { type FileHandle } from 'node:fs/promises';
+export { TEMP_DIR_OUTSIDE_TMPDIR_CODE } from './apply-decisions.js';
+/**
+ * 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 declare function renameFileAtomic(from: string, to: string): Promise<void>;
+/**
+ * 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 declare function removeEntry(entry: string): Promise<void>;
+/**
+ * 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 declare function replaceFile(dest: string, contents: string | Uint8Array): Promise<void>;
+/**
+ * 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 declare function makeDirectoryUnder(root: string, relative: string, writing: string): Promise<string>;
+/** What decides the entry already AT the name of a file VAT makes under a tree, and what a refusal calls the file. */
+export interface FileUnderOptions {
+    /**
+     * - `refuse`: anything there refuses the file.
+     * - `replace`: a regular file there is removed first (VAT's own earlier output, or a file the source
+     *   shipped that VAT's supersedes); a link or a directory still refuses.
+     */
+    readonly existing: 'refuse' | 'replace';
+    /** What the file is, for a refusal's message. */
+    readonly writing: string;
+}
+/**
+ * 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 declare function writeFileUnder(root: string, relative: string, contents: string | Uint8Array, options: FileUnderOptions): Promise<void>;
+/**
+ * {@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 declare function openFileUnder(root: string, relative: string, options: FileUnderOptions): Promise<FileHandle>;
+/**
+ * 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 declare function disposeTempDir(dir: string): Promise<unknown>;
+/**
+ * {@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 declare function disposeTempDirSync(dir: string): unknown;
+/**
+ * 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 declare function disposeTempDirAfterFailure(dir: string, failure: unknown): Promise<unknown>;
+/** What {@link withTempDir} hands back once its work SUCCEEDED: the work's value, and what the disposal left. */
+export interface TempDirOutcome<T> {
+    /** What `work` returned. */
+    readonly value: T;
+    /**
+     * `undefined` when the directory went; otherwise the classified fault (an `FsFaultError`, side
+     * `environment`, its message naming the directory) of a directory the OS would not remove. The
+     * work is DONE: this is never its refusal, but the one `TREE_CLEANUP_INCOMPLETE` warning a verb
+     * reports beside the work it finished.
+     */
+    readonly leftover: unknown;
+}
+/**
+ * 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 declare function withTempDir<T>(prefix: string, work: (dir: string) => Promise<T>): Promise<TempDirOutcome<T>>;
+//# sourceMappingURL=files.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/tree-change/files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAW,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAmBvD,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAWpE;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAExE;AA4BD;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9D;AA+DD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB5F;AAkCD;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEzG;AAED,sHAAsH;AACtH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AA6BD;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5I;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAE5G;AAoBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAGlE;AAOD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQvD;AASD;;;;;;;;;;;;GAYG;AACH,wBAAsB,0BAA0B,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAKhG;AAED,iHAAiH;AACjH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAWlH"}