@williamthorsen/toolbelt.filesystem 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.7.0 — 2026-08-21
+
+### Features
+
+- 🚨 **Breaking:** Fix createTempTree's symlink guard and disposal, and complete its entry API (#207)
+
+  Fixes an issue where `TempTree.symlink` in `@williamthorsen/toolbelt.filesystem/candidate` refused a target outside the tree and rewrote a relative target to an absolute path inside it. The containment check now applies to the link path alone and the target is stored as given, so a link reads back as the string that was passed.
+
+  Separately, fixes an issue where disposing a `TempTree` left the tree on disk when one of its directories had been made read-only.
+
+  Adds six methods to `TempTree`. `writeAll` applies the constructor's map of entries to a tree already built; `exists`, `list`, `read`, `readJson`, and `rm` read the tree back and remove from it, so a suite scaffolding through the handle reads its own fixture through it rather than reaching for `node:fs`.
+
+  Migration: A caller relying on the previous absolute storage passes `tree.resolve(target)`, which is written unchanged.
+
 ## 0.6.0 — 2026-08-16
 
 ### Features

package/README.md

@@ -3,13 +3,19 @@
 Filesystem utilities for TypeScript and JavaScript.
 
 <!-- section:release-notes -->
-## Release notes — v0.6.0 (2026-08-16)
+## Release notes — v0.7.0 (2026-08-21)
 
 ### Features
 
