Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

40.7 KB
Raw Blame
/**
 * Claudish Profile Configuration
 *
 * Manages user profiles for model mapping.
 * Supports two scopes:
 *   - Global: ~/.claudish/config.json (shared across all projects)
 *   - Local:  .claudish.json in project root (project-specific overrides)
 *
 * Resolution order: local config takes priority over global config.
 */

import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { dirname, join, parse } from "node:path";
import { type CodeModeSetting, parseCodeModeSetting } from "./code-mode/policy.js";
import { activeGlobalConfigFile, getConfigFileOverride } from "./config-override.js";

// Config directory and file paths
const CONFIG_DIR = join(homedir(), ".claudish");
const CONFIG_FILE = join(CONFIG_DIR, "config.json");
const LOCAL_CONFIG_FILENAME = ".claudish.json";

// Run-scoped config override (`--config <file>` / `CLAUDISH_CONFIG`) is owned by
// config-override.ts — the single, dependency-free authority every config reader
// consults (profile-config, op-source, onepassword-config). Re-exported here so
// existing importers keep working; the STATE lives in exactly one place.
export { setConfigFileOverride } from "./config-override.js";

/** The active global-config path — the override if set, else the machine file. */
export function activeConfigFile(): string {
  return activeGlobalConfigFile(CONFIG_FILE);
}

export type ProfileScope = "local" | "global";

/**
 * Model mapping for a profile
 * Maps Claude model types to OpenRouter model IDs
 */
export interface ModelMapping {
  opus?: string; // Model for opus (claude-opus-4-*)
  sonnet?: string; // Model for sonnet (claude-sonnet-4-*)
  haiku?: string; // Model for haiku (claude-haiku-*)
  subagent?: string; // Model for subagents (CLAUDE_CODE_SUBAGENT_MODEL)
}

/**
 * A named profile with model mappings
 */
export interface Profile {
  name: string;
  description?: string;
  models: ModelMapping;
  createdAt: string;
  updatedAt: string;
}

/**
 * Profile with scope metadata for display
 */
export interface ProfileWithScope extends Profile {
  scope: ProfileScope;
  isDefault: boolean;
  shadowed?: boolean; // global profile hidden by same-name local profile
}

/**
 * A single routing destination: either "provider" (uses the original model name)
 * or "provider@model" (uses a specific model on that provider).
 */
export type RoutingEntry = string;

/**
 * Custom routing rules: maps a model name pattern to an ordered list of routing
 * destinations to try. Patterns can be exact names, globs ("kimi-*"), or "*"
 * catch-all. A project .claudish.json rule overrides the global rule with the
 * same pattern, and every other global rule still applies (`loadRoutingRules`
 * merges the two per pattern). The merged rules are then matched as one set —
 * exact, then the longest glob, then "*" — whichever file each came from.
 */
export type RoutingRules = Record<string, RoutingEntry[]>;

/**
 * Telemetry consent state. Persisted to ~/.claudish/config.json under the
 * "telemetry" key. Absence of the "telemetry" key means the user has never
 * been prompted (equivalent to enabled: false, askedAt: undefined).
 */
export interface TelemetryConsent {
  /** Explicit opt-in. Default is false (disabled until user says yes). */
  enabled: boolean;
  /**
   * ISO 8601 UTC timestamp of when the user was asked. Absent means the user
   * has never seen the consent prompt. This is the gate for re-prompting.
   */
  askedAt?: string;
  /**
   * Claudish version string when the user was first prompted. Stored for
   * future re-consent logic (e.g., if schema changes significantly).
   */
  promptedVersion?: string;
}

/**
 * Anonymous usage stats consent state. Persisted to ~/.claudish/config.json
 * under the "stats" key. Stats are OFF by default — user must explicitly enable.
 */
export interface StatsConsent {
  /** Explicit opt-in. Default: false (disabled until user says yes). */
  enabled: boolean;
  /** ISO 8601 UTC of when the user first enabled stats. */
  enabledAt?: string;
  /** ISO 8601 UTC of last monthly banner shown. */
  lastMonthlyPrompt?: string;
  /** ISO 8601 UTC of last successful batch send. */
  lastSentAt?: string;
  /** Claudish version when first prompted. */
  promptedVersion?: string;
}

/**
 * Root configuration structure
 */
