amicus 4.1.2 → 4.2.0

package/scripts/postinstall.js

@@ -6,229 +6,30 @@
  * 1. Copies SKILL.md to ~/.claude/skills/sidecar/
  * 2. Registers MCP server in Claude Code (~/.claude.json)
  * 3. Registers MCP server in Claude Desktop/Cowork config
+ *
+ * The registration core (skill install, MCP registration, legacy migration)
+ * lives in src/utils/claude-register.js (Task 15, v4.2 §4.8/C2) so `amicus
+ * init` can re-run it on demand — this file is now a thin consumer that
+ * wires that core into the npm postinstall lifecycle (dev hooks, electron
+ * provisioning, and the top-level never-fail wrapper below).
  */
 
-const fs = require('fs');
 const path = require('path');
-const os = require('os');
 const { execFileSync } = require('child_process');
 
 const { repairElectron } = require('../src/sidecar/electron-install');
 const HINTS = require('../src/utils/remediation-hints');
-const { isAmicusMcpConfig } = require('../src/utils/mcp-self-identity');
+const reg = require('../src/utils/claude-register');
+const {
+  installSkill, installCouncilSkill, registerClaudeCode, registerClaudeDesktop,
+  migrateLegacyMcp, addMcpToConfigFile, COUNCIL_FILES,
+} = reg;
 
 const SETUP_HOOKS_SCRIPT = path.join(__dirname, 'setup-hooks.js');
 
 /** Short cache-only provision budget: a slow disk must never hang the install. */
 const PROVISION_TIMEOUT_MS = 15000;
 
