feat(settings): auto-detect running CLIProxyAPI and show import banner (#190)

## Summary

Follow-up to #178 (CLIProxyAPI preset). When Settings > Models mounts,
probe `http://127.0.0.1:8317/v1/models` — if CPA is running locally and
not yet configured, show a one-click Import banner at the top of the
provider list.

Pattern borrowed from EasyCLI (official CPA GUI) and ProxyPal (1k★
SolidJS+Tauri wrapper). Both show the running CPA prominently on first
load; users click once and are done.

## Flow

1. Models tab mounts → `useEffect` fires once
2. Skip if localStorage `cpa-detection-dismissed-v1` is set or any
existing provider points at `localhost:8317`
3. Call `window.codesign.config.testEndpoint({ wire: 'anthropic',
baseUrl: 'http://127.0.0.1:8317', apiKey: '' })` — CPA has wildcard CORS
+ the IPC bridges through main process anyway
4. On success, render `LocalCpaImportCard` (Zap icon + title + body +
Import/Dismiss buttons)
5. "Import" reuses existing `customProviderPreset` state →
`AddCustomProviderModal` pre-filled with CPA preset. Modal's
auto-discovery fills defaultModel. User clicks Save. Done.

## Test plan

- [ ] `pnpm typecheck` green
- [ ] `pnpm lint` green
- [ ] Manual: install + run CPA → open Settings → see banner
- [ ] Manual: click Import → modal opens with preset → save → banner
disappears and does not reappear
- [ ] Manual: click Dismiss → banner disappears and does not reappear on
subsequent Settings opens
- [ ] Manual: no CPA running → no banner (silent failure)

## PR chain

Depends on #178. Base is `feat/cpa-preset` so the diff stays focused on
this change. Will rebase to `main` after #178 merges.

---------

Signed-off-by: hqhq1025 <1506751656@qq.com>
Co-authored-by: Sun-sunshine06 <Sun-sunshine06@users.noreply.github.com>

Author: hqhq1025

.changeset/cpa-autodetect.md

@@ -0,0 +1,8 @@
+---
+'@open-codesign/desktop': patch
+'@open-codesign/i18n': patch
+---
+
+feat(settings): auto-detect running CLIProxyAPI and show import banner
+
+When the Models tab mounts, probes `http://127.0.0.1:8317/v1/models` via the existing `testEndpoint` IPC bridge. If CLIProxyAPI is running and no provider is already configured at that address, displays a `LocalCpaImportCard` banner above the provider list offering one-click import into `AddCustomProviderModal`. The banner is dismissible and the preference persists to `localStorage` via key `cpa-detection-dismissed-v1`.

apps/desktop/src/renderer/src/components/Settings.test.ts

@@ -39,6 +39,48 @@ describe('applyLocaleChange', () => {
     expect(result).toBe('zh-CN');
   });
 });