export interface ClaudishProfileConfig {
  version: string;
  defaultProfile: string;
  profiles: Record<string, Profile>;
  /** Telemetry consent state. Absent = never prompted. */
  telemetry?: TelemetryConsent;
  /** Anonymous usage stats consent state. Absent = never configured (defaults to disabled). */
  stats?: StatsConsent;
  /**
   * Custom routing rules. Maps model name patterns (exact, glob, or "*") to ordered
   * lists of routing entries. A project .claudish.json rule overrides the global
   * rule with the same pattern; the other global rules still apply.
   */
  routing?: RoutingRules;
  /** API keys stored in config (NOT env files). Env vars take precedence at runtime. */
  apiKeys?: Record<string, string>;
  /** Custom provider endpoints (env var name → URL) */
  endpoints?: Record<string, string>;
  /**
   * 1Password imports. Each entry is a glob (`op://.../*` or
   * `op://.../<section>/<fieldGlob>`) that expands to MANY env vars named by
   * field label, OR a single `op://vault/item/[section]/field` reference named
   * by its trailing field label. Resolved at startup (explicit opt-in → a
   * failure hard-fails). Env vars already set always win.
   */
  onepassword?: string[];
  /**
   * The 1Password account URL (e.g. `my-team.1password.com`) to use for SDK
   * DesktopAuth when no OP_SERVICE_ACCOUNT_TOKEN / OP_ACCOUNT is set. Saved by
   * the interactive multi-account picker, or set manually. Resolves below
   * OP_ACCOUNT (env) but above auto-detection.
   */
  onepasswordAccount?: string;
  /**
   * 1Password Environment IDs to load at startup (SDK beta API). Each entry's
   * variables are hydrated into process.env (overwrite, mirroring `--op-env`).
   * Persisted form of the `--op-env <id>` flag. Resolved below `--op-env` but
   * above `onepassword[]` single refs/globs. A failure hard-fails (explicit
   * opt-in, like all 1Password sources).
   */
  onepasswordEnvironments?: string[];
  /**
   * macOS Keychain backend state.
   *
   * `enabled` is a LAZINESS GATE, not a record of what is stored. It says only
   * "this machine uses the keychain backend", which lets `hasKeychainSource()`
   * answer synchronously without spawning `security` for a user who has never
   * opted in. The stored variable NAMES are deliberately not mirrored here: the
   * keychain enumerates its own contents in one ~28ms call, and a second copy
   * of a list is a second thing that can be wrong.
   *
   * Set automatically on the first successful keychain write.
   */
  keychain?: {
    enabled?: boolean;
  };
  /**
   * Opt IN to using a real ANTHROPIC_API_KEY for native Claude models, accepting
   * metered API billing. Default (absent/false) hides the key so Claude Code
   * uses the claude.ai subscription — a key bundled into a shared .env /
   * 1Password Environment alongside other providers' keys must not silently
   * switch billing. Overridden by CLAUDISH_ANTHROPIC_API_BILLING and
   * --anthropic-api-billing.
   */
  anthropicApiBilling?: boolean;
  /** Built-in local providers explicitly enabled in global config. */
  localProviders?: string[];
  /** ISO timestamp when user confirmed auto-approve behavior. Absent = never confirmed. */
  autoApproveConfirmedAt?: string;
  /** Diagnostic output mode: auto (default), logfile, off */
  diagMode?: "auto" | "logfile" | "off";

  /**
   * Always enable claudish's own debug logging (equivalent to passing
   * `-d` / `--debug-claudish` on every run). Writes a full debug log to
   * `logs/claudish_*.log` and bumps the log level to `debug`.
   * Precedence: `-d` / `--no-debug-claudish` flag > CLAUDISH_DEBUG env > this field.
   */
  debug?: boolean;

  /**
   * The provider in the FALLBACK position: the last hop of a bare name's
   * catalog-gathered chain. A claudish provider name or shortcut, or a
   * `customEndpoints` key. Not used for an explicit `provider@model` spec, nor when
   * a user routing rule matches (that chain is used verbatim).
   *
   *   - unset: `openrouter`.
   *   - `""`: no fallback hop. A name the catalog does not serve gets no route.
   *
   * Precedence (`resolveDefaultProvider`): `--default-provider` flag >
   * CLAUDISH_DEFAULT_PROVIDER env > this field. An empty flag or env value is an
   * answer too: it disables the hop and overrides this field.
   *
   * Read from the global config (or the `--config` file) only. A `defaultProvider`
   * in a project `.claudish.json` is kept on disk, but no routing path reads it.
   */
  defaultProvider?: string;

  /**
   * Named custom endpoints. Each entry is either a "simple" config
   * (URL + format + key) or a "complex" config (full provider profile).
   * NOTE: This is distinct from the legacy `endpoints?: Record<string, string>` field
   * which is just an env-var → URL map for builtin providers.
   * Validation of entries happens at the consumption site (Phase 3) via Zod, not here.
   */
  customEndpoints?: Record<string, unknown>;

  /**
   * Opt-out surface for the endpoint catalog that ships inside the package
   * (`providers/predefined-catalog.ts`): `{ enabled?, disable?, enable? }`.
   * Validated at the consumption site (`providers/predefined-endpoints.ts`) via
   * Zod, not here — `loadConfig` stays Zod-free.
   *
   * SCOPE: global only, exactly like `customEndpoints`. That is not an
   * oversight — the two are read as ONE object, because a suppression set built
   * from a wider scope than the endpoints it suppresses would delete a provider
   * outright (a project-level `customEndpoints.groq` would suppress the bundled
   * row while the replacement, loaded from global config only, never registers).
   */
  predefinedEndpoints?: Record<string, unknown>;

