@stonyx/utils 0.2.3-alpha.3 → 0.2.3-alpha.30

package/README.md

@@ -1,6 +1,10 @@
+[![CI](https://github.com/abofs/stonyx-utils/actions/workflows/ci.yml/badge.svg)](https://github.com/abofs/stonyx-utils/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@stonyx/utils.svg)](https://www.npmjs.com/package/@stonyx/utils)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
 # stonyx-utils
 
-Utilities module for the Stonyx Framework. Provides helpers for files, objects, strings, dates, and promises.
+Utilities module for the Stonyx Framework. Provides helpers for files, objects, strings, dates, promises, and prompts.
 
 ---
 
@@ -71,10 +75,16 @@ Creates a file at the given path.
 
 #### `updateFile(filePath, data, options={})`
 
-Updates a file atomically by writing to a temporary file first.
+Updates a file atomically by writing to a sibling swap file first, then renaming it over the target. Throws if the file does not exist.
 
 * `options.json` — boolean, serialize as JSON.
 
+**Concurrency: last writer wins.** Concurrent `updateFile` calls on the same path are safe — each uses a swap file unique to its process and call, so neither caller's swap file can collide with the other's. The rename-time `ENOENT` and the silent cross-caller byte clobber of [#44](https://github.com/abofs/stonyx-utils/issues/44) are both gone. (`updateFile` still throws `ENOENT` from its own precondition when the target does not exist — that is the documented contract above, and it is unrelated to concurrency.) Calls are not serialized: the surviving value is whichever caller renames last.
+
+**File mode is preserved; other inode metadata is not.** The swap file is created with the target's permission bits and `chmod`ed to them before the rename, so a `0600` file stays `0600`. ACLs, extended attributes, hard links and ownership are *not* carried across — the target necessarily gets a new inode.
+
+**Swap files after abnormal termination.** Cleanup runs on every failure path `updateFile` controls, but a process killed between the write and the rename leaves a `<path>.temp-<pid>-<token>` sibling behind, and no module ships a sweeper. This is a deliberate trade against the previous whole-second swap name, which was reused — and reuse is exactly the collision that caused #44, so uniqueness has to win. Be precise about what that costs: the old name only ever collapsed two orphans that were abandoned within the *same whole second*, so at any ordinary crash cadence it reclaimed nothing either (measured: five crashes 1200 ms apart leave five orphans under both names). The accumulation uniqueness genuinely adds is confined to a sub-second crash loop. Consumers that persist into a directory they scan, sync or commit should sweep or ignore `*.temp-*` siblings of their targets; an app that runs `git add` over its data directory will otherwise commit one.
+
 #### `copyFile(sourcePath, targetPath, options={})`
 
 Copies a file from source to target.
@@ -241,6 +251,8 @@ Prompts the user with `(y/N)` and resolves to `true` only if the answer is `"y"`
 * `options.input` — Readable stream (default: `process.stdin`).
 * `options.output` — Writable stream (default: `process.stdout`).
 
+**TTY required:** Rejects with an error if `process.stdin` is not a TTY and no custom `input` stream is provided. For headless/container deployments, use `autoMigrate` config or provide a custom input stream.
+
 #### `prompt(question, options={})`
 
 Prompts the user with a question and resolves to the trimmed input string.
@@ -248,6 +260,8 @@ Prompts the user with a question and resolves to the trimmed input string.
 * `options.input` — Readable stream (default: `process.stdin`).
 * `options.output` — Writable stream (default: `process.stdout`).
 
+**TTY required:** Rejects with an error if `process.stdin` is not a TTY and no custom `input` stream is provided.
+
 ```js
 import { confirm, prompt } from '@stonyx/utils/prompt';
 

package/dist/date.d.ts

@@ -0,0 +1 @@
+export declare function getTimestamp(dateObject?: Date | null): number;

package/dist/date.js

@@ -0,0 +1,4 @@
+export function getTimestamp(dateObject = null) {
+    const ts = dateObject ? dateObject.getTime() : Date.now();
+    return Math.floor(ts / 1000);
+}

package/dist/file.d.ts

@@ -0,0 +1,79 @@
+import fs from 'fs';
+interface FileOptions {
+    json?: boolean;
+}
+interface ReadFileOptions extends FileOptions {
+    missingFileCallback?: (filePath: string) => string | Record<string, unknown>;
+    encoding?: BufferEncoding | null;
+}
+interface DeleteFileOptions {
+    ignoreAccessFailure?: boolean;
+}
+interface ForEachFileImportOptions {
+    ignoreAccessFailure?: boolean;
+    recursive?: boolean;
+    recursiveNaming?: boolean;
+    rawName?: boolean;
+    namePrefix?: string;
+    fullExport?: boolean;
+}
+interface FileImportMeta {
+    name: string;
+    stats: import('fs').Stats;
+    path: string;
+}
+export declare function createFile(filePath: string, data: string | Record<string, unknown>, options?: FileOptions): Promise<void>;
+/**
+ * Atomically replace the contents of an existing file.
+ *
+ * Writes to a swap file that is a **sibling** of the target — so `rename` stays
+ * on one filesystem and therefore stays atomic — then renames it over the
+ * target. The swap name carries `process.pid` and a short random token rather
+ * than a timestamp: a whole-second token collided between concurrent callers,
+ * which made one caller throw `ENOENT` and the other silently persist bytes it
+ * had not written (abofs/stonyx-utils#44).
+ *
+ * Concurrency contract: **last writer wins**. Unique swap names remove the
+ * `ENOENT` and the byte-level clobber, but overlapping calls on one path still
+ * race on which value lands last. `updateFile` does not serialize, and callers
+ * needing a serialization guarantee must supply their own — an in-process queue
+ * would not provide one across processes anyway.
+ *
+ * The target's mode is read before the write and reapplied to the swap file, so
+ * the rename does not widen a deliberately restrictive file (a `0600` database
+ * would otherwise become `0666 & ~umask`). Other inode-bound metadata — ACLs,
+ * extended attributes, hard links, ownership — is *not* carried across; the
+ * target gets a new inode by construction.
+ *
+ * `rename` is atomic against concurrent *readers*, not against power loss:
+ * there is no `fsync`, so this is namespace atomicity, not crash durability.
+ * If the target is a symlink it is replaced by a regular file — the link's
+ * destination is never written through.
+ *
+ * Swap files are cleaned up on every failure path this function controls, but
+ * a process killed between the write and the rename leaves a permanently
+ * distinct `<path>.temp-<pid>-<token>` sibling that nothing reclaims. No
+ * sweeper ships with this module; `*.temp-*` siblings of a target are safe for
+ * a consumer to delete.
+ */
+export declare function updateFile(filePath: string, data: string | Record<string, unknown>, options?: FileOptions): Promise<void>;
+interface CopyFileOptions {
+    overwrite?: boolean;
+}
+export declare function copyFile(sourcePath: string, targetPath: string, options?: CopyFileOptions): Promise<boolean>;
+export declare function readFile(filePath: string, options: ReadFileOptions & {
+    encoding: null;
+}): Promise<Buffer>;
+export declare function readFile(filePath: string, options: ReadFileOptions & {
+    json: true;
+}): Promise<Record<string, unknown>>;
+export declare function readFile(filePath: string, options?: ReadFileOptions): Promise<string>;
+export declare function deleteFile(filePath: string, options?: DeleteFileOptions): Promise<void>;
+export declare function deleteFileSync(filePath: string, options?: DeleteFileOptions): void;
+export declare function deleteDirectory(dir: string): Promise<void>;
+export declare function createDirectory(dir: string): Promise<void>;
+export declare function createReadStream(filePath: string, options?: Parameters<typeof fs.createReadStream>[1]): fs.ReadStream;
+export declare function createWriteStream(filePath: string, options?: Parameters<typeof fs.createWriteStream>[1]): fs.WriteStream;
+export declare function forEachFileImport(dir: string, callback: (output: unknown, meta: FileImportMeta) => void | Promise<void>, options?: ForEachFileImportOptions): Promise<void>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+export {};

package/dist/file.js

@@ -0,0 +1,234 @@
+import { kebabCaseToCamelCase } from './string.js';
+import { objToJson } from './object.js';
+import fs from 'fs';
+import { promises as fsp } from 'fs';
+import path from 'path';
+import { randomBytes } from 'crypto';
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+export async function createFile(filePath, data, options = {}) {
+    try {
+        filePath = path.resolve(filePath);
+        await createDirectory(path.dirname(filePath));
+        await fsp.writeFile(filePath, options.json ? objToJson(data) : String(data), 'utf8');
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+}
+/**
+ * Atomically replace the contents of an existing file.
+ *
+ * Writes to a swap file that is a **sibling** of the target — so `rename` stays
+ * on one filesystem and therefore stays atomic — then renames it over the
+ * target. The swap name carries `process.pid` and a short random token rather
+ * than a timestamp: a whole-second token collided between concurrent callers,
+ * which made one caller throw `ENOENT` and the other silently persist bytes it
+ * had not written (abofs/stonyx-utils#44).
+ *
+ * Concurrency contract: **last writer wins**. Unique swap names remove the
+ * `ENOENT` and the byte-level clobber, but overlapping calls on one path still
+ * race on which value lands last. `updateFile` does not serialize, and callers
+ * needing a serialization guarantee must supply their own — an in-process queue
+ * would not provide one across processes anyway.
+ *
+ * The target's mode is read before the write and reapplied to the swap file, so
+ * the rename does not widen a deliberately restrictive file (a `0600` database
+ * would otherwise become `0666 & ~umask`). Other inode-bound metadata — ACLs,
+ * extended attributes, hard links, ownership — is *not* carried across; the
+ * target gets a new inode by construction.
+ *
+ * `rename` is atomic against concurrent *readers*, not against power loss:
+ * there is no `fsync`, so this is namespace atomicity, not crash durability.
+ * If the target is a symlink it is replaced by a regular file — the link's
+ * destination is never written through.
+ *
+ * Swap files are cleaned up on every failure path this function controls, but
+ * a process killed between the write and the rename leaves a permanently
+ * distinct `<path>.temp-<pid>-<token>` sibling that nothing reclaims. No
+ * sweeper ships with this module; `*.temp-*` siblings of a target are safe for
+ * a consumer to delete.
+ */
+export async function updateFile(filePath, data, options = {}) {
+    try {
+        filePath = path.resolve(filePath);
+        await fsp.access(filePath);
+        // The swap file becomes the target's inode, so it has to carry the target's
+        // permission bits or a routine save silently widens them.
+        const { mode } = await fsp.stat(filePath);
+        const targetMode = mode & 0o7777;
+        // pid + random token, never a timestamp: the swap name is a uniqueness
+        // token, and whole seconds cannot discriminate between concurrent callers.
+        // The token is deliberately short — a full 36-char UUID pushed the name
+        // overhead to 48 characters and made ~210-character basenames fail
+        // ENAMETOOLONG on a 255-byte NAME_MAX. 6 CSPRNG bytes as base64url is 8
+        // characters carrying 48 bits, where the first 8 hex characters of a UUID
+        // would be the same width but only 32 bits; at 32 bits a 1000-sample
+        // distinctness check collides about once in 8,600 runs. `wx` below makes
+        // any residual collision loud rather than corrupting.
+        const swapFile = `${filePath}.temp-${process.pid}-${randomBytes(6).toString('base64url')}`;
+        // Which stage failed, so the catch can tell "the open collided" from "the
+        // open succeeded and something later failed" — see the catch.
+        let wrote = false;
+        try {
+            // `wx` turns any residual name collision into a loud EEXIST rather than a
+            // silent overwrite of another caller's swap bytes. `mode` here is masked
+            // by the umask, so it only narrows — the chmod below sets the exact bits.
+            await fsp.writeFile(swapFile, options.json ? objToJson(data) : String(data), { encoding: 'utf8', flag: 'wx', mode: targetMode });
+            wrote = true;
+            await fsp.chmod(swapFile, targetMode);
+            await fsp.rename(swapFile, filePath);
+        }
+        catch (swapError) {
+            // Leave no orphan behind, and never let the cleanup mask the real error.
+            //
+            // Exactly one case is not ours to remove: the `wx` open lost a race, so
+            // the swap file is another writer's and unlinking it would reintroduce
+            // #44. That is EEXIST *from the write stage* — both halves matter.
+            //   - Code alone is not enough: `rename` surfaces EEXIST on Windows and
+            //     some network filesystems, and that file is one we created.
+            //   - Stage alone is not enough: a write that fails after the open
+            //     succeeded (ENOSPC, EDQUOT, EIO) also lands here with `wrote` false,
+            //     and skipping it is the orphaned partial payload this PR exists to
+            //     close.
+            const lostTheOpenRace = !wrote && isNodeError(swapError) && swapError.code === 'EEXIST';
+            if (!lostTheOpenRace) {
+                await fsp.unlink(swapFile).catch(() => { });
+            }
+            throw swapError;
+        }
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+}
+export async function copyFile(sourcePath, targetPath, options = {}) {
+    try {
+        sourcePath = path.resolve(sourcePath);
+        targetPath = path.resolve(targetPath);
+        await fsp.access(sourcePath);
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+    try {
+        await fsp.access(targetPath);
+        if (!options.overwrite)
+            return false;
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') { /* file doesn't exist — proceed with copy */ }
+        else
+            throw error;
+    }
+    try {
+        await fsp.copyFile(sourcePath, targetPath);
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+    return true;
+}
+export async function readFile(filePath, options = {}) {
+    try {
+        filePath = path.resolve(filePath);
+        await fsp.access(filePath);
+        const encoding = options.encoding === undefined ? 'utf8' : options.encoding;
+        const fileData = await fsp.readFile(filePath, { encoding: encoding });
+        if (encoding === null)
+            return fileData;
+        if (options.json)
+            return JSON.parse(fileData);
+        return fileData;
+    }
+    catch (error) {
+        const { missingFileCallback } = options;
+        if (isNodeError(error) && error.code === 'ENOENT' && missingFileCallback) {
+            return missingFileCallback(filePath);
+        }
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+}
+export async function deleteFile(filePath, options) {
+    try {
+        filePath = path.resolve(filePath);
+        await fsp.access(filePath);
+    }
+    catch (error) {
+        if (options?.ignoreAccessFailure)
+            return;
+        throw error;
+    }
+    await fsp.unlink(filePath);
+}
+export function deleteFileSync(filePath, options) {
+    try {
+        filePath = path.resolve(filePath);
+        fs.accessSync(filePath);
+    }
+    catch (error) {
+        if (options?.ignoreAccessFailure)
+            return;
+        throw error;
+    }
+    fs.unlinkSync(filePath);
+}
+export async function deleteDirectory(dir) {
+    await fsp.rm(dir, { recursive: true, force: true });
+}
+export async function createDirectory(dir) {
+    await fsp.mkdir(dir, { recursive: true });
+}
+export function createReadStream(filePath, options) {
+    return fs.createReadStream(path.resolve(filePath), options);
+}
+export function createWriteStream(filePath, options) {
+    return fs.createWriteStream(path.resolve(filePath), options);
+}
+export async function forEachFileImport(dir, callback, options = {}) {
+    if (typeof callback !== 'function')
+        throw new Error('Callback must be valid function');
+    try {
+        await fsp.access(dir);
+    }
+    catch (error) {
+        if (!options.ignoreAccessFailure)
+            throw new Error(`Unable to access directory: ${dir}`);
+        return;
+    }
+    const files = await fsp.readdir(dir);
+    for (const file of files) {
+        const filePath = path.join(dir, file);
+        const stats = await fsp.stat(filePath);
+        if (options.recursive && stats.isDirectory()) {
+            const newOptions = { ...options };
+            if (options.recursiveNaming) {
+                const pathPrefix = options.rawName ? file : `${kebabCaseToCamelCase(file)}`;
+                newOptions.namePrefix = options.namePrefix ? `${options.namePrefix}${pathPrefix}/` : `${pathPrefix}/`;
+            }
+            await forEachFileImport(filePath, callback, newOptions);
+            continue;
+        }
+        if (!stats.isFile() || !(file.endsWith('.js') || file.endsWith('.ts')))
+            continue;
+        const prefix = process.platform === 'win32' ? 'file://' : '';
+        const rawName = file.replace(/\.(js|ts)$/, '');
+        let name = options.rawName ? rawName : kebabCaseToCamelCase(rawName);
+        if (options.namePrefix)
+            name = `${options.namePrefix}${name}`;
+        const exported = await import(prefix + path.resolve(filePath));
+        const output = !options.fullExport ? exported.default : exported;
+        callback(output, { name, stats, path: filePath });
+    }
+}
+export async function fileExists(filePath) {
+    try {
+        filePath = path.resolve(filePath);
+        await fsp.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/fuzzy-match.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Generic fuzzy string matching for cross-source reconciliation.
+ * Handles Unicode normalization, stop-word filtering, and word-set similarity scoring.
+ */
+export interface FuzzyMatchOptions {
+    stopWords?: string[];
+    delimiter?: string;
+    threshold?: number;
+}
+export interface FuzzyMatchResult<T extends {
+    name: string;
+}> {
+    entry: T;
+    score: number;
+}
+export default class FuzzyMatch {
+    stopWords: string[];
+    delimiter: string;
+    threshold: number;
+    constructor(options?: FuzzyMatchOptions);
+    normalize(name: string): string;
+    similarity(nameA: string, nameB: string): number;
+    findBestMatch<T extends {
+        name: string;
+    }>(nameA: string, nameB: string, entries: T[], threshold?: number): FuzzyMatchResult<T> | null;
+}

package/dist/fuzzy-match.js

@@ -0,0 +1,80 @@
+/**
+ * Generic fuzzy string matching for cross-source reconciliation.
+ * Handles Unicode normalization, stop-word filtering, and word-set similarity scoring.
+ */
+function normalizeString(name, stopWords = []) {
+    let result = name
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, ' ');
+    if (stopWords.length) {
+        const pattern = new RegExp(`\\b(${stopWords.join('|')})\\b`, 'g');
+        result = result.replace(pattern, '');
+    }
+    return result.replace(/\s+/g, ' ').trim();
+}
+function wordSet(normalized) {
+    return new Set(normalized.split(' ').filter(w => w.length > 1));
+}
+export default class FuzzyMatch {
+    stopWords;
+    delimiter;
+    threshold;
+    constructor(options = {}) {
+        this.stopWords = options.stopWords || [];
+        this.delimiter = options.delimiter || '\u00B7';
+        this.threshold = options.threshold || 0.35;
+    }
+    normalize(name) {
+        return normalizeString(name, this.stopWords);
+    }
+    similarity(nameA, nameB) {
+        const aN = this.normalize(nameA);
+        const sN = this.normalize(nameB);
+        if (!aN || !sN)
+            return 0;
+        if (aN === sN)
+            return 1.0;
+        if (aN.includes(sN) || sN.includes(aN))
+            return 0.9;
+        const aWords = wordSet(aN);
+        const sWords = wordSet(sN);
+        if (aWords.size === 0 || sWords.size === 0)
+            return 0;
+        let overlap = 0;
+        for (const w of aWords) {
+            if (sWords.has(w)) {
+                overlap++;
+            }
+            else {
+                for (const sw of sWords) {
+                    if (sw.startsWith(w) || w.startsWith(sw)) {
+                        overlap += 0.7;
+                        break;
+                    }
+                }
+            }
+        }
+        return overlap / Math.max(aWords.size, sWords.size);
+    }
+    findBestMatch(nameA, nameB, entries, threshold) {
+        const minScore = threshold ?? this.threshold;
+        let bestMatch = null;
+        let bestScore = 0;
+        for (const entry of entries) {
+            const parts = entry.name.split(this.delimiter);
+            if (parts.length !== 2)
+                continue;
+            const [entryA, entryB] = parts;
+            const normalScore = (this.similarity(nameA, entryA) + this.similarity(nameB, entryB)) / 2;
+            const reversedScore = (this.similarity(nameA, entryB) + this.similarity(nameB, entryA)) / 2;
+            const score = Math.max(normalScore, reversedScore);
+            if (score > bestScore) {
+                bestScore = score;
+                bestMatch = entry;
+            }
+        }
+        return bestScore >= minScore && bestMatch ? { entry: bestMatch, score: bestScore } : null;
+    }
+}

package/dist/object.d.ts

@@ -0,0 +1,14 @@
+export declare function deepCopy<T>(obj: T): T;
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function objToJson(obj: JsonValue | Record<string, unknown>, format?: string | number): string;
+export declare function makeArray<T>(obj: T | T[]): T[];
+interface MergeOptions {
+    ignoreNewKeys?: boolean;
+}
+export declare function mergeObject(obj1: Record<string, unknown>, obj2: Record<string, unknown>, options?: MergeOptions): Record<string, unknown>;
+export declare function get(obj: Record<string, unknown>, path: string): unknown;
+export declare function get(obj: unknown, path?: unknown): undefined;
+export declare function getOrSet<K, V>(map: Map<K, V>, key: K, defaultValue: V | (() => V)): V;
+export {};

package/dist/object.js

@@ -0,0 +1,60 @@
+export function deepCopy(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+export function objToJson(obj, format = '\t') {
+    return JSON.stringify(obj, null, format);
+}
+export function makeArray(obj) {
+    return Array.isArray(obj) ? obj : [obj];
+}
+function cloneShallow(value) {
+    if (Array.isArray(value))
+        return value.slice();
+    if (value && typeof value === 'object')
+        return { ...value };
+    return value;
+}
+export function mergeObject(obj1, obj2, options = {}) {
+    if (Array.isArray(obj1) || Array.isArray(obj2))
+        throw new Error('Cannot merge arrays.');
+    if (obj1 === null || typeof obj1 !== 'object')
+        return cloneShallow(obj2);
+    if (obj2 === null || typeof obj2 !== 'object')
+        return cloneShallow(obj1);
+    const result = {};
+    for (const key of Object.keys(obj1))
+        result[key] = cloneShallow(obj1[key]);
+    for (const key of Object.keys(obj2)) {
+        if (options.ignoreNewKeys && !(key in obj1))
+            continue;
+        const val1 = obj1[key];
+        const val2 = obj2[key];
+        const shouldMerge = val1 && val2 && typeof val1 === 'object' && typeof val2 === 'object' && !Array.isArray(val1) && !Array.isArray(val2);
+        result[key] = shouldMerge ? mergeObject(val1, val2, options) : cloneShallow(val2);
+    }
+    return result;
+}
+export function get(obj, path) {
+    if (arguments.length !== 2)
+        return console.error('Get must be called with two arguments; an object and a property key.');
+    if (!obj)
+        return console.error(`Cannot call get with '${path}' on an undefined object.`);
+    if (typeof path !== 'string')
+        return console.error('The path provided to get must be a string.');
+    let current = obj;
+    for (const key of path.split('.')) {
+        if (current[key] === undefined)
+            return;
+        current = current[key];
+    }
+    return current;
+}
+export function getOrSet(map, key, defaultValue) {
+    if (!(map instanceof Map))
+        throw new Error('First argument to getOrSet must be a Map.');
+    if (!map.has(key)) {
+        const value = typeof defaultValue === 'function' ? defaultValue() : defaultValue;
+        map.set(key, value);
+    }
+    return map.get(key);
+}

package/dist/plurarize.d.ts

@@ -0,0 +1 @@
+export default function pluralize(word: string): string;

package/dist/plurarize.js

@@ -0,0 +1,87 @@
+// --- Irregular nouns ---
+const irregular = {
+    person: 'people',
+    man: 'men',
+    woman: 'women',
+    child: 'children',
+    tooth: 'teeth',
+    foot: 'feet',
+    mouse: 'mice',
+    goose: 'geese',
+    ox: 'oxen',
+    cactus: 'cacti',
+    nucleus: 'nuclei',
+    syllabus: 'syllabi',
+    focus: 'foci',
+    fungus: 'fungi',
+    appendix: 'appendices',
+    index: 'indices',
+    criterion: 'criteria',
+    phenomenon: 'phenomena',
+    die: 'dice',
+    thesis: 'theses',
+    analysis: 'analyses',
+    crisis: 'crises',
+    radius: 'radii',
+    corpus: 'corpora',
+};
+// --- Uncountables ---
+const uncountable = new Set([
+    'sheep', 'fish', 'deer', 'series', 'species', 'news', 'information',
+    'rice', 'moose', 'bison', 'salmon', 'aircraft', 'offspring'
+]);
+// --- Exceptions ---
+const fExceptions = new Set(['chief', 'roof', 'belief', 'chef', 'cliff', 'reef', 'proof', 'brief']);
+// Keep only true irregular -o exceptions (consonant + o but take just "s")
+const oExceptions = new Set(['piano', 'photo', 'halo', 'canto', 'solo']);
+// --- Utility to preserve casing ---
+function applyCasing(original, plural) {
+    if (original === original.toUpperCase())
+        return plural.toUpperCase();
+    if (original === original.toLowerCase())
+        return plural.toLowerCase();
+    if (original[0] === original[0].toUpperCase()) {
+        return plural.charAt(0).toUpperCase() + plural.slice(1);
+    }
+    return plural;
+}
+// --- Rule-based pluralization ---
+const rules = [
+    // quiz -> quizzes, waltz -> waltzes, topaz -> topazes
+    [/z$/i, w => (/iz$/i.test(w) ? w + 'zes' : w + 'es')],
+    // bus -> buses, box -> boxes, church -> churches, but stomach -> stomachs (exclude -ach)
+    [/(s|x|ch|sh)$/i, w => (/ach$/i.test(w) ? w + 's' : w + 'es')],
+    // vowel + y -> +s (key -> keys)
+    [/[aeiou]y$/i, w => w + 's'],
+    // consonant + y -> -ies (city -> cities)
+    [/y$/i, w => w.slice(0, -1) + 'ies'],
+    // -fe -> -ves (knife -> knives), but not chief/roof/etc
+    [/fe$/i, w => (fExceptions.has(w) ? w + 's' : w.slice(0, -2) + 'ves')],
+    // -f -> -ves (wolf -> wolves), but not cliff/etc
+    [/f$/i, w => (fExceptions.has(w) ? w + 's' : w.slice(0, -1) + 'ves')],
+    // -sis -> -ses (analysis -> analyses, thesis -> theses)
+    [/sis$/i, w => w.slice(0, -2) + 'ses'],
+    // vowel + o -> +s (zoo -> zoos, video -> videos, patio -> patios)
+    [/[aeiou]o$/i, w => w + 's'],
+    // consonant + o -> usually +es, unless in oExceptions
+    [/o$/i, w => (oExceptions.has(w) ? w + 's' : w + 'es')],
+    // default: just +s
+    [/$/i, w => w + 's']
+];
+// --- Exported pluralizer ---
+export default function pluralize(word) {
+    if (typeof word !== 'string' || !/^[a-zA-Z]+$/.test(word))
+        return word;
+    const lower = word.toLowerCase();
+    if (uncountable.has(lower))
+        return word;
+    if (irregular[lower]) {
+        return applyCasing(word, irregular[lower]);
+    }
+    for (const [pattern, transform] of rules) {
+        if (pattern.test(lower)) {
+            return applyCasing(word, transform(lower));
+        }
+    }
+    return word; // fallback (shouldn't hit)
+}

package/dist/promise.d.ts

@@ -0,0 +1 @@
+export declare function sleep(seconds: number): Promise<void>;

package/dist/promise.js

@@ -0,0 +1,5 @@
+export async function sleep(seconds) {
+    return new Promise(resolve => {
+        setTimeout(resolve, 1000 * seconds);
+    });
+}

package/dist/prompt.d.ts

@@ -0,0 +1,8 @@
+import type { Readable, Writable } from 'stream';
+interface PromptOptions {
+    input?: Readable;
+    output?: Writable;
+}
+export declare function confirm(question: string, { input, output }?: PromptOptions): Promise<boolean>;
+export declare function prompt(question: string, { input, output }?: PromptOptions): Promise<string>;
+export {};