fix(desktop): split Claude Code import into OAuth / API-key / proxy branches

Users who logged into Claude Code via OAuth (Pro/Max subscription) hit a
silent death path: clicking "Import from Claude Code" would set
activeProvider to claude-code-imported but store no key, so toState()
returned hasKey:false — yet the UI was already past onboarding and
surfaced the generic "Onboarding is not complete" when the user tried
to generate.

Root causes:
  1. parseClaudeCodeSettings only looked at settings.json env block,
     never at process.env or OAuth-evidence filesystem hints.
  2. runImportClaudeCode unconditionally flipped activeProvider to the
     imported id even when no key was available.
  3. No branching for the three practical Claude Code user types
     (OAuth subscription / API key / local proxy) — one banner, one
     import path, one outcome.

Changes:

- packages/shared/src/error-codes.ts
  New codes: CLAUDE_CODE_OAUTH_ONLY, PROVIDER_ACTIVE_MISSING_KEY.

- apps/desktop/src/main/imports/claude-code-config.ts
  Rewrite parser around a ClaudeCodeUserType classification:
    has-api-key | oauth-only | local-proxy | remote-gateway | no-config
  Falls back to process.env ANTHROPIC_{AUTH_TOKEN,API_KEY} when
  settings.json env block is empty. Adds checkClaudeCodeOAuthEvidence()
  (filesystem-only probe for ~/.claude/.credentials.json or
  ~/Library/Application Support/Claude/). Provider entry now always
  carries envKey: 'ANTHROPIC_AUTH_TOKEN' for runtime fallback.

- apps/desktop/src/main/onboarding-ipc.ts
  getApiKeyForProvider: if secret missing but entry.envKey is set,
  resolve from process.env before throwing. Rescues shell-env users who
  launch from terminal.
  runImportClaudeCode: oauth-only → throw CLAUDE_CODE_OAUTH_ONLY without
  touching config. no-key + non-oauth → create entry but preserve the
  existing activeProvider. This kills the death path.
  detect-external-configs: return richer meta (userType, baseUrl,
  hasApiKey, apiKeySource) so the renderer can render three banners.

- apps/desktop/src/renderer/src/components/Settings.tsx
  Branch the claudeCode banner on userType:
    oauth-only     → OAuthSubscriptionBanner with Console link + local
                     proxy CTA + dismiss
    has-api-key    → green import banner with source/baseUrl
    local-proxy    → neutral banner explaining proxy setup
    remote-gateway → neutral banner, "Import (needs key)" action
  handleImportClaudeCode catches CLAUDE_CODE_OAUTH_ONLY and shows the
  info-tone toast instead of the generic "import failed" error.

- apps/desktop/src/renderer/src/store.ts
  Replace the generic "Onboarding is not complete" with a specific
  "provider X has no key, open Settings" message when config.provider
  is set but hasKey:false.

- packages/i18n/src/locales/{en,zh-CN}.json
  New strings for the three banner variants, the OAuth CTAs, and the
  providerMissingKey error.

Tests:

- 12 new parseClaudeCodeSettings cases covering every userType.
- runImportClaudeCode tests for oauth-only throw, local-proxy no-activate,
  has-api-key activate.
- getApiKeyForProvider envKey fallback tests.
- Full suite: 414 desktop tests, all passing.

Author: hqhq1025

apps/desktop/src/main/imports/claude-code-config.test.ts

@@ -10,31 +10,93 @@ describe('parseClaudeCodeSettings', () => {
         ANTHROPIC_AUTH_TOKEN: 'sk-ant-test',
       },
     });
-    const out = parseClaudeCodeSettings(json);
+    const out = parseClaudeCodeSettings(json, { env: {} });
     expect(out.provider?.id).toBe('claude-code-imported');
     expect(out.provider?.wire).toBe('anthropic');
     expect(out.provider?.baseUrl).toBe('https://gateway.example.com');
     expect(out.provider?.defaultModel).toBe('claude-opus-4-1');
     expect(out.apiKey).toBe('sk-ant-test');
