@james-pre/config 0.0.1

package/dist/node/process.d.ts

@@ -0,0 +1,25 @@
+export declare function setCommandTimeout(value: number): void;
+/**
+ * Run a system command with fancy I/O like "Example... done."
+ * @deprecated Use {@link trackCommand} instead, this function is unsafe.
+ */
+export declare function runShell(message: string, command: string): Promise<string>;
+export interface TrackCommandOptions {
+    text: string;
+    /** Whether to ignore the command's exit code (or which codes to ignore) */
+    ignoreCode?: boolean | number[];
+}
+/**
+ * Run a system command with fancy I/O like "Example... done."
+ */
+export declare function trackCommand(message: string, command: string, ...args: string[]): string;
+export declare function trackCommand(options: TrackCommandOptions, command: string, ...args: string[]): string;
+export { 
+/**
+ * @deprecated use {@link runShell}
+ */
+runShell as run, };
+/** Yet another convenience function */
+export declare function exit(message: unknown, code?: number): never;
+/** Use a different working directory for the rest of a block */
+export declare function withCWD(path: string): string & Disposable;

package/dist/node/process.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+/* eslint-disable @typescript-eslint/only-throw-error */
+import { exec, spawnSync } from 'node:child_process';
+import * as io from '../core.js';
+let timeout = 1000;
+export function setCommandTimeout(value) {
+    timeout = value;
+}
+/**
+ * Run a system command with fancy I/O like "Example... done."
+ * @deprecated Use {@link trackCommand} instead, this function is unsafe.
+ */
+export async function runShell(message, command) {
+    let stderr;
+    try {
+        io.start(message);
+        const { promise, resolve, reject } = Promise.withResolvers();
+        exec(command, { timeout }, (err, stdout, _stderr) => {
+            stderr = _stderr.startsWith('ERROR:') ? _stderr.slice(6).trim() : _stderr;
+            if (err)
+                reject('[command]');
+            else
+                resolve(stdout);
+        });
+        const value = await promise;
+        io.done();
+        return value;
+    }
+    catch (error) {
+        io.done(true);
+        throw error == '[command]'
+            ? stderr?.slice(0, 100) || 'failed.'
+            : typeof error == 'object' && 'message' in error
+                ? error.message
+                : error;
+    }
+}
+export function trackCommand(message, command, ...args) {
+    const { text, ignoreCode } = typeof message === 'string' ? { text: message, ignoreCode: false } : message;
+    io.start(text);
+    const result = spawnSync(command, args, { encoding: 'utf-8', timeout });
+    if (result.error) {
+        io.done(true);
+        throw result.error;
+    }
+    const stderr = result.stderr.startsWith('ERROR:') ? result.stderr.slice(6).trim() : result.stderr.trim();
+    if (result.status && (!ignoreCode || (Array.isArray(ignoreCode) && !ignoreCode.includes(result.status)))) {
+        io.done(true);
+        throw stderr.slice(0, 100) || 'failed.';
+    }
+    io.done();
+    return result.stdout;
+}
+export { 
+/**
+ * @deprecated use {@link runShell}
+ */
+runShell as run, };
+/** Yet another convenience function */
+export function exit(message, code = 1) {
+    if (typeof message == 'number') {
+        code = message;
+        message = 'Unknown error!';
+    }
+    io.done(true);
+    io.error(io.errorText(message));
+    process.exit(code);
+}
+/** Use a different working directory for the rest of a block */
+export function withCWD(path) {
+    const original = process.cwd();
+    process.chdir(path);
+    return Object.assign(original, {
+        [Symbol.dispose]() {
+            process.chdir(original);
+        },
+    });
+}

package/dist/node/rl.d.ts

@@ -0,0 +1,13 @@
+import { type Interface } from 'node:readline/promises';
+/**
+ * Get a readline reference. While held, this means process.stdin is ref'ed if it's a TTY.
+ */
+export declare function getReadline(): Interface;
+/**
+ * Confirm a yes/no question
+ */
+export declare function confirm(question?: string | null, defaultAnswer?: boolean): Promise<boolean>;
+/**
+ * Assert that the answer to a question is yes, otherwise fail and exit
+ */
+export declare function assertYes(question?: string | null, failureMessage?: string): Promise<void>;

package/dist/node/rl.js