-const SKILL_SOURCE = path.join(__dirname, '..', 'skills', 'sidecar', 'SKILL.md');
-const COUNCIL_SOURCE_DIR = path.join(__dirname, '..', 'skills', 'second-opinion');
-
-/** Council files + per-file install semantics: SKILL/COUNCIL-DESIGN/SEAT-BRIEFS are
- * product code (overwrite on update, so upgrades keep them in sync with the package);
- * MODEL-NOTES is user data — its reviewer-reliability table evolves per-run, so it is
- * seeded once and never clobbered. */
-const COUNCIL_FILES = [
-  { file: 'SKILL.md', mode: 'overwrite' },
-  { file: 'COUNCIL-DESIGN.md', mode: 'overwrite' },
-  { file: 'SEAT-BRIEFS.md', mode: 'overwrite' },
-  { file: 'MANUAL-ORCHESTRATION.md', mode: 'overwrite' },
-  { file: 'MODEL-NOTES.md', mode: 'if-missing' },
-];
-
-function skillsRoot() {
-  return path.join(os.homedir(), '.claude', 'skills');
-}
-
-const MCP_CONFIG = { command: 'npx', args: ['-y', 'amicus@latest', 'mcp'] };
-
-/**
- * Add or update an MCP server in a JSON config file.
- *
- * Refreshes command/args on every install/upgrade. If the EXISTING entry at
- * this key is already amicus-shaped (per isAmicusMcpConfig — Phase 1's single
- * source of truth for "this is amicus"), we MERGE instead of overwrite: the
- * user's `env` (and any other extra keys, e.g. a future `cwd`) survive the
- * refresh. Without this, `npm i -g amicus` silently wiped
- * "env": {"AMICUS_LEGACY_ALIASES":"1"} — the exact opt-in escape hatch Phase 4
- * tells users to add — on every upgrade.
- *
- * A NON-amicus-shaped entry at this key is overwritten as before: 'amicus' is
- * a reserved registration name, so a foreign entry there is reclaimed rather
- * than merged with.
- *
- * @param {string} configPath - Path to the JSON config file
- * @param {string} name - MCP server name
- * @param {object} config - MCP server config object
- * @returns {string} 'added', 'updated', or 'unchanged'
- */
-function addMcpToConfigFile(configPath, name, config) {
-  let existing = {};
-  try {
-    existing = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-  } catch {
-    // File doesn't exist or invalid JSON — start fresh
-  }
-
-  if (!existing.mcpServers) { existing.mcpServers = {}; }
-
-  const prev = existing.mcpServers[name];
-  const nextConfig = (prev && isAmicusMcpConfig(prev)) ? { ...prev, ...config } : config;
-  const status = !prev ? 'added' : JSON.stringify(prev) !== JSON.stringify(nextConfig) ? 'updated' : 'unchanged';
-
-  existing.mcpServers[name] = nextConfig;
-  if (status !== 'unchanged') {
-    const dir = path.dirname(configPath);
-    if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); }
-    fs.writeFileSync(configPath, JSON.stringify(existing, null, 2), { mode: 0o600 });
-  }
-  return status;
-}
-
-/** Install the chat skill to ~/.claude/skills/sidecar/ */
-function installSkill() {
-  try {
-    const destDir = path.join(skillsRoot(), 'sidecar');
-    fs.mkdirSync(destDir, { recursive: true });
-    fs.copyFileSync(SKILL_SOURCE, path.join(destDir, 'SKILL.md'));
-    console.log('[amicus] Chat skill installed to ~/.claude/skills/sidecar/');
-  } catch (err) {
-    console.error(`[amicus] Warning: Could not install chat skill: ${err.message}`);
-  }
-}
-
-/** Install the LLM Council skill to ~/.claude/skills/second-opinion/ */
-function installCouncilSkill(sourceDir = COUNCIL_SOURCE_DIR) {
-  const destDir = path.join(skillsRoot(), 'second-opinion');
-  try {
-    fs.mkdirSync(destDir, { recursive: true });
-  } catch (err) {
-    console.error(`[amicus] Warning: Could not create council skill dir: ${err.message}`);
-    return;
-  }
-  let failed = 0;
-  for (const { file, mode } of COUNCIL_FILES) {
-    try {
-      const dest = path.join(destDir, file);
-      if (mode === 'if-missing' && fs.existsSync(dest)) { continue; }
-      fs.copyFileSync(path.join(sourceDir, file), dest);
-    } catch (err) {
-      failed++;
-      console.error(`[amicus] Warning: Could not install council file ${file}: ${err.message}`);
-    }
-  }
-  if (failed === COUNCIL_FILES.length) {
-    console.error('[amicus] Warning: Council skill NOT installed (all files failed — see warnings above).');
-  } else if (failed > 0) {
-    console.log(`[amicus] Council skill partially installed (${failed}/${COUNCIL_FILES.length} files failed — see warnings above).`);
-  } else {
-    console.log('[amicus] Council skill installed to ~/.claude/skills/second-opinion/');
-  }
-}
-
-/**
- * Read the previous 'amicus' entry from ~/.claude.json, if any — used by the
- * CLI add-json path to merge env the same way the file-fallback path does.
- * Never throws: a missing/unreadable file just means "no previous entry".
- * @returns {object|undefined}
- */
-function readPrevClaudeCodeAmicusEntry() {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.claude.json'), 'utf-8'));
-    return parsed && parsed.mcpServers ? parsed.mcpServers.amicus : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/** Register MCP server in Claude Code config */
-function registerClaudeCode() {
-  // Try the CLI first
-  try {
-    // Merge the PREVIOUS registration's env into the add-json payload — same
-    // merge semantics as addMcpToConfigFile's file-fallback path (`{ ...prev,
-    // ...config }`: prev env keys survive, canonical MCP_CONFIG keys win on
-    // collision). Without this, a user's custom env (API key, AMICUS_* tuning
-    // knobs) on the old registration was silently dropped whenever the
-    // `claude` CLI was present, because the CLI path built its JSON payload
-    // from the bare MCP_CONFIG and delegated overwrite semantics to the
-    // claude binary — which has no idea about the user's previous entry.
-    const prev = readPrevClaudeCodeAmicusEntry();
-    const nextConfig = (prev && isAmicusMcpConfig(prev)) ? { ...prev, ...MCP_CONFIG } : MCP_CONFIG;
-    const mcpJson = JSON.stringify(nextConfig);
-    execFileSync('claude', ['mcp', 'add-json', 'amicus', mcpJson, '--scope', 'user'], {
-      stdio: 'pipe',
-      timeout: 10000,
-    });
-    console.log('[amicus] MCP registered in Claude Code (via CLI).');
-
-    return;
-  } catch {
-    // CLI not available or failed — fall back to file edit
-  }
-
-  // Fallback: direct file edit
-  const claudeConfigPath = path.join(os.homedir(), '.claude.json');
-  const status = addMcpToConfigFile(claudeConfigPath, 'amicus', MCP_CONFIG);
-  if (status === 'added') {
-    console.log('[amicus] MCP registered in Claude Code (~/.claude.json).');
-  } else if (status === 'updated') {
-    console.log('[amicus] MCP config updated in Claude Code (~/.claude.json).');
-  } else {
-    console.log('[amicus] MCP already registered in Claude Code.');
-  }
-}
-
-/** Register MCP server in Claude Desktop / Cowork config */
-function registerClaudeDesktop() {
-  let configDir;
-  if (process.platform === 'darwin') {
-    configDir = path.join(os.homedir(), 'Library', 'Application Support', 'Claude');
-  } else if (process.platform === 'win32') {
-    configDir = path.join(process.env.APPDATA || '', 'Claude');
-  } else {
-    configDir = path.join(os.homedir(), '.config', 'claude');
-  }
-
-  const configPath = path.join(configDir, 'claude_desktop_config.json');
-  const status = addMcpToConfigFile(configPath, 'amicus', MCP_CONFIG);
-  if (status === 'added') {
-    console.log('[amicus] MCP registered in Claude Desktop.');
-  } else if (status === 'updated') {
-    console.log('[amicus] MCP config updated in Claude Desktop.');
-  } else {
-    console.log('[amicus] MCP already registered in Claude Desktop.');
-  }
-}
-
-/**
- * One-shot migration: drop the duplicate legacy 'sidecar' MCP entry that
- * pre-1.8 postinstalls registered alongside 'amicus' (same server twice —
- * doubled the client-visible tool list). Only removes an entry whose command
- * is an amicus MCP invocation; a customized 'sidecar' entry is left alone.
- * Covers both files the three legacy registration paths wrote to:
- * ~/.claude.json (CLI + file fallback) and claude_desktop_config.json.
- * Never throws (postinstall must always exit 0).
- */
-function migrateLegacyMcp(deps = {}) {
-  try {
-    const impl = deps.migrateLegacySidecar
-      || require('../src/utils/legacy-mcp-migration').migrateLegacySidecar;
-    for (const r of impl()) {
-      if (r.result === 'removed') {
-        console.log(`[amicus] Removed duplicate legacy 'sidecar' MCP entry from ${r.target} (same server — kept as 'amicus').`);
-      } else if (r.result === 'customized') {
-        console.log(`[amicus] Kept custom 'sidecar' MCP entry in ${r.target} (does not point at amicus).`);
-      } else if (r.result === 'write-failed') {
-        console.warn(`[amicus] Warning: could not remove the legacy 'sidecar' MCP entry from ${r.target} — run: amicus doctor --fix`);
-      }
-    }
-  } catch (err) {
-    console.warn(`[amicus] Warning: legacy MCP cleanup skipped: ${err && err.message}`);
-  }
-}
-
 /**
  * NON-FATAL, CACHE-ONLY provisioning of the OPTIONAL electron binary (#57,
  * supersedes #30's warn-only verifyElectron). Electron is an optionalDependency:
@@ -333,7 +134,7 @@ function setupHooks(deps = {}) {
 
 async function main(deps = {}) {
   if (process.env.AMICUS_SKIP_POSTINSTALL === '1') {
-    console.log('[amicus] AMICUS_SKIP_POSTINSTALL set — skipping global setup (plugin channel handles registration).');
+    console.log('[amicus] AMICUS_SKIP_POSTINSTALL set — skipping global setup. Run `amicus init` to register skills + MCP on demand.');
     return;
   }
   const _installSkill = deps.installSkill || installSkill;

package/src/cli-handlers-doctor.js

@@ -7,6 +7,9 @@ const mcpChecks = require('./utils/doctor-mcp-checks');
 // engine-mcp check body — verifies the engine in the npx-cache copies the MCP
 // actually launches (bug report #1). Split out to keep this file under the gate.
 const engineCheck = require('./utils/doctor-engine-check');
+// local-providers check body (v4.2 §4.7 C8) — split out to keep this file
+// under the gate (mirrors the engineCheck/mcpChecks split above).
+const localProvidersCheck = require('./utils/doctor-local-providers-check');
 
 const MAX_CATALOG_AGE_MS = 24 * 60 * 60 * 1000; // 24h (mirrors model-catalog DEFAULT_MAX_AGE_MS)
 
@@ -58,6 +61,10 @@ function realDeps() {
     hasAmicusRegistration: () => require('./utils/mcp-discovery').hasAmicusRegistration(),
     inspectLegacyMcpEntries: () => require('./utils/legacy-mcp-migration').inspectAllLegacySidecarEntries(),
     migrateLegacyMcpEntries: () => require('./utils/legacy-mcp-migration').migrateLegacySidecar(),
+    // local-providers check (v4.2 §4.7 C8): both injectable so tests never
+    // fire a real network probe when a depsOverride omits them (M14).
+    getLocalProviders: () => require('./utils/local-providers').getLocalProviders(),
+    probeLocalProvider: (e, o) => require('./utils/local-probe').probeLocalProvider(e, o),
     skillInstalled: () => {
       const dir = path.join(os.homedir(), '.claude', 'skills');
       return fs.existsSync(path.join(dir, 'sidecar', 'SKILL.md'))
@@ -220,6 +227,11 @@ async function runDoctorChecks(depsOverride = {}) {
     return { id: 'openrouter-credit', name: 'OpenRouter credit', status: 'ok', message: `credit ok${remaining}`, hint: null };
   }));
 
+  // v4.2 §4.7 C8: configured local / OpenAI-compatible providers (Ollama, LM
+  // Studio, vLLM, generic) — reachability only; warn, never error (a napping
+  // `ollama serve` is not a doctor failure).
+  checks.push(await guardAsync('local-providers', 'Local providers', () => localProvidersCheck.evaluateLocalProviders(d)));
+
   // #43: project-root sanity — warns when cwd looks like an app/install dir or lacks project markers.
   checks.push(guard('project-root', 'Project root', () => {
     const dir = d.getCwd();

package/src/cli-handlers-init.js

@@ -0,0 +1,83 @@
+/**
+ * `amicus init [--claude] [--desktop] [--json]` (v4.2 §4.8, C2). Re-runs the
+ * SAME registration core `npm install`'s postinstall runs (src/utils/
+ * claude-register.js — Task 15's extraction), with per-step status and a
+ * compact doctor summary (Task 14's summarizeDoctor). Useful after a failed
+ * postinstall, for plugin-channel / --ignore-scripts installs (which set
+ * AMICUS_SKIP_POSTINSTALL), or to repair deleted ~/.claude state. Never does
+ * keys/model setup or engine/electron provisioning — that is `amicus setup` /
+ * `amicus doctor --fix`.
+ *
+ * DI-injected (mirrors cli-handlers-doctor.js / cli-handlers-provider.js) so
+ * it is unit-testable without ever touching a real Claude Code / Claude
+ * Desktop config file.
+ */
+'use strict';
+
+function realDeps() {
+  return {
+    reg: require('./utils/claude-register'),
+    runDoctorChecks: (o) => require('./cli-handlers-doctor').runDoctorChecks(o),
+    summarizeDoctor: (c) => require('./utils/doctor-summary').summarizeDoctor(c),
+    print: (l) => process.stdout.write(`${l}\n`),
+    emitJson: (o) => process.stdout.write(`${JSON.stringify(o, null, 2)}\n`),
+  };
+}
+
+/**
+ * Run one registration step, isolating a throw to just this step so the rest
+ * of `init` can still make progress — graceful degradation (a broken Claude
+ * Code registration must not skip an otherwise-working Claude Desktop one).
+ * @param {object} steps - mutated in place: steps[key] = status | 'failed: <msg>'
+ * @param {string} key
+ * @param {() => (string|void)} fn - returns a status string, or void for
+ *   fire-and-forget steps (skills/legacyMigration), which report 'done'. A
+ *   falsy return (including undefined, e.g. from a stale/incompatible dep)
+ *   also reports the honest 'done' fallback rather than fabricating a
+ *   specific added/updated/unchanged value it cannot back up.
+ * @returns {boolean} true if the step succeeded
+ */
+function runStep(steps, key, fn) {
+  try {
+    steps[key] = fn() || 'done';
+    return true;
+  } catch (e) {
+    steps[key] = `failed: ${e.message}`;
+    return false;
+  }
+}
+
+/**
+ * @param {{_:string[], claude?:boolean, desktop?:boolean, json?:boolean}} args
+ * @param {object} [deps] DI overrides (reg/runDoctorChecks/summarizeDoctor/print/emitJson)
+ * @returns {Promise<number>} exit code (0 ok, 1 a target genuinely failed)
+ */
+async function handleInit(args, deps = {}) {
+  const d = { ...realDeps(), ...deps };
+  const both = !args.claude && !args.desktop;
+  const steps = {};
+  let ok = true;
+
+  // Fire-and-forget: best-effort skill copy, reported as a single combined step.
+  ok = runStep(steps, 'skills', () => { d.reg.installSkill(); d.reg.installCouncilSkill(); }) && ok;
+  if (both || args.claude) { ok = runStep(steps, 'claudeCode', () => d.reg.registerClaudeCode()) && ok; }
+  if (both || args.desktop) { ok = runStep(steps, 'claudeDesktop', () => d.reg.registerClaudeDesktop()) && ok; }
+  ok = runStep(steps, 'legacyMigration', () => { d.reg.migrateLegacyMcp(); }) && ok;
+
+  // Guarded polish: a bug in the doctor check / summary formatting must never
+  // crash `init` itself — registration already happened above; the summary
+  // is a best-effort bonus tacked on at the end.
+  let summary = '';
+  try { summary = d.summarizeDoctor(await d.runDoctorChecks()); } catch { summary = ''; }
+
+  if (args.json) {
+    d.emitJson({ ok, steps, ...(summary ? { summary } : {}) });
+  } else {
+    for (const [k, v] of Object.entries(steps)) { d.print(`  ${k}: ${v}`); }
+    if (summary) { d.print(summary); }
+    if (!ok) { d.print('amicus init: one or more steps failed — see above'); }
+  }
+  return ok ? 0 : 1;
+}
+
+module.exports = { handleInit };

package/src/cli-handlers-key-local.js

@@ -0,0 +1,144 @@
+/**
+ * amicus key <localId> — bearer lifecycle for a config-defined local /
+ * OpenAI-compatible provider (v4.2 §4.6, Task 11). Split out of
+ * cli-handlers.js to keep that file under the 300-line gate (mirrors the
+ * cli-handlers-abort.js extraction). Local ids never touch PROVIDER_ENV_MAP
+ * or VALIDATION_ENDPOINTS — they're config-defined (local-providers.js) and
+ * validated with a bearer-attached reachability probe instead.
+ *
+ * Errors here write to stderr and RETURN rather than process.exit(1): the
+ * malformed-env-var case is exercised by a test that spies on
+ * process.stderr.write without mocking process.exit, and a real exit() call
+ * tears down the whole Jest worker (confirmed while TDD'ing this file — the
+ * pre-Task-11 "Unknown provider" path really does kill an unmocked test run).
+ */
+'use strict';
+
+/**
+ * Mask a raw secret the same way api-key-store's readApiKeyHints does: first
+ * 8 chars visible, the rest replaced with bullets. Never returns the full value.
+ * @param {string} key
+ * @returns {string}
+ */
+function maskKey(key) {
+  const visible = key.slice(0, 8);
+  return visible + '•'.repeat(Math.max(0, Math.min(key.length - 8, 12)));
+}
+
+/**
+ * Render the 'Local providers:' block appended to 'amicus key' (no-args list
+ * view). A provider with no apiKeyEnv needs no bearer at all; one with
+ * apiKeyEnv shows a masked hint (never the raw token) or 'not set'.
+ * @param {Object<string,object>} localProviders id -> normalized entry (getLocalProviders())
+ * @param {Map<string,string>} envEntries file-backed env values (api-key-store's loadEnvEntries())
+ * @returns {string[]} lines to print (empty when there are no local providers)
+ */
+function formatLocalKeyList(localProviders, envEntries) {
+  const ids = Object.keys(localProviders);
+  if (ids.length === 0) { return []; }
+  const lines = ['', 'Local providers:'];
+  for (const id of ids) {
+    const entry = localProviders[id];
+    let status;
+    if (!entry.apiKeyEnv) {
+      status = 'no key required';
+    } else {
+      const raw = envEntries.get(entry.apiKeyEnv) || process.env[entry.apiKeyEnv] || '';
+      status = raw ? `✓  ${maskKey(raw)}` : '✗  not set';
+    }
+    lines.push(`  ${id.padEnd(12)} ${status}`);
+  }
+  return lines;
+}
+
+/**
+ * amicus key <localId> [<token>|--remove]. Called only after the caller has
+ * already confirmed `provider` is an own key of getLocalProviders() (never a
+ * bare map[id] — a provider named 'constructor' must resolve to its real
+ * entry, not the inherited Object.prototype.constructor).
+ * @param {object} entry normalized local-provider entry (getLocalProviders()[provider])
+ * @param {string} provider the local id
+ * @param {object} args parsed CLI args (args._[2] = token, args.remove, args.json)
+ */
+async function handleLocalKey(entry, provider, args) {
+  const { saveRawEnv, removeRawEnv } = require('./utils/api-key-store');
+  const { deriveKeyEnv } = require('./utils/local-providers');
+  const envVar = entry.apiKeyEnv || deriveKeyEnv(provider);
+
+  if (args.remove) {
+    removeRawEnv(envVar);
+    // B3 (whole-branch review): clear the apiKeyEnv stamp too, not just the .env
+    // line, so --remove is symmetric with `amicus key <token>` (which stamps
+    // apiKeyEnv onto config.providers[id] the first time a bearer is added — see
+    // below). Leaving apiKeyEnv on config after the .env line is gone bricks the
+    // provider: gateway-router.js's resolveLocal treats
+    // `entry.apiKeyEnv && !entry.keyPresent` as a hard no_local_key error, so a
+    // provider that started keyless would never again resolve without the user
+    // re-adding a key or removing/re-adding the whole provider — "remove
+    // doesn't undo add". config.providers[id] has no field recording WHY
+    // apiKeyEnv is set (auto-stamped by `key <token>` vs. required via
+    // `provider add --bearer-env`), so this can't be done selectively; clearing
+    // it unconditionally is the safest, most predictable behavior — --remove
+    // fully reverts the provider to the no-auth state it was in before `amicus
+    // key <token>`. A user who wants the provider to require auth again can
+    // reconfigure it (`provider add --bearer-env` or another `amicus key <token>`).
+    const { loadConfig, saveConfig } = require('./utils/config');
+    const config = loadConfig() || {};
+    if (config.providers && Object.prototype.hasOwnProperty.call(config.providers, provider) &&
+        config.providers[provider].apiKeyEnv) {
+      delete config.providers[provider].apiKeyEnv;
+      saveConfig(config);
+    }
+    if (args.json) { process.stdout.write(`${JSON.stringify({ ok: true, removed: provider })}\n`); }
+    else { process.stdout.write(`Removed bearer for '${provider}'.\n`); }
+    return;
+  }
+
+  const token = args._[2];
+  if (!token) {
+    process.stderr.write(`This local provider needs a bearer token: amicus key ${provider} <token>\n`);
+    return;
+  }
+
+  // B2 (whole-branch review, security consistency): a bearer headed to a plain
+  // http:// non-loopback host travels in cleartext. `provider add` (doAdd) and
+  // the Electron save handler (ipc-setup-local.js) both warn about this; this
+  // surface never did. Reuse their exact-hostname check (not a new
+  // substring-based one) so 127.0.0.1.evil.com still correctly warns. Warn
+  // BEFORE the probe below, which is itself the first thing to send the token
+  // over the wire.
+  const { isPlaintextRemote } = require('./cli-handlers-provider');
+  if (isPlaintextRemote(entry.baseURL)) {
+    process.stderr.write('Warning: sending a bearer token over plain http:// to a non-loopback host transmits it in cleartext.\n');
+  }
+
+  const { probeLocalProvider } = require('./utils/local-probe');
+  const probe = await probeLocalProvider(entry, { timeoutMs: 2000, bearer: token });
+
+  // M12: saveRawEnv validates envVar against /^[A-Z][A-Z0-9_]*$/ and returns
+  // {success:false, error} WITHOUT throwing — bail BEFORE stamping apiKeyEnv
+  // onto config, mirroring the direct-vendor check in cli-handlers.js.
+  const saved = saveRawEnv(envVar, token);
+  if (saved && saved.success === false) {
+    process.stderr.write(`${saved.error}\n`);
+    return;
+  }
+
+  // If the entry had no apiKeyEnv yet, stamp it so buildProviderModels interpolates it.
+  if (!entry.apiKeyEnv) {
+    const { loadConfig, saveConfig } = require('./utils/config');
+    const config = loadConfig() || {};
+    if (config.providers && Object.prototype.hasOwnProperty.call(config.providers, provider)) {
+      config.providers[provider].apiKeyEnv = envVar;
+      saveConfig(config);
+    }
+  }
+
+  const msg = probe.status === 'ok'
+    ? `Bearer saved for '${provider}' (${probe.models.length} model(s) reachable).`
+    : `Bearer saved for '${provider}' (endpoint unreachable — check the server).`;
+  if (args.json) { process.stdout.write(`${JSON.stringify({ ok: true, provider, reachable: probe.status === 'ok' })}\n`); }
+  else { process.stdout.write(`${msg}\n`); }
+}
+
+module.exports = { handleLocalKey, formatLocalKeyList, maskKey };