  /**
   * The pre-hook-system `behavior` block. The hook system never reads it: its
   * only reader there is the reporter in hooks/config.ts, which tells the user
   * what to move into `hooks`.
   * It stays on the allowlist as an opaque passthrough so the next global save
   * does not silently drop it before the user has moved it.
   */
  behavior?: Record<string, unknown>;

  /**
   * The hook system (modules, severity, injection cap, observer, telemetry
   * consent). Read from the GLOBAL config only — a project `.claudish.json` is
   * repo-controlled and must not name code to run. Validated at the consumption
   * site via Zod in hooks/config.ts; `loadConfig` stays Zod-free.
   */
  hooks?: Record<string, unknown>;

  /**
   * Apply a model's catalog provider-preset (e.g. `reasoning.mode=pro`) while
   * the Claude Code session is in ultracode. Opt-in and default OFF — a pro
   * preset burns quota faster, so it must never turn itself on.
   * Precedence: --pro-on-ultracode flag > CLAUDISH_PRO_ON_ULTRACODE env >
   * project `.claudish.json` > this field > false. The scoped read is
   * `readProOnUltracode()`, NOT this allowlist — see its doc comment.
   */
  proOnUltracode?: boolean;

  /**
   * Code mode for `openai-codex` (`auto` | `on` | `off`, default `auto`): Claude
   * Code's tools are offered to the model as one freeform `exec` tool running
   * a script, the protocol the official Codex client uses.
   * Precedence: --code-mode flag > CLAUDISH_CODE_MODE env > project
   * `.claudish.json` > this field > auto. The scoped read is `readCodeMode()`,
   * NOT this allowlist — same reason as `proOnUltracode`.
   */
  codeMode?: CodeModeSetting;

  /**
   * Master switch for connection RECOVERY itself — the retry ladder claudish
   * runs when it cannot even reach the provider. Default ON. Turning it off
   * restores the immediate `connection_error` 400 everywhere.
   *
   * It exists for CI and scripted `-p` runs, which would otherwise hold a dead
   * endpoint open for the whole tier-1 deadline instead of failing at once.
   * Precedence: --recovery/--no-recovery flag > CLAUDISH_RECOVERY env >
   * project `.claudish.json` > this field > true. The scoped read is
   * `readRecoveryEnabled()`, NOT this allowlist — see its doc comment.
   *
   * An OBJECT rather than a bare boolean so a later `deadlineMs` needs no
   * second allowlist entry, and because `{}` can then mean "no opinion" and
   * fall through to the next scope, which a boolean cannot express.
   */
  recovery?: { enabled?: boolean };

  /**
   * Whether claudish may own a terminal surface on which a recovery episode's
   * reason is legible. Default ON.
   *
   * What it actually decides, and the blast radius is larger than "a banner":
   *
   *   - whether the interactive session is WRAPPED in a magmux pane at launch
   *     (`claude-runner.ts` → `planMagmuxWrap`);
   *   - whether `CLAUDE_CODE_RETRY_WATCHDOG=1` is exported to Claude Code,
   *     which moves its retry budget from ~11 attempts to ~300 for every 503
   *     the session sees (it is one of three gates — see `retryWatchdogEnv`);
   *   - and through those, whether an exhausted hold can ever answer a
   *     retryable 503 rather than an inline 400, since the 503 requires a live
   *     pane lease.
   *
   * It never decides whether a RETRY happens. There is no loopback carve-out
   * and its absence is deliberate (`composed-handler.ts`'s `shouldSkipTier1`);
   * an earlier draft of this comment described one, and it had already been
   * deleted.
   *
   * Precedence: --recovery-ui/--no-recovery-ui flag > CLAUDISH_RECOVERY_UI env
   * > project `.claudish.json` > this field > true. The scoped read is
   * `readRecoveryUi()`, NOT this allowlist — see its doc comment.
   */
  recoveryUi?: { enabled?: boolean };
}

/**
 * Default configuration
 */
const DEFAULT_CONFIG: ClaudishProfileConfig = {
  version: "1.0.0",
  defaultProfile: "default",
  profiles: {
    default: {
      name: "default",
      description: "Default profile - shows model selector when no model specified",
      models: {},
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
    },
  },
};

// ─── Global Config ───────────────────────────────────────

/**
 * Ensure global config directory exists
 */
function ensureConfigDir(): void {
  if (!existsSync(CONFIG_DIR)) {
    mkdirSync(CONFIG_DIR, { recursive: true });
  }
}

/**
 * Load global configuration from ~/.claudish/config.json
 * Returns default config if file doesn't exist
 */
