@williamthorsen/toolbelt.filesystem 0.8.2 → 0.9.0

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

@@ -0,0 +1,24 @@
+/**
+ * Writes `content` to `filePath` through a sibling temp file and a rename, so a concurrent reader sees either the
+ * previous file or the complete new one, never a partial write. Siting the temp file beside the target
+ * keeps the rename within one filesystem, where it is atomic.
+ *
+ * Missing parent directories are created. An existing target's permission bits are copied onto the replacement,
+ * which a bare `writeFile` would preserve by truncating in place and a rename would otherwise reset to the
+ * platform default.
+ *
+ * Two guarantees that it does not make. Nothing is fsynced, so a power loss can lose a write from which this
+ * function has already returned; "atomic" here means no torn reads. And the rename replaces the target's directory
+ * entry, so a symlink at `filePath` becomes a regular file rather than being written through.
+ *
+ * A failure removes the temp file best-effort and rethrows the error that caused it. Where the cleanup itself
+ * fails, the temp file survives beside the target under a dot-prefixed name ending in `.tmp`.
+ *
+ * @example
+ * await writeAtomic('.agents/manifest.json', `${JSON.stringify(manifest, null, 2)}\n`);
+ *
+ * @category Filesystem
+ * @experimental
+ * @stage candidate
+ */
+export declare function writeAtomic(filePath: string, content: string | Uint8Array): Promise<void>;

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

@@ -1,9 +1,48 @@
 import { type ListDirectoryChainOptions } from './listDirectoryChain.js';
 export interface DirectoryChainMatch {
+    /** The chain level at which the match was found, which differs from the entry's own directory for a nested name. */
     dir: string;
     entryName: string;
     entryPath: string;
 }
+/** Forwarded to `listDirectoryChain`. */
 export type DirectoryChainMatchOptions = ListDirectoryChainOptions;
+/**
+ * Returns the nearest directory at or above `startDir` holding one of `names`, or `undefined` when none does.
+ *
+ * Probing stops at the first level that matches, so no level beyond it is touched. Where every level's match
+ * matters rather than the nearest, `listDirectoryChainMatches` collects them all.
+ *
+ * Each name is a path relative to the level against which it is probed, so a nested location such as
+ * `.config/stack.config.mjs` works. A name that would leave its level is rejected before any level is probed.
+ *
+ * @example
+ * findDirectoryChainMatch('/home/dev/app/src', ['.git']);
+ * // { dir: '/home/dev/app', entryName: '.git', entryPath: '/home/dev/app/.git' }
+ *
+ * @category Filesystem
+ * @stage release
+ * @throws If a name is absolute or escapes its level, or if `stopAtDir` is not on the chain.
+ */
 export declare function findDirectoryChainMatch(startDir: string, names: ReadonlyArray<string>, options?: DirectoryChainMatchOptions): DirectoryChainMatch | undefined;
+/**
+ * Returns, for each directory in the chain at or above `startDir`, the first of `names` that exists there.
+ *
+ * Ordering is nearest first, and a level yields at most one match: the earliest of `names` found there. 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.
+ *
+ * Every level is probed. Where only the nearest match matters, `findDirectoryChainMatch` stops at the first.
+ *
+ * Each name is a path relative to the level against which it is probed, so a nested location such as
+ * `.config/stack.config.mjs` works. A name that would leave its level is rejected before any level is probed.
+ *
+ * @example
+ * listDirectoryChainMatches('/home/dev/app/src', ['.git'], { stopAtDir: '/home/dev' });
+ * // [{ dir: '/home/dev/app', entryName: '.git', entryPath: '/home/dev/app/.git' }]
+ *
+ * @category Filesystem
+ * @stage release
+ * @throws If a name is absolute or escapes its level, or if `stopAtDir` is not on the chain.
+ */
 export declare function listDirectoryChainMatches(startDir: string, names: ReadonlyArray<string>, options?: DirectoryChainMatchOptions): DirectoryChainMatch[];

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

@@ -1,4 +1,19 @@
+/**
+ * Returns `startDir` resolved to an absolute path, followed by each of its ancestors, nearest first.
+ *
+ * The chain runs to the filesystem root unless `stopAtDir` bounds it, and always holds at least the start
+ * directory, which the return type records. Paths are manipulated as strings; nothing is read from disk.
+ *
+ * @example
+ * listDirectoryChain('/home/dev/app/src', { stopAtDir: '/home/dev' });
+ * // ['/home/dev/app/src', '/home/dev/app', '/home/dev']
+ *
+ * @category Filesystem
+ * @stage release
+ * @throws If `stopAtDir` is neither the start directory nor one of its ancestors.
+ */
 export declare function listDirectoryChain(startDir: string, options?: ListDirectoryChainOptions): [string, ...string[]];
 export interface ListDirectoryChainOptions {
+    /** Bounds the ascent, inclusive. Must be the start directory or one of its ancestors. */
     stopAtDir?: string | undefined;
 }

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