+    expect(out.apiKeySource).toBe('settings-json');
+    expect(out.userType).toBe('has-api-key');
   });
 
-  it('accepts ANTHROPIC_API_KEY as a fallback to ANTHROPIC_AUTH_TOKEN', () => {
+  it('accepts ANTHROPIC_API_KEY from settings.json as a fallback to ANTHROPIC_AUTH_TOKEN', () => {
     const json = JSON.stringify({ env: { ANTHROPIC_API_KEY: 'k' } });
-    const out = parseClaudeCodeSettings(json);
+    const out = parseClaudeCodeSettings(json, { env: {} });
     expect(out.apiKey).toBe('k');
+    expect(out.apiKeySource).toBe('settings-json');
+    expect(out.userType).toBe('has-api-key');
   });
 
-  it('warns when no key is present but still returns a provider', () => {
+  it('falls back to shell env ANTHROPIC_AUTH_TOKEN when settings.json has no key', () => {
     const json = JSON.stringify({ env: {} });
-    const out = parseClaudeCodeSettings(json);
-    expect(out.provider).not.toBeNull();
+    const out = parseClaudeCodeSettings(json, { env: { ANTHROPIC_AUTH_TOKEN: 'shell-key' } });
+    expect(out.apiKey).toBe('shell-key');
+    expect(out.apiKeySource).toBe('shell-env');
+    expect(out.userType).toBe('has-api-key');
+  });
+
+  it('attaches envKey: ANTHROPIC_AUTH_TOKEN on the provider for runtime fallback', () => {
+    const json = JSON.stringify({ env: { ANTHROPIC_AUTH_TOKEN: 'k' } });
+    const out = parseClaudeCodeSettings(json, { env: {} });
+    expect(out.provider?.envKey).toBe('ANTHROPIC_AUTH_TOKEN');
+  });
+
+  it('classifies no-key + localhost baseUrl as local-proxy', () => {
+    const json = JSON.stringify({ env: { ANTHROPIC_BASE_URL: 'http://localhost:8082' } });
+    const out = parseClaudeCodeSettings(json, { env: {} });
+    expect(out.userType).toBe('local-proxy');
+    expect(out.apiKey).toBeNull();
+    expect(out.provider?.baseUrl).toBe('http://localhost:8082');
+  });
+
+  it('classifies no-key + custom remote baseUrl as remote-gateway', () => {
+    const json = JSON.stringify({ env: { ANTHROPIC_BASE_URL: 'https://api.custom.example.com' } });
+    const out = parseClaudeCodeSettings(json, { env: {} });
+    expect(out.userType).toBe('remote-gateway');
+    expect(out.apiKey).toBeNull();
+  });
+
+  it('classifies no-key + OAuth evidence + default baseUrl as oauth-only and returns no provider', () => {
+    const json = JSON.stringify({ env: {} });
+    const out = parseClaudeCodeSettings(json, { env: {}, oauthEvidence: true });
+    expect(out.userType).toBe('oauth-only');
+    expect(out.provider).toBeNull();
+    expect(out.hasOAuthEvidence).toBe(true);
+  });
+
+  it('classifies no-key + no OAuth evidence + default baseUrl as no-config', () => {
+    const json = JSON.stringify({ env: {} });
+    const out = parseClaudeCodeSettings(json, { env: {}, oauthEvidence: false });
+    expect(out.userType).toBe('no-config');
+    expect(out.provider).toBeNull();
+  });
+
+  it('surfaces apiKeyHelper presence as a warning without executing it', () => {
+    const json = JSON.stringify({
+      env: { ANTHROPIC_BASE_URL: 'http://localhost:8082' },
+      apiKeyHelper: 'security find-generic-password -s anthropic -w',
+    });
+    const out = parseClaudeCodeSettings(json, { env: {} });
+    expect(out.warnings.join(' ')).toMatch(/apiKeyHelper/);
     expect(out.apiKey).toBeNull();
-    expect(out.warnings.join(' ')).toMatch(/manually/);
+  });
+
+  it('ignores an empty ANTHROPIC_AUTH_TOKEN string and falls through to env', () => {
+    const json = JSON.stringify({ env: { ANTHROPIC_AUTH_TOKEN: '   ' } });
+    const out = parseClaudeCodeSettings(json, { env: { ANTHROPIC_API_KEY: 'real' } });
+    expect(out.apiKey).toBe('real');
+    expect(out.apiKeySource).toBe('shell-env');
   });
 
   it('returns a warning on non-JSON input', () => {
-    const out = parseClaudeCodeSettings('{ bad json');
+    const out = parseClaudeCodeSettings('{ bad json', { env: {} });
     expect(out.provider).toBeNull();
     expect(out.warnings[0]).toMatch(/not valid JSON/);
   });
+
+  it('promotes malformed JSON with OAuth evidence to oauth-only so the banner still fires', () => {
+    const out = parseClaudeCodeSettings('{ bad json', { env: {}, oauthEvidence: true });
+    expect(out.userType).toBe('oauth-only');
+  });
 });

apps/desktop/src/main/imports/claude-code-config.ts

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { access, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { ProviderEntry } from '@open-codesign/shared';
@@ -7,21 +7,84 @@ export function claudeCodeSettingsPath(home: string = homedir()): string {
   return join(home, '.claude', 'settings.json');
 }
 
+/**
+ * Coarse classification of the Claude Code user we just scanned. Drives
+ * which banner the Settings UI shows (subscription warning vs. one-click
+ * import vs. manual-finish-required) and which import path we take.
+ *
+ * The app cannot reuse an OAuth subscription — Anthropic binds the token
+ * to the Claude Code client, and refreshing it requires that client's
+ * embedded OAuth ID. So `oauth-only` is a terminal "please get an API
+ * key" state, not a failure we can code around.
+ */
+export type ClaudeCodeUserType =
+  /** settings.json or shell env exposes a real ANTHROPIC_* key we can use. */
+  | 'has-api-key'
+  /** No key anywhere, and filesystem evidence suggests the user logs in via OAuth. */
+  | 'oauth-only'
+  /** baseUrl points at localhost — typical Claude Code Proxy / LiteLLM setup. */
+  | 'local-proxy'
+  /** baseUrl points at a non-anthropic remote endpoint, but no key was found. */
+  | 'remote-gateway'
+  /** No settings.json, no OAuth evidence — nothing to offer. */
+  | 'no-config';
+
 export interface ClaudeCodeImport {
   provider: ProviderEntry | null;
-  /** The API key pulled from env (if ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY
-   * was inlined in settings.json). */
   apiKey: string | null;
+  apiKeySource: 'settings-json' | 'shell-env' | 'none';
+  userType: ClaudeCodeUserType;
+  hasOAuthEvidence: boolean;
   activeModel: string | null;
   warnings: string[];
 }
 
 type ClaudeCodeSettings = {
   env?: Record<string, string>;
+  apiKeyHelper?: string;
 };
 
-export function parseClaudeCodeSettings(json: string): ClaudeCodeImport {
+export interface ParseClaudeCodeOptions {
+  /** Defaults to `process.env`. Tests can inject a stub. */
+  env?: NodeJS.ProcessEnv;
+  /** Defaults to the result of `checkClaudeCodeOAuthEvidence()`. */
+  oauthEvidence?: boolean;
+}
+
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '::1']);
+
+function baseUrlHost(url: string): string | null {
+  try {
+    return new URL(url).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function classifyUserType(args: {
+  apiKeySource: 'settings-json' | 'shell-env' | 'none';
+  baseUrl: string;
+  oauthEvidence: boolean;
+}): ClaudeCodeUserType {
+  if (args.apiKeySource !== 'none') return 'has-api-key';
+  const host = baseUrlHost(args.baseUrl);
+  if (host !== null && LOCAL_HOSTS.has(host)) return 'local-proxy';
+  if (args.oauthEvidence) return 'oauth-only';
+  if (host !== null && host !== 'api.anthropic.com') return 'remote-gateway';
+  // Default Anthropic endpoint, no key, no OAuth evidence — treat as no-config
+  // rather than oauth-only so we don't nag users who happen to have a stray
+  // settings.json without a key.
+  return 'no-config';
+}
+
+export function parseClaudeCodeSettings(
+  json: string,
+  options: ParseClaudeCodeOptions = {},
+): ClaudeCodeImport {
+  const env = options.env ?? process.env;
+  const oauthEvidence = options.oauthEvidence ?? false;
   const warnings: string[] = [];
+
   let parsed: unknown;
   try {
     parsed = JSON.parse(json);
@@ -30,6 +93,9 @@ export function parseClaudeCodeSettings(json: string): ClaudeCodeImport {
     return {
       provider: null,
       apiKey: null,
+      apiKeySource: 'none',
+      userType: oauthEvidence ? 'oauth-only' : 'no-config',
+      hasOAuthEvidence: oauthEvidence,
       activeModel: null,
       warnings: [`Claude Code settings.json is not valid JSON: ${msg}`],
     };
@@ -38,16 +104,72 @@ export function parseClaudeCodeSettings(json: string): ClaudeCodeImport {
     return {
       provider: null,
       apiKey: null,
+      apiKeySource: 'none',
+      userType: oauthEvidence ? 'oauth-only' : 'no-config',
+      hasOAuthEvidence: oauthEvidence,
       activeModel: null,
       warnings: ['Claude Code settings.json has unexpected shape'],
     };
   }
 
   const settings = parsed as ClaudeCodeSettings;
-  const env = settings.env ?? {};
-  const baseUrl = env['ANTHROPIC_BASE_URL'] ?? 'https://api.anthropic.com';
-  const model = env['ANTHROPIC_MODEL'] ?? 'claude-sonnet-4-6';
-  const apiKey = env['ANTHROPIC_AUTH_TOKEN'] ?? env['ANTHROPIC_API_KEY'] ?? null;
+  const settingsEnv = settings.env ?? {};
+  const baseUrl = settingsEnv['ANTHROPIC_BASE_URL'] ?? 'https://api.anthropic.com';
+  const model = settingsEnv['ANTHROPIC_MODEL'] ?? 'claude-sonnet-4-6';
+
+  // Resolve the API key in priority order: settings.json first (explicit
+  // per-project config), shell env second (user exported globally). Note
+  // that Electron inherits shell env only when launched from a terminal —
+  // GUI launches on macOS will have a sparse process.env.
+  let apiKey: string | null = null;
+  let apiKeySource: 'settings-json' | 'shell-env' | 'none' = 'none';
+  const settingsToken = settingsEnv['ANTHROPIC_AUTH_TOKEN'] ?? settingsEnv['ANTHROPIC_API_KEY'];
+  if (typeof settingsToken === 'string' && settingsToken.trim().length > 0) {
+    apiKey = settingsToken.trim();
+    apiKeySource = 'settings-json';
+  } else {
+    const shellToken = env['ANTHROPIC_AUTH_TOKEN'] ?? env['ANTHROPIC_API_KEY'];
+    if (typeof shellToken === 'string' && shellToken.trim().length > 0) {
+      apiKey = shellToken.trim();
+      apiKeySource = 'shell-env';
+    }
+  }
+
+  if (apiKey === null && typeof settings.apiKeyHelper === 'string' && settings.apiKeyHelper.length > 0) {
+    warnings.push(
+      `Claude Code settings.json defines apiKeyHelper ("${settings.apiKeyHelper}"). ` +
+        'Open CoDesign does not execute helper scripts — please paste a key manually, ' +
+        'or export ANTHROPIC_API_KEY in your shell before launching from terminal.',
+    );
+  }
+
+  const userType = classifyUserType({ apiKeySource, baseUrl, oauthEvidence });
+
+  // For oauth-only users we deliberately return provider=null: there's no
+  // config worth saving, and the caller treats provider===null as "nothing
+  // to import" so Settings never seeds a zombie entry.
+  if (userType === 'oauth-only') {
+    return {
+      provider: null,
+      apiKey: null,
+      apiKeySource: 'none',
+      userType,
+      hasOAuthEvidence: oauthEvidence,
+      activeModel: null,
+      warnings,
+    };
+  }
+  if (userType === 'no-config') {
+    return {
+      provider: null,
+      apiKey: null,
+      apiKeySource: 'none',
+      userType,
+      hasOAuthEvidence: oauthEvidence,
+      activeModel: null,
+      warnings,
+    };
+  }
 
   const provider: ProviderEntry = {
     id: 'claude-code-imported',
@@ -56,32 +178,84 @@ export function parseClaudeCodeSettings(json: string): ClaudeCodeImport {
     wire: 'anthropic',
     baseUrl,
     defaultModel: model,
+    // Always attach the env key hint. Runtime `getApiKeyForProvider` uses
+    // it as a last-resort fallback: if the stored secret gets wiped or the
+    // user exports the token after import, we still resolve it without a
+    // round-trip through onboarding.
+    envKey: 'ANTHROPIC_AUTH_TOKEN',
     // Claude Code proxies commonly gate reasoning effort by plan — the
     // consumer-tier endpoint accepts only 'medium'. Seed this default so
     // imports just work; higher-tier users can raise it in Settings →
     // Providers → Reasoning depth.
     reasoningLevel: 'medium',
   };
 
-  if (apiKey === null) {
+  if (apiKey === null && userType !== 'local-proxy' && userType !== 'remote-gateway') {
     warnings.push(
-      'Claude Code settings.json did not inline ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY — you will need to paste the key manually.',
+      'Claude Code settings.json did not inline ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY — ' +
+        'paste the key manually, or export it in your shell and relaunch from terminal.',
     );
   }
 
-  return { provider, apiKey, activeModel: model, warnings };
+  return {
+    provider,
+    apiKey,
+    apiKeySource,
+    userType,
+    hasOAuthEvidence: oauthEvidence,
+    activeModel: model,
+    warnings,
+  };
+}
+
+/**
+ * Best-effort probe for evidence that the user logs into Claude Code via
+ * OAuth. We look at the filesystem only — `security find-generic-password`
+ * would cover the macOS Keychain case but invoking shell from the main
+ * process for classification feels heavier than the 5% extra accuracy buys.
+ * False negatives (OAuth user with neither path present) fall through to
+ * `no-config` and see no banner, which is safer than nagging.
+ */
+export async function checkClaudeCodeOAuthEvidence(home: string = homedir()): Promise<boolean> {
+  const candidates = [
+    join(home, '.claude', '.credentials.json'),
+    join(home, 'Library', 'Application Support', 'Claude'),
+  ];
+  for (const path of candidates) {
+    try {
+      await access(path);
+      return true;
+    } catch {
+      /* not present, keep trying */
+    }
+  }
+  return false;
 }
 
 export async function readClaudeCodeSettings(
   home: string = homedir(),
 ): Promise<ClaudeCodeImport | null> {
   const path = claudeCodeSettingsPath(home);
+  const oauthEvidence = await checkClaudeCodeOAuthEvidence(home);
+
   let raw: string;
   try {
     raw = await readFile(path, 'utf8');
   } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
-    throw err;
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    // settings.json absent. If OAuth evidence is present, synthesize a
+    // minimal ClaudeCodeImport so the Settings banner still offers the
+    // subscription-user guidance — otherwise return null and stay silent.
+    if (!oauthEvidence) return null;
+    return {
+      provider: null,
+      apiKey: null,
+      apiKeySource: 'none',
+      userType: 'oauth-only',
+      hasOAuthEvidence: true,
+      activeModel: null,
+      warnings: [],
+    };
   }
-  return parseClaudeCodeSettings(raw);
+  return parseClaudeCodeSettings(raw, { oauthEvidence });
 }