export function loadConfig(): ClaudishProfileConfig {
  const activeFile = activeConfigFile();
  // Only touch ~/.claudish when reading the real machine file — an override
  // points elsewhere and must not create the machine dir as a side effect.
  if (!getConfigFileOverride()) ensureConfigDir();

  if (!existsSync(activeFile)) {
    return { ...DEFAULT_CONFIG };
  }

  try {
    const content = readFileSync(activeFile, "utf-8");
    const config = JSON.parse(content) as ClaudishProfileConfig;

    // Validate and merge with defaults
    const merged: ClaudishProfileConfig = {
      version: config.version || DEFAULT_CONFIG.version,
      defaultProfile: config.defaultProfile || DEFAULT_CONFIG.defaultProfile,
      profiles: config.profiles || DEFAULT_CONFIG.profiles,
    };
    // Preserve telemetry consent state if present
    if (config.telemetry !== undefined) {
      merged.telemetry = config.telemetry;
    }
    // Preserve stats consent state if present
    if (config.stats !== undefined) {
      merged.stats = config.stats;
    }
    // Preserve custom routing rules if present
    if (config.routing !== undefined) {
      merged.routing = config.routing;
    }
    if (config.apiKeys !== undefined) {
      merged.apiKeys = config.apiKeys;
    }
    if (config.endpoints !== undefined) {
      merged.endpoints = config.endpoints;
    }
    if (config.onepassword !== undefined) {
      merged.onepassword = config.onepassword;
    }
    if (config.onepasswordAccount !== undefined) {
      merged.onepasswordAccount = config.onepasswordAccount;
    }
    if (config.onepasswordEnvironments !== undefined) {
      merged.onepasswordEnvironments = config.onepasswordEnvironments;
    }
    // Same trap as onepasswordEnvironments below: omitted from this allowlist,
    // the block survives on disk until the first global save and is then
    // silently dropped — which would quietly disable the keychain backend.
    if (config.keychain !== undefined) {
      merged.keychain = config.keychain;
    }
    if (config.anthropicApiBilling !== undefined) {
      merged.anthropicApiBilling = config.anthropicApiBilling;
    }
    if (config.localProviders !== undefined) {
      merged.localProviders = Array.from(new Set(config.localProviders)).sort();
    }
    if (config.autoApproveConfirmedAt !== undefined) {
      merged.autoApproveConfirmedAt = config.autoApproveConfirmedAt;
    }
    if (config.defaultProvider !== undefined) {
      merged.defaultProvider = config.defaultProvider;
    }
    if (config.debug !== undefined) {
      merged.debug = config.debug;
    }
    if (config.customEndpoints !== undefined) {
      merged.customEndpoints = config.customEndpoints;
    }
    // Without this line the block survives on disk until the first global save
    // and is then silently dropped — the trap `onepasswordEnvironments` hit.
    if (config.predefinedEndpoints !== undefined) {
      merged.predefinedEndpoints = config.predefinedEndpoints;
    }
    if (config.behavior !== undefined) {
      merged.behavior = config.behavior;
    }
    // Same trap as keychain/onepasswordEnvironments: omitted from this
    // allowlist, the block survives on disk until the first global save and is
    // then silently dropped — every user hook would stop loading with no error.
    if (config.hooks !== undefined) {
      merged.hooks = config.hooks;
    }
    // Same trap as keychain/onepasswordEnvironments above: omitted from this
    // allowlist, the field survives on disk until the first global save and is
    // then silently dropped — quietly turning the feature off with no error.
    if (config.proOnUltracode !== undefined) {
      merged.proOnUltracode = config.proOnUltracode;
    }
    // Same trap: omitted here, `codeMode` is dropped at the first global save.
    if (config.codeMode !== undefined) {
      merged.codeMode = config.codeMode;
    }
    // Same trap again, for both recovery switches. Omitted here, the field
    // survives on disk until the first global save and is then silently
    // dropped — turning the user's off-switch back ON with no error.
    if (config.recovery !== undefined) {
      merged.recovery = config.recovery;
    }
    if (config.recoveryUi !== undefined) {
      merged.recoveryUi = config.recoveryUi;
    }
    return merged;
  } catch (error) {
    console.error(`Warning: Failed to load config, using defaults: ${error}`);
    return { ...DEFAULT_CONFIG };
  }
}

/**
 * Save global configuration to file
 */
export function saveConfig(config: ClaudishProfileConfig): void {
  // Writes target the ACTIVE file: with a --config override, persist to that
  // file (never mutate ~/.claudish/config.json with override-derived data).
  if (!getConfigFileOverride()) ensureConfigDir();
  writeFileSync(activeConfigFile(), JSON.stringify(config, null, 2), "utf-8");
}

/**
 * Check if global config file exists
 */
export function configExists(): boolean {
  return existsSync(CONFIG_FILE);
}

/**
 * Get global config file path
 */
export function getConfigPath(): string {
  return CONFIG_FILE;
}

// ─── Local Config ────────────────────────────────────────

/**
 * Get path to local config file (.claudish.json).
 *
 * Walks up from cwd to find an existing .claudish.json so users can run
 * `claudish` from any subdirectory of their project. Walk-up stops at:
 *   - $HOME (don't escape into the user's home dir)
 *   - The git repo root (presence of `.git`) — bounds project scope
 *   - The filesystem root
 *
 * If no .claudish.json is found in the walk-up chain, returns the path at
 * cwd so first-time saves create the file at the user's working directory
 * (preserves prior "create at cwd" semantics for fresh projects).
 *
 * Behavior change vs. v7.x: previously cwd-only. This unifies how every
 * local-config consumer (Profiles, Routing, custom endpoints) discovers
 * the project file. Documented in app-tsx-split PR.
 */
