clementine-agent 1.1.0 → 1.1.2

package/dist/config/clementine-json.js

@@ -0,0 +1,123 @@
+/**
+ * Clementine JSON config loader.
+ *
+ * `~/.clementine/clementine.json` is the canonical user-editable config file.
+ * Each field is optional — missing values fall through to .env, then to
+ * compiled defaults. Precedence (highest first):
+ *
+ *   1. process.env (CI/runtime overrides)
+ *   2. ~/.clementine/.env (existing user-edited config)
+ *   3. ~/.clementine/clementine.json (this file)
+ *   4. Compiled defaults
+ *
+ * The file is created on first run by the 0005 migration (kind: 'config').
+ * Loader validates with zod and falls back gracefully on malformed input —
+ * a corrupt file is logged and treated as empty.
+ *
+ * Cached by mtime so subsequent reads are O(1) absent file changes.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { z } from 'zod';
+const logger = pino({ name: 'clementine.config-json' });
+// ── Schema ───────────────────────────────────────────────────────────
+export const clementineJsonSchema = z.object({
+    schemaVersion: z.literal(1),
+    ownerName: z.string().optional(),
+    assistantName: z.string().optional(),
+    timezone: z.string().optional(),
+    models: z.object({
+        default: z.string().optional(),
+        haiku: z.string().optional(),
+        sonnet: z.string().optional(),
+        opus: z.string().optional(),
+    }).optional(),
+    budgets: z.object({
+        heartbeat: z.number().nonnegative().optional(),
+        cronT1: z.number().nonnegative().optional(),
+        cronT2: z.number().nonnegative().optional(),
+        chat: z.number().nonnegative().optional(),
+    }).optional(),
+    heartbeat: z.object({
+        intervalMinutes: z.number().int().positive().optional(),
+        activeStart: z.number().int().min(0).max(23).optional(),
+        activeEnd: z.number().int().min(0).max(23).optional(),
+    }).optional(),
+    unleashed: z.object({
+        phaseTurns: z.number().int().positive().optional(),
+        defaultMaxHours: z.number().positive().optional(),
+        maxPhases: z.number().int().positive().optional(),
+    }).optional(),
+});
+const cache = new Map();
+export function clementineJsonPath(baseDir) {
+    return path.join(baseDir, 'clementine.json');
+}
+/**
+ * Load and validate clementine.json. Returns an empty object if the file
+ * is missing, unreadable, or fails validation. Cached by mtime.
+ */
+export function loadClementineJson(baseDir) {
+    const filePath = clementineJsonPath(baseDir);
+    if (!existsSync(filePath))
+        return { schemaVersion: 1 };
+    let mtime;
+    try {
+        mtime = statSync(filePath).mtimeMs;
+    }
+    catch {
+        return { schemaVersion: 1 };
+    }
+    const cached = cache.get(filePath);
+    if (cached && cached.mtime === mtime)
+        return cached.data;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+    }
+    catch (err) {
+        logger.warn({ err, filePath }, 'Failed to parse clementine.json — using empty config');
+        return { schemaVersion: 1 };
+    }
+    const parsed = clementineJsonSchema.safeParse(raw);
+    if (!parsed.success) {
+        logger.warn({ filePath, errors: parsed.error.issues.slice(0, 3) }, 'clementine.json failed validation — using empty config');
+        return { schemaVersion: 1 };
+    }
+    cache.set(filePath, { mtime, data: parsed.data });
+    return parsed.data;
+}
+/** Test-only: clear the loader cache. */
+export function _resetClementineJsonCache() {
+    cache.clear();
+}
+// ── Resolution helpers (pure) ────────────────────────────────────────
+//
+// `getEnv` in config.ts feeds `envValue` here. Precedence is the env
+// value (already process.env > .env merged by getEnv), then the JSON
+// value, then the compiled default. Empty string from env is treated
+// as unset to match the .env parser's "key with empty value" behavior.
+/** String resolution. */
+export function resolveString(envValue, jsonValue, fallback) {
+    if (envValue)
+        return envValue;
+    if (jsonValue)
+        return jsonValue;
+    return fallback;
+}
+/**
+ * Numeric resolution. Env values that don't parse as finite numbers
+ * fall through to JSON, then the default — mirrors optionalTokenEnv tolerance.
+ */
+export function resolveNumber(envValue, jsonValue, fallback) {
+    if (envValue) {
+        const n = Number(envValue);
+        if (Number.isFinite(n))
+            return n;
+    }
+    if (jsonValue !== undefined)
+        return jsonValue;
+    return fallback;
+}
+//# sourceMappingURL=clementine-json.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * Config doctor — proactive validation of ~/.clementine/.
+ *
+ * Runs a series of checks against the effective config (env + clementine.json
+ * + defaults) and surfaces issues that would otherwise silently degrade the
+ * daemon. Each check produces a Finding {severity, key, message, fix}.
+ *
+ * Severity:
+ *   error    — daemon is misconfigured in a way that affects behavior
+ *   warning  — works, but bad practice or fragile
+ *   info     — note worth surfacing, not actionable
+ *
+ * Pure: no module-level side effects, no shell calls beyond what
+ * computeEffectiveConfig already does (lazy keychain resolution).
+ */
+export type Severity = 'error' | 'warning' | 'info';
+export interface Finding {
+    severity: Severity;
+    key?: string;
+    message: string;
+    /** Suggested next-step command or action. */
+    fix?: string;
+}
+export interface DoctorReport {
+    baseDir: string;
+    hasEnvFile: boolean;
+    hasJsonFile: boolean;
+    findings: Finding[];
+    /** Counts by severity, for quick rendering. */
+    counts: Record<Severity, number>;
+    /** Suggested process exit code: 1 if any errors, 0 otherwise. */
+    exitCode: 0 | 1;
+}
+export declare function runDoctor(baseDir: string): DoctorReport;
+/** Keys-list helper for tests. */
+export declare function listNumericKeys(): readonly string[];
+export declare function listEnumKeys(): readonly string[];
+//# sourceMappingURL=config-doctor.d.ts.map

