feat: refactor config system to centralize model d

Author: sudoeren

AGENTS.md

@@ -19,15 +19,15 @@ Verification order: `npm run lint` then `npm test`.
 ## Architecture
 
 - `src/index.js` — single entrypoint. `commander` CLI, defines subcommands + aliases (`c`=commit, `e`=easy, `st`=status, `p`=push, `t`=story, `s`=start, `pv`=provider, `m`=model). UI modules are **lazy-loaded** via `app()`/`require()` to keep startup fast — don't eagerly require UI modules at the top of index.js.
-- `src/helpers/` — pure logic: `git.js` (wraps `simple-git`), `ai.js` (provider HTTP via axios), `config.js` (config + saved AI connections), `patch.js`.
+- `src/helpers/` — pure logic: `git.js` (wraps `simple-git`), `ai.js` (provider HTTP via axios), `config.js` (config + saved AI connections + legacy migration), `providers.js` (single provider registry: labels, credential fields, model keys, defaults, model-fetch dispatch), `patch.js`.
 - `src/ui/` — all interaction: `app.js` (main menu loop), `common.js` (styles `s.*`, `clear`, `header`), `screen.js` (inquirer prompts, `spinner`/`done`/`fail`), `diff-view.js`.
 - `src/ui/modules/` — one file per feature, each exporting `doXxx(info)` for the menu flow plus smaller helpers. Follow this pattern for new features; keep git/AI logic in `helpers/`.
 
 ## Gotchas
 
 - **Module-level caches**: `helpers/config.js` caches config (`getConfig` returns the same object), `helpers/git.js` caches the simple-git instance, `helpers/ai.js` caches provider connection status. Tests must call `resetConfigCache()` / `resetGitCache()` / `resetAIConnectionCache()` in `beforeEach` (existing tests do this).
 - **Config precedence**: defaults ← `~/.eckra/config.json` ← active saved AI connection (`aiConnections` map, resolved in `getConfig`) ← repo-local `.eckrarc` (searched up the directory tree) ← `ECKRA_*` env vars. `.eckrarc` is gitignored because it can hold API keys. Global config is written with `0600` permissions — keep that security behavior.
-- **Saved AI connections**: multiple provider credentials (per provider and per account) live in the global config under `aiConnections`; `activeAiConnection` selects one. Manage them only via the dedicated helpers (`saveAIConnection`, `setActiveAIConnection`, …) or `eckra provider` — the raw `aiConnections` key is excluded from `eckra config set/unset` (`MANAGED_CONFIG_KEYS`). When a connection is active, provider settings/model changes must be written back into it, not to the flat keys (see `saveProviderSettings` in `ui/modules/settings.js`).
+- **Connections-first AI settings**: all provider credentials/models live as named connections in the global config under `aiConnections`; `activeAiConnection` selects one (resolution: explicit → `default` → first alphabetical — see `resolveActiveConnectionName` in `helpers/config.js`). Setup writes a `default` connection; legacy flat keys (`openaiApiKey`, …) are auto-copied into it once by `migrateLegacyToDefaultIfNeeded` (flat keys stay on disk for downgrade safety). All provider metadata (labels, key fields, model keys, model fetching) comes from `src/helpers/providers.js` — add new providers there, not as switches. UI exposes only **Switch** and **Manage** (`manageProvidersMenu` + shared `connectionWizard`). `eckra config set/unset` rejects provider-managed keys (`PROVIDER_MANAGED_KEYS`) with guidance to use `eckra provider`.
 - **Provider URLs**: `lmStudioUrl` / `ollamaUrl` are normalized (trailing slashes stripped) in `getConfig` so downstream path concatenation doesn't double up `/`.
 - **Conventional commits**: AI-generated messages follow `type: subject` style; keep new commit messages consistent with the repo history (`feat:`, `fix:`, `refactor:`, `docs:`…).
 - `.eckrarc`, `.eckra/`, `docs/`, `*.log` are gitignored.

README.md

@@ -77,7 +77,7 @@ Or jump straight into action:
 | `eckra doctor`  | `dr`  | Health check                  |
 | `eckra suggest` | `sg`  | Print an AI commit message    |
 | `eckra setup`   |       | Run the setup/onboarding wizard |
-| `eckra model`   | `m`   | Show current AI settings & change model/provider/connection |
+| `eckra model`   | `m`   | Show current AI settings & switch/manage providers |
 
 > [!TIP]
 > `eckra e` stages everything, generates an AI message, and asks you before committing and pushing.
