@mudah-cli/config 0.7.0 → 0.9.0

package/dist/secrets.js

@@ -0,0 +1,302 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isPlainObject } from './paths.js';
+import { redactSecrets } from './redact.js';
+const ENV_PREFIX = 'MUDAH_SECRET_';
+function readJsonObject(file) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (!isPlainObject(parsed))
+            return {};
+        const out = {};
+        for (const [key, value] of Object.entries(parsed)) {
+            if (typeof value === 'string')
+                out[key] = value;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+function writeJsonObject(file, data) {
+    mkdirSync(join(file, '..'), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    // mode on writeFileSync is ignored when the file already exists.
+    chmodSync(file, 0o600);
+}
+function defaultSecretsDir() {
+    return join(homedir(), '.mudah', 'secrets');
+}
+function secretsFile(dir) {
+    return dir.endsWith('.json') ? dir : join(dir, 'secrets.json');
+}
+/**
+ * Read secrets from the environment. `get('FOO')` looks at
+ * `MUDAH_SECRET_FOO`, then `process.env.FOO`.
+ */
+export function envSecretDriver(env = process.env) {
+    return {
+        name: 'env',
+        get(name) {
+            const prefixed = env[`${ENV_PREFIX}${name}`];
+            if (prefixed !== undefined)
+                return prefixed;
+            const upper = env[`${ENV_PREFIX}${name.toUpperCase()}`];
+            if (upper !== undefined)
+                return upper;
+            return env[name];
+        },
+        set(name, value) {
+            env[`${ENV_PREFIX}${name}`] = value;
+        },
+        delete(name) {
+            const keys = [`${ENV_PREFIX}${name}`, `${ENV_PREFIX}${name.toUpperCase()}`, name];
+            let removed = false;
+            for (const key of keys) {
+                if (env[key] !== undefined) {
+                    delete env[key];
+                    removed = true;
+                }
+            }
+            return removed;
+        },
+        list() {
+            const names = [];
+            for (const key of Object.keys(env)) {
+                if (key.startsWith(ENV_PREFIX))
+                    names.push(key.slice(ENV_PREFIX.length));
+            }
+            return names;
+        },
+    };
+}
+/**
+ * Persist secrets as a JSON object. `dir` is a directory (`secrets.json`
+ * inside it) or a `.json` file path.
+ */
+export function fileSecretDriver(dir) {
+    const file = secretsFile(dir);
+    return {
+        name: 'file',
+        get(name) {
+            return readJsonObject(file)[name];
+        },
+        set(name, value) {
+            const data = readJsonObject(file);
+            data[name] = value;
+            writeJsonObject(file, data);
+        },
+        delete(name) {
+            const data = readJsonObject(file);
+            if (!(name in data))
+                return false;
+            delete data[name];
+            writeJsonObject(file, data);
+            return true;
+        },
+        list() {
+            return Object.keys(readJsonObject(file));
+        },
+    };
+}
+function defaultKeyringSpawn(command, args, options = {}) {
+    try {
+        const result = spawnSync(command, [...args], {
+            encoding: 'utf8',
+            input: options.input,
+            timeout: 3000,
+        });
+        if (result.error)
+            return null;
+        return { status: result.status ?? 1, stdout: result.stdout ?? '' };
+    }
+    catch {
+        return null;
+    }
+}
+function toolAvailable(spawn, command) {
+    return spawn(command, ['--version']) !== null;
+}
+function fallbackKeyringFile(options) {
+    if (options.filePath !== undefined && options.filePath.length > 0)
+        return options.filePath;
+    const home = options.home ?? homedir();
+    return join(home, '.mudah', 'keyring.json');
+}
+function pickBackend(spawn, platform) {
+    const order = platform === 'darwin' ? ['security', 'secret-tool'] : ['secret-tool', 'security'];
+    for (const command of order) {
+        if (toolAvailable(spawn, command))
+            return command;
+    }
+    return 'file';
+}
+/**
+ * Best-effort OS keyring. Tries `secret-tool` (libsecret) or `security`
+ * (macOS) via an injectable spawn. When neither tool is available, secrets
+ * live in `~/.mudah/keyring.json`.
+ */
+export function keyringSecretDriver(options = {}) {
+    const spawn = options.spawn ?? defaultKeyringSpawn;
+    const platform = options.platform ?? process.platform;
+    const fileDriver = fileSecretDriver(fallbackKeyringFile(options));
+    let backend;
+    const resolve = () => {
+        if (backend === undefined)
+            backend = pickBackend(spawn, platform);
+        return backend;
+    };
+    return {
+        name: 'keyring',
+        get(name) {
+            const kind = resolve();
+            if (kind === 'file')
+                return fileDriver.get(name);
+            if (kind === 'secret-tool') {
+                const result = spawn('secret-tool', ['lookup', 'service', 'mudah', 'key', name]);
+                if (result !== null && result.status === 0) {
+                    const value = result.stdout.replace(/\n$/, '');
+                    if (value.length > 0)
+                        return value;
+                }
+                // A store that fell back to the file (tool missing/refused) must be
+                // readable here too, otherwise `set` writes something `get` can't see.
+                return fileDriver.get(name);
+            }
+            const result = spawn('security', ['find-generic-password', '-s', 'mudah', '-a', name, '-w']);
+            if (result !== null && result.status === 0) {
+                const value = result.stdout.replace(/\n$/, '');
+                if (value.length > 0)
+                    return value;
+            }
+            // macOS writes go to the file backend (see `set`), so read it back.
+            return fileDriver.get(name);
+        },
+        set(name, value) {
+            const kind = resolve();
+            if (kind === 'file') {
+                fileDriver.set(name, value);
+                return;
+            }
+            if (kind === 'secret-tool') {
+                const result = spawn('secret-tool', ['store', '--label', `mudah:${name}`, 'service', 'mudah', 'key', name], { input: value });
+                if (result === null || result.status !== 0)
+                    fileDriver.set(name, value);
+                return;
+            }
+            // macOS `security -w` puts the secret on argv (visible in `ps`).
+            // Writes go to the 0600 file backend instead.
+            fileDriver.set(name, value);
+        },
+        delete(name) {
+            const kind = resolve();
+            if (kind === 'file')
+                return fileDriver.delete(name);
+            if (kind === 'secret-tool') {
+                const result = spawn('secret-tool', ['clear', 'service', 'mudah', 'key', name]);
+                const fileRemoved = fileDriver.delete(name);
+                return (result !== null && result.status === 0) || fileRemoved;
+            }
+            const result = spawn('security', ['delete-generic-password', '-s', 'mudah', '-a', name]);
+            const fileRemoved = fileDriver.delete(name);
+            return (result !== null && result.status === 0) || fileRemoved;
+        },
+        list() {
+            const names = new Set(fileDriver.list());
+            const kind = resolve();
+            if (kind === 'secret-tool') {
+                // `secret-tool search` prints one block per match, with each stored
+                // attribute as `attribute.key = <name>`.
+                const result = spawn('secret-tool', ['search', '--all', 'service', 'mudah']);
+                if (result !== null && result.status === 0) {
+                    for (const line of result.stdout.split('\n')) {
+                        const match = /^\s*attribute\.key\s*=\s*(.+?)\s*$/.exec(line);
+                        if (match?.[1] !== undefined)
+                            names.add(match[1]);
+                    }
+                }
+            }
+            return [...names].sort();
+        },
+    };
+}
+/**
+ * First-win secret store. `get` returns the first driver that has the name;
+ * `set` writes to the first driver; `delete` removes the name from every
+ * driver so a later one can't resurrect it.
+ */
+export class SecretStore {
+    drivers;
+    constructor(options) {
+        this.drivers = options.drivers;
+    }
+    get(name) {
+        for (const driver of this.drivers) {
+            const value = driver.get(name);
+            if (value !== undefined)
+                return value;
+        }
+        return undefined;
+    }
+    set(name, value) {
+        const driver = this.drivers[0];
+        driver?.set(name, value);
+    }
+    delete(name) {
+        let removed = false;
+        for (const driver of this.drivers) {
+            if (driver.delete(name))
+                removed = true;
+        }
+        return removed;
+    }
+    list() {
+        const names = new Set();
+        for (const driver of this.drivers) {
+            for (const name of driver.list())
+                names.add(name);
+        }
+        return [...names];
+    }
+    /** Redacted view of every stored secret. Safe for `dump` / debug output. */
+    dump() {
+        const raw = {};
+        for (const name of this.list()) {
+            const value = this.get(name);
+            if (value !== undefined)
+                raw[name] = value;
+        }
+        return redactSecrets(raw, { keys: [/.+/] });
+    }
+    /** Alias of {@link dump} for debug printers. */
+    debug() {
+        return this.dump();
+    }
+}
+/** Build a {@link SecretStore} from an ordered driver list. */
+export function createSecretStore(options) {
+    return new SecretStore(options);
+}
+const SECRET_REF = /^(env|file|keyring):(.+)$/;
+/**
+ * Resolve a secret reference (`env:FOO`, `file:token`, `keyring:api`).
+ * Unknown or empty refs return `undefined`.
+ */
+export function resolveSecret(ref, options = {}) {
+    const match = SECRET_REF.exec(ref);
+    if (!match)
+        return undefined;
+    const kind = match[1];
+    const name = match[2] ?? '';
+    if (name.length === 0)
+        return undefined;
+    if (kind === 'env')
+        return envSecretDriver(options.env).get(name);
+    if (kind === 'file')
+        return fileSecretDriver(options.fileDir ?? defaultSecretsDir()).get(name);
+    return keyringSecretDriver(options.keyring).get(name);
+}
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"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"}

package/dist/watch.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Minimal `fs.watch` surface. Tests inject a fake so they never touch the
+ * real filesystem or need a live file.
+ */
+export type ConfigWatchFn = (path: string, listener: (eventType: string, filename: string | Buffer | null) => void) => {
+    close(): void;
+};
+export interface WatchConfigOptions {
+    /** Aborting this signal disposes the watchers. */
+    signal?: AbortSignal;
+    /** Watch implementation (default `fs.watch`). */
+    watch?: ConfigWatchFn;
+}
+/**
+ * Watch config files and invoke `onReload` when any of them change.
+ * Returns a disposer. Missing paths are skipped; `signal` abort is equivalent
+ * to calling the disposer.
+ */
+export declare function watchConfig(paths: string | readonly string[], onReload: (path: string) => void, options?: WatchConfigOptions): () => void;
+/**
+ * Enough of `process` to subscribe to SIGUSR1. Tests inject an EventEmitter
+ * so they never signal the real process.
+ */
+export interface SignalProcess {
+    on(event: string, listener: (...args: unknown[]) => void): unknown;
+    removeListener?(event: string, listener: (...args: unknown[]) => void): unknown;
+    off?(event: string, listener: (...args: unknown[]) => void): unknown;
+}
+export interface ConfigReloadSignalOptions {
+    process?: SignalProcess;
+}
+/**
+ * Call `reload` when the process receives SIGUSR1. Returns a disposer that
+ * removes the handler.
+ */
+export declare function installConfigReloadSignal(reload: () => void | Promise<void>, options?: ConfigReloadSignalOptions): () => void;

package/dist/watch.js

@@ -0,0 +1,57 @@
+import { watch as fsWatch } from 'node:fs';
+/**
+ * Watch config files and invoke `onReload` when any of them change.
+ * Returns a disposer. Missing paths are skipped; `signal` abort is equivalent
+ * to calling the disposer.
+ */
+export function watchConfig(paths, onReload, options = {}) {
+    const list = typeof paths === 'string' ? [paths] : [...paths];
+    const watchFn = options.watch ?? defaultWatch;
+    const watchers = [];
+    const dispose = () => {
+        for (const watcher of watchers) {
+            try {
+                watcher.close();
+            }
+            catch {
+                // already closed
+            }
+        }
+        watchers.length = 0;
+    };
+    if (options.signal?.aborted)
+        return dispose;
+    for (const path of list) {
+        try {
+            watchers.push(watchFn(path, () => {
+                onReload(path);
+            }));
+        }
+        catch {
+            // Missing path, or the platform rejected the watch.
+        }
+    }
+    options.signal?.addEventListener('abort', dispose, { once: true });
+    return dispose;
+}
+function defaultWatch(path, listener) {
+    return fsWatch(path, listener);
+}
+/**
+ * Call `reload` when the process receives SIGUSR1. Returns a disposer that
+ * removes the handler.
+ */
+export function installConfigReloadSignal(reload, options = {}) {
+    const proc = options.process ?? process;
+    const handler = () => {
+        void reload();
+    };
+    proc.on('SIGUSR1', handler);
+    return () => {
+        if (typeof proc.removeListener === 'function')
+            proc.removeListener('SIGUSR1', handler);
+        else
+            proc.off?.('SIGUSR1', handler);
+    };
+}
+//# sourceMappingURL=watch.js.map

package/dist/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../src/watch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,OAAO,EAAE,MAAM,SAAS,CAAC;AAkB3C;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,KAAiC,EACjC,QAAgC,EAChC,OAAO,GAAuB,EAAE;IAEhC,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;IAC9C,MAAM,QAAQ,GAA6B,EAAE,CAAC;IAE9C,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,iBAAiB;YACnB,CAAC;QACH,CAAC;QACD,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IACtB,CAAC,CAAC;IAEF,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5C,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CACX,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE;gBACjB,QAAQ,CAAC,IAAI,CAAC,CAAC;YACjB,CAAC,CAAC,CACH,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,oDAAoD;QACtD,CAAC;IACH,CAAC;IAED,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,YAAY,CACnB,IAAY,EACZ,QAAuE;IAEvE,OAAO,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACjC,CAAC;AAgBD;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAkC,EAClC,OAAO,GAA8B,EAAE;IAEvC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC;IACxC,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,KAAK,MAAM,EAAE,CAAC;IAChB,CAAC,CAAC;IACF,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC5B,OAAO,GAAG,EAAE;QACV,IAAI,OAAO,IAAI,CAAC,cAAc,KAAK,UAAU;YAAE,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;;YAClF,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,9 +1,23 @@
 {
   "name": "@mudah-cli/config",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Typed configuration repository, .env loading, and dotted-key access.",
   "type": "module",
   "license": "MIT",
+  "author": "Mudah Contributors",
+  "homepage": "https://github.com/thesimonharms/mudah#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thesimonharms/mudah.git",
+    "directory": "packages/config"
+  },
+  "keywords": [
+    "config",
+    "dotenv",
+    "schema",
+    "validation",
+    "typescript"
+  ],
   "engines": {
     "node": ">=26"
   },