@@ -1,17 +1,53 @@
+/**
+ * Loads every config file between a starting directory and `stopAtDir`, nearest first.
+ *
+ * At each level from `startDir` up to and including `stopAtDir`, the first of `fileNames` that exists
+ * is taken as that level's config; levels holding none contribute nothing. The matched files are then
+ * imported one at a time, nearest first, and `shouldStopAscent` is consulted after each: Once it returns
+ * true, the ascent halts and no farther file is imported. Nothing above `stopAtDir` is ever read:
+ * Each name must stay within the level against which it is probed, so one that escapes is rejected up front.
+ *
+ * The boundary is the caller's to choose, which keeps this function free of any notion of what
+ * marks a project. `findProjectRoot` from `@williamthorsen/toolbelt.packaging` resolves one from markers.
+ *
+ * Each config is the module's default export; validating its contents is the caller's job.
+ *
+ * @example
+ * const { entries } = await loadConfigCascade({
+ *   fileNames: ['stack.config.mjs'],
+ *   shouldStopAscent: (config) => config.shouldStopAscent === true,
+ *   startDir: process.cwd(),
+ *   stopAtDir: findProjectRoot(process.cwd()).rootDir,
+ * });
+ *
+ * @category Filesystem
+ * @stage release
+ * @throws If a file name is absolute or escapes its level, if `stopAtDir` is off the chain, or if a matched
+ * file has no default export.
+ */
 export declare function loadConfigCascade<TConfig = unknown>(options: LoadConfigCascadeOptions<TConfig>): Promise<ConfigCascade<TConfig>>;
 export type CascadeStopReason = 'predicate' | 'stop-dir';
 export interface ConfigCascade<TConfig> {
+    /** Ordered nearest first, starting at `startDir`. */
     entries: ConfigEntry<TConfig>[];
     stopReason: CascadeStopReason;
 }
 export interface ConfigEntry<TConfig> {
     config: TConfig;
+    /** The cascade level at which the file was found, which differs from the file's own directory when `fileNames` holds a nested path. */
     dir: string;
     filePath: string;
 }
 export interface LoadConfigCascadeOptions<TConfig> {
+    /**
+     * Paths relative to each level, in precedence order; the first that exists at a level is that level's config.
+     * A name that leaves its level (an absolute path, or one whose `..` segments escape it) is rejected, since
+     * it would read outside the bounds that the cascade exists to enforce.
+     */
     fileNames: ReadonlyArray<string>;
+    /** Called after each config is loaded; returning true halts the ascent before the next import. */
     shouldStopAscent?: ((config: TConfig) => boolean) | undefined;
     startDir: string;
+    /** Bounds the ascent, inclusive. Must be the start directory or one of its ancestors. */
     stopAtDir: string;
 }

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