-- Add mkdir, symlink, write, and writeJson methods to `TempTree` (#176)
+- 🚨 **Breaking:** Fix createTempTree's symlink guard and disposal, and complete its entry API (#207)
 
-  Adds four write methods to `TempTree` in `@williamthorsen/toolbelt.filesystem`: `mkdir`, `symlink`, `write`, and `writeJson`. Each takes a tree-relative path, creates the parent directories it needs, resolves through the same containment check `resolve` applies, and returns the absolute path, so a suite writing into a built temporary tree reaches it through the handle rather than through `node:fs`. `symlink` accepts a link path and a target, and picks the link type from the target.
+  Fixes an issue where `TempTree.symlink` in `@williamthorsen/toolbelt.filesystem/candidate` refused a target outside the tree and rewrote a relative target to an absolute path inside it. The containment check now applies to the link path alone and the target is stored as given, so a link reads back as the string that was passed.
+
+  Separately, fixes an issue where disposing a `TempTree` left the tree on disk when one of its directories had been made read-only.
+
+  Adds six methods to `TempTree`. `writeAll` applies the constructor's map of entries to a tree already built; `exists`, `list`, `read`, `readJson`, and `rm` read the tree back and remove from it, so a suite scaffolding through the handle reads its own fixture through it rather than reaching for `node:fs`.
+
+  Migration: A caller relying on the previous absolute storage passes `tree.resolve(target)`, which is written unchanged.
 <!-- /section:release-notes -->
 
 ## Installation
@@ -292,10 +298,16 @@ A prefix that would place the tree anywhere but directly inside the system tempo
 ```ts
 interface TempTree extends Disposable {
   readonly dir: string;
+  exists(entryPath: string): boolean;
+  list(entryPath?: string): string[];
   mkdir(entryPath: string): string;
+  read(entryPath: string): string;
+  readJson(entryPath: string): unknown;
   resolve(...segments: string[]): string;
+  rm(entryPath: string): void;
   symlink(linkPath: string, targetPath: string): string;
   write(entryPath: string, contents: string | Uint8Array): string;
+  writeAll(entries: Record<string, string | Uint8Array>): void;
   writeJson(entryPath: string, value: unknown): string;
 }
 ```
@@ -304,7 +316,7 @@ interface TempTree extends Disposable {
 
 `resolve` joins `segments` against the root and throws when the result would fall outside it, so a stray `..` fails loudly rather than reaching into the enclosing directory. An absolute segment landing inside the root is returned unchanged. The containment test is lexical, so it does not follow a symlink inside the tree that points out of it.
 
-`mkdir`, `symlink`, `write`, and `writeJson` write into the tree after it is built, for a fixture that varies per test or a file created to trigger a re-read:
+`mkdir`, `symlink`, `write`, `writeAll`, and `writeJson` write into the tree after it is built, for a fixture that varies per test or a file created to trigger a re-read:
 
 ```ts
 using tree = createTempTree({ 'packages/app/package.json': '{ "name": "app" }' });
@@ -314,23 +326,47 @@ tree.writeJson('tsconfig.json', { include: ['src'] });
 tree.mkdir('packages/empty');
 ```
 
-Each creates the parent directories it needs, resolves through the same containment check as `resolve`, and returns the absolute path of what it wrote. Both of `symlink`'s paths are checked, so an escaping target is refused as well as an escaping link.
+Each creates the parent directories it needs, resolves through the same containment check as `resolve`, and returns the absolute path of what it wrote. `symlink`'s link path is checked; its target is not, being a string the link holds rather than a location the tree writes to.
+
+`writeAll` takes the same map the constructor takes, `/`-suffix convention included, so a fixture built in one call can be added to in one call:
+
+```ts
+tree.writeAll({ 'packages/empty/': '', 'packages/app/src/main.ts': 'export {};\n' });
+```
+
+It returns nothing, there being no single path to return, and unlike the constructor it is not atomic: a failure part-way leaves the entries already written in place, there being no whole tree to discard.
 
 They part company on an entry that already exists: `write` replaces it, `mkdir` leaves it and its contents alone, and `symlink` raises `EEXIST`.
 
-`symlink` takes the link first and the target second, inverting `fs.symlinkSync`, so that it reads like the other methods: the path being created leads. The link type is chosen from the target, which is where the one portability difference lives. A directory is linked as a junction, which Windows creates without the elevation a directory symlink needs; every other target, one that does not exist included, is linked as a file. That last case matches what Node falls back to when no type is given, and it leaves the link dangling until the target appears.
+`symlink` takes the link first and the target second, inverting `fs.symlinkSync`, so that it reads like the other methods: the path being created leads. The target is stored verbatim, so it may be absolute or relative, name something outside the tree, or dangle until the target appears; a relative one resolves against the link's own directory, as POSIX resolves it. Code under test that reads a link rather than following it therefore sees the string that was passed, which is what a consumer hashing a link's target depends on.
 
 ```ts
 using tree = createTempTree({ 'store/kit/package.json': '{ "name": "kit" }' });
 
-tree.symlink('node_modules/kit', 'store/kit'); // a junction, so Windows needs no elevation
+tree.symlink('node_modules/kit', '../store/kit'); // reads back as '../store/kit'
+tree.symlink('node_modules/.bin', tree.resolve('store/kit/bin')); // reads back absolute
+```
+
+The link type is chosen from the target, which is where the one portability difference lives. An absolute directory target is linked as a junction, which Windows creates without the elevation a directory symlink needs; a relative directory target is linked as a directory, which needs that elevation, because Node normalizes a junction's target to an absolute path and would discard the relative string. Every other target, one that does not exist included, is linked as a file, matching what Node falls back to when no type is given.
+
+`exists`, `list`, `read`, `readJson`, and `rm` read the tree back and remove from it, each through the same containment check:
+
+```ts
+using tree = createTempTree({ 'packages/app/package.json': '{ "name": "app" }', 'packages/app/src/main.ts': 'export {};\n' });
+
+tree.list(); // ['packages'], defaulting to the tree root
+tree.list('packages/app'); // ['package.json', 'src'], sorted
+tree.read('packages/app/src/main.ts'); // 'export {};\n'
+tree.readJson('packages/app/package.json'); // unknown, for the caller to narrow
+tree.exists('packages/app/tsconfig.json'); // false
+tree.rm('packages/app');
 ```
 
-The link stores an absolute path, which a junction requires. Code under test that reads a link rather than following it therefore sees a path under the tree root, where a package manager would have written a relative one; a fixture reproducing that shape reaches for `fs.symlinkSync` directly.
+`read` returns UTF-8 text, and a missing entry raises `ENOENT` rather than answering emptily -- `exists` is the check. `readJson` returns `unknown`, so a caller narrows it rather than trusting an asserted type; contents that do not parse raise an error naming the entry, which the parse error alone does not. `exists` follows a symlink, so a dangling one answers `false`. `rm` is recursive and silent on an entry that is not there.
 
 `writeJson` writes two-space-indented JSON ending in a newline, so a tree outliving a crashed run reads as a real config file would. A fixture needing exact bytes goes through `write` instead. A value `JSON.stringify` cannot represent -- `undefined`, a function, a symbol -- is refused rather than written, so an optional binding that arrived empty fails at the call that passed it instead of surfacing later as a parse error.
 
-Disposal is idempotent.
+Disposal is idempotent, and it removes a tree that has been made unwritable: unlinking an entry needs write permission on the directory containing it, so disposal restores permission across the tree and retries once before giving up. A suite that chmods a directory to exercise a write-failure path therefore needs no wrapper to chmod it back.
 
 `Disposable` is declared in `lib.esnext.disposable.d.ts` alone, so consuming this export requires `ESNext.Disposable` in your `lib`.
 

package/dist/esm/3-candidate/createTempTree.d.ts

@@ -4,9 +4,15 @@ export interface CreateTempTreeOptions {
 }
 export interface TempTree extends Disposable {
     readonly dir: string;
+    exists(entryPath: string): boolean;
+    list(entryPath?: string): string[];
     mkdir(entryPath: string): string;
+    read(entryPath: string): string;
+    readJson(entryPath: string): unknown;
     resolve(...segments: string[]): string;
+    rm(entryPath: string): void;
     symlink(linkPath: string, targetPath: string): string;
     write(entryPath: string, contents: string | Uint8Array): string;
+    writeAll(entries: Record<string, string | Uint8Array>): void;
     writeJson(entryPath: string, value: unknown): string;
 }

package/dist/esm/3-candidate/createTempTree.js

@@ -6,32 +6,45 @@ export function createTempTree(entries, options = {}) {
     assertNamesDirectChild(prefix);
     const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
     try {
-        for (const [entry, contents] of Object.entries(entries)) {
-            if (entry.endsWith('/')) {
-                mkdir(entry);
-            }
-            else {
-                write(entry, contents);
-            }
-        }
+        writeAll(entries);
     }
     catch (error) {
         fs.rmSync(dir, { force: true, recursive: true });
         throw error;
     }
+    function exists(entryPath) {
+        return fs.existsSync(resolveWithinTree(dir, [entryPath]));
+    }
+    function list(entryPath = '') {
+        return fs.readdirSync(resolveWithinTree(dir, [entryPath])).toSorted();
+    }
     function mkdir(entryPath) {
         const absolutePath = resolveWithinTree(dir, [entryPath]);
         fs.mkdirSync(absolutePath, { recursive: true });
         return absolutePath;
     }
+    function read(entryPath) {
+        return fs.readFileSync(resolveWithinTree(dir, [entryPath]), 'utf8');
+    }
+    function readJson(entryPath) {
+        const contents = read(entryPath);
+        try {
+            return JSON.parse(contents);
+        }
+        catch (error) {
+            throw new Error(`Entry "${entryPath}" is not readable as JSON`, { cause: error });
+        }
+    }
     function resolve(...segments) {
         return resolveWithinTree(dir, segments);
     }
+    function rm(entryPath) {
+        fs.rmSync(resolveWithinTree(dir, [entryPath]), { force: true, recursive: true });
+    }
     function symlink(linkPath, targetPath) {
         const absoluteLink = resolveWithinTree(dir, [linkPath]);
-        const absoluteTarget = resolveWithinTree(dir, [targetPath]);
         fs.mkdirSync(path.dirname(absoluteLink), { recursive: true });
-        fs.symlinkSync(absoluteTarget, absoluteLink, chooseLinkType(absoluteTarget));
+        fs.symlinkSync(targetPath, absoluteLink, chooseLinkType(absoluteLink, targetPath));
         return absoluteLink;
     }
     function write(entryPath, contents) {
@@ -40,6 +53,16 @@ export function createTempTree(entries, options = {}) {
         fs.writeFileSync(absolutePath, contents);
         return absolutePath;
     }
+    function writeAll(newEntries) {
+        for (const [entry, contents] of Object.entries(newEntries)) {
+            if (entry.endsWith('/')) {
+                mkdir(entry);
+            }
+            else {
+                write(entry, contents);
+            }
+        }
+    }
     function writeJson(entryPath, value) {
         const json = JSON.stringify(value, null, 2);
         if (json === undefined) {
@@ -49,13 +72,25 @@ export function createTempTree(entries, options = {}) {
     }
     return {
         dir,
+        exists,
+        list,
         mkdir,
+        read,
+        readJson,
         resolve,
+        rm,
         symlink,
         write,
+        writeAll,
         writeJson,
         [Symbol.dispose]() {
-            fs.rmSync(dir, { force: true, recursive: true });
+            try {
+                fs.rmSync(dir, { force: true, recursive: true });
+            }
+            catch {
+                restoreDirectoryPermissions(dir);
+                fs.rmSync(dir, { force: true, recursive: true });
+            }
         },
     };
 }
@@ -67,8 +102,21 @@ function assertNamesDirectChild(prefix) {
         throw new Error(`Temporary-directory prefix "${prefix}" names no new directory`);
     }
 }
-function chooseLinkType(targetPath) {
-    return fs.statSync(targetPath, { throwIfNoEntry: false })?.isDirectory() === true ? 'junction' : 'file';
+function chooseLinkType(absoluteLinkPath, targetPath) {
+    const resolvedTarget = path.resolve(path.dirname(absoluteLinkPath), targetPath);
+    if (fs.statSync(resolvedTarget, { throwIfNoEntry: false })?.isDirectory() !== true) {
+        return 'file';
+    }
+    return path.isAbsolute(targetPath) ? 'junction' : 'dir';
+}
+function restoreDirectoryPermissions(dir) {
+    fs.chmodSync(dir, 0o700);
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            restoreDirectoryPermissions(path.join(dir, entry.name));
+        }
+    }
 }
 function resolveWithinTree(dir, segments) {
     const target = path.resolve(dir, ...segments);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.filesystem",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Filesystem utilities",
   "keywords": [
     "config-cascade",
@@ -44,7 +44,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.errors": "0.5.0"
+    "@williamthorsen/toolbelt.errors": "0.6.0"
   },
   "engines": {
     "node": ">=24.0.0"