@substrate-ai/core 0.19.54

package/dist/config/config-system-impl.js

@@ -0,0 +1,364 @@
+/**
+ * ConfigSystem implementation — loads configuration in hierarchy order and
+ * exposes get/set/getMasked operations.
+ *
+ * Hierarchy (lowest → highest priority):
+ *   built-in defaults
+ *     → global user config  (~/.substrate/config.yaml)
+ *     → project config      (./.substrate/config.yaml)
+ *     → environment vars    (ADT_* prefixed)
+ *     → CLI flag overrides  (passed via ConfigSystemOptions.cliOverrides)
+ *
+ * No imports from src/ (monolith) — zero monolith dependencies.
+ */
+import { readFile, writeFile, mkdir, access } from 'fs/promises';
+import { join, resolve } from 'path';
+import { homedir } from 'os';
+import yaml from 'js-yaml';
+import { ConfigError, ConfigIncompatibleFormatError } from './errors.js';
+import { SubstrateConfigSchema, PartialSubstrateConfigSchema, CURRENT_CONFIG_FORMAT_VERSION, SUPPORTED_CONFIG_FORMAT_VERSIONS, } from './types.js';
+import { isVersionSupported, formatUnsupportedVersionError } from './version-utils.js';
+import { defaultConfigMigrator } from './config-migrator.js';
+import { DEFAULT_CONFIG } from './defaults.js';
+// ---------------------------------------------------------------------------
+// Credential masking (inlined from src/cli/utils/masking.ts to avoid monolith import)
+// ---------------------------------------------------------------------------
+const MASKED_VALUE = '***';
+const CREDENTIAL_FIELDS = new Set([
+    'api_key',
+    'apiKey',
+    'api_key_env',
+    'api_key_value',
+    'token',
+    'secret',
+    'password',
+]);
+function deepMask(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (Array.isArray(value))
+        return value.map(deepMask);
+    if (typeof value === 'object') {
+        const obj = value;
+        const masked = {};
+        for (const [k, v] of Object.entries(obj)) {
+            if (CREDENTIAL_FIELDS.has(k)) {
+                masked[k] = MASKED_VALUE;
+            }
+            else {
+                masked[k] = deepMask(v);
+            }
+        }
+        return masked;
+    }
+    return value;
+}
+export function deepMerge(base, override) {
+    const result = { ...base };
+    for (const [key, val] of Object.entries(override)) {
+        if (val !== null &&
+            val !== undefined &&
+            typeof val === 'object' &&
+            !Array.isArray(val) &&
+            typeof result[key] === 'object' &&
+            result[key] !== null &&
+            !Array.isArray(result[key])) {
+            result[key] = deepMerge(result[key], val);
+        }
+        else if (val !== undefined) {
+            result[key] = val;
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Environment variable resolution
+// ---------------------------------------------------------------------------
+/**
+ * Map of ADT_ environment variable names to config paths.
+ * Only overrides scalar values; does not support nested structures via env.
+ */
+const ENV_VAR_MAP = {
+    ADT_LOG_LEVEL: 'global.log_level',
+    ADT_MAX_CONCURRENT_TASKS: 'global.max_concurrent_tasks',
+    ADT_BUDGET_CAP_TOKENS: 'global.budget_cap_tokens',
+    ADT_BUDGET_CAP_USD: 'global.budget_cap_usd',
+    ADT_WORKSPACE_DIR: 'global.workspace_dir',
+    ADT_CLAUDE_ENABLED: 'providers.claude.enabled',
+    ADT_CODEX_ENABLED: 'providers.codex.enabled',
+    ADT_GEMINI_ENABLED: 'providers.gemini.enabled',
+};
+/**
+ * Read relevant environment variables and return a partial config overlay.
+ */
+function readEnvOverrides(logger) {
+    const overrides = {};
+    for (const [envKey, configPath] of Object.entries(ENV_VAR_MAP)) {
+        const rawValue = process.env[envKey];
+        if (rawValue === undefined)
+            continue;
+        const parts = configPath.split('.');
+        let cursor = overrides;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const part = parts[i] ?? '';
+            if (cursor[part] === undefined)
+                cursor[part] = {};
+            cursor = cursor[part];
+        }
+        const lastKey = parts[parts.length - 1] ?? '';
+        // Coerce to appropriate type
+        if (rawValue === 'true')
+            cursor[lastKey] = true;
+        else if (rawValue === 'false')
+            cursor[lastKey] = false;
+        else if (/^\d+$/.test(rawValue))
+            cursor[lastKey] = parseInt(rawValue, 10);
+        else if (/^\d*\.\d+$/.test(rawValue))
+            cursor[lastKey] = parseFloat(rawValue);
+        else
+            cursor[lastKey] = rawValue;
+    }
+    // Validate the env overrides as partial config
+    const parsed = PartialSubstrateConfigSchema.safeParse(overrides);
+    if (!parsed.success) {
+        logger.warn({ errors: parsed.error.issues }, 'Invalid environment variable overrides ignored');
+        return {};
+    }
+    return parsed.data;
+}
+// ---------------------------------------------------------------------------
+// Dot-notation key accessor / setter
+// ---------------------------------------------------------------------------
+/**
+ * Get a value from a nested object using dot-notation key.
+ */
+export function getByPath(obj, path) {
+    const parts = path.split('.');
+    let cursor = obj;
+    for (const part of parts) {
+        if (cursor === null || cursor === undefined || typeof cursor !== 'object')
+            return undefined;
+        cursor = cursor[part];
+    }
+    return cursor;
+}
+/**
+ * Return a deep clone of `obj` with `path` set to `value`.
+ * Creates intermediate objects as needed.
+ */
+export function setByPath(obj, path, value) {
+    const parts = path.split('.');
+    const result = { ...obj };
+    let cursor = result;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i] ?? '';
+        const existing = cursor[part];
+        if (existing === null || existing === undefined || typeof existing !== 'object') {
+            cursor[part] = {};
+        }
+        else {
+            cursor[part] = { ...existing };
+        }
+        cursor = cursor[part];
+    }
+    const lastKey = parts[parts.length - 1] ?? '';
+    cursor[lastKey] = value;
+    return result;
+}
+// ---------------------------------------------------------------------------
+// getVersionCompatibility — utility exported from core
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a config format version is compatible with this toolkit.
+ *
+ * @param version - Version string to check
+ * @returns true if the version is in SUPPORTED_CONFIG_FORMAT_VERSIONS
+ */
+export function getVersionCompatibility(version) {
+    return isVersionSupported(version, SUPPORTED_CONFIG_FORMAT_VERSIONS);
+}
+// ---------------------------------------------------------------------------
+// ConfigSystemImpl
+// ---------------------------------------------------------------------------
+export class ConfigSystemImpl {
+    _config = null;
+    _projectConfigDir;
+    _globalConfigDir;
+    _cliOverrides;
+    _logger;
+    constructor(options = {}) {
+        this._projectConfigDir = options.projectConfigDir
+            ? resolve(options.projectConfigDir)
+            : resolve(process.cwd(), '.substrate');
+        this._globalConfigDir = options.globalConfigDir
+            ? resolve(options.globalConfigDir)
+            : resolve(homedir(), '.substrate');
+        this._cliOverrides = options.cliOverrides ?? {};
+        this._logger = options.logger ?? console;
+    }
+    get isLoaded() {
+        return this._config !== null;
+    }
+    async load() {
+        // 1. Start with built-in defaults
+        let merged = structuredClone(DEFAULT_CONFIG);
+        // 2. Apply global user config if present
+        const globalConfig = await this._loadYamlFile(join(this._globalConfigDir, 'config.yaml'));
+        if (globalConfig !== null) {
+            merged = deepMerge(merged, globalConfig);
+        }
+        // 3. Apply project config if present
+        const projectConfig = await this._loadYamlFile(join(this._projectConfigDir, 'config.yaml'));
+        if (projectConfig !== null) {
+            merged = deepMerge(merged, projectConfig);
+        }
+        // 4. Apply environment variable overrides
+        const envOverrides = readEnvOverrides(this._logger);
+        if (Object.keys(envOverrides).length > 0) {
+            merged = deepMerge(merged, envOverrides);
+        }
+        // 5. Apply CLI flag overrides
+        if (Object.keys(this._cliOverrides).length > 0) {
+            merged = deepMerge(merged, this._cliOverrides);
+        }
+        // 6. Validate the merged config
+        const result = SubstrateConfigSchema.safeParse(merged);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((issue) => `  • ${issue.path.join('.')}: ${issue.message}`)
+                .join('\n');
+            throw new ConfigError(`Configuration validation failed:\n${issues}`, { issues: result.error.issues });
+        }
+        this._config = result.data;
+        this._logger.debug('Configuration loaded successfully');
+    }
+    getConfig() {
+        if (this._config === null) {
+            throw new ConfigError('Configuration has not been loaded. Call load() before getConfig().', {});
+        }
+        return this._config;
+    }
+    get(key) {
+        const config = this.getConfig();
+        return getByPath(config, key);
+    }
+    async set(key, value) {
+        // Validate key exists in schema by checking current merged config path
+        const current = this.getConfig();
+        const existing = getByPath(current, key);
+        // Reject unknown keys — the key must resolve to something in the merged config
+        if (existing === undefined) {
+            throw new ConfigError(`Unknown config key: ${key}`, { key });
+        }
+        // Key path must resolve to a non-object (scalar) — we don't allow replacing whole sections
+        if (typeof existing === 'object' &&
+            existing !== null) {
+            throw new ConfigError(`Cannot set object key "${key}" — use a more specific dot-notation path`, { key });
+        }
+        // Load the raw project config file (or start fresh)
+        let projectConfigRaw = {};
+        const projectConfigPath = join(this._projectConfigDir, 'config.yaml');
+        const existingYaml = await this._loadYamlFile(projectConfigPath);
+        if (existingYaml !== null) {
+            projectConfigRaw = existingYaml;
+        }
+        // Apply the change
+        const updated = setByPath(projectConfigRaw, key, value);
+        // Validate the partial update
+        const partial = PartialSubstrateConfigSchema.safeParse(updated);
+        if (!partial.success) {
+            const issues = partial.error.issues
+                .map((i) => `  • ${i.path.join('.')}: ${i.message}`)
+                .join('\n');
+            throw new ConfigError(`Invalid value for "${key}":\n${issues}`, { key, value, issues: partial.error.issues });
+        }
+        // Write back and reload
+        await mkdir(this._projectConfigDir, { recursive: true });
+        const yamlStr = yaml.dump(updated);
+        await writeFile(projectConfigPath, yamlStr, 'utf-8');
+        // Reload to get the updated merged config
+        await this.load();
+    }
+    getMasked() {
+        const config = this.getConfig();
+        return deepMask(config);
+    }
+    getConfigFormatVersion() {
+        return CURRENT_CONFIG_FORMAT_VERSION;
+    }
+    isCompatible(version) {
+        return SUPPORTED_CONFIG_FORMAT_VERSIONS.includes(version);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    async _fileExists(filePath) {
+        try {
+            await access(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async _loadYamlFile(filePath) {
+        if (!(await this._fileExists(filePath)))
+            return null;
+        try {
+            const raw = await readFile(filePath, 'utf-8');
+            let parsed = yaml.load(raw);
+            // Pre-check config_format_version and attempt auto-migration before Zod runs (AC4, AC5)
+            if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const rawObj = parsed;
+                const version = rawObj['config_format_version'];
+                if (version !== undefined && typeof version === 'string' && !isVersionSupported(version, SUPPORTED_CONFIG_FORMAT_VERSIONS)) {
+                    // Attempt auto-migration if a migration path exists (FR63)
+                    if (defaultConfigMigrator.canMigrate(version, CURRENT_CONFIG_FORMAT_VERSION)) {
+                        const migrationOutput = defaultConfigMigrator.migrate(rawObj, version, CURRENT_CONFIG_FORMAT_VERSION, filePath);
+                        if (migrationOutput.result.success) {
+                            this._logger.info({ from: version, to: CURRENT_CONFIG_FORMAT_VERSION, backup: migrationOutput.result.backupPath }, 'Config auto-migrated successfully');
+                            parsed = migrationOutput.config;
+                        }
+                        else {
+                            throw new ConfigIncompatibleFormatError(`Config migration failed: ${migrationOutput.result.manualStepsRequired.join('; ')}`, { filePath, version });
+                        }
+                    }
+                    else {
+                        throw new ConfigIncompatibleFormatError(formatUnsupportedVersionError('config', version, SUPPORTED_CONFIG_FORMAT_VERSIONS), { filePath });
+                    }
+                }
+            }
+            const result = PartialSubstrateConfigSchema.safeParse(parsed);
+            if (!result.success) {
+                const issues = result.error.issues
+                    .map((i) => `  • ${i.path.join('.')}: ${i.message}`)
+                    .join('\n');
+                throw new ConfigError(`Invalid config file at ${filePath}:\n${issues}`, { filePath, issues: result.error.issues });
+            }
+            return result.data;
+        }
+        catch (err) {
+            if (err instanceof ConfigError)
+                throw err;
+            if (err instanceof ConfigIncompatibleFormatError)
+                throw err;
+            const message = err instanceof Error ? err.message : String(err);
+            throw new ConfigError(`Failed to read config file at ${filePath}: ${message}`, { filePath });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory function
+// ---------------------------------------------------------------------------
+/**
+ * Create a new ConfigSystem instance.
+ *
+ * @example
+ * const config = createConfigSystem()
+ * await config.load()
+ * const cfg = config.getConfig()
+ */
+export function createConfigSystem(options = {}) {
+    return new ConfigSystemImpl(options);
+}
+//# sourceMappingURL=config-system-impl.js.map

package/dist/config/config-system-impl.js.map

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

package/dist/config/config-watcher.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ConfigWatcher — file watcher for hot-reloading substrate.config.yaml.
+ *
+ * Responsibilities (Story 5.6):
+ *  - Watch the config file using Node.js fs.watch
+ *  - Debounce rapid file change events (default 300ms)
+ *  - Validate the new config using the Zod schema
+ *  - Call onReload with the parsed config on success
+ *  - Call onError with validation/parse errors on failure
+ *  - Clean up file handles on stop()
+ *
+ * Architecture constraints:
+ *  - No imports from src/ (monolith) — zero monolith dependencies
+ *  - ESM imports: ALL imports use .js extension
+ */
+import type { ILogger } from '../dispatch/types.js';
+import { type SubstrateConfig } from './types.js';
+export interface ConfigWatcherOptions {
+    /** Absolute path to the config file to watch */
+    configPath: string;
+    /** Called with the new validated config when the file changes successfully */
+    onReload: (newConfig: SubstrateConfig) => void;
+    /** Called when validation or parsing fails */
+    onError: (err: Error) => void;
+    /** Debounce delay in milliseconds (default: 300) */
+    debounceMs?: number;
+    /**
+     * Logger instance. Defaults to console if not provided.
+     */
+    logger?: ILogger;
+}
+export interface ConfigWatcher {
+    /** Start watching the config file */
+    start(): void;
+    /** Stop watching and clean up resources */
+    stop(): void;
+}
+/**
+ * Recursively flatten a nested object into dot-notation key/value pairs.
+ * Arrays are treated as leaf values (not recursed into).
+ */
+export declare function flattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+/**
+ * Compute the set of dot-notation keys that differ between two configs.
+ *
+ * @param prev - Previous config
+ * @param next - New config
+ * @returns Array of dot-notation paths that changed (e.g., 'global.max_concurrent_tasks')
+ */
+export declare function computeChangedKeys(prev: SubstrateConfig, next: SubstrateConfig): string[];
+/**
+ * Create a config file watcher that detects changes and reloads the config.
+ *
+ * AC1: Registers file watcher on configPath with persistent=false
+ * AC2: Debounces events, reads+parses+validates on change
+ * AC3: Calls onError for invalid config without calling onReload
+ */
+export declare function createConfigWatcher(options: ConfigWatcherOptions): ConfigWatcher;
+//# sourceMappingURL=config-watcher.d.ts.map

package/dist/config/config-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-watcher.d.ts","sourceRoot":"","sources":["../../src/config/config-watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAA;AAMxE,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAA;IAClB,8EAA8E;IAC9E,QAAQ,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,IAAI,CAAA;IAC9C,8CAA8C;IAC9C,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAA;IAC7B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,KAAK,IAAI,IAAI,CAAA;IACb,2CAA2C;IAC3C,IAAI,IAAI,IAAI,CAAA;CACb;AAMD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,SAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUhG;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,CAKzF;AAMD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAkFhF"}

package/dist/config/config-watcher.js

@@ -0,0 +1,137 @@
+/**
+ * ConfigWatcher — file watcher for hot-reloading substrate.config.yaml.
+ *
+ * Responsibilities (Story 5.6):
+ *  - Watch the config file using Node.js fs.watch
+ *  - Debounce rapid file change events (default 300ms)
+ *  - Validate the new config using the Zod schema
+ *  - Call onReload with the parsed config on success
+ *  - Call onError with validation/parse errors on failure
+ *  - Clean up file handles on stop()
+ *
+ * Architecture constraints:
+ *  - No imports from src/ (monolith) — zero monolith dependencies
+ *  - ESM imports: ALL imports use .js extension
+ */
+import { watch, readFile, existsSync } from 'node:fs';
+import yaml from 'js-yaml';
+import { SubstrateConfigSchema } from './types.js';
+// ---------------------------------------------------------------------------
+// flattenObject — deep-flatten for changed-keys computation
+// ---------------------------------------------------------------------------
+/**
+ * Recursively flatten a nested object into dot-notation key/value pairs.
+ * Arrays are treated as leaf values (not recursed into).
+ */
+export function flattenObject(obj, prefix = '') {
+    return Object.entries(obj).reduce((acc, [key, val]) => {
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+            Object.assign(acc, flattenObject(val, fullKey));
+        }
+        else {
+            acc[fullKey] = val;
+        }
+        return acc;
+    }, {});
+}
+// ---------------------------------------------------------------------------
+// computeChangedKeys
+// ---------------------------------------------------------------------------
+/**
+ * Compute the set of dot-notation keys that differ between two configs.
+ *
+ * @param prev - Previous config
+ * @param next - New config
+ * @returns Array of dot-notation paths that changed (e.g., 'global.max_concurrent_tasks')
+ */
+export function computeChangedKeys(prev, next) {
+    const prevFlat = flattenObject(prev);
+    const nextFlat = flattenObject(next);
+    const allKeys = new Set([...Object.keys(prevFlat), ...Object.keys(nextFlat)]);
+    return [...allKeys].filter((k) => prevFlat[k] !== nextFlat[k]);
+}
+// ---------------------------------------------------------------------------
+// createConfigWatcher
+// ---------------------------------------------------------------------------
+/**
+ * Create a config file watcher that detects changes and reloads the config.
+ *
+ * AC1: Registers file watcher on configPath with persistent=false
+ * AC2: Debounces events, reads+parses+validates on change
+ * AC3: Calls onError for invalid config without calling onReload
+ */
+export function createConfigWatcher(options) {
+    const { configPath, onReload, onError, debounceMs = 300 } = options;
+    const logger = options.logger ?? console;
+    let watcher = null;
+    let debounceTimer = null;
+    const handleChange = () => {
+        // Debounce: cancel any pending reload
+        if (debounceTimer !== null) {
+            clearTimeout(debounceTimer);
+            debounceTimer = null;
+        }
+        debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            readFile(configPath, 'utf-8', (readErr, raw) => {
+                if (readErr !== null) {
+                    logger.error({ err: readErr, configPath }, 'Config reload failed: could not read file');
+                    onError(readErr);
+                    return;
+                }
+                try {
+                    const parsed = yaml.load(raw);
+                    const result = SubstrateConfigSchema.safeParse(parsed);
+                    if (!result.success) {
+                        const message = result.error.issues
+                            .map((e) => `${e.path.join('.')}: ${e.message}`)
+                            .join('; ');
+                        const err = new Error(`Config validation failed: ${message}. Continuing with previous config.`);
+                        logger.error({ configPath, details: message }, 'Config reload failed: schema validation error. Continuing with previous config.');
+                        onError(err);
+                        return;
+                    }
+                    onReload(result.data);
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err : new Error(String(err));
+                    logger.error({ err: error, configPath }, 'Config reload failed: YAML parse error. Continuing with previous config.');
+                    onError(error);
+                }
+            });
+        }, debounceMs);
+    };
+    return {
+        start() {
+            if (watcher !== null) {
+                logger.warn({ configPath }, 'ConfigWatcher.start() called but watcher already running');
+                return;
+            }
+            if (!existsSync(configPath)) {
+                logger.info({ configPath }, 'Config file not found, hot-reload disabled');
+                return;
+            }
+            logger.info({ configPath }, 'Config watcher active: watching substrate.config.yaml');
+            watcher = watch(configPath, { persistent: false }, (_eventType, _filename) => {
+                handleChange();
+            });
+            watcher.on('error', (err) => {
+                logger.error({ err, configPath }, 'Config watcher error');
+                onError(err);
+            });
+        },
+        stop() {
+            if (debounceTimer !== null) {
+                clearTimeout(debounceTimer);
+                debounceTimer = null;
+            }
+            if (watcher !== null) {
+                watcher.close();
+                watcher = null;
+                logger.info({ configPath }, 'Config watcher stopped');
+            }
+        },
+    };
+}
+//# sourceMappingURL=config-watcher.js.map

package/dist/config/config-watcher.js.map

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

package/dist/config/defaults.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Built-in default values for the Substrate configuration system.
+ *
+ * These are the lowest-priority defaults; they are overridden by:
+ *   global config → project config → environment variables → CLI flags
+ */
+import type { SubstrateConfig, ProviderConfig, GlobalSettings } from './types.js';
+export declare const DEFAULT_CLAUDE_PROVIDER: ProviderConfig;
+export declare const DEFAULT_CODEX_PROVIDER: ProviderConfig;
+export declare const DEFAULT_GEMINI_PROVIDER: ProviderConfig;
+export declare const DEFAULT_GLOBAL_SETTINGS: GlobalSettings;
+export declare const DEFAULT_CONFIG: SubstrateConfig;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/config/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/config/defaults.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACf,MAAM,YAAY,CAAA;AAMnB,eAAO,MAAM,uBAAuB,EAAE,cAWrC,CAAA;AAED,eAAO,MAAM,sBAAsB,EAAE,cAMpC,CAAA;AAED,eAAO,MAAM,uBAAuB,EAAE,cAMrC,CAAA;AAMD,eAAO,MAAM,uBAAuB,EAAE,cAKrC,CAAA;AAMD,eAAO,MAAM,cAAc,EAAE,eAa5B,CAAA"}