@mudah-cli/config 0.8.0 → 0.9.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mudah Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @mudah-cli/config
+
+Typed configuration repository, `.env` loading, and dotted-key access.
+
+Part of [Mudah](https://github.com/thesimonharms/mudah) — an ergonomic, animation-rich CLI
+framework. No Mudah dependencies; usable standalone.
+
+## Install
+
+```sh
+npm install @mudah-cli/config
+```
+
+## Usage
+
+```ts
+import { defineConfig, env, s } from '@mudah-cli/config';
+
+export default defineConfig(
+  s.object({
+    url: s.string(),
+    pool: s.number().min(1).default(5),
+  }),
+  {
+    url: env('DATABASE_URL', 'sqlite:///local.db'),
+    pool: env('DB_POOL', 5),
+  },
+);
+```
+
+Pass a schema as the first argument and a bad value fails at import with every offending key
+listed. `get('db.pool')` reads dotted keys; `mergeConfigFrom` merges defaults under existing
+values (existing wins). `.env` loading is native (`process.loadEnvFile`) with typed parsing in
+`env()`.
+
+## Links
+
+- [Full documentation](https://github.com/thesimonharms/mudah#readme)
+- [License: MIT](LICENSE)

package/dist/config-repository.d.ts

@@ -1,4 +1,26 @@
 import { type Schema, type SchemaResult } from './schema.js';
+/**
+ * Where a dotted key last came from. Later layers win in the usual
+ * defaults < file < env < flag < remote < runtime stack; the repository
+ * records whichever layer the caller passes to `set` / `merge`.
+ */
+export type ConfigLayer = 'default' | 'file' | 'env' | 'flag' | 'remote' | 'runtime';
+/** A single key's recorded layer and current value. */
+export interface ConfigSource {
+    readonly layer: ConfigLayer;
+    readonly value: unknown;
+}
+/** One row of {@link ConfigRepository.precedence}. */
+export interface PrecedenceRow {
+    readonly key: string;
+    readonly layer: ConfigLayer;
+    readonly value: unknown;
+}
+/**
+ * Render precedence rows as `key  layer  value` lines (two spaces between
+ * fields), e.g. `app.name  file  mudah`.
+ */
+export declare function formatPrecedence(rows: ReadonlyArray<PrecedenceRow>): string[];
 /**
  * Dotted-key configuration repository.
  *
@@ -8,8 +30,25 @@ import { type Schema, type SchemaResult } from './schema.js';
  */
 export declare class ConfigRepository {
     private root;
-    /** Set a value at a dotted key, creating intermediate objects as needed. */
-    set(key: string, value: unknown): this;
+    private onChange?;
+    private readonly layers;
+    private boundSchema;
+    /** Register a callback to be notified when any config value is mutated. */
+    onChangeNotification(cb: (key: string) => void): void;
+    /**
+     * Bind a schema used by `config:set` / `config:validate` to reject unknown
+     * keys and type violations. Pass `undefined` to clear.
+     */
+    bindSchema(schema: Schema<unknown> | undefined): this;
+    /** The schema bound by {@link bindSchema}, if any. */
+    get schema(): Schema<unknown> | undefined;
+    set schema(schema: Schema<unknown> | undefined);
+    private notify;
+    /**
+     * Set a value at a dotted key, creating intermediate objects as needed.
+     * `layer` defaults to `'runtime'`.
+     */
+    set(key: string, value: unknown, layer?: ConfigLayer): this;
     /** Read a value at a dotted key, or `defaultValue` when missing. */
     get<T = unknown>(key: string, defaultValue?: T): T;
     /** Whether a dotted key holds a value. */
@@ -20,9 +59,17 @@ export declare class ConfigRepository {
     all(): Record<string, unknown>;
     /**
      * Merge defaults under an existing config group. Values already present
-     * win; missing keys are filled in.
+     * win; missing keys are filled in. Newly filled keys are tagged with
+     * `layer` (default `'default'`).
      */
-    merge(key: string, defaults: Record<string, unknown>): this;
+    merge(key: string, defaults: Record<string, unknown>, layer?: ConfigLayer): this;
+    /**
+     * Which layer last set `key`. `undefined` when the key was never recorded
+     * (missing, or created only as an intermediate object).
+     */
+    source(key: string): ConfigSource | undefined;
+    /** Every recorded key, sorted, with its layer and current value. */
+    precedence(): PrecedenceRow[];
     /** Replace the entire configuration tree. */
     clear(): this;
     /**
@@ -33,4 +80,13 @@ export declare class ConfigRepository {
      * confusing `undefined` three layers down.
      */
     validate<T>(key: string, schema: Schema<T>): SchemaResult<T>;
+    /**
+     * Schema node at `key` when a schema is bound. `undefined` for unknown
+     * keys (or when nothing is bound).
+     */
+    schemaAt(key: string): Schema<unknown> | undefined;
+    private recordLayer;
+    private recordFilled;
+    private pruneMissing;
+    private removeLayers;
 }

package/dist/config-repository.js

@@ -1,5 +1,20 @@
 import { assignPath, deepMerge, hasPath, isPlainObject, readPath, removePath } from './paths.js';
-import { validateSchema } from './schema.js';
+import { schemaAt, validateSchema } from './schema.js';
+function joinKey(prefix, name) {
+    return prefix === '' ? name : `${prefix}.${name}`;
+}
+function formatValue(value) {
+    if (typeof value === 'string')
+        return value;
+    return JSON.stringify(value);
+}
+/**
+ * Render precedence rows as `key  layer  value` lines (two spaces between
+ * fields), e.g. `app.name  file  mudah`.
+ */
+export function formatPrecedence(rows) {
+    return rows.map((row) => `${row.key}  ${row.layer}  ${formatValue(row.value)}`);
+}
 /**
  * Dotted-key configuration repository.
  *
@@ -9,9 +24,40 @@ import { validateSchema } from './schema.js';
  */
 export class ConfigRepository {
     root = {};
-    /** Set a value at a dotted key, creating intermediate objects as needed. */
-    set(key, value) {
+    onChange;
+    layers = new Map();
+    boundSchema;
+    /** Register a callback to be notified when any config value is mutated. */
+    onChangeNotification(cb) {
+        this.onChange = cb;
+    }
+    /**
+     * Bind a schema used by `config:set` / `config:validate` to reject unknown
+     * keys and type violations. Pass `undefined` to clear.
+     */
+    bindSchema(schema) {
+        this.boundSchema = schema;
+        return this;
+    }
+    /** The schema bound by {@link bindSchema}, if any. */
+    get schema() {
+        return this.boundSchema;
+    }
+    set schema(schema) {
+        this.boundSchema = schema;
+    }
+    notify(key) {
+        this.onChange?.(key);
+    }
+    /**
+     * Set a value at a dotted key, creating intermediate objects as needed.
+     * `layer` defaults to `'runtime'`.
+     */
+    set(key, value, layer = 'runtime') {
         assignPath(this.root, key, value);
+        this.recordLayer(key, value, layer);
+        this.pruneMissing(key);
+        this.notify(key);
         return this;
     }
     /** Read a value at a dotted key, or `defaultValue` when missing. */
@@ -24,7 +70,12 @@ export class ConfigRepository {
     }
     /** Remove a dotted key. Returns whether anything was removed. */
     delete(key) {
-        return removePath(this.root, key);
+        const removed = removePath(this.root, key);
+        if (removed) {
+            this.removeLayers(key);
+            this.notify(key);
+        }
+        return removed;
     }
     /** The entire configuration tree (live reference, use with care). */
     all() {
@@ -32,17 +83,46 @@ export class ConfigRepository {
     }
     /**
      * Merge defaults under an existing config group. Values already present
-     * win; missing keys are filled in.
+     * win; missing keys are filled in. Newly filled keys are tagged with
+     * `layer` (default `'default'`).
      */
-    merge(key, defaults) {
+    merge(key, defaults, layer = 'default') {
         const existing = this.get(key, undefined);
+        // A scalar already set at this key wins outright — merging an object under
+        // it would silently discard the value the caller set.
+        if (existing !== undefined && !isPlainObject(existing))
+            return this;
         const base = isPlainObject(existing) ? existing : {};
-        this.set(key, deepMerge(base, defaults));
+        assignPath(this.root, key, deepMerge(base, defaults));
+        this.recordFilled(key, isPlainObject(existing) ? existing : undefined, defaults, layer);
+        this.notify(key);
         return this;
     }
+    /**
+     * Which layer last set `key`. `undefined` when the key was never recorded
+     * (missing, or created only as an intermediate object).
+     */
+    source(key) {
+        const layer = this.layers.get(key);
+        if (layer === undefined)
+            return undefined;
+        return { layer, value: this.get(key) };
+    }
+    /** Every recorded key, sorted, with its layer and current value. */
+    precedence() {
+        return [...this.layers.keys()]
+            .sort()
+            .filter((key) => hasPath(this.root, key))
+            .map((key) => ({
+            key,
+            layer: this.layers.get(key),
+            value: this.get(key),
+        }));
+    }
     /** Replace the entire configuration tree. */
     clear() {
         this.root = {};
+        this.layers.clear();
         return this;
     }
     /**
@@ -56,5 +136,47 @@ export class ConfigRepository {
         const value = key === '' ? this.root : this.get(key, undefined);
         return validateSchema(schema, value, key);
     }
+    /**
+     * Schema node at `key` when a schema is bound. `undefined` for unknown
+     * keys (or when nothing is bound).
+     */
+    schemaAt(key) {
+        if (this.boundSchema === undefined)
+            return undefined;
+        return schemaAt(this.boundSchema, key);
+    }
+    recordLayer(key, value, layer) {
+        this.layers.set(key, layer);
+        if (isPlainObject(value)) {
+            for (const [name, child] of Object.entries(value)) {
+                this.recordLayer(joinKey(key, name), child, layer);
+            }
+        }
+    }
+    recordFilled(prefix, existing, incoming, layer) {
+        for (const [name, value] of Object.entries(incoming)) {
+            const path = joinKey(prefix, name);
+            const had = existing?.[name];
+            if (isPlainObject(value)) {
+                this.recordFilled(path, isPlainObject(had) ? had : undefined, value, layer);
+            }
+            else if (had === undefined) {
+                this.layers.set(path, layer);
+            }
+        }
+    }
+    pruneMissing(prefix) {
+        for (const key of [...this.layers.keys()]) {
+            if ((key === prefix || key.startsWith(`${prefix}.`)) && !hasPath(this.root, key)) {
+                this.layers.delete(key);
+            }
+        }
+    }
+    removeLayers(prefix) {
+        for (const key of [...this.layers.keys()]) {
+            if (key === prefix || key.startsWith(`${prefix}.`))
+                this.layers.delete(key);
+        }
+    }
 }
 //# sourceMappingURL=config-repository.js.map

package/dist/config-repository.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-repository.js","sourceRoot":"","sources":["../src/config-repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACjG,OAAO,EAAE,cAAc,EAAkC,MAAM,aAAa,CAAC;AAE7E;;;;;;GAMG;AACH,MAAM,OAAO,gBAAgB;IACnB,IAAI,GAA4B,EAAE,CAAC;IAE3C,4EAA4E;IAC5E,GAAG,CAAC,GAAW,EAAE,KAAc;QAC7B,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oEAAoE;IACpE,GAAG,CAAc,GAAW,EAAE,YAAgB;QAC5C,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,YAAY,CAAM,CAAC;IACrD,CAAC;IAED,0CAA0C;IAC1C,GAAG,CAAC,GAAW;QACb,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,GAAW;QAChB,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;IAED,qEAAqE;IACrE,GAAG;QACD,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAW,EAAE,QAAiC;QAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAsC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC/E,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6CAA6C;IAC7C,KAAK;QACH,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAI,GAAW,EAAE,MAAiB;QACxC,MAAM,KAAK,GAAG,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAChE,OAAO,cAAc,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC;CACF"}
+{"version":3,"file":"config-repository.js","sourceRoot":"","sources":["../src/config-repository.ts"],"names":[],"mappings":"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"}

package/dist/env.d.ts

@@ -1,12 +1,16 @@
 /**
  * Load a `.env` file into `process.env` using the native
  * `process.loadEnvFile`. Returns false when the file does not exist, so
- * scaffolds work before a `.env` is created.
+ * scaffolds work before a `.env` is created. Any other failure (permissions,
+ * malformed content) is rethrown rather than reported as "missing".
  */
 export declare function loadEnvFile(path?: string): boolean;
 /**
  * Read a typed environment variable. Strings are parsed to booleans
  * (`true`/`false`), null, numbers, and JSON objects/arrays when they look
  * like them; everything else passes through as a string.
+ *
+ * Values are classified on their trimmed form, but a value that stays a string
+ * is returned exactly as found, so surrounding whitespace is preserved.
  */
 export declare function env<T = string>(key: string, defaultValue?: T): T | undefined;

package/dist/env.js

@@ -1,21 +1,27 @@
 /**
  * Load a `.env` file into `process.env` using the native
  * `process.loadEnvFile`. Returns false when the file does not exist, so
- * scaffolds work before a `.env` is created.
+ * scaffolds work before a `.env` is created. Any other failure (permissions,
+ * malformed content) is rethrown rather than reported as "missing".
  */
 export function loadEnvFile(path = '.env') {
     try {
         process.loadEnvFile(path);
         return true;
     }
-    catch {
-        return false;
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return false;
+        throw error;
     }
 }
 /**
  * Read a typed environment variable. Strings are parsed to booleans
  * (`true`/`false`), null, numbers, and JSON objects/arrays when they look
  * like them; everything else passes through as a string.
+ *
+ * Values are classified on their trimmed form, but a value that stays a string
+ * is returned exactly as found, so surrounding whitespace is preserved.
  */
 export function env(key, defaultValue) {
     const raw = process.env[key];
@@ -24,18 +30,19 @@ export function env(key, defaultValue) {
     return parseValue(raw);
 }
 function parseValue(raw) {
-    const lowered = raw.toLowerCase();
+    const text = raw.trim();
+    const lowered = text.toLowerCase();
     if (lowered === 'true')
         return true;
     if (lowered === 'false')
         return false;
     if (lowered === 'null' || lowered === 'none')
         return null;
-    if (/^-?\d+(\.\d+)?$/.test(raw))
-        return Number(raw);
-    if (raw.startsWith('{') || raw.startsWith('[')) {
+    if (looksNumeric(text))
+        return Number(text);
+    if (text.startsWith('{') || text.startsWith('[')) {
         try {
-            return JSON.parse(raw);
+            return JSON.parse(text);
         }
         catch {
             return raw;
@@ -43,4 +50,18 @@ function parseValue(raw) {
     }
     return raw;
 }
+/**
+ * Whether `text` is a plain decimal number worth coercing. Zero-padded
+ * integers (`007`, `0123`) are deliberately excluded — they are almost always
+ * identifiers or codes, and coercing them silently drops the leading zeros.
+ */
+function looksNumeric(text) {
+    const match = /^-?(\d+)(\.\d+)?$/.exec(text);
+    if (!match)
+        return false;
+    const integerPart = match[1];
+    if (integerPart.length > 1 && integerPart.startsWith('0'))
+        return false;
+    return true;
+}
 //# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAAI,GAAG,MAAM;IACvC,IAAI,CAAC;QACH,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAa,GAAW,EAAE,YAAgB;IAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAC3C,OAAO,UAAU,CAAI,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,UAAU,CAAI,GAAW;IAChC,MAAM,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAClC,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,IAAS,CAAC;IACzC,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,KAAU,CAAC;IAC3C,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,IAAS,CAAC;IAC/D,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC,GAAG,CAAM,CAAC;IACzD,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,GAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAI,GAAG,MAAM;IACvC,IAAI,CAAC;QACH,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA2C,EAAE,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAClF,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,GAAG,CAAa,GAAW,EAAE,YAAgB;IAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAC3C,OAAO,UAAU,CAAI,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,UAAU,CAAI,GAAW;IAChC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACxB,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACnC,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,IAAS,CAAC;IACzC,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,KAAU,CAAC;IAC3C,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,IAAS,CAAC;IAC/D,IAAI,YAAY,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAM,CAAC;IACjD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,GAAQ,CAAC;AAClB,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,IAAY;IAChC,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IAC9B,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACxE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,10 @@
-export { ConfigRepository } from './config-repository.js';
+export { type ConfigLayer, ConfigRepository, type ConfigSource, formatPrecedence, type PrecedenceRow, } from './config-repository.js';
 export { defineConfig } from './define-config.js';
 export { env, loadEnvFile } from './env.js';
-export { loadConfigFiles, type LoadConfigOptions } from './load-config-files.js';
+export { type LoadConfigOptions, loadConfigFiles } from './load-config-files.js';
 export { deepMerge, isPlainObject } from './paths.js';
-export { assertSchema, ConfigValidationError, s, validateSchema, type AnySchemaBuilder, type ArraySchemaBuilder, type BooleanSchemaBuilder, type NumberSchemaBuilder, type ObjectShape, type ObjectSchemaBuilder, type Schema, type SchemaIssue, type SchemaResult, type StringSchemaBuilder, } from './schema.js';
+export { REDACT_KEYS, type RedactOptions, redactSecrets } from './redact.js';
+export { assertRemoteUrl, type LoadRemoteConfigOptions, loadRemoteConfig, REMOTE_CONFIG_CACHE_FILE, REMOTE_CONFIG_TTL_MS, resolveRemoteUrl, } from './remote.js';
+export { type AnySchemaBuilder, type ArraySchemaBuilder, assertSchema, type BooleanSchemaBuilder, ConfigValidationError, type NumberSchemaBuilder, type ObjectSchemaBuilder, type ObjectShape, type Schema, type SchemaIssue, type SchemaResult, type StringSchemaBuilder, s, schemaAt, validateSchema, } from './schema.js';
+export { createSecretStore, envSecretDriver, fileSecretDriver, type KeyringDriverOptions, type KeyringSpawn, type KeyringSpawnResult, keyringSecretDriver, type ResolveSecretOptions, resolveSecret, type SecretDriver, SecretStore, type SecretStoreOptions, } from './secrets.js';
+export { type ConfigReloadSignalOptions, type ConfigWatchFn, installConfigReloadSignal, type SignalProcess, type WatchConfigOptions, watchConfig, } from './watch.js';

package/dist/index.js

@@ -1,7 +1,11 @@
-export { ConfigRepository } from './config-repository.js';
+export { ConfigRepository, formatPrecedence, } from './config-repository.js';
 export { defineConfig } from './define-config.js';
 export { env, loadEnvFile } from './env.js';
 export { loadConfigFiles } from './load-config-files.js';
 export { deepMerge, isPlainObject } from './paths.js';
-export { assertSchema, ConfigValidationError, s, validateSchema, } from './schema.js';
+export { REDACT_KEYS, redactSecrets } from './redact.js';
+export { assertRemoteUrl, loadRemoteConfig, REMOTE_CONFIG_CACHE_FILE, REMOTE_CONFIG_TTL_MS, resolveRemoteUrl, } from './remote.js';
+export { assertSchema, ConfigValidationError, s, schemaAt, validateSchema, } from './schema.js';
+export { createSecretStore, envSecretDriver, fileSecretDriver, keyringSecretDriver, resolveSecret, SecretStore, } from './secrets.js';
+export { installConfigReloadSignal, watchConfig, } from './watch.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAAE,eAAe,EAA0B,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,CAAC,EACD,cAAc,GAWf,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,gBAAgB,EAEhB,gBAAgB,GAEjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAA0B,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,WAAW,EAAsB,aAAa,EAAE,MAAM,aAAa,CAAC;AAC7E,OAAO,EACL,eAAe,EAEf,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAGL,YAAY,EAEZ,qBAAqB,EAQrB,CAAC,EACD,QAAQ,EACR,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAIhB,mBAAmB,EAEnB,aAAa,EAEb,WAAW,GAEZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,yBAAyB,EAGzB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/load-config-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"load-config-files.js","sourceRoot":"","sources":["../src/load-config-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAOzC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,OAAO,GAAsB,EAAE;IAE/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC;IACpC,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAE7D,IAAI,OAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO;SAClB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;SAC1E,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1B,IAAI,EAAE,CAAC;IAEV,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACnE,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC;YACjC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACvC,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YACvB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,OAAO,CAAC,KAAK,CAAC,2BAA2B,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"load-config-files.js","sourceRoot":"","sources":["../src/load-config-files.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAOzC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAgB,EAChB,OAAO,GAAsB,EAAE;IAE/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,QAAQ,CAAC;IACpC,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAE7D,IAAI,OAAyB,CAAC;IAC9B,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,OAAO;SAClB,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;SAC1E,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;SAC1B,IAAI,EAAE,CAAC;IAEV,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACnE,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC;YACjC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACvC,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YACvB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,OAAO,CAAC,KAAK,CAAC,2BAA2B,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/paths.d.ts

@@ -1,10 +1,21 @@
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Throw when a write key tries to address the prototype chain. */
+export declare function assertSafeKey(key: string): void;
 export declare function readPath(root: Record<string, unknown>, key: string, defaultValue?: unknown): unknown;
 export declare function hasPath(root: Record<string, unknown>, key: string): boolean;
 export declare function assignPath(root: Record<string, unknown>, key: string, value: unknown): void;
 export declare function removePath(root: Record<string, unknown>, key: string): boolean;
+/**
+ * Deep copy a config value so the repository never aliases the caller's
+ * objects. Plain objects and arrays are copied; other values (Date, Map,
+ * class instances, functions) are shared as-is — merging config should not
+ * silently clone arbitrary user objects.
+ */
+export declare function cloneConfigValue<T>(value: T): T;
 /**
  * Deep-merge where `target` wins: values already present in the target are
  * kept, missing keys are filled in from `source` (mergeConfig semantics).
+ * Filled-in containers are copied, so the result never shares structure with
+ * `source`.
  */
 export declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Record<string, unknown>): T;

package/dist/paths.js

@@ -4,13 +4,27 @@ export function isPlainObject(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * Segments that would walk (or write) the prototype chain. `Object.prototype`
+ * itself satisfies `isPlainObject` (its prototype is null), so a `__proto__`
+ * segment would otherwise let a dotted key reach the global prototype.
+ */
+const FORBIDDEN_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
+/** Throw when a write key tries to address the prototype chain. */
+export function assertSafeKey(key) {
+    for (const segment of segments(key)) {
+        if (FORBIDDEN_SEGMENTS.has(segment)) {
+            throw new Error(`[config] Refusing to use "${segment}" in config key "${key}" (prototype-pollution guard).`);
+        }
+    }
+}
 function segments(key) {
     return key.split('.');
 }
 export function readPath(root, key, defaultValue) {
     let current = root;
     for (const segment of segments(key)) {
-        if (!isPlainObject(current))
+        if (!isPlainObject(current) || !Object.hasOwn(current, segment))
             return defaultValue;
         current = current[segment];
     }
@@ -18,19 +32,20 @@ export function readPath(root, key, defaultValue) {
 }
 export function hasPath(root, key) {
     let current = root;
-    const parts = segments(key);
-    for (const segment of parts) {
-        if (!isPlainObject(current) || !(segment in current))
+    for (const segment of segments(key)) {
+        if (!isPlainObject(current) || !Object.hasOwn(current, segment))
             return false;
         current = current[segment];
     }
     return true;
 }
 export function assignPath(root, key, value) {
+    assertSafeKey(key);
     const parts = segments(key);
     let current = root;
     for (const segment of parts.slice(0, -1)) {
-        const next = current[segment];
+        // Descend only through own plain objects; never into a prototype.
+        const next = Object.hasOwn(current, segment) ? current[segment] : undefined;
         if (!isPlainObject(next)) {
             current[segment] = {};
         }
@@ -43,20 +58,42 @@ export function removePath(root, key) {
     const parts = segments(key);
     let current = root;
     for (const segment of parts.slice(0, -1)) {
-        const next = current[segment];
+        const next = Object.hasOwn(current, segment) ? current[segment] : undefined;
         if (!isPlainObject(next))
             return false;
         current = next;
     }
     const last = parts[parts.length - 1];
-    if (!(last in current))
+    if (!Object.hasOwn(current, last))
         return false;
     delete current[last];
     return true;
 }
+/**
+ * Deep copy a config value so the repository never aliases the caller's
+ * objects. Plain objects and arrays are copied; other values (Date, Map,
+ * class instances, functions) are shared as-is — merging config should not
+ * silently clone arbitrary user objects.
+ */
+export function cloneConfigValue(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => cloneConfigValue(entry));
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [key, entry] of Object.entries(value)) {
+            if (FORBIDDEN_SEGMENTS.has(key))
+                continue;
+            out[key] = cloneConfigValue(entry);
+        }
+        return out;
+    }
+    return value;
+}
 /**
  * Deep-merge where `target` wins: values already present in the target are
  * kept, missing keys are filled in from `source` (mergeConfig semantics).
+ * Filled-in containers are copied, so the result never shares structure with
+ * `source`.
  */
 export function deepMerge(target, source) {
     const result = { ...target };
@@ -66,7 +103,7 @@ export function deepMerge(target, source) {
             result[key] = deepMerge(existing, value);
         }
         else if (existing === undefined) {
-            result[key] = value;
+            result[key] = cloneConfigValue(value);
         }
     }
     return result;

package/dist/paths.js.map

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

package/dist/redact.d.ts

@@ -0,0 +1,14 @@
+/** Key names whose values are treated as secrets and masked in dumps. */
+export declare const REDACT_KEYS: ReadonlyArray<RegExp>;
+export interface RedactOptions {
+    /** Override the set of sensitive key patterns. */
+    keys?: ReadonlyArray<RegExp>;
+    /** Replacement rendered in place of a redacted value. */
+    mask?: string;
+}
+/**
+ * Recursively replace values whose key is sensitive. Scalars under matching
+ * keys become `mask`; objects/arrays recurse so sensitive leaves are masked
+ * regardless of depth. Non-sensitive scalars and arrays pass through unchanged.
+ */
+export declare function redactSecrets(value: unknown, options?: RedactOptions): unknown;