@@ -0,0 +1,97 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { createInterface } from 'node:readline/promises';
+import * as z from 'zod';
+import { exit } from './process.js';
+const _rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+});
+_rl[Symbol.dispose] = () => process.stdin.unref?.();
+process.stdin.unref?.();
+/**
+ * Get a readline reference. While held, this means process.stdin is ref'ed if it's a TTY.
+ */
+export function getReadline() {
+    process.stdin.ref?.();
+    return _rl;
+}
+/**
+ * Confirm a yes/no question
+ */
+export async function confirm(question, defaultAnswer = false) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const rl = __addDisposableResource(env_1, getReadline(), false);
+        const raw = await rl.question(`${question || 'Is this ok'} [${defaultAnswer ? 'Y/n' : 'y/N'}]: `).catch(() => null);
+        if (raw === null || raw === '')
+            return defaultAnswer;
+        const { data, error } = z.stringbool().default(defaultAnswer).safeParse(raw);
+        return !!error || data;
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
+    }
+}
+/**
+ * Assert that the answer to a question is yes, otherwise fail and exit
+ */
+export async function assertYes(question, failureMessage = 'Aborted.') {
+    const yes = await confirm(question);
+    if (!yes)
+        exit(failureMessage);
+}

package/dist/table.d.ts

@@ -0,0 +1,26 @@
+export interface TableColumn<T> {
+    name?: string;
+    size?: number;
+    text(row: T): unknown;
+    length?(row: T): number;
+    /** @deprecated Include the formatting in `text` instead */
+    format?(text: string, row: T): string;
+    /** If set pad the start instead of the end */
+    padStart?: boolean;
+    /** Growth factor when there is extra space */
+    grow?: number;
+}
+export interface TableOptions {
+    /** If specified, indent by this about of spaces before each row */
+    indent?: number;
+    /** Customize the header formatting */
+    formatHead?(text: string): string;
+    /** If set do not output anything. Useful for when you want interleaved output */
+    noOutput?: boolean;
+}
+export declare function setTableTargetWidth(width: number): void;
+export declare function setANSIStripper(fn: (text: string) => string): void;
+/**
+ * Output a table, or prepare to output a table
+ */
+export declare function table<T>(columns: TableColumn<T>[], options?: TableOptions, data?: T[]): (row: T) => void;

package/dist/table.js