export function getLocalConfigPath(): string {
  const home = homedir();
  let dir = process.cwd();
  const root = parse(dir).root;

  while (dir !== root && dir !== home) {
    const candidate = join(dir, LOCAL_CONFIG_FILENAME);
    if (existsSync(candidate)) return candidate;
    if (existsSync(join(dir, ".git"))) {
      // At git root; if .claudish.json doesn't exist here, stop walking and
      // return this path so first-time saves create the file at the git root
      // (the natural project boundary), not at cwd or somewhere above the repo.
      return candidate;
    }
    dir = dirname(dir);
  }
  // No project boundary found — fall back to cwd.
  return join(process.cwd(), LOCAL_CONFIG_FILENAME);
}

/**
 * Check if local config file exists
 */
export function localConfigExists(): boolean {
  return existsSync(getLocalConfigPath());
}

/**
 * The two config scopes `readProOnUltracode` consults, as thunks.
 *
 * A seam rather than direct calls because `homedir()` cannot be re-pointed at
 * runtime in Bun — the same approach as onepassword-config.test.ts.
 */
export interface ScopedConfigPaths {
  global: () => string;
  project: () => string;
}

const defaultScopedConfigPaths: ScopedConfigPaths = {
  // activeConfigFile(), NOT the raw CONFIG_FILE constant: `--config <file>` /
  // CLAUDISH_CONFIG must redirect this read like every other config reader,
  // and `bun run test:safe` relies on that to stay off the real machine file.
  global: () => activeConfigFile(),
  project: () => getLocalConfigPath(),
};

/**
 * Read `proOnUltracode` from the project file, else the global file.
 *
 * Deliberately a RAW per-file read rather than `loadConfig()`. `loadConfig`
 * merges only the global scope through its allowlist, so a project
 * `.claudish.json` that sets ONLY this key would be invisible to it. That is
 * the whole point of this function, not an oversight.
 *
 * Returns undefined when neither scope states a boolean — the caller then
 * applies its own default (false).
 */
export function readProOnUltracode(
  paths: ScopedConfigPaths = defaultScopedConfigPaths
): boolean | undefined {
  for (const pathFn of [paths.project, paths.global]) {
    try {
      const path = pathFn();
      if (!existsSync(path)) continue;
      const parsed = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
      if (typeof parsed?.proOnUltracode === "boolean") return parsed.proOnUltracode;
    } catch {
      // Garbled/unreadable file → skip this scope rather than fail the run.
    }
  }
  return undefined;
}

/**
 * Read `codeMode` from the project file, else the global file.
 *
 * A RAW per-file read, for the same reason `readProOnUltracode` is one: a
 * project `.claudish.json` that sets only this key is invisible to
 * `loadConfig`. A value other than `auto`/`on`/`off` is skipped (that scope
 * states nothing). Returns undefined when neither scope states a setting —
 * the caller then applies the default (`off`).
 */
export function readCodeMode(
  paths: ScopedConfigPaths = defaultScopedConfigPaths
): CodeModeSetting | undefined {
  for (const pathFn of [paths.project, paths.global]) {
    try {
      const path = pathFn();
      if (!existsSync(path)) continue;
      const parsed = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
      const setting = parseCodeModeSetting(parsed?.codeMode);
      if (setting) return setting;
    } catch {
      // Garbled/unreadable file → skip this scope rather than fail the run.
    }
  }
  return undefined;
}

/**
 * Read a `{ enabled?: boolean }` switch from the project file, else the global
 * file. Shared by `readRecoveryEnabled` and `readRecoveryUi`.
 *
 * The nesting is what makes `{}` expressible, and `{}` means "no opinion" —
 * a project file that carries `"recovery": {}` must fall through to the global
 * scope rather than reading as `true`. That is why this checks
 * `typeof parsed?.[key]?.enabled === "boolean"` and not the bare-boolean shape
 * `readProOnUltracode` uses: the two fields have different types on purpose.
 */
function readNestedEnabled(
  key: "recovery" | "recoveryUi",
  paths: ScopedConfigPaths
): boolean | undefined {
  for (const pathFn of [paths.project, paths.global]) {
    try {
      const path = pathFn();
      if (!existsSync(path)) continue;
      const parsed = JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
      const value = (parsed?.[key] as { enabled?: unknown } | undefined)?.enabled;
      if (typeof value === "boolean") return value;
    } catch {
      // Garbled/unreadable file → skip this scope rather than fail the run.
    }
  }
  return undefined;
}

/**
 * Read `recovery.enabled` from the project file, else the global file.
 *
 * Deliberately a RAW per-file read rather than `loadConfig()`, for the same
 * reason `readProOnUltracode` is: `loadConfig` merges only the GLOBAL scope, so
 * a project `.claudish.json` setting this key would be invisible to it.
 *
 * Returns undefined when neither scope states a boolean — the caller then
 * applies its own default (true).
 */
