pikiloop 0.4.0

package/dist/browser-supervisor.js

@@ -0,0 +1,249 @@
+/**
+ * Process-level singleton supervisor for the managed browser.
+ *
+ * Owns the lifecycle decisions for the managed Chrome instance so that all
+ * agent streams in this pikiloop process share one browser. Replaces the old
+ * per-stream `prepareManagedBrowserForAutomation` call inside the MCP bridge,
+ * which was relaunching Chrome at the start of every task.
+ *
+ * Three operations:
+ *   - probe(): non-launching health check; returns the current CDP endpoint
+ *     iff a managed Chrome is already reachable.
+ *   - ensure(): idempotent prepare with singleflight; launches Chrome only
+ *     when no healthy instance is reachable. Caches the result for re-use
+ *     across streams.
+ *   - invalidate(): drop the cache after a confirmed downstream failure
+ *     (e.g. CDP socket closed mid-stream).
+ */
+import { forceCloseManagedBrowser, getConfiguredRemoteCdpUrl, getManagedBrowserProfileDir, prepareManagedBrowserForAutomation, } from './browser-profile.js';
+import { PIKILOOP_BROWSER_CDP_URL_ENV } from './core/constants.js';
+import { writeScopedLog } from './core/logging.js';
+const HEALTH_CACHE_MS = 30_000;
+const CDP_PROBE_TIMEOUT_MS = 1_500;
+let cached = null;
+let inflight = null;
+function log(message, level = 'debug') {
+    writeScopedLog('browser-supervisor', message, { level, stream: 'stderr' });
+}
+/**
+ * The user-configured remote endpoint from {@link PIKILOOP_BROWSER_CDP_URL_ENV}.
+ * When set, every supervisor codepath bypasses local Chrome launching. Aliased
+ * to the shared `getConfiguredRemoteCdpUrl` so the bridge and supervisor read
+ * the same normalized value.
+ */
+const getRemoteCdpUrl = getConfiguredRemoteCdpUrl;
+/**
+ * Snapshot for the remote-CDP path. The URL is taken on trust as configured —
+ * health is verified by {@link pingCdpEndpoint} before caching, and by the
+ * usual freshness check on every reuse.
+ */
+async function snapshotRemote(remoteUrl, now) {
+    if (cached?.cdpEndpoint === remoteUrl && now - cached.validatedAt < HEALTH_CACHE_MS) {
+        return snapshotFromCache(cached);
+    }
+    const healthy = await pingCdpEndpoint(remoteUrl);
+    if (!healthy) {
+        if (cached?.cdpEndpoint === remoteUrl)
+            cached = null;
+        log(`remote CDP endpoint ${remoteUrl} not reachable`, 'warn');
+        return { cdpEndpoint: null, connectionMode: 'unavailable' };
+    }
+    cached = { cdpEndpoint: remoteUrl, connectionMode: 'attach', validatedAt: now };
+    log(`using remote CDP endpoint ${remoteUrl} (from ${PIKILOOP_BROWSER_CDP_URL_ENV})`);
+    return snapshotFromCache(cached);
+}
+function snapshotFromCache(state) {
+    return { cdpEndpoint: state.cdpEndpoint, connectionMode: state.connectionMode };
+}
+async function fetchWithTimeout(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        return response;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Two-stage health check.
+ *
+ * Stage 1 (`/json/version`) hits Chrome's static info handler — confirms the
+ * process is alive and the debug HTTP server is bound. Stage 2 (`/json`) reads
+ * from the target manager, exercising the CDP dispatch loop. Chrome can end up
+ * in a state where stage 1 still answers but stage 2 hangs, typically after
+ * many stale CDP sessions accumulate; treating stage-1-only responses as
+ * healthy lets that state poison every subsequent agent run.
+ *
+ * Both stages share the same `CDP_PROBE_TIMEOUT_MS`. This probe does NOT catch
+ * the case where stage 2 succeeds but the *first page target* is itself stuck
+ * (e.g. a heavy SPA frozen mid-init); that has to be handled reactively from
+ * the MCP-tool-error path.
+ */
+async function pingCdpEndpoint(endpoint) {
+    if (!endpoint)
+        return false;
+    const versionResp = await fetchWithTimeout(`${endpoint}/json/version`, CDP_PROBE_TIMEOUT_MS);
+    if (!versionResp || !versionResp.ok)
+        return false;
+    const versionPayload = await versionResp.json().catch(() => null);
+    if (typeof versionPayload?.webSocketDebuggerUrl !== 'string')
+        return false;
+    const targetsResp = await fetchWithTimeout(`${endpoint}/json`, CDP_PROBE_TIMEOUT_MS);
+    if (!targetsResp || !targetsResp.ok)
+        return false;
+    const targets = await targetsResp.json().catch(() => null);
+    return Array.isArray(targets);
+}
+async function freshenCacheIfPossible(now) {
+    if (!cached?.cdpEndpoint)
+        return null;
+    if (now - cached.validatedAt < HEALTH_CACHE_MS)
+        return snapshotFromCache(cached);
+    const healthy = await pingCdpEndpoint(cached.cdpEndpoint);
+    if (healthy) {
+        cached.validatedAt = now;
+        return snapshotFromCache(cached);
+    }
+    log(`cached endpoint ${cached.cdpEndpoint} no longer reachable; clearing cache`, 'warn');
+    cached = null;
+    return null;
+}
+/**
+ * Non-launching probe. Returns the current CDP endpoint iff a managed Chrome
+ * is already reachable. Never starts a new Chrome process.
+ */
+export async function probeManagedBrowser() {
+    const remoteUrl = getRemoteCdpUrl();
+    if (remoteUrl)
+        return snapshotRemote(remoteUrl, Date.now());
+    const fresh = await freshenCacheIfPossible(Date.now());
+    if (fresh)
+        return fresh;
+    return { cdpEndpoint: null, connectionMode: 'unavailable' };
+}
+/**
+ * Idempotent prepare. Returns a healthy CDP endpoint, launching Chrome only
+ * when no reachable managed instance is available. Concurrent callers share
+ * one in-flight preparation promise (singleflight).
+ *
+ * When {@link PIKILOOP_BROWSER_CDP_URL_ENV} is set we skip the local-launch
+ * branch entirely and just verify the remote endpoint — no `findChromeExecutable`
+ * lookup, no SIGKILL of detected pids on restart.
+ */
+export async function ensureManagedBrowser(opts = {}) {
+    const { headless = false, force = false } = opts;
+    const now = Date.now();
+    const remoteUrl = getRemoteCdpUrl();
+    if (remoteUrl) {
+        if (force && cached?.cdpEndpoint === remoteUrl)
+            cached = null;
+        return snapshotRemote(remoteUrl, now);
+    }
+    if (!force) {
+        const fresh = await freshenCacheIfPossible(now);
+        if (fresh)
+            return fresh;
+    }
+    if (inflight)
+        return inflight;
+    inflight = (async () => {
+        try {
+            const result = await prepareManagedBrowserForAutomation(getManagedBrowserProfileDir(), { headless });
+            const state = {
+                cdpEndpoint: result.cdpEndpoint,
+                connectionMode: result.cdpEndpoint ? result.connectionMode : 'unavailable',
+                validatedAt: Date.now(),
+            };
+            if (state.cdpEndpoint) {
+                cached = state;
+                log(`prepared managed browser: mode=${state.connectionMode} endpoint=${state.cdpEndpoint}`);
+            }
+            else {
+                cached = null;
+                log(`managed browser unavailable (mode=${result.connectionMode}); will fall back to upstream-managed launch`, 'warn');
+            }
+            return snapshotFromCache(state);
+        }
+        catch (err) {
+            cached = null;
+            log(`ensure failed: ${err?.message || err}`, 'error');
+            return { cdpEndpoint: null, connectionMode: 'unavailable' };
+        }
+        finally {
+            inflight = null;
+        }
+    })();
+    return inflight;
+}
+const RESTART_COOLDOWN_MS = 30_000;
+let lastRestartAt = 0;
+let restartInflight = null;
+/**
+ * Reactive recovery for a confirmed CDP-layer failure: drops the supervisor
+ * cache, SIGKILLs Chrome, wipes session-restore. The next `ensureManagedBrowser`
+ * will detect no CDP endpoint and relaunch Chrome cold.
+ *
+ * The current stream is not rescued — its MCP child has already lost stdio,
+ * and Claude CLI's MCP client won't reconnect mid-tool-call. The benefit lands
+ * on the next agent turn, which will attach to a fresh browser instead of
+ * inheriting the wedged one.
+ *
+ * Cooldown-throttled and singleflight: a single agent run can spit many
+ * "Connection closed" lines as the MCP child stays dead; we only act once.
+ */
+export function restartManagedBrowser(reason) {
+    const now = Date.now();
+    if (restartInflight)
+        return restartInflight;
+    if (now - lastRestartAt < RESTART_COOLDOWN_MS) {
+        log(`restart skipped (within ${RESTART_COOLDOWN_MS / 1000}s cooldown): ${reason}`, 'debug');
+        return Promise.resolve();
+    }
+    lastRestartAt = now;
+    // Remote CDP path: we don't own the Chrome process (it's a sidecar / external
+    // service), so don't SIGKILL anything — just drop the cache so the next
+    // ensure re-probes the endpoint.
+    const remoteUrl = getRemoteCdpUrl();
+    if (remoteUrl) {
+        log(`invalidating remote CDP cache (${remoteUrl}): ${reason}`, 'warn');
+        cached = null;
+        return Promise.resolve();
+    }
+    log(`restarting managed browser: ${reason}`, 'warn');
+    restartInflight = (async () => {
+        try {
+            cached = null;
+            const killed = await forceCloseManagedBrowser();
+            log(`forced close complete; killed pids=[${killed.join(',')}]`);
+        }
+        catch (err) {
+            log(`force-close failed: ${err?.message || err}`, 'error');
+        }
+        finally {
+            restartInflight = null;
+        }
+    })();
+    return restartInflight;
+}
+/** Drop any cached endpoint, e.g. after a confirmed CDP failure mid-stream. */
+export function invalidateManagedBrowser() {
+    if (cached)
+        log(`invalidating cached endpoint ${cached.cdpEndpoint}`);
+    cached = null;
+}
+/** Synchronous accessor for the cached endpoint without any I/O. */
+export function getCachedManagedBrowserEndpoint() {
+    return cached?.cdpEndpoint || null;
+}
+/** Test-only: reset module state. */
+export function _resetManagedBrowserSupervisor() {
+    cached = null;
+    inflight = null;
+    lastRestartAt = 0;
+    restartInflight = null;
+}

package/dist/catalog/cli-tools.js

@@ -0,0 +1,421 @@
+/**
+ * CLI tool catalog — single source of truth for what the Dashboard shows under
+ * Extensions → CLI.
+ *
+ * ─── How this plugs into the rest of the stack ───────────────────────────────
+ *
+ *   Dashboard → GET /api/extensions/cli/catalog
+ *     → dashboard/routes/cli.ts
+ *       → agent/cli/catalog.ts    (merge + live detection)
+ *         → agent/cli/registry.ts (types + re-exports this array)
+ *           ← src/catalog/cli-tools.ts ← YOU ARE HERE
+ *
+ * The registry module defines the `RecommendedCli` type and other helpers; the
+ * detector spawns `which <binary>` + the status command, and the auth runner
+ * streams the login sub-process. This file owns only the *data*.
+ *
+ * ─── How to add a CLI ────────────────────────────────────────────────────────
+ *
+ *   1. Append an entry to `CLI_TOOLS`.
+ *   2. Pick an `auth.type`:
+ *        - 'oauth-web' if the CLI has a first-party `<cli> ... login --web`
+ *          flavor (gh, wrangler, vercel, …). The runner spawns that command,
+ *          streams stdout/stderr to the UI, and polls `statusArgv` until it
+ *          reports authed.
+ *        - 'token' if the user pastes an API key. Implement the write-path in
+ *          `agent/cli/auth.ts` → `applyCliToken` for that id (keeps secret
+ *          handling explicit per CLI).
+ *        - 'none' for CLIs that don't need sign-in (docker, pnpm).
+ *   3. Fill `install.{darwin,linux,win}` with canonical commands. The UI shows
+ *      the current OS's list and always renders a "Copy" button. We deliberately
+ *      do NOT auto-run installers — package managers often need sudo or
+ *      interactive confirmation and we'd rather keep the user in charge.
+ */
+export const CLI_TOOLS = [
+    // ── Dev: source control & platforms ────────────────────────────────────────
+    {
+        id: 'gh',
+        binary: 'gh',
+        name: 'GitHub CLI',
+        description: 'Manage pull requests, issues, and Actions from the terminal',
+        descriptionZh: '终端直管 PR、Issue 和 Actions',
+        category: 'dev',
+        iconSlug: 'github',
+        homepage: 'https://cli.github.com/',
+        recommendedScope: 'global',
+        versionArgv: ['gh', '--version'],
+        install: {
+            docs: 'https://github.com/cli/cli#installation',
+            darwin: [{ label: 'Homebrew', cmd: 'brew install gh' }],
+            linux: [
+                { label: 'apt (Debian/Ubuntu)', cmd: 'sudo apt install gh' },
+                { label: 'dnf (Fedora)', cmd: 'sudo dnf install gh' },
+            ],
+            win: [{ label: 'winget', cmd: 'winget install GitHub.cli' }],
+        },
+        auth: {
+            type: 'oauth-web',
+            statusArgv: ['gh', 'auth', 'status'],
+            loginArgv: ['gh', 'auth', 'login', '--web', '--git-protocol', 'https'],
+            logoutArgv: ['gh', 'auth', 'logout', '--hostname', 'github.com'],
+            loginHint: 'Opens a browser for GitHub OAuth.',
+            loginHintZh: '将打开浏览器完成 GitHub OAuth 授权。',
+        },
+    },
+    // ── Cloud platforms ────────────────────────────────────────────────────────
+    {
+        id: 'wrangler',
+        binary: 'wrangler',
+        name: 'Cloudflare Wrangler',
+        description: 'Build and deploy Cloudflare Workers, Pages, and D1',
+        descriptionZh: '构建并部署 Workers / Pages / D1',
+        category: 'cloud',
+        iconSlug: 'cloudflare',
+        homepage: 'https://developers.cloudflare.com/workers/wrangler/',
+        recommendedScope: 'global',
+        versionArgv: ['wrangler', '--version'],
+        install: {
+            docs: 'https://developers.cloudflare.com/workers/wrangler/install-and-update/',
+            darwin: [{ label: 'npm', cmd: 'npm i -g wrangler' }],
+            linux: [{ label: 'npm', cmd: 'npm i -g wrangler' }],
+            win: [{ label: 'npm', cmd: 'npm i -g wrangler' }],
+        },
+        auth: {
+            type: 'oauth-web',
+            statusArgv: ['wrangler', 'whoami'],
+            loginArgv: ['wrangler', 'login'],
+            logoutArgv: ['wrangler', 'logout'],
+            loginHint: 'Opens a browser for Cloudflare OAuth.',
+            loginHintZh: '将打开浏览器完成 Cloudflare OAuth 授权。',
+        },
+    },
+    {
+        id: 'vercel',
+        binary: 'vercel',
+        name: 'Vercel CLI',
+        description: 'Deploy Next.js / frontend projects to Vercel',
+        descriptionZh: '将 Next.js / 前端项目部署到 Vercel',
+        category: 'cloud',
+        iconSlug: 'vercel',
+        homepage: 'https://vercel.com/docs/cli',
+        recommendedScope: 'global',
+        versionArgv: ['vercel', '--version'],
+        install: {
+            docs: 'https://vercel.com/docs/cli#installing-vercel-cli',
+            darwin: [{ label: 'npm', cmd: 'npm i -g vercel' }],
+            linux: [{ label: 'npm', cmd: 'npm i -g vercel' }],
+            win: [{ label: 'npm', cmd: 'npm i -g vercel' }],
+        },
+        auth: {
+            type: 'oauth-web',
+            statusArgv: ['vercel', 'whoami'],
+            loginArgv: ['vercel', 'login'],
+            logoutArgv: ['vercel', 'logout'],
+            // `vercel login` opens an interactive picker (email / GitHub / GitLab /
+            // Bitbucket / SAML) that needs a real TTY. Surface the official command.
+            manualLoginCommands: [
+                { label: 'Sign in to Vercel', cmd: 'vercel login' },
+            ],
+            loginHint: 'Run `vercel login` in your own terminal — it interactively asks which login method to use, which doesn\'t render well here. After signing in, click "Re-check status".',
+            loginHintZh: '请在自己的终端里运行 `vercel login` —— 该命令需要交互式选择登录方式（邮箱 / GitHub / GitLab 等），不适合在此面板里完成。登录后回到这里点击「重新检测状态」。',
+        },
+    },
+    {
+        id: 'netlify',
+        binary: 'netlify',
+        name: 'Netlify CLI',
+        description: 'Deploy and manage Netlify sites, Functions, and Edge',
+        descriptionZh: '部署并管理 Netlify 站点、Functions、Edge',
+        category: 'cloud',
+        iconSlug: 'netlify',
+        homepage: 'https://docs.netlify.com/cli/get-started/',
+        recommendedScope: 'global',
+        versionArgv: ['netlify', '--version'],
+        install: {
+            docs: 'https://docs.netlify.com/cli/get-started/#installation',
+            darwin: [{ label: 'npm', cmd: 'npm i -g netlify-cli' }],
+            linux: [{ label: 'npm', cmd: 'npm i -g netlify-cli' }],
+            win: [{ label: 'npm', cmd: 'npm i -g netlify-cli' }],
+        },
+        auth: {
+            type: 'oauth-web',
+            statusArgv: ['netlify', 'status'],
+            loginArgv: ['netlify', 'login'],
+            logoutArgv: ['netlify', 'logout'],
+            loginHint: 'Opens a browser for Netlify OAuth.',
+            loginHintZh: '将打开浏览器完成 Netlify OAuth 授权。',
+        },
+    },
+    {
+        id: 'supabase',
+        binary: 'supabase',
+        name: 'Supabase CLI',
+        description: 'Manage Supabase projects, Postgres, and Edge Functions',
+        descriptionZh: '管理 Supabase 项目、Postgres 与 Edge Functions',
+        category: 'data',
+        iconSlug: 'supabase',
+        homepage: 'https://supabase.com/docs/guides/cli',
+        recommendedScope: 'global',
+        versionArgv: ['supabase', '--version'],
+        install: {
+            docs: 'https://supabase.com/docs/guides/cli/getting-started',
+            darwin: [{ label: 'Homebrew', cmd: 'brew install supabase/tap/supabase' }],
+            linux: [{ label: 'Script', cmd: 'curl -sL https://supabase.com/install.sh | sh' }],
+            win: [{ label: 'scoop', cmd: 'scoop bucket add supabase https://github.com/supabase/scoop-bucket.git && scoop install supabase' }],
+        },
+        auth: {
+            type: 'oauth-web',
+            statusArgv: ['supabase', 'projects', 'list'],
+            loginArgv: ['supabase', 'login'],
+            logoutArgv: ['supabase', 'logout'],
+            loginHint: 'Opens a browser for Supabase OAuth.',
+            loginHintZh: '将打开浏览器完成 Supabase OAuth 授权。',
+        },
+    },
+    {
+        id: 'heroku',
+        binary: 'heroku',
+        name: 'Heroku CLI',
+        description: 'Create and manage Heroku apps and dynos',
+        descriptionZh: '创建与管理 Heroku 应用和 dyno',
+        category: 'cloud',
+        iconSlug: 'heroku',
+        homepage: 'https://devcenter.heroku.com/articles/heroku-cli',
+        recommendedScope: 'global',
+        versionArgv: ['heroku', '--version'],
+        install: {
+            docs: 'https://devcenter.heroku.com/articles/heroku-cli#install-the-heroku-cli',
+            darwin: [{ label: 'Homebrew', cmd: 'brew tap heroku/brew && brew install heroku' }],
+            linux: [{ label: 'Snap', cmd: 'sudo snap install --classic heroku' }],
+            win: [{ label: 'Installer', cmd: 'winget install --id=Heroku.HerokuCLI' }],
+        },
+        auth: {
+            type: 'oauth-web',
+            statusArgv: ['heroku', 'whoami'],
+            loginArgv: ['heroku', 'login'],
+            logoutArgv: ['heroku', 'logout'],
+            // `heroku login` prompts "Press any key to open up the browser to login
+            // or q to exit" — a hard TTY dependency. Surface the official command.
+            manualLoginCommands: [
+                { label: 'Sign in to Heroku', cmd: 'heroku login' },
+            ],
+            loginHint: 'Run `heroku login` in your own terminal — the CLI prompts "Press any key to open the browser", which requires a real TTY. After signing in, click "Re-check status".',
+            loginHintZh: '请在自己的终端里运行 `heroku login` —— 该命令会提示「Press any key」，必须在交互式终端里完成。登录后回到这里点击「重新检测状态」。',
+        },
+    },
+    // ── Commerce & payments ────────────────────────────────────────────────────
+    {
+        id: 'stripe',
+        binary: 'stripe',
+        name: 'Stripe CLI',
+        description: 'Test webhooks, trigger events, inspect API logs',
+        descriptionZh: '调试 Webhook、触发事件、查看 API 日志',
+        category: 'commerce',
+        iconSlug: 'stripe',
+        homepage: 'https://stripe.com/docs/stripe-cli',
+        recommendedScope: 'global',
+        versionArgv: ['stripe', '--version'],
+        install: {
+            docs: 'https://docs.stripe.com/stripe-cli#install',
+            darwin: [{ label: 'Homebrew', cmd: 'brew install stripe/stripe-cli/stripe' }],
+            linux: [{ label: 'apt', cmd: "curl -s https://packages.stripe.dev/api/security/keypair/stripe-cli-gpg/public | gpg --dearmor | sudo tee /usr/share/keyrings/stripe.gpg >/dev/null && echo 'deb [signed-by=/usr/share/keyrings/stripe.gpg] https://packages.stripe.dev/stripe-cli-debian-local stable main' | sudo tee /etc/apt/sources.list.d/stripe.list && sudo apt update && sudo apt install stripe" }],
+            win: [{ label: 'scoop', cmd: 'scoop bucket add stripe https://github.com/stripe/scoop-stripe-cli.git && scoop install stripe' }],
+        },
+        auth: {
+            type: 'oauth-web',
+            statusArgv: ['stripe', 'config', '--list'],
+            loginArgv: ['stripe', 'login'],
+            logoutArgv: ['stripe', 'logout'],
+            loginHint: 'Opens a browser and writes credentials to ~/.config/stripe/.',
+            loginHintZh: '打开浏览器完成授权，凭据写入 ~/.config/stripe/。',
+        },
+    },
+    // ── Cloud giants (token-based profile flows) ───────────────────────────────
+    {
+        id: 'aws',
+        binary: 'aws',
+        name: 'AWS CLI',
+        description: 'Interact with AWS services (S3, Lambda, IAM, …)',
+        descriptionZh: '访问 AWS 的 S3 / Lambda / IAM 等服务',
+        category: 'cloud',
+        iconSlug: 'aws',
+        homepage: 'https://aws.amazon.com/cli/',
+        recommendedScope: 'global',
+        versionArgv: ['aws', '--version'],
+        install: {
+            docs: 'https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html',
+            darwin: [{ label: 'Homebrew', cmd: 'brew install awscli' }],
+            linux: [{ label: 'Bundled installer', cmd: 'curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscli.zip && unzip awscli.zip && sudo ./aws/install' }],
+            win: [{ label: 'MSI', cmd: 'msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi' }],
+        },
+        auth: {
+            type: 'token',
+            statusArgv: ['aws', 'sts', 'get-caller-identity'],
+            tokenFields: [
+                { key: 'AWS_ACCESS_KEY_ID', label: 'Access key ID', labelZh: 'Access Key ID', required: true },
+                { key: 'AWS_SECRET_ACCESS_KEY', label: 'Secret key', labelZh: 'Secret Access Key', secret: true, required: true },
+                { key: 'AWS_DEFAULT_REGION', label: 'Region', labelZh: '默认区域', placeholder: 'us-east-1' },
+            ],
+            loginHint: 'Writes credentials to ~/.aws/credentials under [default].',
+            loginHintZh: '凭据会写入 ~/.aws/credentials 的 [default] 下。',
+        },
+    },
+    {
+        id: 'gcloud',
+        binary: 'gcloud',
+        name: 'Google Cloud CLI',
+        description: 'Manage GCP projects, compute, storage, and IAM',
+        descriptionZh: '管理 GCP 项目、计算、存储与 IAM',
+        category: 'cloud',
+        iconSlug: 'google-cloud',
+        homepage: 'https://cloud.google.com/sdk/gcloud',
+        recommendedScope: 'global',
+        versionArgv: ['gcloud', '--version'],
+        install: {
+            docs: 'https://cloud.google.com/sdk/docs/install',
+            darwin: [{ label: 'Homebrew Cask', cmd: 'brew install --cask google-cloud-sdk' }],
+            linux: [{ label: 'Bundled installer', cmd: 'curl https://sdk.cloud.google.com | bash' }],
+            win: [{ label: 'Installer', cmd: 'winget install Google.CloudSDK' }],
+        },
+        auth: {
+            type: 'oauth-web',
+            // `gcloud auth list ... --format=value(account)` exits 0 even when no
+            // account is signed in (just prints an empty line). Require non-empty
+            // output so an empty list isn't mistaken for ready.
+            statusArgv: ['gcloud', 'auth', 'list', '--filter=status:ACTIVE', '--format=value(account)'],
+            statusReadyPattern: '\\S',
+            loginArgv: ['gcloud', 'auth', 'login'],
+            logoutArgv: ['gcloud', 'auth', 'revoke'],
+            // `gcloud auth login` orchestrates a local callback server + interactive
+            // prompts — needs a real TTY. ADC for SDK code is a separate command.
+            manualLoginCommands: [
+                { label: 'Sign in (user credentials)', cmd: 'gcloud auth login' },
+                { label: 'Optional: Application Default Credentials', cmd: 'gcloud auth application-default login' },
+            ],
+            loginHint: 'Run `gcloud auth login` in your own terminal — it relies on a local callback server and interactive prompts that don\'t work here. SDK code paths use Application Default Credentials, which is a separate command. After signing in, click "Re-check status".',
+            loginHintZh: '请在自己的终端里运行 `gcloud auth login` —— 它依赖本地回调服务器与交互式提示，不能在此面板里完成。SDK 用的 Application Default 凭证是另一个命令。登录后回到这里点击「重新检测状态」。',
+        },
+    },
+    // ── Social & messaging ─────────────────────────────────────────────────────
+    {
+        id: 'lark-cli',
+        binary: 'lark-cli',
+        name: 'Lark CLI',
+        description: 'Official Lark/Feishu CLI — Messenger, Docs, Base, Calendar, Tasks (200+ commands, Agent-native)',
+        descriptionZh: '飞书官方 CLI — 消息、文档、多维表格、日历、任务等 200+ 命令，专为 Agent 设计',
+        category: 'social',
+        iconSlug: 'lark',
+        homepage: 'https://github.com/larksuite/cli',
+        recommendedScope: 'global',
+        versionArgv: ['lark-cli', '--version'],
+        install: {
+            docs: 'https://github.com/larksuite/cli#installation--quick-start',
+            darwin: [{ label: 'npm', cmd: 'npm i -g @larksuite/cli' }],
+            linux: [{ label: 'npm', cmd: 'npm i -g @larksuite/cli' }],
+            win: [{ label: 'npm', cmd: 'npm i -g @larksuite/cli' }],
+        },
+        auth: {
+            type: 'oauth-web',
+            statusArgv: ['lark-cli', 'auth', 'status'],
+            loginArgv: ['lark-cli', 'auth', 'login', '--recommend'],
+            logoutArgv: ['lark-cli', 'auth', 'logout'],
+            // Lark CLI sign-in has two ordered steps and renders a terminal QR that
+            // doesn't fit a streamed-output panel. Both commands run in the user's
+            // own terminal; only after step 2 does `lark-cli auth status` exit 0,
+            // so re-check naturally rejects "only step 1 completed".
+            manualLoginCommands: [
+                { label: 'Step 1 — Register a Feishu app (one-time setup)', cmd: 'lark-cli config init --new' },
+                { label: 'Step 2 — Sign in via Device Flow OAuth', cmd: 'lark-cli auth login --recommend' },
+            ],
+            loginHint: 'Lark CLI sign-in has two steps. Run them in order in your own terminal — `lark-cli` prints a QR/Device-Flow URL that doesn\'t render well in this panel. Both steps must complete before authorization counts as successful. After step 2 finishes, click "Re-check status" below. Tip: `npx skills add larksuite/cli -y -g` installs the matching Skills.',
+            loginHintZh: '飞书 CLI 登录分两步，请在自己的终端里依序运行：先用第 1 步注册飞书应用，再用第 2 步完成 OAuth 授权 —— 两步全部完成后才算授权成功。`lark-cli` 登录时打印的二维码 / Device Flow URL 不适合在此面板内展示。完成第 2 步后回到这里点击「重新检测状态」。建议同步安装配套 Skills：`npx skills add larksuite/cli -y -g`。',
+        },
+    },
+    // ── Content & creation ─────────────────────────────────────────────────────
+    {
+        id: 'mocli',
+        binary: 'mocli',
+        name: 'Mowen CLI',
+        description: 'Talk to 墨问 (Mowen) — query notes, search users, view activity from your agent',
+        descriptionZh: '墨问官方 CLI — 查我的笔记、搜用户、看动态，给 Agent 一手接入墨问内容',
+        category: 'content',
+        iconUrl: 'https://github.com/mowenxd.png?size=80',
+        homepage: 'https://github.com/mowenxd/cli',
+        recommendedScope: 'global',
+        versionArgv: ['mocli', '--version'],
+        install: {
+            docs: 'https://github.com/mowenxd/cli#安装与快速开始',
+            darwin: [{ label: 'npm', cmd: 'npm i -g @mowenxd/cli' }],
+            linux: [{ label: 'npm', cmd: 'npm i -g @mowenxd/cli' }],
+            win: [{ label: 'npm', cmd: 'npm i -g @mowenxd/cli' }],
+        },
+        auth: {
+            type: 'token',
+            statusArgv: ['mocli', 'auth', 'info'],
+            logoutArgv: ['mocli', 'auth', 'logout'],
+            tokenFields: [
+                { key: 'MOWEN_API_KEY', label: 'Mowen API Key', labelZh: '墨问 API Key', secret: true, required: true },
+            ],
+            loginHint: 'Get your API Key in the Mowen mini-program → 我的 → 开发者 → 我的 API Key.',
+            loginHintZh: '在墨问小程序里：右下角「我的」→「开发者」→「我的 API Key」，复制粘贴到这里。装完后建议再跑 `npx skills add mowenxd/cli -y -g` 安装配套 Skills。',
+        },
+    },
+    // ── No-auth utilities (detect only) ────────────────────────────────────────
+    {
+        id: 'opencli',
+        binary: 'opencli',
+        name: 'OpenCLI',
+        description: 'Universal CLI hub — call 100+ websites and local binaries as agent-friendly commands via a browser bridge',
+        descriptionZh: '通用 CLI Hub — 借助浏览器桥接，把 100+ 网站与本地二进制变成 Agent 可调用的命令',
+        category: 'dev',
+        iconUrl: 'https://github.com/jackwener.png?size=80',
+        homepage: 'https://github.com/jackwener/opencli',
+        recommendedScope: 'global',
+        versionArgv: ['opencli', '--version'],
+        install: {
+            docs: 'https://github.com/jackwener/opencli#installation',
+            darwin: [{ label: 'npm', cmd: 'npm i -g @jackwener/opencli' }],
+            linux: [{ label: 'npm', cmd: 'npm i -g @jackwener/opencli' }],
+            win: [{ label: 'npm', cmd: 'npm i -g @jackwener/opencli' }],
+        },
+        auth: { type: 'none' },
+    },
+    {
+        id: 'docker',
+        binary: 'docker',
+        name: 'Docker',
+        description: 'Build, run, and ship containers',
+        descriptionZh: '构建、运行和分发容器',
+        category: 'dev',
+        iconSlug: 'docker',
+        homepage: 'https://docs.docker.com/engine/install/',
+        recommendedScope: 'global',
+        versionArgv: ['docker', '--version'],
+        install: {
+            docs: 'https://docs.docker.com/engine/install/',
+            darwin: [{ label: 'Docker Desktop', cmd: 'brew install --cask docker' }],
+            linux: [{ label: 'Script', cmd: 'curl -fsSL https://get.docker.com | sh' }],
+            win: [{ label: 'Docker Desktop', cmd: 'winget install Docker.DockerDesktop' }],
+        },
+        auth: { type: 'none' },
+    },
+    {
+        id: 'pnpm',
+        binary: 'pnpm',
+        name: 'pnpm',
+        description: 'Fast, disk-efficient Node package manager',
+        descriptionZh: '更快、更节省磁盘的 Node 包管理器',
+        category: 'dev',
+        iconSlug: 'pnpm',
+        homepage: 'https://pnpm.io/',
+        recommendedScope: 'global',
+        versionArgv: ['pnpm', '--version'],
+        install: {
+            docs: 'https://pnpm.io/installation',
+            darwin: [{ label: 'npm', cmd: 'npm i -g pnpm' }, { label: 'Homebrew', cmd: 'brew install pnpm' }],
+            linux: [{ label: 'npm', cmd: 'npm i -g pnpm' }],
+            win: [{ label: 'npm', cmd: 'npm i -g pnpm' }],
+        },
+        auth: { type: 'none' },
+    },
+];