package/dist/config/config-doctor.js

@@ -0,0 +1,270 @@
+/**
+ * Config doctor — proactive validation of ~/.clementine/.
+ *
+ * Runs a series of checks against the effective config (env + clementine.json
+ * + defaults) and surfaces issues that would otherwise silently degrade the
+ * daemon. Each check produces a Finding {severity, key, message, fix}.
+ *
+ * Severity:
+ *   error    — daemon is misconfigured in a way that affects behavior
+ *   warning  — works, but bad practice or fragile
+ *   info     — note worth surfacing, not actionable
+ *
+ * Pure: no module-level side effects, no shell calls beyond what
+ * computeEffectiveConfig already does (lazy keychain resolution).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { computeEffectiveConfig } from './effective-config.js';
+import { isSensitiveEnvKey } from '../secrets/sensitivity.js';
+// ── Type expectations ───────────────────────────────────────────────
+//
+// Keys that must parse as a finite number when set. The inspector already
+// handles default fallback for missing values, so we only fail on present-
+// but-wrong values.
+const NUMERIC_KEYS = new Set([
+    'BUDGET_HEARTBEAT_USD',
+    'BUDGET_CRON_T1_USD',
+    'BUDGET_CRON_T2_USD',
+    'BUDGET_CHAT_USD',
+    'HEARTBEAT_INTERVAL_MINUTES',
+    'HEARTBEAT_ACTIVE_START',
+    'HEARTBEAT_ACTIVE_END',
+    'UNLEASHED_PHASE_TURNS',
+    'UNLEASHED_DEFAULT_MAX_HOURS',
+    'UNLEASHED_MAX_PHASES',
+    'WEBHOOK_PORT',
+]);
+const ENUM_KEYS = {
+    CLEMENTINE_ADVISOR_RULES_LOADER: ['off', 'shadow', 'primary'],
+    DEFAULT_MODEL_TIER: ['haiku', 'sonnet', 'opus'],
+    WEBHOOK_ENABLED: ['true', 'false'],
+    ALLOW_ALL_USERS: ['true', 'false'],
+    CLEMENTINE_ALLOW_SOURCE_EDITS: ['true', 'false', '1', '0', 'yes', 'no'],
+};
+const CHANNEL_REQUIREMENTS = [
+    {
+        channel: 'Discord',
+        // Discord is implicit: presence of DISCORD_OWNER_ID != "0" implies usage.
+        enableKey: 'DISCORD_OWNER_ID',
+        enableValuePredicate: (v) => v !== '0' && v !== '',
+        requires: ['DISCORD_OWNER_ID'],
+    },
+    {
+        channel: 'Webhook',
+        enableKey: 'WEBHOOK_ENABLED',
+        enableValuePredicate: (v) => v.toLowerCase() === 'true',
+        requires: ['WEBHOOK_PORT', 'WEBHOOK_BIND'],
+    },
+];
+// ── Doctor ──────────────────────────────────────────────────────────
+export function runDoctor(baseDir) {
+    const cfg = computeEffectiveConfig(baseDir);
+    const findings = [];
+    checkBootstrap(cfg, findings);
+    checkUnresolvedKeychainRefs(cfg, findings);
+    checkNumericTypes(cfg, findings);
+    checkEnumTypes(cfg, findings);
+    checkChannelRequirements(cfg, findings);
+    checkPlaintextSecretsInEnv(cfg, baseDir, findings);
+    checkRangeSanity(cfg, findings);
+    checkSchemaVersion(baseDir, findings);
+    const counts = { error: 0, warning: 0, info: 0 };
+    for (const f of findings)
+        counts[f.severity]++;
+    return {
+        baseDir: cfg.baseDir,
+        hasEnvFile: cfg.hasEnvFile,
+        hasJsonFile: cfg.hasJsonFile,
+        findings,
+        counts,
+        exitCode: counts.error > 0 ? 1 : 0,
+    };
+}
+function checkBootstrap(cfg, findings) {
+    if (!cfg.hasEnvFile && !cfg.hasJsonFile) {
+        findings.push({
+            severity: 'warning',
+            message: 'No .env or clementine.json found — running entirely on compiled defaults',
+            fix: 'clementine config setup',
+        });
+    }
+}
+function checkUnresolvedKeychainRefs(cfg, findings) {
+    for (const entry of cfg.entries) {
+        if (entry.unresolvedRef) {
+            findings.push({
+                severity: 'error',
+                key: entry.key,
+                message: `${entry.key} is set to ${entry.unresolvedRef} but the keychain entry is missing or unreadable. Daemon is silently using the default (${entry.value}).`,
+                fix: `clementine config set ${entry.key} <real value>   # writes plaintext to .env, removing the stale ref`,
+            });
+        }
+    }
+}
+function checkNumericTypes(cfg, findings) {
+    for (const entry of cfg.entries) {
+        if (!NUMERIC_KEYS.has(entry.key))
+            continue;
+        if (entry.source === 'default' || entry.source === 'system')
+            continue;
+        const n = Number(entry.value);
+        if (!Number.isFinite(n)) {
+            findings.push({
+                severity: 'error',
+                key: entry.key,
+                message: `${entry.key} is "${entry.value}" (from ${entry.source}) — does not parse as a number. Numeric coercion silently produces NaN, which means downstream comparisons always fail.`,
+                fix: `clementine config set ${entry.key} <numeric value>`,
+            });
+        }
+    }
+}
+function checkEnumTypes(cfg, findings) {
+    for (const entry of cfg.entries) {
+        const allowed = ENUM_KEYS[entry.key];
+        if (!allowed)
+            continue;
+        if (entry.source === 'default')
+            continue;
+        if (!allowed.includes(String(entry.value).toLowerCase())) {
+            findings.push({
+                severity: 'error',
+                key: entry.key,
+                message: `${entry.key} is "${entry.value}" (from ${entry.source}) — must be one of: ${allowed.join(', ')}. Daemon silently treats this as the first valid option.`,
+                fix: `clementine config set ${entry.key} <one of: ${allowed.join('|')}>`,
+            });
+        }
+    }
+}
+function checkChannelRequirements(cfg, findings) {
+    const byKey = new Map(cfg.entries.map(e => [e.key, e]));
+    for (const req of CHANNEL_REQUIREMENTS) {
+        const enableEntry = req.enableKey ? byKey.get(req.enableKey) : undefined;
+        if (!enableEntry)
+            continue;
+        const enableValue = String(enableEntry.value);
+        const enabled = req.enableValuePredicate
+            ? req.enableValuePredicate(enableValue)
+            : Boolean(enableValue);
+        if (!enabled)
+            continue;
+        for (const reqKey of req.requires) {
+            const entry = byKey.get(reqKey);
+            if (!entry)
+                continue;
+            const v = String(entry.value).trim();
+            if (!v || v === '0') {
+                findings.push({
+                    severity: 'warning',
+                    key: reqKey,
+                    message: `${req.channel} channel is enabled but ${reqKey} is empty. Owner-only commands and notifications may misbehave.`,
+                    fix: `clementine config set ${reqKey} <value>`,
+                });
+            }
+        }
+    }
+}
+function checkPlaintextSecretsInEnv(_cfg, baseDir, findings) {
+    // Scan .env directly for sensitive-looking keys that hold long plaintext
+    // values. Stops bot tokens from quietly sitting in .env when they should
+    // be in the keychain.
+    const envPath = path.join(baseDir, '.env');
+    if (!existsSync(envPath))
+        return;
+    let raw;
+    try {
+        raw = readFileSync(envPath, 'utf-8');
+    }
+    catch {
+        return;
+    }
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = trimmed.slice(0, eq);
+        const value = trimmed.slice(eq + 1);
+        if (!isSensitiveEnvKey(key))
+            continue;
+        if (value.startsWith('keychain:'))
+            continue; // already a ref — fine
+        if (value.length < 16)
+            continue; // probably a config-shaped value (port number, etc.)
+        findings.push({
+            severity: 'warning',
+            key,
+            message: `${key} is stored as plaintext in .env. Credential-shaped keys should live in the keychain on macOS.`,
+            fix: `# In a chat with Clementine: env_set ${key} <value> storage=auto  (auto routes credentials to keychain)`,
+        });
+    }
+}
+function checkRangeSanity(cfg, findings) {
+    const byKey = new Map(cfg.entries.map(e => [e.key, e]));
+    const start = byKey.get('HEARTBEAT_ACTIVE_START');
+    const end = byKey.get('HEARTBEAT_ACTIVE_END');
+    if (start && end) {
+        const s = Number(start.value);
+        const e = Number(end.value);
+        if (Number.isFinite(s) && Number.isFinite(e)) {
+            if (s < 0 || s > 23) {
+                findings.push({ severity: 'error', key: 'HEARTBEAT_ACTIVE_START', message: `must be 0-23, got ${s}` });
+            }
+            if (e < 0 || e > 23) {
+                findings.push({ severity: 'error', key: 'HEARTBEAT_ACTIVE_END', message: `must be 0-23, got ${e}` });
+            }
+            if (Number.isFinite(s) && Number.isFinite(e) && s >= e) {
+                findings.push({
+                    severity: 'warning',
+                    message: `HEARTBEAT_ACTIVE_START (${s}) is not before HEARTBEAT_ACTIVE_END (${e}). Heartbeat will only run during a zero-length window.`,
+                    fix: `clementine config set HEARTBEAT_ACTIVE_END <hour later than ${s}>`,
+                });
+            }
+        }
+    }
+    // Budget sanity: cronT1 should be <= cronT2 (T1 is cheap tier).
+    const t1 = byKey.get('BUDGET_CRON_T1_USD');
+    const t2 = byKey.get('BUDGET_CRON_T2_USD');
+    if (t1 && t2) {
+        const v1 = Number(t1.value);
+        const v2 = Number(t2.value);
+        if (Number.isFinite(v1) && Number.isFinite(v2) && v1 > v2) {
+            findings.push({
+                severity: 'warning',
+                message: `BUDGET_CRON_T1_USD ($${v1}) exceeds BUDGET_CRON_T2_USD ($${v2}). Tier 1 is the cheap tier — these are likely swapped.`,
+            });
+        }
+    }
+}
+function checkSchemaVersion(baseDir, findings) {
+    const jsonPath = path.join(baseDir, 'clementine.json');
+    if (!existsSync(jsonPath))
+        return;
+    try {
+        const raw = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+        if (raw.schemaVersion !== 1) {
+            findings.push({
+                severity: 'error',
+                message: `clementine.json schemaVersion is ${String(raw.schemaVersion)}; expected 1. Loader is treating the whole file as empty.`,
+                fix: 'Set "schemaVersion": 1 in clementine.json',
+            });
+        }
+    }
+    catch {
+        findings.push({
+            severity: 'error',
+            message: 'clementine.json exists but is not valid JSON. Loader is treating the whole file as empty.',
+            fix: 'Repair the JSON syntax or delete the file (next start regenerates it from .env)',
+        });
+    }
+}
+/** Keys-list helper for tests. */
+export function listNumericKeys() {
+    return Array.from(NUMERIC_KEYS);
+}
+export function listEnumKeys() {
+    return Object.keys(ENUM_KEYS);
+}
+//# sourceMappingURL=config-doctor.js.map

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

