@williamthorsen/toolbelt.filesystem 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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

package/README.md

@@ -3,33 +3,23 @@
 Filesystem utilities for TypeScript and JavaScript.
 
 <!-- section:release-notes -->
-## Release notes — v0.3.0 (2026-08-08)
+## Release notes — v0.4.0 (2026-08-12)
 
 ### Features
 
-- Migrate replaceFileExtension into filesystem package (#74)
+- 🚨 **Breaking:** Add reconcileFile to toolbelt.filesystem and promote describeError to release tier (#122)
 
-  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`.
+  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.
 
-- Add directory-chain ascent and lookup exports (#102)
+  Separately, `describeError` is promoted to `@williamthorsen/toolbelt.errors`' release tier, so no release-tier module depends on a candidate one.
 
-  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:
+  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.
 
-  - `listDirectoryChain` returns the directories alone
-  - `listDirectoryChainMatches` returns every level's match
-  - `findDirectoryChainMatch` finds only the nearest match
+- Add reconcileFileFromFile to toolbelt.filesystem (#123)
 
-  All three reject a path that falls outside the range they were asked to search. `findProjectRoot` now applies that same rule to its markers.
+  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.
 
-- 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.
+  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
@@ -40,7 +30,7 @@ pnpm add @williamthorsen/toolbelt.filesystem
 
 ## Runtime requirements
 
-`createTempTree`, `findDirectoryChainMatch`, `listDirectoryChainMatches`, and `loadConfigCascade` 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.
+`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.
 
@@ -185,6 +175,88 @@ const { entries, stopReason } = await loadConfigCascade<StackConfig>({
 
 `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.

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

@@ -1,3 +1,5 @@
 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,3 +1,5 @@
 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/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.3.0",
+  "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"
   },