export function readRecoveryEnabled(
  paths: ScopedConfigPaths = defaultScopedConfigPaths
): boolean | undefined {
  return readNestedEnabled("recovery", paths);
}

/** Read `recoveryUi.enabled` from the project file, else the global file. */
export function readRecoveryUi(
  paths: ScopedConfigPaths = defaultScopedConfigPaths
): boolean | undefined {
  return readNestedEnabled("recoveryUi", paths);
}

/**
 * Detect if CWD looks like a project directory
 */
export function isProjectDirectory(): boolean {
  const cwd = process.cwd();
  return [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".claudish.json"].some(
    (f) => existsSync(join(cwd, f))
  );
}

/**
 * Load local configuration from .claudish.json in CWD
 * Returns null if file doesn't exist
 */
export function loadLocalConfig(): ClaudishProfileConfig | null {
  // A --config override fully replaces machine settings, so the project
  // .claudish.json is ignored for this run (otherwise it would merge back in).
  if (getConfigFileOverride()) return null;

  const localPath = getLocalConfigPath();

  if (!existsSync(localPath)) {
    return null;
  }

  try {
    const content = readFileSync(localPath, "utf-8");
    const config = JSON.parse(content) as ClaudishProfileConfig;

    // Preserve ALL keys present in the file. A read-modify-write cycle
    // (loadLocalConfig → mutate one field → saveLocalConfig) must never drop
    // other settings the user has in `.claudish.json` (e.g. onepasswordAccount,
    // defaultProvider, diagMode). We only backfill the structural fields that
    // downstream code assumes are always present.
    return {
      ...config,
      version: config.version || DEFAULT_CONFIG.version,
      defaultProfile: config.defaultProfile ?? "",
      profiles: config.profiles ?? {},
    };
  } catch (error) {
    console.error(`Warning: Failed to load local config: ${error}`);
    return null;
  }
}

/**
 * Save local configuration to .claudish.json. Prunes empty containers so
 * deleting the last project rule doesn't leave a stub `{"routing": {}}`
 * file behind. If the entire local config carries no meaningful state
 * (no profiles, no routing), the file is unlinked instead of written.
 */
export function saveLocalConfig(config: ClaudishProfileConfig): void {
  // Drop an EMPTY routing object so the on-disk file stays tidy (an empty
  // `{"routing": {}}` carries no rules). This is cosmetic, not data loss.
  const toWrite: ClaudishProfileConfig = { ...config };
  if (toWrite.routing !== undefined && Object.keys(toWrite.routing).length === 0) {
    delete toWrite.routing;
  }

  // Always write what we're given. We deliberately do NOT delete the file when
  // profiles/routing are empty: `.claudish.json` may legitimately hold other
  // settings (onepasswordAccount, defaultProvider, diagMode, …). Deleting it on
  // a profile/routing change would silently wipe those — destructive. Mirror
  // the global saveConfig(): persist the config as-is.
  writeFileSync(getLocalConfigPath(), JSON.stringify(toWrite, null, 2), "utf-8");
}

// ─── Scope-Aware Operations ─────────────────────────────

function loadConfigForScope(scope: ProfileScope): ClaudishProfileConfig {
  if (scope === "local") {
    return loadLocalConfig() || { version: "1.0.0", defaultProfile: "", profiles: {} };
  }
  return loadConfig();
}

function saveConfigForScope(config: ClaudishProfileConfig, scope: ProfileScope): void {
  if (scope === "local") {
    saveLocalConfig(config);
  } else {
    saveConfig(config);
  }
}

/**
 * Check if config exists for a given scope
 */
export function configExistsForScope(scope: ProfileScope): boolean {
  if (scope === "local") {
    return localConfigExists();
  }
  return configExists();
}

/**
 * Get config file path for a given scope
 */
export function getConfigPathForScope(scope: ProfileScope): string {
  if (scope === "local") {
    return getLocalConfigPath();
  }
  return getConfigPath();
}

/**
 * Get a profile by name with optional scope
 * - scope="local": only local config
 * - scope="global": only global config
 * - scope=undefined: local first, then global
 */
export function getProfile(name: string, scope?: ProfileScope): Profile | undefined {
  if (scope === "local") {
    const local = loadLocalConfig();
    return local?.profiles[name];
  }
  if (scope === "global") {
    const config = loadConfig();
    return config.profiles[name];
  }

  // No scope: local first, then global
  const local = loadLocalConfig();
  if (local?.profiles[name]) {
    return local.profiles[name];
  }
  const config = loadConfig();
  return config.profiles[name];
}

/**
 * Get the default profile with optional scope
 * - scope="local": only local config's default
 * - scope="global": only global config's default
 * - scope=undefined: local default first (if local config exists and has a non-empty defaultProfile),
 *   otherwise fall through to global
 */