@@ -190,30 +190,32 @@ ollama pull qwen3.5:2b
 | `Amazon Bedrock`          | Bedrock API key + AWS Region (`bedrock-runtime` endpoint)    | `us.anthropic.claude-haiku-4-5` |
 | `Amazon Bedrock Mantle`   | Bedrock API key + AWS Region (`bedrock-mantle` endpoint)     | `us.anthropic.claude-haiku-4-5` |
 
-Providers are configured via the settings menu (`More > Settings`) or `~/.eckra/config.json`. eckra fetches the available models for you — run `eckra model` to see your current AI settings (provider, connection, model, masked API key) and where they're stored, then change the model, re-configure the provider, or switch saved connections from the same menu. The same actions live in Settings.
+Providers are configured during setup and stored as **named connections** in `~/.eckra/config.json`. The configuration you pick during `eckra setup` becomes your `default` connection. eckra fetches the available models for you — run `eckra model` to see your current AI settings (provider, connection, model, masked API key) and where they're stored, then switch or manage providers from the same menu.
 
 ### Saved connections (multiple providers & accounts)
 
-eckra can store several provider configurations at once — different providers and/or multiple accounts for the same provider (e.g. a work and a personal OpenAI key). One connection is active at a time and every AI call uses it.
+eckra stores several provider configurations side by side — different providers and/or multiple accounts for the same provider (e.g. a work and a personal OpenAI key). One connection is active at a time and every AI call uses it. With no explicit choice, eckra falls back to the `default` connection.
 
-After configuring a provider in **More > Settings**, eckra offers to save it as a named connection. You can also add one directly, then switch anytime:
+The AI surfaces expose exactly two actions — **Switch Provider / Account** (pick an existing connection) and **Manage Providers** (everything else: add, edit credentials/model per connection, rename, delete). They live in the Settings menu and behind `eckra model`:
 
 ```bash
 eckra provider list              # All saved connections, active marked with ✓
-eckra provider add               # Interactive: provider → key → model → name
+eckra provider add               # Interactive wizard: provider → key → model → name
 eckra provider add --name work --provider openai \
   --set openaiApiKey=sk-... openaiModel=gpt-5-mini --use   # Non-interactive
+eckra provider edit work         # Wizard: fix the API key or change the model
 eckra provider use work          # Switch globally
 eckra provider use home --local  # Pin a connection to this repo only (.eckrarc)
 eckra provider show work         # Details (secrets masked)
 eckra provider rename work is    # Rename (stays active if it was)
 eckra provider remove work -y    # Delete
 ```
 
-The same actions live in the settings menu under **Switch Provider / Account** and **Manage Saved Providers**.
+> [!NOTE]
+> Upgrading from an older eckra? Your existing flat settings are migrated automatically into a `default` connection on first run — nothing to do. The old keys stay in the file for downgrade safety but are no longer used.
 
 > [!NOTE]
-> The active connection can also be set per environment with `ECKRA_ACTIVE_AI_CONNECTION`, or per repository via `.eckrarc` (`eckra config set activeAiConnection <name> --local`). With no active connection, eckra falls back to your base settings.
+> The active connection can also be set per environment with `ECKRA_ACTIVE_AI_CONNECTION`, or per repository via `.eckrarc` (`eckra config set activeAiConnection <name> --local`).
 
 > [!NOTE]
 > Per-repository overrides go in `.eckrarc` (gitignored, as it can hold API keys).
@@ -234,7 +236,7 @@ eckra config path               # Config file path
 > [!NOTE]
 > Add `--local` to target the project's `.eckrarc` instead.
 
-A few useful keys: `commitType` (commit message format), `subjectMaxLength` (max subject characters, default 50), `locale` (language for messages, default `en`), `timeout` (AI request timeout in ms, default 30000), and `activeAiConnection` (the saved connection in use). Saved connections themselves live under the `aiConnections` key — manage them with `eckra provider`, not `eckra config set`.
+A few useful keys: `commitType` (commit message format), `subjectMaxLength` (max subject characters, default 50), `locale` (language for messages, default `en`), `timeout` (AI request timeout in ms, default 30000), and `activeAiConnection` (the saved connection in use). Provider credentials and models live inside named connections — manage them with `eckra provider` / `eckra model`, not `eckra config set` (which now rejects those keys with guidance).
 
 ### Health check
 

src/helpers/config.js