@@ -0,0 +1,40 @@
+/**
+ * Effective-config inspector.
+ *
+ * Re-reads the same sources config.ts uses (process.env, ~/.clementine/.env,
+ * ~/.clementine/clementine.json) and produces a structured report of every
+ * known key — value plus provenance.
+ *
+ * Pure: no module-level side effects. Safe to call from any CLI / dashboard
+ * surface without touching the running daemon's config snapshot.
+ *
+ * Mirrors the precedence: process.env > .env > clementine.json > compiled default.
+ */
+export type ConfigSource = 'process.env' | '.env' | 'clementine.json' | 'default' | 'system';
+export interface ConfigEntry {
+    key: string;
+    value: string | number | boolean;
+    source: ConfigSource;
+    /** Optional: which other source(s) had a non-empty value for this key (helps debug overrides). */
+    shadowedBy?: ConfigSource[];
+    /** Optional: human-readable section/group for the report. */
+    group?: string;
+    /** Set when the source held a `keychain:` ref that the inspector resolved on-the-fly. */
+    resolvedFrom?: 'keychain';
+    /** Set when the source held a keychain ref but resolution failed (no entry / denied). */
+    unresolvedRef?: string;
+}
+export interface EffectiveConfig {
+    baseDir: string;
+    hasEnvFile: boolean;
+    hasJsonFile: boolean;
+    entries: ConfigEntry[];
+}
+/**
+ * Compute the effective config: every known key with its resolved value
+ * and the source it came from. Optionally include sensitive entries unmasked.
+ */
+export declare function computeEffectiveConfig(baseDir: string): EffectiveConfig;
+/** Return the SPECS array — exported so tests can iterate keys without re-importing. */
+export declare function listKnownConfigKeys(): readonly string[];
+//# sourceMappingURL=effective-config.d.ts.map