+
+describe('CPA detection regex', () => {
+  const CPA_REGEX = /^https?:\/\/(localhost|127\.0\.0\.1):8317/;
+
+  it('matches http://localhost:8317', () => {
+    expect('http://localhost:8317').toMatch(CPA_REGEX);
+  });
+
+  it('matches https://127.0.0.1:8317', () => {
+    expect('https://127.0.0.1:8317').toMatch(CPA_REGEX);
+  });
+
+  it('does not match other ports', () => {
+    expect('http://localhost:8080').not.toMatch(CPA_REGEX);
+    expect('https://example.com:8317').not.toMatch(CPA_REGEX);
+  });
+});
+
+describe('CPA detection localStorage dismissal', () => {
+  const KEY = 'cpa-detection-dismissed-v1';
+
+  it('reads and writes dismissal flag', () => {
+    const values = new Map<string, string>();
+    const storage = {
+      getItem: vi.fn((key: string) => values.get(key) ?? null),
+      setItem: vi.fn((key: string, value: string) => {
+        values.set(key, value);
+      }),
+    };
+
+    // Check initial read
+    expect(storage.getItem(KEY)).toBeNull();
+
+    // Simulate user dismissal
+    storage.setItem(KEY, '1');
+    expect(storage.setItem).toHaveBeenCalledWith(KEY, '1');
+
+    // Verify we can read it back
+    expect(storage.getItem(KEY)).toBe('1');
+  });
+});
+
 describe('computeModelOptions', () => {
   const suffix = '(active, not in provider list)';
 

apps/desktop/src/renderer/src/components/Settings.tsx

@@ -22,6 +22,7 @@ import {
   RotateCcw,
   Sliders,
   Trash2,
+  Zap,
 } from 'lucide-react';
 import { useEffect, useMemo, useRef, useState } from 'react';
 import type { AppPaths, Preferences, ProviderRow, StorageKind } from '../../../preload/index';
@@ -856,6 +857,47 @@ function WarningsList({ warnings }: { warnings: string[] }) {
   );
 }
 
+const CPA_DETECTION_DISMISSED_KEY = 'cpa-detection-dismissed-v1';
+
+function LocalCpaImportCard({
+  onImport,
+  onDismiss,
+}: {
+  onImport: () => void;
+  onDismiss: () => void;
+}) {
+  const t = useT();
+  return (
+    <div className="rounded-[var(--radius-md)] border border-[var(--color-accent)] bg-[var(--color-accent-tint)] px-[var(--space-3)] py-[var(--space-2_5)] flex items-start gap-[var(--space-3)]">
+      <Zap className="w-4 h-4 mt-0.5 shrink-0 text-[var(--color-accent)]" aria-hidden="true" />
+      <div className="flex-1 min-w-0">
+        <p className="text-[var(--text-sm)] font-medium text-[var(--color-text-primary)] leading-snug">
+          {t('settings.providers.cpaDetection.title')}
+        </p>
+        <p className="text-[var(--text-xs)] text-[var(--color-text-secondary)] mt-0.5 leading-[var(--leading-body)]">
+          {t('settings.providers.cpaDetection.body')}
+        </p>
+      </div>
+      <div className="flex items-center gap-[var(--space-1_5)] shrink-0">
+        <button
+          type="button"
+          onClick={onImport}
+          className="h-7 px-[var(--space-2_5)] rounded-[var(--radius-sm)] text-[var(--text-xs)] text-[var(--color-on-accent)] bg-[var(--color-accent)] hover:opacity-90 transition-opacity whitespace-nowrap"
+        >
+          {t('settings.providers.cpaDetection.importAction')}
+        </button>
+        <button
+          type="button"
+          onClick={onDismiss}
+          className="h-7 px-[var(--space-2)] rounded-[var(--radius-sm)] text-[var(--text-xs)] text-[var(--color-text-secondary)] hover:bg-[var(--color-surface-hover)] transition-colors whitespace-nowrap"
+        >
+          {t('settings.providers.cpaDetection.dismissAction')}
+        </button>
+      </div>
+    </div>
+  );
+}
+
 function ModelsTab() {
   const t = useT();
   const config = useCodesignStore((s) => s.config);
@@ -866,6 +908,9 @@ function ModelsTab() {
   const [loading, setLoading] = useState(true);
   const [showAddCustom, setShowAddCustom] = useState(false);
   const [showAddMenu, setShowAddMenu] = useState(false);
+  const [cpaDetection, setCpaDetection] = useState<
+    'idle' | 'detecting' | 'available' | 'unavailable'
+  >('idle');
   const [externalConfigs, setExternalConfigs] = useState<{
     codex?: { count: number } | undefined;
     claudeCode?:
@@ -994,6 +1039,44 @@ function ModelsTab() {
       });
   }, [pushToast, t]);
 
+  useEffect(() => {
+    if (!window.codesign?.config?.testEndpoint) return;
+    // Only probe once — once we've reached a terminal state, skip.
+    if (cpaDetection !== 'idle') return;
+    // Skip if user already dismissed this banner for this install.
+    try {
+      if (window.localStorage.getItem(CPA_DETECTION_DISMISSED_KEY) === '1') return;
+    } catch {
+      // localStorage unavailable — proceed with detection
+    }
+    // Skip detection if a provider is already pointing at the CPA port.
+    // We wait for the rows load to settle before probing so we don't flash
+    // the banner and immediately hide it on the next render tick.
+    if (loading) return;
+    const alreadyConfigured = rows.some((r) =>
+      /^https?:\/\/(localhost|127\.0\.0\.1):8317/.test(r.baseUrl ?? ''),
+    );
+    if (alreadyConfigured) return;
+
+    setCpaDetection('detecting');
+    void window.codesign.config
+      .testEndpoint({ wire: 'anthropic', baseUrl: 'http://127.0.0.1:8317', apiKey: '' })
+      .then((res) => {
+        setCpaDetection(res.ok ? 'available' : 'unavailable');
+      })
+      .catch((err) => {
+        reportableErrorToast({
+          code: 'CPA_DETECTION_FAILED',
+          scope: 'settings',
+          title: t('settings.imageGen.toast.loadFailed', {
+            defaultValue: 'Image generation settings failed to load',
+          }),
+          description: cleanIpcError(err) || t('settings.common.unknownError'),
+        });
+        setCpaDetection('unavailable');
+      });
+  }, [cpaDetection, loading, rows, pushToast, reportableErrorToast, t]);
+
   async function reloadRows() {
     if (!window.codesign) return;
     const [nextRows, state] = await Promise.all([
@@ -1313,6 +1396,28 @@ function ModelsTab() {
 
       <div className="space-y-[var(--space-3)]">
         <ChatgptLoginCard onStatusChange={reloadRows} />
+        {cpaDetection === 'available' && (
+          <LocalCpaImportCard
+            onImport={() => {
+              setCustomProviderPreset({
+                name: 'CLIProxyAPI',
+                baseUrl: 'http://127.0.0.1:8317',
+                wire: 'anthropic',
+                defaultModel: '',
+              });
+              setShowAddCustom(true);
+              setCpaDetection('unavailable');
+            }}
+            onDismiss={() => {
+              try {
+                window.localStorage.setItem(CPA_DETECTION_DISMISSED_KEY, '1');
+              } catch {
+                // non-fatal
+              }
+              setCpaDetection('unavailable');
+            }}
+          />
+        )}
         {externalConfigs !== null &&
           (externalConfigs.codex !== undefined ||
             externalConfigs.claudeCode !== undefined ||

packages/i18n/src/locales/en.json

@@ -313,6 +313,12 @@
         "apiKeyOptional": "API key only required if you configured `api-keys` in CPA config.yaml",
         "thinkingHint": "Tip: append `(high)` / `(xhigh)` / `(8192)` to model name to control thinking budget"
       },
+      "cpaDetection": {
+        "title": "CLIProxyAPI detected on your machine",
+        "body": "Import it as a provider to use your OAuth-authenticated Claude / Codex / Gemini accounts.",
+        "importAction": "Import",
+        "dismissAction": "Dismiss"
+      },
       "reasoning": {
         "label": "Reasoning depth",
         "default": "Default (auto)",

packages/i18n/src/locales/zh-CN.json

@@ -313,6 +313,12 @@
         "apiKeyOptional": "仅当你在 CPA config.yaml 里配置了 api-keys 才需要填",
         "thinkingHint": "提示：在 model 名后加 `(high)` / `(xhigh)` / `(8192)` 可控制思考力度"
       },
+      "cpaDetection": {
+        "title": "检测到本机运行的 CLIProxyAPI",
+        "body": "一键导入即可使用你已登录的 Claude / Codex / Gemini 订阅账号。",
+        "importAction": "导入",
+        "dismissAction": "忽略"
+      },
       "reasoning": {
         "label": "推理深度",
         "default": "默认（自动）",