@@ -45,36 +45,18 @@ const DEFAULT_CONFIG = {
     "Use concise, present tense, and descriptive language. Focus on the 'why' of the changes.",
 };
 
-/**
- * Field names each provider may store inside a saved AI connection.
- * Single source of truth for validating `saveAIConnection` input.
- */
-const PROVIDER_FIELDS = {
-  lmstudio: ["lmStudioUrl", "model"],
-  ollama: ["ollamaUrl", "ollamaModel"],
-  openai: ["openaiApiKey", "openaiModel"],
-  anthropic: ["anthropicApiKey", "anthropicModel"],
-  openrouter: ["openrouterApiKey", "openrouterModel"],
-  gemini: ["geminiApiKey", "geminiModel"],
-  opencodego: ["opencodeGoApiKey", "opencodeGoModel"],
-  deepseek: ["deepseekApiKey", "deepseekModel"],
-  bedrock: ["bedrockApiKey", "bedrockRegion", "bedrockModel"],
-  bedrockmantle: [
-    "bedrockMantleApiKey",
-    "bedrockMantleRegion",
-    "bedrockMantleModel",
-  ],
-  ollamacloud: ["ollamaCloudApiKey", "ollamaCloudModel"],
-};
-
-const AI_PROVIDERS = Object.keys(PROVIDER_FIELDS);
+const { PROVIDER_FIELDS, AI_PROVIDERS } = require("./providers");
 
 /**
  * Config keys managed through dedicated commands (`eckra provider`) rather
  * than `eckra config set` — raw maps are unsafe to edit as CLI strings.
  */
 const MANAGED_CONFIG_KEYS = ["aiConnections"];
 
+const PROVIDER_MANAGED_KEYS = [
+  ...new Set(Object.values(PROVIDER_FIELDS).flat()),
+];
+
 /**
  * Ensure config directory exists
  */