export function getDefaultProfile(scope?: ProfileScope): Profile {
  if (scope === "local") {
    const local = loadLocalConfig();
    if (local?.defaultProfile && local.profiles[local.defaultProfile]) {
      return local.profiles[local.defaultProfile];
    }
    // Local config exists but no valid default — return empty
    return DEFAULT_CONFIG.profiles.default;
  }

  if (scope === "global") {
    const config = loadConfig();
    const profile = config.profiles[config.defaultProfile];
    if (profile) return profile;
    const firstProfile = Object.values(config.profiles)[0];
    if (firstProfile) return firstProfile;
    return DEFAULT_CONFIG.profiles.default;
  }

  // No scope: local-first resolution
  const local = loadLocalConfig();
  if (local?.defaultProfile) {
    // Resolve the name local-first, then global
    const profile = getProfile(local.defaultProfile);
    if (profile) return profile;
  }

  // Fall through to global
  const config = loadConfig();
  const profile = config.profiles[config.defaultProfile];
  if (profile) return profile;
  const firstProfile = Object.values(config.profiles)[0];
  if (firstProfile) return firstProfile;
  return DEFAULT_CONFIG.profiles.default;
}

/**
 * Get all profile names with optional scope
 * - scope="local"/"global": names from that scope only
 * - scope=undefined: merged set from both
 */
export function getProfileNames(scope?: ProfileScope): string[] {
  if (scope === "local") {
    const local = loadLocalConfig();
    return local ? Object.keys(local.profiles) : [];
  }
  if (scope === "global") {
    const config = loadConfig();
    return Object.keys(config.profiles);
  }

  // Merged set
  const local = loadLocalConfig();
  const config = loadConfig();
  const names = new Set<string>([
    ...(local ? Object.keys(local.profiles) : []),
    ...Object.keys(config.profiles),
  ]);
  return [...names];
}

/**
 * Add or update a profile in the specified scope
 */
export function setProfile(profile: Profile, scope: ProfileScope = "global"): void {
  const config = loadConfigForScope(scope);

  const existingProfile = config.profiles[profile.name];
  if (existingProfile) {
    profile.createdAt = existingProfile.createdAt;
  } else {
    profile.createdAt = new Date().toISOString();
  }
  profile.updatedAt = new Date().toISOString();

  config.profiles[profile.name] = profile;
  saveConfigForScope(config, scope);
}

/**
 * Delete a profile from the specified scope
 * For global scope: cannot delete the last profile
 * For local scope: can delete any profile (local config can be empty)
 */
export function deleteProfile(name: string, scope: ProfileScope = "global"): boolean {
  const config = loadConfigForScope(scope);

  if (!config.profiles[name]) {
    return false;
  }

  // Only enforce "last profile" constraint on global scope
  if (scope === "global") {
    const profileCount = Object.keys(config.profiles).length;
    if (profileCount <= 1) {
      throw new Error("Cannot delete the last global profile");
    }
  }

  delete config.profiles[name];

  // If we deleted the default profile, set a new default
  if (config.defaultProfile === name) {
    const remaining = Object.keys(config.profiles);
    config.defaultProfile = remaining.length > 0 ? remaining[0] : "";
  }

  saveConfigForScope(config, scope);
  return true;
}

/**
 * Set the default profile in the specified scope
 */
export function setDefaultProfile(name: string, scope: ProfileScope = "global"): void {
  const config = loadConfigForScope(scope);

  if (!config.profiles[name]) {
    // For setting default, the profile must exist in the target scope
    throw new Error(`Profile "${name}" does not exist in ${scope} config`);
  }

  config.defaultProfile = name;
  saveConfigForScope(config, scope);
}

/** The model tiers a run takes from a profile, and where that profile came from. */
export interface RunModelMapping {
  models: ModelMapping;
  /**
   * The profile's name when it came from the project `.claudish.json`, which ships with
   * the checkout; null for the user's own config. `project-models.ts` checks a project
   * profile's tiers before a run uses them.
   */
  projectProfile: string | null;
}

/**
 * The model tiers of the profile a run uses: `profileName`, or the default profile,
 * resolved local-first exactly as `getProfile(name)` / `getDefaultProfile()` resolve it,
 * keeping the scope those discard.
 */
export function getRunModelMapping(profileName?: string): RunModelMapping {
  const local = loadLocalConfig();
  const name = profileName || local?.defaultProfile || undefined;
  if (name !== undefined) {
    const fromLocal = local?.profiles[name];
    if (fromLocal) return { models: fromLocal.models ?? {}, projectProfile: name };
    const fromGlobal = loadConfig().profiles[name];
    if (fromGlobal) return { models: fromGlobal.models, projectProfile: null };
    if (profileName) return { models: {}, projectProfile: null };
  }
  return { models: getDefaultProfile("global").models, projectProfile: null };
}

/**
 * Create a new profile with the given models in the specified scope
 */
export function createProfile(
  name: string,
  models: ModelMapping,
  description?: string,
  scope: ProfileScope = "global"
): Profile {
  const now = new Date().toISOString();
  const profile: Profile = {
    name,
    description,
    models,
    createdAt: now,
    updatedAt: now,
  };

  setProfile(profile, scope);
  return profile;
}

