@ontrails/config 1.0.0-beta.12

package/dist/define-config.js

@@ -0,0 +1,90 @@
+/**
+ * Trails-specific config wrapper — `appConfig('trails', ...)` with
+ * framework conventions for loadout selection and local overrides.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { appConfig } from './app-config.js';
+import { resolveConfig } from './resolve.js';
+// ---------------------------------------------------------------------------
+// Local overrides discovery
+// ---------------------------------------------------------------------------
+const LOCAL_OVERRIDE_CANDIDATES = ['local.ts', 'local.js'];
+/**
+ * Discover and synchronously import a `.trails/config/local.{ts,js}` file.
+ *
+ * Skipped when `TRAILS_ENV=test` for hermetic test environments.
+ */
+const discoverLocalOverrides = async (cwd, envRecord) => {
+    if (envRecord['TRAILS_ENV'] === 'test') {
+        return undefined;
+    }
+    for (const filename of LOCAL_OVERRIDE_CANDIDATES) {
+        const candidate = join(cwd, '.trails', 'config', filename);
+        if (existsSync(candidate)) {
+            const mod = await import(candidate);
+            return (mod['default'] ?? mod);
+        }
+    }
+    return undefined;
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Define Trails app config.
+ *
+ * This is `appConfig('trails', ...)` with the framework's own conventions:
+ * `TRAILS_ENV` selects the loadout. When `envFromNodeEnv` is true,
+ * `NODE_ENV` is used as a fallback when `TRAILS_ENV` is unset.
+ *
+ * @example
+ * ```ts
+ * const config = defineConfig({
+ *   schema: z.object({
+ *     port: z.number().default(3000),
+ *     debug: z.boolean().default(false),
+ *   }),
+ *   base: { port: 8080 },
+ *   loadouts: {
+ *     production: { debug: false },
+ *     test: { debug: true, port: 0 },
+ *   },
+ * });
+ *
+ * const result = config.resolve();
+ * ```
+ */
+export const defineConfig = (options) => {
+    const config = appConfig('trails', {
+        formats: ['toml', 'json'],
+        schema: options.schema,
+    });
+    return {
+        ...config,
+        base: options.base,
+        loadouts: options.loadouts,
+        resolve: async (resolveOpts) => {
+            const envRecord = {
+                ...(resolveOpts?.env ?? process.env),
+            };
+            if (options.envFromNodeEnv &&
+                envRecord['TRAILS_ENV'] === undefined &&
+                envRecord['NODE_ENV'] !== undefined) {
+                envRecord['TRAILS_ENV'] = envRecord['NODE_ENV'];
+            }
+            const cwd = resolveOpts?.cwd ?? process.cwd();
+            const localOverrides = await discoverLocalOverrides(cwd, envRecord);
+            return resolveConfig({
+                base: options.base,
+                env: envRecord,
+                loadout: resolveOpts?.loadout ?? envRecord['TRAILS_ENV'],
+                loadouts: options.loadouts,
+                localOverrides,
+                schema: options.schema,
+            });
+        },
+        schema: options.schema,
+    };
+};
+//# sourceMappingURL=define-config.js.map

package/dist/define-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../src/define-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAuB7C,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E,MAAM,yBAAyB,GAAG,CAAC,UAAU,EAAE,UAAU,CAAU,CAAC;AAEpE;;;;GAIG;AACH,MAAM,sBAAsB,GAAG,KAAK,EAClC,GAAW,EACX,SAA6C,EACC,EAAE;IAChD,IAAI,SAAS,CAAC,YAAY,CAAC,KAAK,MAAM,EAAE,CAAC;QACvC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,MAAM,QAAQ,IAAI,yBAAyB,EAAE,CAAC;QACjD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAC3D,IAAI,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC1B,MAAM,GAAG,GAA4B,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;YAC7D,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,GAAG,CAA4B,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAEF,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,OAA+B,EAC/B,EAAE;IACF,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,EAAE;QACjC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;QACzB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;IAEH,OAAO;QACL,GAAG,MAAM;QACT,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,OAAO,EAAE,KAAK,EAAE,WAAwC,EAAE,EAAE;YAC1D,MAAM,SAAS,GAAG;gBAChB,GAAG,CAAC,WAAW,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;aACC,CAAC;YAExC,IACE,OAAO,CAAC,cAAc;gBACtB,SAAS,CAAC,YAAY,CAAC,KAAK,SAAS;gBACrC,SAAS,CAAC,UAAU,CAAC,KAAK,SAAS,EACnC,CAAC;gBACD,SAAS,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;YAClD,CAAC;YAED,MAAM,GAAG,GAAG,WAAW,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;YAC9C,MAAM,cAAc,GAAG,MAAM,sBAAsB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAEpE,OAAO,aAAa,CAAC;gBACnB,IAAI,EAAE,OAAO,CAAC,IAA2C;gBACzD,GAAG,EAAE,SAAS;gBACd,OAAO,EAAE,WAAW,EAAE,OAAO,IAAI,SAAS,CAAC,YAAY,CAAC;gBACxD,QAAQ,EAAE,OAAO,CAAC,QAEL;gBACb,cAAc;gBACd,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC,CAAC;QACL,CAAC;QACD,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC;AACJ,CAAC,CAAC"}

package/dist/describe.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Config introspection — describe all fields in a schema without values.
+ *
+ * Returns a structured catalog suitable for CLI rendering or agent inspection.
+ */
+import type { z } from 'zod';
+/** Description of a single config field. */
+export interface FieldDescription {
+    readonly path: string;
+    readonly type: string;
+    readonly description?: string;
+    readonly default?: unknown;
+    readonly required: boolean;
+    readonly env?: string;
+    readonly secret?: boolean;
+    readonly deprecated?: string;
+    readonly constraints?: Record<string, unknown>;
+}
+/**
+ * Describe all fields in a schema without needing a config file.
+ *
+ * Returns a structured catalog suitable for CLI rendering or agent inspection.
+ */
+export declare const describeConfig: (schema: z.ZodObject<Record<string, z.ZodType>>) => readonly FieldDescription[];
+//# sourceMappingURL=describe.d.ts.map

package/dist/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["../src/describe.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAS7B,4CAA4C;AAC5C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChD;AAsMD;;;;GAIG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAC7C,SAAS,gBAAgB,EAmB3B,CAAC"}

package/dist/describe.js

@@ -0,0 +1,147 @@
+/**
+ * Config introspection — describe all fields in a schema without values.
+ *
+ * Returns a structured catalog suitable for CLI rendering or agent inspection.
+ */
+import { globalRegistry } from 'zod';
+import { collectConfigMeta } from './collect.js';
+import { isZodObject, unwrapToBase, zodDef } from './zod-utils.js';
+// ---------------------------------------------------------------------------
+// Helpers (defined before consumers — satisfies no-use-before-define)
+// ---------------------------------------------------------------------------
+/** Read the description from the Zod global registry. */
+const getDescription = (schema) => {
+    const meta = globalRegistry.get(schema);
+    return meta?.description;
+};
+/** Handle a single unwrap step; returns updated inner type and state, or null to stop. */
+const unwrapStep = (def, state) => {
+    const typeName = def['type'];
+    if (typeName === 'default') {
+        return {
+            inner: def['innerType'],
+            state: { ...state, defaultValue: def['defaultValue'], hasDefault: true },
+        };
+    }
+    if (typeName === 'optional') {
+        return {
+            inner: def['innerType'],
+            state: { ...state, isOptional: true },
+        };
+    }
+    if (typeName === 'nullable') {
+        return { inner: def['innerType'], state };
+    }
+    return null;
+};
+/** Unwrap through default/optional/nullable wrappers to find the base type. */
+const unwrapSchema = (schema) => {
+    let current = schema;
+    let state = {
+        defaultValue: undefined,
+        hasDefault: false,
+        isOptional: false,
+    };
+    for (let depth = 0; depth < 10; depth += 1) {
+        const result = unwrapStep(zodDef(current), state);
+        if (!result) {
+            break;
+        }
+        current = result.inner;
+        ({ state } = result);
+    }
+    return { base: current, ...state };
+};
+/** Resolve the user-facing type name from a base Zod schema. */
+const resolveTypeName = (schema) => {
+    const typeName = zodDef(schema)['type'];
+    const typeMap = {
+        boolean: 'boolean',
+        enum: 'enum',
+        number: 'number',
+        string: 'string',
+    };
+    return typeMap[typeName] ?? typeName;
+};
+/** Extract enum values from an enum def. */
+const extractEnumConstraints = (def) => {
+    const entries = def['entries'];
+    if (!entries) {
+        return undefined;
+    }
+    return { values: Object.values(entries) };
+};
+/** Extract min/max from a number schema's properties. */
+const extractNumberConstraints = (schema) => {
+    const result = {};
+    const numSchema = schema;
+    if (numSchema.minValue !== undefined && numSchema.minValue !== null) {
+        result['min'] = numSchema.minValue;
+    }
+    if (numSchema.maxValue !== undefined && numSchema.maxValue !== null) {
+        result['max'] = numSchema.maxValue;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+};
+/** Extract constraints from a base schema (min, max, enum values). */
+const extractConstraints = (schema) => {
+    const def = zodDef(schema);
+    const typeName = def['type'];
+    if (typeName === 'enum') {
+        return extractEnumConstraints(def);
+    }
+    if (typeName === 'number') {
+        return extractNumberConstraints(schema);
+    }
+    return undefined;
+};
+/** Build a single FieldDescription from a leaf schema and its metadata. */
+const buildFieldDescription = (path, fieldSchema, configMeta) => {
+    const { base, defaultValue, hasDefault, isOptional } = unwrapSchema(fieldSchema);
+    const meta = configMeta.get(path);
+    const description = getDescription(base) ?? getDescription(fieldSchema);
+    const constraints = extractConstraints(base);
+    return {
+        ...(constraints ? { constraints } : {}),
+        ...(hasDefault ? { default: defaultValue } : {}),
+        ...(meta?.deprecated ? { deprecated: meta.deprecated } : {}),
+        ...(description ? { description } : {}),
+        ...(meta?.env ? { env: meta.env } : {}),
+        path,
+        required: !hasDefault && !isOptional,
+        ...(meta?.secret ? { secret: meta.secret } : {}),
+        type: resolveTypeName(base),
+    };
+};
+/** Walk one level of an object shape, collecting leaves and queuing nested objects. */
+const walkShapeLevel = (shape, prefix, configMeta, results, queue) => {
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (isZodObject(fieldSchema)) {
+            queue.push({ prefix: path, schema: unwrapToBase(fieldSchema) });
+        }
+        else {
+            results.push(buildFieldDescription(path, fieldSchema, configMeta));
+        }
+    }
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Describe all fields in a schema without needing a config file.
+ *
+ * Returns a structured catalog suitable for CLI rendering or agent inspection.
+ */
+export const describeConfig = (schema) => {
+    const configMeta = collectConfigMeta(schema);
+    const queue = [];
+    const results = [];
+    walkShapeLevel(schema.shape, '', configMeta, results, queue);
+    for (let entry = queue.pop(); entry; entry = queue.pop()) {
+        const nested = zodDef(entry.schema)['shape'];
+        walkShapeLevel(nested, entry.prefix, configMeta, results, queue);
+    }
+    return results;
+};
+//# sourceMappingURL=describe.js.map

package/dist/describe.js.map

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

package/dist/doctor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Config doctor — structured diagnostics for a config object against a schema.
+ *
+ * Reports which fields are valid, missing, using defaults, deprecated, or invalid.
+ */
+import type { z } from 'zod';
+/** Diagnostic status for a single config field. */
+export interface ConfigDiagnostic {
+    readonly path: string;
+    readonly status: 'valid' | 'missing' | 'invalid' | 'deprecated' | 'default';
+    readonly message: string;
+    readonly value?: unknown;
+}
+/** Aggregated result from checking config against a schema. */
+export interface CheckResult {
+    readonly diagnostics: readonly ConfigDiagnostic[];
+    readonly valid: boolean;
+}
+/**
+ * Check a config object against a schema and return structured diagnostics.
+ *
+ * Reports which fields are valid, missing, using defaults, deprecated, or invalid.
+ */
+export declare const checkConfig: <T extends z.ZodType>(schema: T, values: Record<string, unknown>, options?: {
+    readonly env?: Record<string, string | undefined>;
+}) => CheckResult;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAS7B,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAsND;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAC7C,QAAQ,CAAC,EACT,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,UAAU;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,KAC9D,WAkBF,CAAC"}

package/dist/doctor.js

@@ -0,0 +1,167 @@
+/**
+ * Config doctor — structured diagnostics for a config object against a schema.
+ *
+ * Reports which fields are valid, missing, using defaults, deprecated, or invalid.
+ */
+import { collectConfigMeta } from './collect.js';
+import { getAtPath, isZodObject, unwrapToBase, zodDef } from './zod-utils.js';
+// ---------------------------------------------------------------------------
+// Helpers (defined before consumers)
+// ---------------------------------------------------------------------------
+/** Check if a schema wraps a ZodDefault. */
+const isDefaultWrapper = (schema) => zodDef(schema)['type'] === 'default';
+/** Check if a schema wraps a ZodOptional. */
+const isOptionalWrapper = (schema) => zodDef(schema)['type'] === 'optional';
+/** Get the default value from a ZodDefault wrapper. */
+const getDefaultValue = (schema) => zodDef(schema)['defaultValue'];
+const BOOL_TRUE = new Set(['true', '1']);
+const BOOL_FALSE = new Set(['false', '0']);
+/** Set a value at a dot-separated path, creating intermediate objects. */
+const setAtPath = (obj, path, value) => {
+    const parts = path.split('.');
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i += 1) {
+        const part = parts[i];
+        const next = current[part];
+        const nested = typeof next === 'object' && next !== null
+            ? next
+            : {};
+        current[part] = nested;
+        current = nested;
+    }
+    const lastPart = parts.at(-1);
+    current[lastPart] = value;
+};
+const resolveBaseTypeName = (schema) => zodDef(unwrapToBase(schema))['type'];
+const coerceEnvValue = (raw, schema) => {
+    switch (resolveBaseTypeName(schema)) {
+        case 'number':
+            return Number(raw);
+        case 'boolean':
+            if (BOOL_TRUE.has(raw)) {
+                return true;
+            }
+            if (BOOL_FALSE.has(raw)) {
+                return false;
+            }
+            return raw;
+        default:
+            return raw;
+    }
+};
+const getFieldSchema = (schema, path) => {
+    let current = schema;
+    for (const part of path.split('.')) {
+        if (!isZodObject(current)) {
+            return undefined;
+        }
+        const shape = zodDef(unwrapToBase(current))['shape'];
+        const next = shape?.[part];
+        if (!next) {
+            return undefined;
+        }
+        current = next;
+    }
+    return current;
+};
+/** Build values object with env overrides applied. */
+const applyEnvToValues = (values, schema, envVars) => {
+    const meta = collectConfigMeta(schema);
+    const result = structuredClone(values);
+    for (const [path, fieldMeta] of meta) {
+        if (fieldMeta.env && envVars[fieldMeta.env] !== undefined) {
+            const envValue = envVars[fieldMeta.env];
+            const fieldSchema = getFieldSchema(schema, path);
+            setAtPath(result, path, fieldSchema ? coerceEnvValue(envValue, fieldSchema) : envValue);
+        }
+    }
+    return result;
+};
+/** Validate a single field value against its schema. */
+const validateFieldValue = (path, fieldSchema, value) => {
+    const result = fieldSchema.safeParse(value);
+    if (result.success) {
+        return { message: 'OK', path, status: 'valid', value };
+    }
+    const issue = result.error?.issues?.[0];
+    const msg = issue ? issue.message : 'Invalid value';
+    return { message: msg, path, status: 'invalid', value };
+};
+/** Classify a single field and produce a diagnostic. */
+const classifyField = (path, fieldSchema, values, deprecatedMeta) => {
+    const value = getAtPath(values, path);
+    const deprecationMsg = deprecatedMeta.get(path);
+    if (deprecationMsg && value !== undefined) {
+        return { message: deprecationMsg, path, status: 'deprecated', value };
+    }
+    if (value === undefined && isDefaultWrapper(fieldSchema)) {
+        return {
+            message: 'Using default value',
+            path,
+            status: 'default',
+            value: getDefaultValue(fieldSchema),
+        };
+    }
+    if (value === undefined && !isOptionalWrapper(fieldSchema)) {
+        return {
+            message: `Required field "${path}" is missing`,
+            path,
+            status: 'missing',
+        };
+    }
+    return validateFieldValue(path, fieldSchema, value);
+};
+/** Collect deprecated metadata paths from config meta. */
+const collectDeprecatedPaths = (schema) => {
+    const meta = collectConfigMeta(schema);
+    const result = new Map();
+    for (const [path, fieldMeta] of meta) {
+        if (fieldMeta.deprecated) {
+            result.set(path, fieldMeta.deprecated);
+        }
+    }
+    return result;
+};
+/** Walk an object shape and enqueue leaf fields or nested objects. */
+const walkShape = (schema, prefix, queue, leaves) => {
+    const shape = zodDef(schema)['shape'];
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (isZodObject(fieldSchema)) {
+            queue.push({ path, schema: unwrapToBase(fieldSchema) });
+        }
+        else {
+            leaves.push({ path, schema: fieldSchema });
+        }
+    }
+};
+/** Collect all leaf fields from a schema, walking nested objects iteratively. */
+const collectLeaves = (schema) => {
+    const queue = [];
+    const leaves = [];
+    walkShape(schema, '', queue, leaves);
+    for (let entry = queue.pop(); entry; entry = queue.pop()) {
+        walkShape(entry.schema, entry.path, queue, leaves);
+    }
+    return leaves;
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Check a config object against a schema and return structured diagnostics.
+ *
+ * Reports which fields are valid, missing, using defaults, deprecated, or invalid.
+ */
+export const checkConfig = (schema, values, options) => {
+    const objSchema = schema;
+    const effectiveValues = options?.env
+        ? applyEnvToValues(values, objSchema, options.env)
+        : values;
+    const deprecatedMeta = collectDeprecatedPaths(objSchema);
+    const leaves = collectLeaves(objSchema);
+    const diagnostics = leaves.map((leaf) => classifyField(leaf.path, leaf.schema, effectiveValues, deprecatedMeta));
+    const valid = diagnostics.every((d) => d.status !== 'missing' && d.status !== 'invalid');
+    return { diagnostics, valid };
+};
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

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

package/dist/explain.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Config provenance — show which source won for each config field.
+ *
+ * Used for debugging: answers "where did this value come from?"
+ */
+import type { z } from 'zod';
+/** Provenance entry describing the source of a resolved config value. */
+export interface ProvenanceEntry {
+    readonly path: string;
+    readonly value: unknown;
+    readonly source: 'default' | 'base' | 'loadout' | 'local' | 'env';
+    readonly redacted: boolean;
+}
+/** Options for explaining config provenance. */
+export interface ExplainConfigOptions<T extends z.ZodType> {
+    readonly schema: T;
+    readonly base?: Record<string, unknown>;
+    readonly loadout?: Record<string, unknown>;
+    readonly local?: Record<string, unknown>;
+    readonly env?: Record<string, string | undefined>;
+    readonly resolved: Record<string, unknown>;
+}
+/**
+ * Show which source won for each config field.
+ *
+ * Used for debugging — answers "where did this value come from?"
+ *
+ */
+export declare const explainConfig: <T extends z.ZodType>(options: ExplainConfigOptions<T>) => readonly ProvenanceEntry[];
+//# sourceMappingURL=explain.d.ts.map

package/dist/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAU7B,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,CAAC;IAClE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO;IACvD,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAiHD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAC/C,SAAS,oBAAoB,CAAC,CAAC,CAAC,KAC/B,SAAS,eAAe,EAoC1B,CAAC"}

package/dist/explain.js

@@ -0,0 +1,114 @@
+/**
+ * Config provenance — show which source won for each config field.
+ *
+ * Used for debugging: answers "where did this value come from?"
+ */
+import { collectConfigMeta } from './collect.js';
+import { isLikelySecret } from './secret-heuristics.js';
+import { getAtPath, isZodObject, unwrapToBase, zodDef } from './zod-utils.js';
+// ---------------------------------------------------------------------------
+// Helpers (defined before consumers)
+// ---------------------------------------------------------------------------
+/** Build a map of path → env var name from config metadata. */
+const buildEnvMap = (schema) => {
+    const meta = collectConfigMeta(schema);
+    const result = new Map();
+    for (const [path, fieldMeta] of meta) {
+        if (fieldMeta.env) {
+            result.set(path, fieldMeta.env);
+        }
+    }
+    return result;
+};
+/** Build a set of paths marked as secret from config metadata. */
+const buildSecretSet = (schema) => {
+    const meta = collectConfigMeta(schema);
+    const result = new Set();
+    for (const [path, fieldMeta] of meta) {
+        if (fieldMeta.secret) {
+            result.add(path);
+        }
+    }
+    return result;
+};
+const hasPath = (obj, path) => {
+    let current = obj;
+    for (const part of path.split('.')) {
+        if (typeof current !== 'object' || current === null) {
+            return false;
+        }
+        if (!Object.hasOwn(current, part)) {
+            return false;
+        }
+        current = current[part];
+    }
+    return true;
+};
+/** Determine which source provided the winning value for a given path. */
+const determineSource = (path, resolved, layers, envMap, envVars) => {
+    if (envVars && envMap.has(path)) {
+        const envVar = envMap.get(path);
+        if (envVar && envVars[envVar] !== undefined) {
+            return 'env';
+        }
+    }
+    const resolvedValue = getAtPath(resolved, path);
+    for (const [name, values] of layers) {
+        if (values && hasPath(values, path) && getAtPath(values, path) === resolvedValue) {
+            return name;
+        }
+    }
+    return 'default';
+};
+/** Collect all leaf field paths from an object schema. */
+const collectLeafPaths = (schema, prefix) => {
+    const paths = [];
+    const queue = [{ prefix, schema }];
+    for (let entry = queue.pop(); entry; entry = queue.pop()) {
+        const shape = zodDef(entry.schema)['shape'];
+        for (const [key, fieldSchema] of Object.entries(shape)) {
+            const path = entry.prefix ? `${entry.prefix}.${key}` : key;
+            if (isZodObject(fieldSchema)) {
+                queue.push({ prefix: path, schema: unwrapToBase(fieldSchema) });
+            }
+            else {
+                paths.push(path);
+            }
+        }
+    }
+    return paths;
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Show which source won for each config field.
+ *
+ * Used for debugging — answers "where did this value come from?"
+ *
+ */
+export const explainConfig = (options) => {
+    const objSchema = options.schema;
+    const envMap = buildEnvMap(objSchema);
+    const secretSet = buildSecretSet(objSchema);
+    const layers = [
+        ['local', options.local],
+        ['loadout', options.loadout],
+        ['base', options.base],
+    ];
+    const paths = collectLeafPaths(objSchema, '');
+    return paths.map((path) => {
+        const source = determineSource(path, options.resolved, layers, envMap, options.env);
+        const envVarName = envMap.get(path);
+        const isSecret = secretSet.has(path) ||
+            (envVarName !== undefined && isLikelySecret(envVarName));
+        const rawValue = getAtPath(options.resolved, path);
+        return {
+            path,
+            redacted: isSecret,
+            source,
+            value: isSecret ? '[REDACTED]' : rawValue,
+        };
+    });
+};
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAwB9E,8EAA8E;AAC9E,qCAAqC;AACrC,8EAA8E;AAE9E,+DAA+D;AAC/D,MAAM,WAAW,GAAG,CAClB,MAA8C,EACzB,EAAE;IACvB,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC;QACrC,IAAI,SAAS,CAAC,GAAG,EAAE,CAAC;YAClB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,kEAAkE;AAClE,MAAM,cAAc,GAAG,CACrB,MAA8C,EACjC,EAAE;IACf,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,IAAI,EAAE,CAAC;QACrC,IAAI,SAAS,CAAC,MAAM,EAAE,CAAC;YACrB,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAQF,MAAM,OAAO,GAAG,CAAC,GAA4B,EAAE,IAAY,EAAW,EAAE;IACtE,IAAI,OAAO,GAAY,GAAG,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACpD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAkC,EAAE,IAAI,CAAC,EAAE,CAAC;YAC7D,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,GAAI,OAAmC,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,eAAe,GAAG,CACtB,IAAY,EACZ,QAAiC,EACjC,MAA8B,EAC9B,MAA2B,EAC3B,OAAuD,EAC5B,EAAE;IAC7B,IAAI,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;YAC5C,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAChD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACpC,IAAI,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,aAAa,EAAE,CAAC;YACjF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAYF,0DAA0D;AAC1D,MAAM,gBAAgB,GAAG,CAAC,MAAiB,EAAE,MAAc,EAAY,EAAE;IACvE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAgB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEhD,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC;QACzD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,CAA8B,CAAC;QACzE,KAAK,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;YAC3D,IAAI,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;gBAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;YAClE,CAAC;iBAAM,CAAC;gBACN,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,OAAgC,EACJ,EAAE;IAC9B,MAAM,SAAS,GAAG,OAAO,CAAC,MAEzB,CAAC;IACF,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IAE5C,MAAM,MAAM,GAA2B;QACrC,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC;QACxB,CAAC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC;QAC5B,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC;KACvB,CAAC;IAEF,MAAM,KAAK,GAAG,gBAAgB,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAE9C,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,MAAM,GAAG,eAAe,CAC5B,IAAI,EACJ,OAAO,CAAC,QAAQ,EAChB,MAAM,EACN,MAAM,EACN,OAAO,CAAC,GAAG,CACZ,CAAC;QACF,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,QAAQ,GACZ,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;YACnB,CAAC,UAAU,KAAK,SAAS,IAAI,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;QAC3D,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAEnD,OAAO;YACL,IAAI;YACJ,QAAQ,EAAE,QAAQ;YAClB,MAAM;YACN,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ;SAC1C,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC"}