@@ -0,0 +1,65 @@
+let targetWidth;
+export function setTableTargetWidth(width) {
+    targetWidth = width;
+}
+/**
+ * Matches CSI/OSC sequences: an introducer (ESC or 8-bit CSI) followed by either
+ * an OSC-style payload terminated by BEL, or parameter bytes plus a final byte.
+ */
+const ansiRegex = 
+// eslint-disable-next-line no-control-regex
+/[\u001B\u009B][[\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\d/#&.:=?%@~_]+)*|[a-zA-Z\d]+(?:;[-a-zA-Z\d/#&.:=?%@~_]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g;
+let stripANSI = (text) => text.replaceAll(ansiRegex, '');
+export function setANSIStripper(fn) {
+    stripANSI = fn;
+}
+/**
+ * Output a table, or prepare to output a table
+ */
+export function table(columns, options = {}, data = []) {
+    const nColumns = columns.length;
+    for (const col of columns) {
+        let max = Math.max(col.size || 0, col.name?.length || 0);
+        for (const row of data)
+            max = Math.max(max, col.length ? col.length(row) : stripANSI(String(col.text(row))).length);
+        col.size = max;
+    }
+    let currentWidth = columns.reduce((sum, col) => sum + col.size, nColumns - 1);
+    const canGrow = columns.some(col => !!(col.grow ?? 1));
+    while (canGrow && targetWidth && currentWidth < targetWidth) {
+        for (const col of columns) {
+            const extra = Math.max(0, Math.min(targetWidth - currentWidth, col.grow ?? 1));
+            col.size += extra;
+            currentWidth += extra;
+        }
+    }
+    function output(row) {
+        const out = [];
+        for (const col of columns) {
+            const text = String(col.text(row));
+            const padding = ' '.repeat(Math.max(0, col.size - stripANSI(text).length));
+            let formatted = col.padStart ? padding + text : text + padding;
+            if (col.format)
+                formatted = col.format(formatted, row);
+            out.push(formatted);
+        }
+        console.log(...out);
+    }
+    function outputHead() {
+        const out = [];
+        for (const col of columns) {
+            const text = String(col.name ?? '');
+            let formatted = col.padStart ? text.padStart(col.size) : text.padEnd(col.size);
+            if (options.formatHead)
+                formatted = options.formatHead(formatted);
+            out.push(formatted);
+        }
+        console.log(...out);
+    }
+    if (!options.noOutput) {
+        outputHead();
+        for (const row of data)
+            output(row);
+    }
+    return output;
+}

package/dist/tracking.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Track the execution of a thunk with appropriate I/O handling.
+ * Errors thrown by the thunk are re-thrown, if you want them logged see {@link tryTrack}.
+ */
+export declare function track<T>(label: string, thunk: () => T): T;
+/**
+ * Track the settlement of a promise with appropriate I/O handling.
+ * Rejections are re-thrown, if you want them logged see {@link tryTrack}.
+ */
+export declare function track<T>(label: string, promise: Promise<T>): Promise<T>;
+/**
+ * Track the execution of a thunk with appropriate I/O handling.
+ * Errors thrown by the thunk are logged, if you want them rethrown see {@link track}.
+ */
+export declare function tryTrack<T>(label: string, thunk: () => T): T | null;
+/**
+ * Track the settlement of a promise with appropriate I/O handling.
+ * Rejections are logged, if you want them thrown see {@link track}.
+ */
+export declare function tryTrack<T>(label: string, promise: Promise<T>): Promise<T | null>;

package/dist/tracking.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: LGPL-3.0-or-later
+import { done, error, errorText, start } from './core.js';
+export function track(label, value) {
+    start(label);
+    if (typeof value == 'function')
+        try {
+            const result = value();
+            done();
+            return result;
+        }
+        catch (e) {
+            done(true);
+            throw e;
+        }
+    return value
+        .then(v => {
+        done();
+        return v;
+    })
+        .catch(e => {
+        done(true);
+        throw e;
+    });
+}
+export function tryTrack(label, value) {
+    start(label);
+    if (typeof value == 'function')
+        try {
+            const result = value();
+            done();
+            return result;
+        }
+        catch (e) {
+            done(true);
+            error(errorText(e));
+            return null;
+        }
+    return value
+        .then(v => {
+        done();
+        return v;
+    })
+        .catch(e => {
+        done(true);
+        error(errorText(e));
+        return null;
+    });
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+	"name": "@james-pre/config",
+	"version": "0.0.1",
+	"description": "Manage configuration files",
+	"funding": {
+		"type": "individual",
+		"url": "https://github.com/sponsors/james-pre"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"type": "module",
+	"exports": {
+		".": "./dist/index.js",
+		"./*": "./dist/*.js"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"format:check": "prettier --check .",
+		"format": "prettier --write .",
+		"build": "tsc",
+		"lint": "tsc --noEmit && eslint src",
+		"prepublishOnly": "npx tsc"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/james-pre/@james-pre/config.git"
+	},
+	"author": "James Prevett <jp@jamespre.dev> (https://jamespre.dev)",
+	"license": "LGPL-3.0-or-later",
+	"bugs": {
+		"url": "https://github.com/james-pre/@james-pre/config/issues"
+	},
+	"homepage": "https://github.com/james-pre/@james-pre/config#readme",
+	"engines": {
+		"node": ">=22.0.0"
+	},
+	"peerDependencies": {
+		"utilium": "^3.7.0",
+		"zod": "^4.5.0"
+	},
+	"publishConfig": {
+		"provenance": true,
+		"access": "public"
+	},
+	"devDependencies": {
+		"@eslint/js": "^10.0.1",
+		"@types/node": "^24.7.0",
+		"eslint": "^10.1.0",
+		"globals": "^17.4.0",
+		"prettier": "^3.2.5",
+		"typedoc": "^0.28.18",
+		"typescript": "^6.0.2",
+		"typescript-eslint": "^8.58.0"
+	},
+	"prettier": {
+		"singleQuote": true,
+		"useTabs": true,
+		"trailingComma": "es5",
+		"tabWidth": 4,
+		"printWidth": 120,
+		"arrowParens": "avoid",
+		"experimentalOperatorPosition": "start"
+	}
+}