@@ -134,6 +116,74 @@ function findLocalConfig(startDir = process.cwd()) {
 
 let _cachedConfig = null;
 
+/**
+ * Active connection resolution:
+ * 1. The explicitly active name (precedence: local file > env var > global file)
+ * 2. If that name is missing/empty and a `default` connection exists, use it
+ * 3. Otherwise the first connection sorted alphabetically (if any)
+ */
+function resolveActiveConnectionName(
+  rawActiveName,
+  connections,
+  localRaw,
+  envOverrides,
+  globalRaw
+) {
+  if (typeof rawActiveName === "string" && rawActiveName.trim()) {
+    return rawActiveName.trim();
+  }
+  const map =
+    connections ||
+    (globalRaw.aiConnections && typeof globalRaw.aiConnections === "object"
+      ? globalRaw.aiConnections
+      : {});
+  const names = Object.keys(map);
+  if (names.includes("default")) return "default";
+  if (names.length > 0)
+    return names.slice().sort((a, b) => a.localeCompare(b))[0];
+  return "";
+}
+
+/**
+ * Connections-first migration: legacy flat provider fields (e.g.
+ * `openaiApiKey`) are copied into a `default` connection exactly once.
+ * The flat keys are kept on disk for downgrade safety — only copied, not
+ * removed. Returns true when a migration was written.
+ */
+function migrateLegacyToDefaultIfNeeded(raw) {
+  const existing = raw.aiConnections;
+  const hasConnections =
+    existing &&
+    typeof existing === "object" &&
+    Object.keys(existing).length > 0;
+  if (hasConnections) return false;
+
+  const provider = raw.aiProvider || DEFAULT_CONFIG.aiProvider;
+  const fields = PROVIDER_FIELDS[provider];
+  if (!fields) return false;
+
+  const hasLegacyValue = PROVIDER_MANAGED_KEYS.some(
+    (k) => raw[k] !== undefined && raw[k] !== "" && raw[k] !== null
+  );
+  if (!hasLegacyValue) return false;
+
+  const entry = { provider };
+  for (const field of fields) {
+    const value = raw[field];
+    if (value !== undefined && value !== null && value !== "") {
+      entry[field] = value;
+    }
+  }
+  if (Object.keys(entry).length <= 1) return false; // provider only, nothing to save
+
+  raw.aiConnections = { default: entry };
+  if (!raw.activeAiConnection) raw.activeAiConnection = "default";
+  try {
+    writeConfigFile(JSON.stringify(raw, null, 2));
+  } catch {}
+  return true;
+}
+
 const ENV_PREFIX = "ECKRA_";
 
 /**
@@ -195,6 +245,14 @@ function getConfig() {
     }
   }
 
+  // 1b. Connections-first migration (legacy flat keys → `default` connection, once)
+  if (Object.keys(globalRaw).length > 0) {
+    const didMigrate = migrateLegacyToDefaultIfNeeded(globalRaw);
+    if (didMigrate) {
+      config = { ...config, ...globalRaw };
+    }
+  }
+
   // 2. Local config raw (read once; applied after the active connection)
   let localRaw = {};
   const localConfigPath = findLocalConfig();
@@ -216,22 +274,30 @@ function getConfig() {
   const envOverrides = getEnvConfig();
 
   // 4. Active saved AI connection. The name resolves as
-  // .eckrarc > ECKRA_ACTIVE_AI_CONNECTION > global config; its fields are
-  // merged over the global values but stay weaker than local/env overrides.
+  // .eckrarc > ECKRA_ACTIVE_AI_CONNECTION > global config, falling back to
+  // `default` and then the first alphabetical connection when unset.
   const hasLocalActive = Object.prototype.hasOwnProperty.call(
     localRaw,
     "activeAiConnection"
   );
-  const activeName = hasLocalActive
+  const rawActiveName = hasLocalActive
     ? localRaw.activeAiConnection
     : envOverrides.activeAiConnection !== undefined
       ? envOverrides.activeAiConnection
       : globalRaw.activeAiConnection;
+  const _connectionsForActive =
+    globalRaw.aiConnections && typeof globalRaw.aiConnections === "object"
+      ? globalRaw.aiConnections
+      : {};
+  const activeName = resolveActiveConnectionName(
+    rawActiveName,
+    _connectionsForActive,
+    localRaw,
+    envOverrides,
+    globalRaw
+  );
   if (typeof activeName === "string" && activeName) {
-    const connections =
-      globalRaw.aiConnections && typeof globalRaw.aiConnections === "object"
-        ? globalRaw.aiConnections
-        : {};
+    const connections = _connectionsForActive;
     const connection = connections[activeName];
     if (
       connection &&
@@ -319,13 +385,22 @@ function getRawConfig({ local = false } = {}) {
 }
 
 /**
- * Whether `key` is a known config key (typo protection for set/unset)
+ * Whether `key` is a provider-managed field (stored inside a connection).
+ */
+function isProviderManagedKey(key) {
+  return PROVIDER_MANAGED_KEYS.includes(key);
+}
+
+/**
+ * Whether `key` is a known config key (typo protection for set/unset).
+ * Provider-managed fields are not settable via `eckra config set`.
  */
 function isValidConfigKey(key) {
   return (
     typeof key === "string" &&
     Object.prototype.hasOwnProperty.call(DEFAULT_CONFIG, key) &&
-    !MANAGED_CONFIG_KEYS.includes(key)
+    !MANAGED_CONFIG_KEYS.includes(key) &&
+    !PROVIDER_MANAGED_KEYS.includes(key)
   );
 }
 
@@ -345,9 +420,20 @@ function maskSecret(value) {
  * into the target file. Invalidates the in-memory config cache.
  */
 function setConfigValue(key, value, { local = false } = {}) {
+  if (isProviderManagedKey(key)) {
+    throw new Error(
+      `"${key}" is managed by your connections — use \`eckra provider edit <name>\` or run \`eckra setup\`. See \`eckra provider list\`.`
+    );
+  }
+  if (MANAGED_CONFIG_KEYS.includes(key)) {
+    throw new Error(
+      `"${key}" is managed internally — use \`eckra provider\` to manage connections.`
+    );
+  }
   if (!isValidConfigKey(key)) {
     const validKeys = Object.keys(DEFAULT_CONFIG).filter(
-      (k) => !MANAGED_CONFIG_KEYS.includes(k)
+      (k) =>
+        !MANAGED_CONFIG_KEYS.includes(k) && !PROVIDER_MANAGED_KEYS.includes(k)
     );
     throw new Error(
       `Unknown config key: "${key}". Valid keys: ${validKeys.join(", ")}`
@@ -574,6 +660,10 @@ module.exports = {
   PROVIDER_FIELDS,
   AI_PROVIDERS,
   MANAGED_CONFIG_KEYS,
+  PROVIDER_MANAGED_KEYS,
+  isProviderManagedKey,
+  resolveActiveConnectionName,
+  migrateLegacyToDefaultIfNeeded,
   normalizeUrl,
   envVarName,
   getEnvConfig,