@@ -1,3 +1,24 @@
+/**
+ * Writes `content` to `filePath`, reporting what the write took rather than throwing.
+ *
+ * Missing parent directories are created. An existing file is compared against `content` first, and what counts
+ * as a difference follows `conflictPolicy`: `'replace'` promises the file holds exactly `content` afterwards, so
+ * only byte-identical content reports `up-to-date`; `'skip'` modifies nothing either way, so its comparison
+ * 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 policies: This one has no work to do.
+ *
+ * An I/O error is reported as `failed` rather than thrown, which lets a caller writing several files
+ * collect a result for each instead of losing the rest to the first failure. A dry run writes nothing and
+ * creates no directory, returning the outcome that the real call would have produced, short of a write failure,
+ * which nothing detects without attempting the write.
+ *
+ * @example
+ * reconcileFile('.config/tool.config.ts', template, { conflictPolicy: 'replace' });
+ * // { filePath: '.config/tool.config.ts', outcome: 'overwritten' }
+ *
+ * @category Filesystem
+ * @stage release
+ */
 export declare function reconcileFile(filePath: string, content: string, options?: ReconcileFileOptions): FileReconciliation;
 export type FileReconciliation = {
     filePath: string;
@@ -12,6 +33,7 @@ export type FileReconciliation = {
     error: string;
 };
 export interface ReconcileFileOptions {
+    /** What to do with an existing file whose content differs. Defaults to `'skip'`, which never destroys one. */
     conflictPolicy?: 'replace' | 'skip' | undefined;
     isDryRun?: boolean | undefined;
 }

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

@@ -1,2 +1,23 @@
 import { type FileReconciliation, type ReconcileFileOptions } from './reconcileFile.js';
+/**
+ * Reconciles `filePath` against the utf8 text of `sourcePath`, reporting what the write took rather than throwing.
+ *
+ * Everything past the read is `reconcileFile`: The comparison, the conflict policy, the created parent directories,
+ * and the outcome vocabulary are its. A source that cannot be read reports `failed`, and a missing source is not
+ * distinguished from an unreadable one. The reason names `sourcePath` and the cause; the path is interpolated
+ * because a read-stage failure has none of its own (`EISDIR: illegal operation on a directory, read`) and the
+ * result's `filePath` is the destination.
+ *
+ * The source is read even under `isDryRun`, because the outcome depends on comparing its content, so a dry run can
+ * report `failed` where `reconcileFile` cannot. It still writes nothing.
+ *
+ * The read is utf8 text, so a binary source is not supported.
+ *
+ * @example
+ * reconcileFileFromFile('.config/git-cliff.toml', bundledTemplatePath);
+ * // { filePath: '.config/git-cliff.toml', outcome: 'created' }
+ *
+ * @category Filesystem
+ * @stage release
+ */
 export declare function reconcileFileFromFile(filePath: string, sourcePath: string, options?: ReconcileFileOptions): FileReconciliation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.filesystem",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Filesystem utilities",
   "keywords": [
     "config-cascade",
@@ -40,11 +40,19 @@
     }
   },
   "files": [
+    ".readyup/kits/*.js",
+    ".readyup/manifest.json",
     "dist/*",
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.errors": "0.6.3"
+    "@williamthorsen/toolbelt.errors": "0.8.0"
+  },
+  "devDependencies": {
+    "@williamthorsen/toolbelt.adoption": "0.1.0",
+    "@williamthorsen/toolbelt.testing": "0.6.0",
+    "esbuild": "0.28.2",
+    "readyup": "0.36.0"
   },
   "engines": {
     "node": ">=24.0.0"

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

@@ -1 +0,0 @@
-export declare function writeAtomic(filePath: string, content: string | Uint8Array): Promise<void>;

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

@@ -1,19 +0,0 @@
-export declare function createTempTree(entries: Record<string, string | Uint8Array>, options?: CreateTempTreeOptions): TempTree;
-export interface CreateTempTreeOptions {
-    prefix?: string;
-}
-export interface TempTree extends Disposable {
-    readonly dir: string;
-    exists(entryPath: string): boolean;
-    list(entryPath?: string): string[];
-    listFiles(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

@@ -1,148 +0,0 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-export function createTempTree(entries, options = {}) {
-    const { prefix = 'toolbelt-' } = options;
-    assertNamesDirectChild(prefix);
-    const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
-    try {
-        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 listFiles(entryPath = '') {
-        const rootPath = resolveWithinTree(dir, [entryPath]);
-        if (!fs.existsSync(rootPath))
-            return [];
-        return listFilesBelow(rootPath, '').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]);
-        fs.mkdirSync(path.dirname(absoluteLink), { recursive: true });
-        fs.symlinkSync(targetPath, absoluteLink, chooseLinkType(absoluteLink, targetPath));
-        return absoluteLink;
-    }
-    function write(entryPath, contents) {
-        const absolutePath = resolveWithinTree(dir, [entryPath]);
-        fs.mkdirSync(path.dirname(absolutePath), { recursive: true });
-        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) {
-            throw new Error(`Value of type "${typeof value}" for "${entryPath}" has no JSON representation`);
-        }
-        return write(entryPath, `${json}\n`);
-    }
-    return {
-        dir,
-        exists,
-        list,
-        listFiles,
-        mkdir,
-        read,
-        readJson,
-        resolve,
-        rm,
-        symlink,
-        write,
-        writeAll,
-        writeJson,
-        [Symbol.dispose]() {
-            try {
-                fs.rmSync(dir, { force: true, recursive: true });
-            }
-            catch {
-                restoreDirectoryPermissions(dir);
-                fs.rmSync(dir, { force: true, recursive: true });
-            }
-        },
-    };
-}
-function assertNamesDirectChild(prefix) {
-    if (prefix.includes('/') || prefix.includes('\\')) {
-        throw new Error(`Temporary-directory prefix "${prefix}" contains a path separator`);
-    }
-    if (['', '.', '..'].includes(prefix)) {
-        throw new Error(`Temporary-directory prefix "${prefix}" names no new directory`);
-    }
-}
-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 listFilesBelow(dir, prefix) {
-    const paths = [];
-    const entries = fs.readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-        const relativePath = `${prefix}${entry.name}`;
-        if (entry.isFile()) {
-            paths.push(relativePath);
-        }
-        else if (entry.isDirectory()) {
-            paths.push(...listFilesBelow(path.join(dir, entry.name), `${relativePath}/`));
-        }
-    }
-    return paths;
-}
-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);
-    if (target !== dir && !target.startsWith(dir + path.sep)) {
-        throw new Error(`Path "${target}" falls outside the temporary tree at "${dir}"`);
-    }
-    return target;
-}