@williamthorsen/toolbelt.filesystem 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.4.0 — 2026-08-12
+
+### Features
+
+- 🚨 **Breaking:** Add reconcileFile to toolbelt.filesystem and promote describeError to release tier (#122)
+
+  Adds `reconcileFile` to `@williamthorsen/toolbelt.filesystem`: an idempotent file write that creates what is missing, refuses by default to replace what is not, and reports which of those it did as a structured outcome rather than throwing.
+
+  Separately, `describeError` is promoted to `@williamthorsen/toolbelt.errors`' release tier, so no release-tier module depends on a candidate one.
+
+  Migration: `describeError` is imported from `@williamthorsen/toolbelt.errors` rather than `@williamthorsen/toolbelt.errors/candidate`, which no longer exports it. `chainError`, `isError`, and `assertIsError` remain at candidate tier.
+
+- Add reconcileFileFromFile to toolbelt.filesystem (#123)
+
+  Adds `reconcileFileFromFile` to `@williamthorsen/toolbelt.filesystem`. It reads a source path as utf8 text and reconciles a destination against it, sharing `reconcileFile`'s options, outcome vocabulary, and `FileReconciliation` result type.
+
+  A source that cannot be read reports `failed` with a reason naming the source and the cause, rather than throwing. Because the outcome depends on the source's content, the read happens even under `isDryRun`, so a dry run can report `failed` where `reconcileFile`'s cannot.
+
+## 0.3.0 — 2026-08-08
+
+### Features
+
+- Migrate replaceFileExtension into filesystem package (#74)
+
+  Adds `replaceFileExtension` to the filesystem utilities. The function replaces the file extension in a file path; unlike analogous built-in functions, it supports multi-part extensions such as `.d.ts`.
+
+- Add directory-chain ascent and lookup exports (#102)
+
+  Adds three functions for upward directory search, which walk from a starting directory to either the filesystem root or a bounded ceiling, finding named files or directories at each level along the way:
+
+  - `listDirectoryChain` returns the directories alone
+  - `listDirectoryChainMatches` returns every level's match
+  - `findDirectoryChainMatch` finds only the nearest match
+
+  All three reject a path that falls outside the range they were asked to search. `findProjectRoot` now applies that same rule to its markers.
+
+- Add createTempTree with scope-bound disposal (#106)
+
+  Adds `createTempTree` to `@williamthorsen/toolbelt.filesystem/proposed`. The new function allows a caller to describe a directory tree as a plain object mapping paths to contents and receive a handle in return; the tree is removed when that handle goes out of scope.
+
+- 🚨 **Breaking:** Add findPackageRoot, getSelfVersion, and findProjectRoot to toolbelt.packaging (#107)
+
+  Adds a way for any module, whether it runs from a source tree or a compiled build, to identify the package that owns it and the version that package declares.
+
+  `findProjectRoot` moves from `@williamthorsen/toolbelt.filesystem` to `@williamthorsen/toolbelt.packaging`. Callers of `loadConfigCascade` must now state where its upward search stops, rather than relying on a project root the function found for them.
+
+### Tooling
+
+- Migrate Vitest configs to the nmr projects model (#73)
+
+  Packages no longer need to declare their own Vitest config. Test suites are now selected by a test file's name suffix rather than by choosing a config file: `*.app.test.ts` and `*.int.test.ts` route to the app and integration suites, and everything else runs as a unit test. Local development is now declared to require Node 24.16 or later.
+
+- Use identical compiler settings for all packages (#105)
+
+  All packages now have identical compiler settings, using the settings from the `@williamthorsen/tsconfig` base config without modification.
+
 ## 0.2.1 — 2026-07-27
 
 ### Tooling

package/README.md

@@ -2,7 +2,25 @@
 
 Filesystem utilities for TypeScript and JavaScript.
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v0.4.0 (2026-08-12)
+
+### Features
+
+- 🚨 **Breaking:** Add reconcileFile to toolbelt.filesystem and promote describeError to release tier (#122)
+
+  Adds `reconcileFile` to `@williamthorsen/toolbelt.filesystem`: an idempotent file write that creates what is missing, refuses by default to replace what is not, and reports which of those it did as a structured outcome rather than throwing.
+
+  Separately, `describeError` is promoted to `@williamthorsen/toolbelt.errors`' release tier, so no release-tier module depends on a candidate one.
+
+  Migration: `describeError` is imported from `@williamthorsen/toolbelt.errors` rather than `@williamthorsen/toolbelt.errors/candidate`, which no longer exports it. `chainError`, `isError`, and `assertIsError` remain at candidate tier.
+
+- Add reconcileFileFromFile to toolbelt.filesystem (#123)
+
+  Adds `reconcileFileFromFile` to `@williamthorsen/toolbelt.filesystem`. It reads a source path as utf8 text and reconciles a destination against it, sharing `reconcileFile`'s options, outcome vocabulary, and `FileReconciliation` result type.
+
+  A source that cannot be read reports `failed` with a reason naming the source and the cause, rather than throwing. Because the outcome depends on the source's content, the read happens even under `isDryRun`, so a dry run can report `failed` where `reconcileFile`'s cannot.
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -12,64 +30,110 @@ pnpm add @williamthorsen/toolbelt.filesystem
 
 ## Runtime requirements
 
-Both functions reach the filesystem through `node:` builtins, so they run under Node.js 24 or later, Bun, and Deno. They do not run in browsers, nor in edge runtimes that expose no filesystem.
+`createTempTree`, `findDirectoryChainMatch`, `listDirectoryChainMatches`, `loadConfigCascade`, `reconcileFile`, and `reconcileFileFromFile` reach the filesystem through `node:` builtins, so they run under Node.js 24 or later, Bun, and Deno. They do not run in browsers, nor in edge runtimes that expose no filesystem. `listDirectoryChain` and `replaceFileExtension` touch no filesystem, so an edge runtime that exposes none runs them; they still import `node:path`, which a browser bundle has to supply.
 
 `loadConfigCascade` imports each config through the host runtime, so a `.ts` config is subject to whatever that runtime does with TypeScript. Node strips types rather than compiling them, which admits erasable syntax alone: an `enum`, a `namespace`, or a parameter property in a config file fails to parse. A `.mjs` or `.js` config sidesteps the question.
 
-## `findProjectRoot`
+## `listDirectoryChain`
 
 ```ts
-findProjectRoot(startDir: string, options?: { markers?: ReadonlyArray<string> }): ProjectRoot;
+listDirectoryChain(startDir: string, options?: { stopAtDir?: string }): [string, ...string[]];
 ```
 
-Resolves `startDir` to an absolute path, ascends from it, and returns the first directory carrying a root marker, along with the evidence that identified it:
+Resolves `startDir` to an absolute path and returns it followed by each of its ancestors, nearest first. It manipulates paths as strings and reads nothing from disk.
 
 ```ts
-interface ProjectRoot {
-  marker: string | null; // the marker that matched, or null when a fallback answered
-  rootDir: string;
-  source: 'marker' | 'package-json' | 'start-dir';
-}
+import { listDirectoryChain } from '@williamthorsen/toolbelt.filesystem';
+
+listDirectoryChain('/home/dev/app/src');
+// ['/home/dev/app/src', '/home/dev/app', '/home/dev', '/home', '/']
+
+listDirectoryChain('/home/dev/app/src', { stopAtDir: '/home/dev' });
+// ['/home/dev/app/src', '/home/dev/app', '/home/dev']
+```
+
+`stopAtDir` bounds the ascent inclusively and is resolved the same way `startDir` is, so a relative ceiling behaves like a relative start. One that is neither the start directory nor an ancestor of it throws, naming both, rather than being ignored and letting the ascent run past the bound. The comparison is exact, so a `stopAtDir` differing from its target only in case is off the chain even on a volume that would open it.
+
+The result type records that the chain is never empty, which is what spares the nearest directory an undefined check:
+
+```ts
+const [nearestDir] = listDirectoryChain(process.cwd()); // string, not string | undefined
 ```
 
-`DEFAULT_ROOT_MARKERS` is consulted in order, so the earliest entry wins when one directory carries several:
+The ascent terminates at the filesystem root on every platform, so a Windows drive root or UNC share is as safe a starting point as a POSIX path.
+
+## `listDirectoryChainMatches`
+
+```ts
+listDirectoryChainMatches(
+  startDir: string,
+  names: ReadonlyArray<string>,
+  options?: { stopAtDir?: string },
+): DirectoryChainMatch[];
+```
 
-1. `.git`, matching either a directory (an ordinary clone) or a file (a worktree or submodule);
-2. `pnpm-workspace.yaml`;
-3. `pnpm-lock.yaml`;
-4. `package-lock.json`;
-5. `yarn.lock`;
-6. `bun.lock`.
+Returns, for each directory in the chain at or above `startDir`, the first of `names` that exists there:
 
-Passing `markers` replaces that list rather than extending it. Spread `DEFAULT_ROOT_MARKERS` to add to it:
+```ts
+interface DirectoryChainMatch {
+  dir: string; // the chain level, which differs from the entry's own directory for a nested name
+  entryName: string;
+  entryPath: string;
+}
+```
 
 ```ts
-import { DEFAULT_ROOT_MARKERS, findProjectRoot } from '@williamthorsen/toolbelt.filesystem';
+import { listDirectoryChainMatches } from '@williamthorsen/toolbelt.filesystem';
 
-findProjectRoot(process.cwd(), { markers: [...DEFAULT_ROOT_MARKERS, 'deno.json'] });
+listDirectoryChainMatches('/home/dev/app/src', ['.git'], { stopAtDir: '/home/dev' });
+// [{ dir: '/home/dev/app', entryName: '.git', entryPath: '/home/dev/app/.git' }]
 ```
 
-When no directory up to and including the filesystem root carries a marker, the result falls back in this order, reporting a `null` marker either way:
+A level yields at most one match, the earliest of `names` found there, and a level holding none contributes nothing, so an empty result is an ordinary outcome rather than an error. A name matches a directory as readily as a file, which is what lets `.git` be probed without knowing whether the clone is ordinary or a worktree.
 
-1. the nearest ancestor holding a `package.json`, reported as `source: 'package-json'`;
-2. `startDir` itself, reported as `source: 'start-dir'`.
+Each name is a path relative to the level it is probed against, so a nested location such as `.config/stack.config.mjs` works. A name that would leave its level (an absolute path, or one whose `..` segments escape it) is rejected before any level is probed, so the rejection never depends on what happens to exist on disk.
 
-The ascent terminates at the filesystem root on every platform, so a Windows drive root or UNC share is as safe a starting point as a POSIX path.
+`options` is forwarded to `listDirectoryChain`, so `stopAtDir` bounds the ascent the same way.
+
+Every level is probed, because every level's match is reported. Where only the nearest match matters, [`findDirectoryChainMatch`](#finddirectorychainmatch) returns it and stops there.
+
+## `findDirectoryChainMatch`
+
+```ts
+findDirectoryChainMatch(
+  startDir: string,
+  names: ReadonlyArray<string>,
+  options?: { stopAtDir?: string },
+): DirectoryChainMatch | undefined;
+```
+
+Returns the nearest directory at or above `startDir` holding one of `names`, or `undefined` when none does. It is `listDirectoryChainMatches` narrowed to the first hit, sharing its result shape, its options, and its name validation:
+
+```ts
+import { findDirectoryChainMatch } from '@williamthorsen/toolbelt.filesystem';
+
+findDirectoryChainMatch('/home/dev/app/src', ['.git']);
+// { dir: '/home/dev/app', entryName: '.git', entryPath: '/home/dev/app/.git' }
+```
+
+Probing stops at the first level that matches, so no level beyond it is touched — the reason to reach for this rather than read element zero off `listDirectoryChainMatches`, which probes to the ceiling regardless. The nullable return type is the other reason: a result that may be absent says so, where an array leaves the caller to narrow.
 
 ## `loadConfigCascade`
 
 ```ts
 loadConfigCascade<TConfig>(options: {
   fileNames: ReadonlyArray<string>;
-  markers?: ReadonlyArray<string>;
   shouldStopAscent?: (config: TConfig) => boolean;
   startDir: string;
+  stopAtDir: string;
 }): Promise<ConfigCascade<TConfig>>;
 ```
 
-Loads every config file between `startDir` and its project root, nearest first, and reads nothing above that root.
+Loads every config file between `startDir` and `stopAtDir`, nearest first, and reads nothing above that boundary.
+
+Discovery is [`listDirectoryChainMatches`](#listdirectorychainmatches) bounded at `stopAtDir`: the first of `fileNames` that exists at a level becomes that level's config, a level holding none contributes nothing, and a name that would leave its level is rejected before any file is read. A `stopAtDir` that is neither the start directory nor one of its ancestors throws, on the same terms `listDirectoryChain` sets out.
 
-At each level from `startDir` up to and including the root, the first of `fileNames` that exists becomes that level's config; a level holding none contributes nothing. Each name is a path relative to the level, so a nested location such as `.config/stack.config.mjs` works. A name that would leave its level (an absolute path, or one whose `..` segments escape it) is rejected before any file is read, since following it would breach the bound the cascade exists to enforce. The project root is resolved by `findProjectRoot`, and `markers` is forwarded to it.
+The boundary is required, and it is the caller's to choose. That is what keeps this function free of any notion of what marks a project: it never asks whether a directory holds a lockfile or a workspace manifest. Where the boundary should be a project root, [`findProjectRoot`](https://github.com/williamthorsen/toolbelt/tree/main/packages/packaging#findprojectroot) in `@williamthorsen/toolbelt.packaging` resolves one from markers.
 
 The matched files are then imported one at a time, and `shouldStopAscent` is consulted after each. Once it returns true, the ascent halts and no farther file is imported at all, rather than being loaded and discarded:
 
@@ -80,8 +144,7 @@ interface ConfigCascade<TConfig> {
     dir: string; // the cascade level, which differs from the file's own directory for a nested file name
     filePath: string;
   }>;
-  projectRoot: ProjectRoot;
-  stopReason: 'predicate' | 'project-root';
+  stopReason: 'predicate' | 'stop-dir';
 }
 ```
 
@@ -93,17 +156,173 @@ The predicate is the caller's whole stop policy, so any field can drive it. By c
 
 ```ts
 import { loadConfigCascade } from '@williamthorsen/toolbelt.filesystem';
+import { findProjectRoot } from '@williamthorsen/toolbelt.packaging';
 
 interface StackConfig {
   rules?: Record<string, string>;
   shouldStopAscent?: boolean;
 }
 
-const { entries, projectRoot, stopReason } = await loadConfigCascade<StackConfig>({
+const { rootDir } = findProjectRoot(process.cwd());
+
+const { entries, stopReason } = await loadConfigCascade<StackConfig>({
   fileNames: ['stack.config.mjs', 'stack.config.js'],
   shouldStopAscent: (config) => config.shouldStopAscent === true,
   startDir: process.cwd(),
+  stopAtDir: rootDir,
 });
 ```
 
-`projectRoot` and `stopReason` are provenance for the caller to surface, so a user can see which directory bounded the cascade and what ended it.
+`stopReason` is provenance for the caller to surface, so a user can see whether the predicate ended the cascade or it simply reached the boundary. Which directory bounded it is the `stopAtDir` the caller passed in.
+
+## `reconcileFile`
+
+```ts
+reconcileFile(
+  filePath: string,
+  content: string,
+  options?: { conflictPolicy?: 'replace' | 'skip'; isDryRun?: boolean },
+): FileReconciliation;
+```
+
+Writes `content` to `filePath` and reports what the write took, rather than throwing:
+
+```ts
+import { reconcileFile } from '@williamthorsen/toolbelt.filesystem';
+
+reconcileFile('.config/tool.config.ts', template);
+// { filePath: '.config/tool.config.ts', outcome: 'created' }
+```
+
+Missing parent directories are created. `isDryRun` writes nothing and creates no directory, returning the outcome the real call would have produced, which is what lets a `--dry-run` flag print the same lines the run itself would. A write that would fail is the exception: nothing detects that without attempting it, so a dry run reports the outcome the write was headed for.
+
+`conflictPolicy` decides what becomes of an existing file whose content differs, and decides nothing else: it is consulted in that case alone. The default, `'skip'`, never replaces a file the user may have edited.
+
+| exists | differs | `conflictPolicy` | outcome       |
+| ------ | ------- | ---------------- | ------------- |
+| no     | —       | —                | `created`     |
+| yes    | no      | either           | `up-to-date`  |
+| yes    | yes     | `replace`        | `overwritten` |
+| yes    | yes     | `skip`           | `skipped`     |
+
+What counts as differing follows the policy, which is the part worth reading twice. `'replace'` promises the file holds exactly `content` afterwards, so only byte-identical content reports `up-to-date`; a file differing from `content` only in trailing whitespace is rewritten, because calling it up to date would leave the caller holding a file that is not what it asked for. `'skip'` modifies nothing either way, so its comparison decides a message alone and ignores trailing whitespace per line and at end of file, which keeps formatter churn from reading as a conflict. `up-to-date` therefore means the same thing under both: this policy has no work to do.
+
+The result discriminates on `outcome`, so a failure always carries its reason:
+
+```ts
+type FileReconciliation =
+  | { filePath: string; outcome: 'created' | 'overwritten' | 'up-to-date' }
+  | { filePath: string; outcome: 'skipped'; error?: string }
+  | { filePath: string; outcome: 'failed'; error: string };
+```
+
+An I/O error on the write path reports `failed` rather than throwing, which is what lets a command writing several files collect a result for each instead of losing the rest to the first failure.
+
+Three behaviors are worth knowing before they surprise you:
+
+- A `skipped` result carrying an `error` means the existing file could not be read for comparison. The file was left alone, which is exactly what `'skip'` promises, so this is not a failure and a command exiting non-zero on failures should not count it as one.
+- The existence probe follows symlinks. A dangling symlink therefore reports as non-existent: the outcome is `created`, the result names the link, and the bytes land at the link's target.
+- The probe and the write are separate calls, leaving a window in which another process can create or remove the file. That gap is left open deliberately: the callers this serves are scaffolding commands with no competing writer, and an exclusive-create flag would close only the create half of it.
+
+## `reconcileFileFromFile`
+
+```ts
+reconcileFileFromFile(
+  filePath: string,
+  sourcePath: string,
+  options?: { conflictPolicy?: 'replace' | 'skip'; isDryRun?: boolean },
+): FileReconciliation;
+```
+
+Reconciles `filePath` against the content of `sourcePath`, which is what a command copying a bundled template reaches for:
+
+```ts
+import { reconcileFileFromFile } from '@williamthorsen/toolbelt.filesystem';
+
+reconcileFileFromFile('.config/git-cliff.toml', bundledTemplatePath);
+// { filePath: '.config/git-cliff.toml', outcome: 'created' }
+```
+
+It is [`reconcileFile`](#reconcilefile) with the read supplied: the outcome table, the conflict policy, the created parent directories, and the result type are that function's, unchanged. Three things are this one's own.
+
+The source is read as utf8 text, so a binary source is not supported: it would be decoded and re-encoded on the way through.
+
+A source that cannot be read reports `failed` rather than throwing, and a missing source is not distinguished from an unreadable one. The reason names the source and the cause:
+
+```
+Failed to read /pkg/cliff.toml.template: ENOENT: no such file or directory, open '/pkg/cliff.toml.template'
+```
+
+The path is interpolated rather than left to the underlying message, which carries none of its own at the read stage: reading a directory yields `EISDIR: illegal operation on a directory, read`. Under `ENOENT` the path therefore reads twice. The result's `filePath` is the destination on this path as on every other, so a caller copying several templates keys its results by destination and still sees which source failed.
+
+The source is read even under `isDryRun`, because the outcome depends on comparing its content. A dry run can therefore report `failed` where `reconcileFile`'s cannot, and it still writes nothing.
+
+## `createTempTree`
+
+Proposed tier: imported from `@williamthorsen/toolbelt.filesystem/proposed` rather than the package root, and subject to change.
+
+```ts
+createTempTree(entries: Record<string, string>): TempTree;
+```
+
+Builds a throwaway directory tree and returns a handle that removes it when the binding leaves scope:
+
+```ts
+import { createTempTree } from '@williamthorsen/toolbelt.filesystem/proposed';
+
+{
+  using tree = createTempTree({
+    '.git/': '',
+    'packages/app/package.json': '{ "name": "app" }',
+  });
+
+  tree.dir; // '/private/var/folders/.../toolbelt-a1b2c3'
+  tree.resolve('packages/app'); // '/private/var/folders/.../toolbelt-a1b2c3/packages/app'
+}
+// The tree is gone here.
+```
+
+Each key of `entries` is a path relative to the tree root. One ending in `/` becomes a directory; any other becomes a file holding the mapped contents, with its intermediate directories created for it. A key resolving outside the root is rejected, and a call that throws leaves nothing on disk.
+
+```ts
+interface TempTree extends Disposable {
+  readonly dir: string;
+  resolve(...segments: string[]): string;
+}
+```
+
+`dir` is realpath-resolved, because `os.tmpdir()` is a symlink on macOS and a caller comparing paths against it would otherwise see a mismatch it did not cause.
+
+`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.
+
+Disposal is idempotent.
+
+`Disposable` is declared in `lib.esnext.disposable.d.ts` alone, so consuming this export requires `ESNext.Disposable` in your `lib`.
+
+## `replaceFileExtension`
+
+Proposed tier: imported from `@williamthorsen/toolbelt.filesystem/proposed` rather than the package root, and subject to change.
+
+```ts
+replaceFileExtension(filePath: string, newExtension: string, options?: { oldExtension?: string }): string;
+```
+
+Returns `filePath` with its extension replaced. It manipulates the string alone and touches no filesystem.
+
+```ts
+import { replaceFileExtension } from '@williamthorsen/toolbelt.filesystem/proposed';
+
+replaceFileExtension('src/main.ts', '.js'); // 'src/main.js'
+replaceFileExtension('src/main.ts', 'js'); // 'src/main.js' -- the leading period is optional
+replaceFileExtension('src/main.ts', ''); // 'src/main' -- an empty replacement removes the extension
+```
+
+The extension being replaced defaults to whatever `path.extname` reports, which is the substring from the final period in the file name. That is wrong for a multi-part extension: `path.extname('src/main.d.ts')` returns `.ts`, so the default would yield `src/main.d.js`. Declare the whole extension through `oldExtension` to replace it entire:
+
+```ts
+replaceFileExtension('src/main.d.ts', '.js', { oldExtension: '.d.ts' }); // 'src/main.js'
+```
+
+Which extension is meant is genuinely ambiguous, since `archive.tar.gz` could reasonably end in `.gz` or in `.tar.gz`, so the caller declares it rather than the function guessing.
+
+Two inputs throw rather than returning a path that would quietly be wrong: a `filePath` ending in a separator, which names a directory rather than a file, and a `filePath` that does not end with a declared `oldExtension`.

package/dist/esm/1-proposed/createTempTree.d.ts

@@ -0,0 +1,5 @@
+export declare function createTempTree(entries: Record<string, string>): TempTree;
+export interface TempTree extends Disposable {
+    readonly dir: string;
+    resolve(...segments: string[]): string;
+}

package/dist/esm/1-proposed/createTempTree.js

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function createTempTree(entries) {
+    const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'toolbelt-')));
+    try {
+        for (const [entry, contents] of Object.entries(entries)) {
+            const entryPath = resolveWithinTree(dir, [entry]);
+            if (entry.endsWith('/')) {
+                fs.mkdirSync(entryPath, { recursive: true });
+            }
+            else {
+                fs.mkdirSync(path.dirname(entryPath), { recursive: true });
+                fs.writeFileSync(entryPath, contents);
+            }
+        }
+    }
+    catch (error) {
+        fs.rmSync(dir, { force: true, recursive: true });
+        throw error;
+    }
+    return {
+        dir,
+        resolve(...segments) {
+            return resolveWithinTree(dir, segments);
+        },
+        [Symbol.dispose]() {
+            fs.rmSync(dir, { force: true, recursive: true });
+        },
+    };
+}
+function resolveWithinTree(dir, segments) {
+    const target = path.resolve(dir, ...segments);
+    if (target !== dir && !target.startsWith(dir + path.sep)) {
+        throw new Error(`Path "${target}" falls outside the temporary tree at "${dir}"`);
+    }
+    return target;
+}

package/dist/esm/1-proposed/index.d.ts

@@ -1 +1,2 @@
-export {};
+export { createTempTree, type TempTree } from './createTempTree.js';
+export { replaceFileExtension, type ReplaceFileExtensionOptions } from './replaceFileExtension.js';

package/dist/esm/1-proposed/index.js

@@ -1 +1,2 @@
-export {};
+export { createTempTree } from "./createTempTree.js";
+export { replaceFileExtension } from "./replaceFileExtension.js";

package/dist/esm/1-proposed/replaceFileExtension.d.ts

@@ -0,0 +1,4 @@
+export declare function replaceFileExtension(filePath: string, newExtension: string, options?: ReplaceFileExtensionOptions): string;
+export interface ReplaceFileExtensionOptions {
+    oldExtension?: string | undefined;
+}

package/dist/esm/1-proposed/replaceFileExtension.js

@@ -0,0 +1,23 @@
+import path from 'node:path';
+export function replaceFileExtension(filePath, newExtension, options = {}) {
+    if (endsWithSeparator(filePath)) {
+        throw new Error(`File path "${filePath}" ends with a path separator, so it names a directory`);
+    }
+    const oldExtension = toDotPrefixed(options.oldExtension ?? path.extname(filePath));
+    const replacement = toDotPrefixed(newExtension);
+    if (oldExtension === '') {
+        return `${filePath}${replacement}`;
+    }
+    if (!filePath.endsWith(oldExtension)) {
+        throw new Error(`File path "${filePath}" does not end with extension "${oldExtension}"`);
+    }
+    return filePath.slice(0, -oldExtension.length) + replacement;
+}
+function endsWithSeparator(filePath) {
+    return filePath.endsWith('/') || filePath.endsWith(path.sep);
+}
+function toDotPrefixed(extension) {
+    if (extension === '' || extension.startsWith('.'))
+        return extension;
+    return `.${extension}`;
+}

package/dist/esm/4-release/directory-chain-matches.d.ts

@@ -0,0 +1,9 @@
+import { type ListDirectoryChainOptions } from './listDirectoryChain.js';
+export interface DirectoryChainMatch {
+    dir: string;
+    entryName: string;
+    entryPath: string;
+}
+export type DirectoryChainMatchOptions = ListDirectoryChainOptions;
+export declare function findDirectoryChainMatch(startDir: string, names: ReadonlyArray<string>, options?: DirectoryChainMatchOptions): DirectoryChainMatch | undefined;
+export declare function listDirectoryChainMatches(startDir: string, names: ReadonlyArray<string>, options?: DirectoryChainMatchOptions): DirectoryChainMatch[];

package/dist/esm/4-release/directory-chain-matches.js

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { listDirectoryChain } from "./listDirectoryChain.js";
+export function findDirectoryChainMatch(startDir, names, options = {}) {
+    assertLevelRelativeNames(names);
+    for (const dir of listDirectoryChain(startDir, options)) {
+        const entryName = findMatchingName(dir, names);
+        if (entryName !== undefined) {
+            return { dir, entryName, entryPath: path.join(dir, entryName) };
+        }
+    }
+    return undefined;
+}
+export function listDirectoryChainMatches(startDir, names, options = {}) {
+    assertLevelRelativeNames(names);
+    const matches = [];
+    for (const dir of listDirectoryChain(startDir, options)) {
+        const entryName = findMatchingName(dir, names);
+        if (entryName !== undefined) {
+            matches.push({ dir, entryName, entryPath: path.join(dir, entryName) });
+        }
+    }
+    return matches;
+}
+function assertLevelRelativeNames(names) {
+    for (const name of names) {
+        if (path.isAbsolute(name)) {
+            throw new Error(`Entry name must be relative to its directory level: ${name}`);
+        }
+        const normalized = path.normalize(name);
+        if (normalized === '..' || normalized.startsWith(`..${path.sep}`)) {
+            throw new Error(`Entry name must not ascend above its directory level: ${name}`);
+        }
+    }
+}
+function findMatchingName(dir, names) {
+    for (const name of names) {
+        if (fs.existsSync(path.join(dir, name))) {
+            return name;
+        }
+    }
+    return undefined;
+}

package/dist/esm/4-release/index.d.ts

@@ -1,2 +1,5 @@
-export { DEFAULT_ROOT_MARKERS, findProjectRoot, type FindProjectRootOptions, type ProjectRoot, type ProjectRootSource, } from './findProjectRoot.js';
+export { type DirectoryChainMatch, type DirectoryChainMatchOptions, findDirectoryChainMatch, listDirectoryChainMatches, } from './directory-chain-matches.js';
+export { listDirectoryChain, type ListDirectoryChainOptions } from './listDirectoryChain.js';
 export { type CascadeStopReason, type ConfigCascade, type ConfigEntry, loadConfigCascade, type LoadConfigCascadeOptions, } from './loadConfigCascade.js';
+export { type FileReconciliation, reconcileFile, type ReconcileFileOptions, type ReconciliationOutcome, } from './reconcileFile.js';
+export { reconcileFileFromFile } from './reconcileFileFromFile.js';

package/dist/esm/4-release/index.js

@@ -1,2 +1,5 @@
-export { DEFAULT_ROOT_MARKERS, findProjectRoot, } from "./findProjectRoot.js";
+export { findDirectoryChainMatch, listDirectoryChainMatches, } from "./directory-chain-matches.js";
+export { listDirectoryChain } from "./listDirectoryChain.js";
 export { loadConfigCascade, } from "./loadConfigCascade.js";
+export { reconcileFile, } from "./reconcileFile.js";
+export { reconcileFileFromFile } from "./reconcileFileFromFile.js";

package/dist/esm/4-release/listDirectoryChain.d.ts

@@ -0,0 +1,4 @@
+export declare function listDirectoryChain(startDir: string, options?: ListDirectoryChainOptions): [string, ...string[]];
+export interface ListDirectoryChainOptions {
+    stopAtDir?: string | undefined;
+}

package/dist/esm/4-release/listDirectoryChain.js

@@ -0,0 +1,22 @@
+import path from 'node:path';
+export function listDirectoryChain(startDir, options = {}) {
+    const { stopAtDir } = options;
+    const resolvedStartDir = path.resolve(startDir);
+    const resolvedStopAtDir = stopAtDir === undefined ? undefined : path.resolve(stopAtDir);
+    const chain = [resolvedStartDir];
+    let dir = resolvedStartDir;
+    let hasReachedStopAtDir = dir === resolvedStopAtDir;
+    while (!hasReachedStopAtDir) {
+        const parentDir = path.dirname(dir);
+        if (parentDir === dir)
+            break;
+        chain.push(parentDir);
+        dir = parentDir;
+        hasReachedStopAtDir = dir === resolvedStopAtDir;
+    }
+    if (resolvedStopAtDir !== undefined && !hasReachedStopAtDir) {
+        throw new Error('Stop directory must be the start directory or one of its ancestors: ' +
+            `stopAtDir=${resolvedStopAtDir}, startDir=${resolvedStartDir}`);
+    }
+    return chain;
+}

package/dist/esm/4-release/loadConfigCascade.d.ts

@@ -1,9 +1,7 @@
-import { type ProjectRoot } from './findProjectRoot.js';
 export declare function loadConfigCascade<TConfig = unknown>(options: LoadConfigCascadeOptions<TConfig>): Promise<ConfigCascade<TConfig>>;
-export type CascadeStopReason = 'predicate' | 'project-root';
+export type CascadeStopReason = 'predicate' | 'stop-dir';
 export interface ConfigCascade<TConfig> {
     entries: ConfigEntry<TConfig>[];
-    projectRoot: ProjectRoot;
     stopReason: CascadeStopReason;
 }
 export interface ConfigEntry<TConfig> {
@@ -13,7 +11,7 @@ export interface ConfigEntry<TConfig> {
 }
 export interface LoadConfigCascadeOptions<TConfig> {
     fileNames: ReadonlyArray<string>;
-    markers?: ReadonlyArray<string> | undefined;
     shouldStopAscent?: ((config: TConfig) => boolean) | undefined;
     startDir: string;
+    stopAtDir: string;
 }

package/dist/esm/4-release/loadConfigCascade.js

@@ -6,56 +6,22 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import fs from 'node:fs';
-import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { findProjectRoot } from "./findProjectRoot.js";
+import { listDirectoryChainMatches } from "./directory-chain-matches.js";
 export async function loadConfigCascade(options) {
-    const { fileNames, markers, shouldStopAscent, startDir } = options;
-    assertLevelRelativeFileNames(fileNames);
-    const projectRoot = findProjectRoot(startDir, { markers });
-    const candidates = collectCandidates(path.resolve(startDir), projectRoot.rootDir, fileNames);
+    const { fileNames, shouldStopAscent, startDir, stopAtDir } = options;
+    const matches = listDirectoryChainMatches(startDir, fileNames, { stopAtDir });
     const entries = [];
-    let stopReason = 'project-root';
-    for (const { dir, filePath } of candidates) {
-        const config = await importDefaultExport(filePath);
-        entries.push({ config, dir, filePath });
+    let stopReason = 'stop-dir';
+    for (const { dir, entryPath } of matches) {
+        const config = await importDefaultExport(entryPath);
+        entries.push({ config, dir, filePath: entryPath });
         if (shouldStopAscent?.(config) === true) {
             stopReason = 'predicate';
             break;
         }
     }
-    return { entries, projectRoot, stopReason };
-}
-function assertLevelRelativeFileNames(fileNames) {
-    for (const fileName of fileNames) {
-        if (path.isAbsolute(fileName)) {
-            throw new Error(`Config file name must be relative to its directory level: ${fileName}`);
-        }
-        const normalized = path.normalize(fileName);
-        if (normalized === '..' || normalized.startsWith(`..${path.sep}`)) {
-            throw new Error(`Config file name must not ascend above its directory level: ${fileName}`);
-        }
-    }
-}
-function collectCandidates(startDir, rootDir, fileNames) {
-    const candidates = [];
-    let dir = startDir;
-    let previousDir = '';
-    while (dir !== previousDir) {
-        for (const fileName of fileNames) {
-            const filePath = path.join(dir, fileName);
-            if (fs.existsSync(filePath)) {
-                candidates.push({ dir, filePath });
-                break;
-            }
-        }
-        if (dir === rootDir)
-            break;
-        previousDir = dir;
-        dir = path.dirname(dir);
-    }
-    return candidates;
+    return { entries, stopReason };
 }
 async function importDefaultExport(filePath) {
     const configModule = await import(__rewriteRelativeImportExtension(pathToFileURL(filePath).href));

package/dist/esm/4-release/reconcileFile.d.ts

@@ -0,0 +1,18 @@
+export declare function reconcileFile(filePath: string, content: string, options?: ReconcileFileOptions): FileReconciliation;
+export type FileReconciliation = {
+    filePath: string;
+    outcome: 'created' | 'overwritten' | 'up-to-date';
+} | {
+    filePath: string;
+    outcome: 'skipped';
+    error?: string | undefined;
+} | {
+    filePath: string;
+    outcome: 'failed';
+    error: string;
+};
+export interface ReconcileFileOptions {
+    conflictPolicy?: 'replace' | 'skip' | undefined;
+    isDryRun?: boolean | undefined;
+}
+export type ReconciliationOutcome = FileReconciliation['outcome'];

package/dist/esm/4-release/reconcileFile.js

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+export function reconcileFile(filePath, content, options = {}) {
+    const { conflictPolicy = 'skip', isDryRun = false } = options;
+    const doesFileExist = existsSync(filePath);
+    if (doesFileExist) {
+        const comparison = compareWithExisting(filePath, content, conflictPolicy);
+        if (comparison.isUpToDate)
+            return { filePath, outcome: 'up-to-date' };
+        if (conflictPolicy === 'skip') {
+            return comparison.error === undefined
+                ? { filePath, outcome: 'skipped' }
+                : { filePath, outcome: 'skipped', error: comparison.error };
+        }
+    }
+    const outcome = doesFileExist ? 'overwritten' : 'created';
+    if (isDryRun)
+        return { filePath, outcome };
+    try {
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        writeFileSync(filePath, content, 'utf8');
+    }
+    catch (error) {
+        return { filePath, outcome: 'failed', error: describeError(error) };
+    }
+    return { filePath, outcome };
+}
+function compareWithExisting(filePath, content, conflictPolicy) {
+    let existingContent;
+    try {
+        existingContent = readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        return { isUpToDate: false, error: describeError(error) };
+    }
+    if (conflictPolicy === 'replace') {
+        return { isUpToDate: existingContent === content };
+    }
+    return { isUpToDate: normalizeTrailingWhitespace(existingContent) === normalizeTrailingWhitespace(content) };
+}
+function normalizeTrailingWhitespace(content) {
+    return content
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .join('\n')
+        .trimEnd();
+}

package/dist/esm/4-release/reconcileFileFromFile.d.ts

@@ -0,0 +1,2 @@
+import { type FileReconciliation, type ReconcileFileOptions } from './reconcileFile.js';
+export declare function reconcileFileFromFile(filePath: string, sourcePath: string, options?: ReconcileFileOptions): FileReconciliation;

package/dist/esm/4-release/reconcileFileFromFile.js

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+import { describeError } from '@williamthorsen/toolbelt.errors';
+import { reconcileFile } from "./reconcileFile.js";
+export function reconcileFileFromFile(filePath, sourcePath, options = {}) {
+    let content;
+    try {
+        content = readFileSync(sourcePath, 'utf8');
+    }
+    catch (error) {
+        return { filePath, outcome: 'failed', error: `Failed to read ${sourcePath}: ${describeError(error)}` };
+    }
+    return reconcileFile(filePath, content, options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.filesystem",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Filesystem utilities",
   "keywords": [],
   "homepage": "https://github.com/williamthorsen/toolbelt/tree/main/packages/filesystem#readme",
@@ -33,6 +33,9 @@
     "dist/*",
     "CHANGELOG.md"
   ],
+  "dependencies": {
+    "@williamthorsen/toolbelt.errors": "0.3.0"
+  },
   "engines": {
     "node": ">=24.0.0"
   },

package/dist/esm/4-release/findProjectRoot.d.ts

@@ -1,11 +0,0 @@
-export declare const DEFAULT_ROOT_MARKERS: ReadonlyArray<string>;
-export declare function findProjectRoot(startDir: string, options?: FindProjectRootOptions): ProjectRoot;
-export interface FindProjectRootOptions {
-    markers?: ReadonlyArray<string> | undefined;
-}
-export interface ProjectRoot {
-    marker: string | null;
-    rootDir: string;
-    source: ProjectRootSource;
-}
-export type ProjectRootSource = 'marker' | 'package-json' | 'start-dir';

package/dist/esm/4-release/findProjectRoot.js

@@ -1,33 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-export const DEFAULT_ROOT_MARKERS = [
-    '.git',
-    'pnpm-workspace.yaml',
-    'pnpm-lock.yaml',
-    'package-lock.json',
-    'yarn.lock',
-    'bun.lock',
-];
-export function findProjectRoot(startDir, options = {}) {
-    const { markers = DEFAULT_ROOT_MARKERS } = options;
-    const resolvedStartDir = path.resolve(startDir);
-    let nearestPackageJsonDir;
-    let dir = resolvedStartDir;
-    let previousDir = '';
-    while (dir !== previousDir) {
-        for (const marker of markers) {
-            if (fs.existsSync(path.join(dir, marker))) {
-                return { marker, rootDir: dir, source: 'marker' };
-            }
-        }
-        if (nearestPackageJsonDir === undefined && fs.existsSync(path.join(dir, 'package.json'))) {
-            nearestPackageJsonDir = dir;
-        }
-        previousDir = dir;
-        dir = path.dirname(dir);
-    }
-    if (nearestPackageJsonDir !== undefined) {
-        return { marker: null, rootDir: nearestPackageJsonDir, source: 'package-json' };
-    }
-    return { marker: null, rootDir: resolvedStartDir, source: 'start-dir' };
-}