/**
 * List profiles from a single scope (legacy behavior for global)
 */
export function listProfiles(): Profile[] {
  const config = loadConfig();
  return Object.values(config.profiles).map((profile) => ({
    ...profile,
    isDefault: profile.name === config.defaultProfile,
  })) as (Profile & { isDefault?: boolean })[];
}

/**
 * List all profiles from both scopes with scope metadata
 */
export function listAllProfiles(): ProfileWithScope[] {
  const globalConfig = loadConfig();
  const localConfig = loadLocalConfig();
  const result: ProfileWithScope[] = [];

  // Local profiles first
  if (localConfig) {
    for (const profile of Object.values(localConfig.profiles)) {
      result.push({
        ...profile,
        scope: "local",
        isDefault: profile.name === localConfig.defaultProfile,
      });
    }
  }

  // Global profiles (mark shadowed if local has same name)
  const localNames = localConfig ? new Set(Object.keys(localConfig.profiles)) : new Set<string>();

  for (const profile of Object.values(globalConfig.profiles)) {
    result.push({
      ...profile,
      scope: "global",
      isDefault: profile.name === globalConfig.defaultProfile,
      shadowed: localNames.has(profile.name),
    });
  }

  return result;
}

// ─── API Key Helpers ──────────────────────────────────────

/**
 * Get a stored API key from ~/.claudish/config.json
 */
export function getApiKey(envVar: string): string | undefined {
  const config = loadConfig();
  return config.apiKeys?.[envVar];
}

/**
 * Store an API key in ~/.claudish/config.json
 */
export function setApiKey(envVar: string, value: string): void {
  const config = loadConfig();
  if (!config.apiKeys) config.apiKeys = {};
  config.apiKeys[envVar] = value;
  saveConfig(config);
}

/**
 * Remove a stored API key from ~/.claudish/config.json
 */
export function removeApiKey(envVar: string): void {
  const config = loadConfig();
  if (config.apiKeys) {
    delete config.apiKeys[envVar];
    saveConfig(config);
  }
}

// ─── Keychain Helpers ─────────────────────────────────────

/**
 * Is the macOS Keychain backend in use on this machine?
 *
 * A cheap SYNC sniff, and the only thing standing between a user who has never
 * touched the keychain and a `security` spawn they do not need. Reads config
 * only — it never asks the keychain anything, which is the point.
 */
export function isKeychainEnabled(): boolean {
  try {
    return loadConfig().keychain?.enabled === true;
  } catch {
    return false;
  }
}

/**
 * Turn the keychain backend on or off in `~/.claudish/config.json`.
 *
 * Enabling does NOT move any secret; it only tells claudish the store is worth
 * consulting. Disabling likewise leaves stored items untouched — they simply
 * stop being read. Removing the secrets themselves is `claudish keychain rm`,
 * which is a separate and deliberately explicit act.
 */
export function setKeychainEnabled(enabled: boolean): void {
  const config = loadConfig();
  if (!config.keychain) config.keychain = {};
  config.keychain.enabled = enabled;
  saveConfig(config);
}

// ─── Endpoint Helpers ─────────────────────────────────────

/**
 * Get a stored custom endpoint URL from ~/.claudish/config.json
 */
export function getEndpoint(name: string): string | undefined {
  const config = loadConfig();
  return config.endpoints?.[name];
}

/**
 * Store a custom endpoint URL in ~/.claudish/config.json
 */
export function setEndpoint(name: string, value: string): void {
  const config = loadConfig();
  if (!config.endpoints) config.endpoints = {};
  config.endpoints[name] = value;
  saveConfig(config);
}

/**
 * Remove a stored custom endpoint from ~/.claudish/config.json
 */
export function removeEndpoint(name: string): void {
  const config = loadConfig();
  if (config.endpoints) {
    delete config.endpoints[name];
    saveConfig(config);
  }
}

// ─── Local Provider Helpers ─────────────────────────────────

/**
 * Check whether a built-in local provider is explicitly enabled in
 * ~/.claudish/config.json.
 */
export function isLocalProviderEnabled(
  providerName: string,
  config: { localProviders?: string[] } = loadConfig()
): boolean {
  return (config.localProviders ?? []).includes(providerName);
}

/**
 * Enable a built-in local provider in ~/.claudish/config.json.
 */
export function enableLocalProvider(providerName: string): void {
  const config = loadConfig();
  const providers = new Set(config.localProviders ?? []);
  providers.add(providerName);
  config.localProviders = Array.from(providers).sort();
  saveConfig(config);
}

/**
 * Disable a built-in local provider in ~/.claudish/config.json.
 */
export function disableLocalProvider(providerName: string): void {
  const config = loadConfig();
  const providers = new Set(config.localProviders ?? []);
  providers.delete(providerName);
  if (providers.size > 0) {
    config.localProviders = Array.from(providers).sort();
  } else {
    delete config.localProviders;
  }
  saveConfig(config);
}