package/dist/config/effective-config.js

@@ -0,0 +1,213 @@
+/**
+ * Effective-config inspector.
+ *
+ * Re-reads the same sources config.ts uses (process.env, ~/.clementine/.env,
+ * ~/.clementine/clementine.json) and produces a structured report of every
+ * known key — value plus provenance.
+ *
+ * Pure: no module-level side effects. Safe to call from any CLI / dashboard
+ * surface without touching the running daemon's config snapshot.
+ *
+ * Mirrors the precedence: process.env > .env > clementine.json > compiled default.
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { loadClementineJson } from './clementine-json.js';
+const SPECS = [
+    // Identity
+    { key: 'OWNER_NAME', group: 'identity', jsonPath: 'ownerName', default: '' },
+    { key: 'ASSISTANT_NAME', group: 'identity', jsonPath: 'assistantName', default: 'Clementine' },
+    { key: 'ASSISTANT_NICKNAME', group: 'identity', default: 'Clemmy' },
+    { key: 'TIMEZONE', group: 'identity', jsonPath: 'timezone', systemDefault: () => Intl.DateTimeFormat().resolvedOptions().timeZone },
+    // Models
+    { key: 'DEFAULT_MODEL_TIER', group: 'models', jsonPath: 'models.default', default: 'sonnet' },
+    { key: 'HAIKU_MODEL', group: 'models', jsonPath: 'models.haiku', default: 'claude-haiku-4-5-20251001' },
+    { key: 'SONNET_MODEL', group: 'models', jsonPath: 'models.sonnet', default: 'claude-sonnet-4-6' },
+    { key: 'OPUS_MODEL', group: 'models', jsonPath: 'models.opus', default: 'claude-opus-4-6' },
+    // Budgets
+    { key: 'BUDGET_HEARTBEAT_USD', group: 'budgets', jsonPath: 'budgets.heartbeat', default: 0.50 },
+    { key: 'BUDGET_CRON_T1_USD', group: 'budgets', jsonPath: 'budgets.cronT1', default: 2.00 },
+    { key: 'BUDGET_CRON_T2_USD', group: 'budgets', jsonPath: 'budgets.cronT2', default: 5.00 },
+    { key: 'BUDGET_CHAT_USD', group: 'budgets', jsonPath: 'budgets.chat', default: 5.00 },
+    // Heartbeat
+    { key: 'HEARTBEAT_INTERVAL_MINUTES', group: 'heartbeat', jsonPath: 'heartbeat.intervalMinutes', default: 30 },
+    { key: 'HEARTBEAT_ACTIVE_START', group: 'heartbeat', jsonPath: 'heartbeat.activeStart', default: 8 },
+    { key: 'HEARTBEAT_ACTIVE_END', group: 'heartbeat', jsonPath: 'heartbeat.activeEnd', default: 22 },
+    // Unleashed
+    { key: 'UNLEASHED_PHASE_TURNS', group: 'unleashed', jsonPath: 'unleashed.phaseTurns', default: 75 },
+    { key: 'UNLEASHED_DEFAULT_MAX_HOURS', group: 'unleashed', jsonPath: 'unleashed.defaultMaxHours', default: 6 },
+    { key: 'UNLEASHED_MAX_PHASES', group: 'unleashed', jsonPath: 'unleashed.maxPhases', default: 50 },
+    // Advisor
+    { key: 'CLEMENTINE_ADVISOR_RULES_LOADER', group: 'advisor', default: 'off' },
+    { key: 'CLEMENTINE_ALLOW_SOURCE_EDITS', group: 'advisor', default: 'false' },
+    // Webhook
+    { key: 'WEBHOOK_ENABLED', group: 'channels', default: 'false' },
+    { key: 'WEBHOOK_PORT', group: 'channels', default: 8420 },
+    { key: 'WEBHOOK_BIND', group: 'channels', default: '127.0.0.1' },
+    // Security
+    { key: 'ALLOW_ALL_USERS', group: 'security', default: 'false' },
+    // Discord / Slack / Telegram (presence-only — values themselves come from secrets)
+    { key: 'DISCORD_OWNER_ID', group: 'channels', default: '0' },
+    { key: 'SLACK_OWNER_USER_ID', group: 'channels', default: '' },
+    { key: 'TELEGRAM_OWNER_ID', group: 'channels', default: '0' },
+    { key: 'WHATSAPP_OWNER_PHONE', group: 'channels', default: '' },
+    // Salesforce
+    { key: 'SF_INSTANCE_URL', group: 'channels', default: '' },
+    { key: 'SF_API_VERSION', group: 'channels', default: 'v62.0' },
+];
+// ── Keychain-ref resolution ──────────────────────────────────────────
+// Mirrors config.ts's lazy/cached resolver but kept independent so this
+// module stays a pure utility (no shared mutable state with the daemon).
+const KEYCHAIN_REF_PREFIX = 'keychain:'; // pragma: allowlist secret
+const refCache = new Map();
+function shellEscape(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function resolveRef(stub) {
+    if (refCache.has(stub)) {
+        const v = refCache.get(stub);
+        return v ?? undefined;
+    }
+    const account = stub.slice(KEYCHAIN_REF_PREFIX.length);
+    try {
+        const result = execSync(`security find-generic-password -s clementine-agent -a ${shellEscape(account)} -w`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        refCache.set(stub, result || null);
+        return result || undefined;
+    }
+    catch {
+        refCache.set(stub, null);
+        return undefined;
+    }
+}
+function readEnvFile(baseDir) {
+    const envPath = path.join(baseDir, '.env');
+    if (!existsSync(envPath))
+        return {};
+    const result = {};
+    for (const line of readFileSync(envPath, 'utf-8').split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const eqIndex = trimmed.indexOf('=');
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex);
+        let value = trimmed.slice(eqIndex + 1);
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function getJsonValue(json, dottedPath) {
+    const parts = dottedPath.split('.');
+    let cur = json;
+    for (const p of parts) {
+        if (cur && typeof cur === 'object' && p in cur) {
+            cur = cur[p];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}
+/**
+ * Compute the effective config: every known key with its resolved value
+ * and the source it came from. Optionally include sensitive entries unmasked.
+ */
+export function computeEffectiveConfig(baseDir) {
+    const envFromFile = readEnvFile(baseDir);
+    const json = loadClementineJson(baseDir);
+    const entries = [];
+    const envPath = path.join(baseDir, '.env');
+    const jsonPath = path.join(baseDir, 'clementine.json');
+    for (const spec of SPECS) {
+        // Resolution order matches config.ts: process.env > .env > json > default.
+        const fromProcessEnv = process.env[spec.key];
+        const fromEnvFile = envFromFile[spec.key];
+        const fromJson = spec.jsonPath ? getJsonValue(json, spec.jsonPath) : undefined;
+        let value;
+        let source;
+        let resolvedFrom;
+        let unresolvedRef;
+        // Helper: if a string source holds a keychain ref, resolve it. On
+        // failure, return undefined so we fall through to the next source.
+        const consume = (raw) => {
+            if (!raw)
+                return null;
+            if (raw.startsWith(KEYCHAIN_REF_PREFIX)) {
+                const r = resolveRef(raw);
+                if (r !== undefined)
+                    return { value: r, resolved: true };
+                return { unresolvedRef: raw };
+            }
+            return { value: raw, resolved: false };
+        };
+        const procResult = consume(fromProcessEnv);
+        const envResult = consume(fromEnvFile);
+        if (procResult && 'value' in procResult) {
+            value = procResult.value;
+            source = 'process.env';
+            if (procResult.resolved)
+                resolvedFrom = 'keychain';
+        }
+        else if (envResult && 'value' in envResult) {
+            value = envResult.value;
+            source = '.env';
+            if (envResult.resolved)
+                resolvedFrom = 'keychain';
+        }
+        else if (fromJson !== undefined && fromJson !== '' && fromJson !== null) {
+            value = fromJson;
+            source = 'clementine.json';
+        }
+        else if (spec.systemDefault) {
+            value = spec.systemDefault();
+            source = 'system';
+        }
+        else {
+            value = spec.default ?? '';
+            source = 'default';
+        }
+        // If the higher-precedence source held an unresolvable ref, surface that
+        // explicitly so users know the daemon is silently using the fallback.
+        if (procResult && 'unresolvedRef' in procResult && source !== 'process.env') {
+            unresolvedRef = procResult.unresolvedRef;
+        }
+        else if (envResult && 'unresolvedRef' in envResult && source !== '.env') {
+            unresolvedRef = envResult.unresolvedRef;
+        }
+        // Track which other sources had values, to surface "this is overriding X."
+        const shadowedBy = [];
+        if (source !== 'process.env' && fromProcessEnv)
+            shadowedBy.push('process.env');
+        if (source !== '.env' && fromEnvFile && fromEnvFile.length > 0)
+            shadowedBy.push('.env');
+        if (source !== 'clementine.json' && fromJson !== undefined && fromJson !== '')
+            shadowedBy.push('clementine.json');
+        entries.push({
+            key: spec.key,
+            value,
+            source,
+            shadowedBy: shadowedBy.length > 0 ? shadowedBy : undefined,
+            group: spec.group,
+            ...(resolvedFrom ? { resolvedFrom } : {}),
+            ...(unresolvedRef ? { unresolvedRef } : {}),
+        });
+    }
+    return {
+        baseDir,
+        hasEnvFile: existsSync(envPath),
+        hasJsonFile: existsSync(jsonPath),
+        entries,
+    };
+}
+/** Return the SPECS array — exported so tests can iterate keys without re-importing. */
+export function listKnownConfigKeys() {
+    return SPECS.map(s => s.key);
+}
+//# sourceMappingURL=effective-config.js.map