@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.1

package/dist/onboarding.d.ts

@@ -4,6 +4,8 @@
  * (see src/ui/components/OnboardingPrompt.tsx); this module only exposes
  * pure(-ish) helpers it consumes, so there's a single input stack.
  */
+import { PROVIDERS, type ProviderDef } from "./data/model-metadata.js";
+export { PROVIDERS, type ProviderDef };
 export interface OnboardingResult {
     /**
      * Pool alias key (e.g. "deepseek-v4-pro"). The engine uses this to switch
@@ -17,25 +19,6 @@ export interface OnboardingResult {
     apiKey: string;
     baseUrl: string;
 }
-export interface ProviderDef {
-    id: string;
-    name: string;
-    envKey: string;
-    provider: string;
-    baseUrl: string;
-    keyUrl: string;
-    keyPrefix: string;
-    /**
-     * The catalog of model IDs to register for this provider. The first
-     * entry doubles as the zero-config default — auto-activated when the
-     * user boots with just an env key (no onboarding). Users override by
-     * picking in the wizard or running `/model`.
-     */
-    models: string[];
-    /** When true, skip API key prompt (e.g. local providers like Ollama). */
-    noKey?: boolean;
-}
-export declare const PROVIDERS: ProviderDef[];
 /**
  * Resolve the model list a provider should expose right now. For
  * OpenRouter this comes from the snapshot; for direct providers it
@@ -65,26 +48,6 @@ export declare function validateApiKey(baseUrl: string, apiKey: string): Promise
  * Priority: 1) command-line option  2) settings.json  3) all provider env vars
  */
 export declare function resolveApiKey(optionsApiKey?: string, settingsApiKey?: string): string | undefined;
-/**
- * Look up a previously-persisted API key for a given provider in
- * ~/.code-shell/settings.json. Matches by baseUrl (each ProviderDef.baseUrl
- * is unique, while `provider` is a generic kind like "openai" shared across
- * multiple endpoints).
- *
- * Returns the first match found in: settings.models[] (preferred — newer),
- * then settings.model (legacy top-level). undefined when nothing matches.
- */
-export declare function findSavedKeyForProvider(provider: ProviderDef): {
-    apiKey: string;
-    baseUrl: string;
-} | undefined;
-/**
- * Return the list of model IDs previously saved under this provider
- * (matched by baseUrl). Used by the onboarding wizard to pre-populate the
- * "model pool" step with the user's prior choices instead of resetting to
- * just the provider's first model.
- */
-export declare function loadSavedModelsForProvider(provider: ProviderDef): string[];
 export declare function hasApiKey(): boolean;
 /**
  * Resolve a model's max-output-token budget. Lookup order:
@@ -135,55 +98,22 @@ export declare function buildModelPool(provider: ProviderDef, apiKey: string): A
     maxContextTokens?: number;
 }>;
 export declare function modelDisplayName(model: string): string;
-export declare function saveSettings(result: OnboardingResult, providerDef?: ProviderDef, poolModels?: string[]): void;
 /**
- * Append-only persistence for the new ProviderModelFlow-based onboarding.
- *
- * Writes the new shape:
- *   - settings.activeKey      — primary source of truth for active model
- *   - settings.models[]       — self-describing entries (key, provider,
- *                                model, baseUrl, apiKey, maxOutput, maxContext)
- *   - settings.providers[]    — credential source for the wizard
- *   - settings.model.*        — legacy mirror of the active entry, kept in
- *                                sync so legacy boot paths (cli/main.ts,
- *                                repl.ts, run.ts) keep working without
- *                                each having to learn about activeKey
- *
- * Append-only: never removes existing entries. To start over use /logout.
- * Writes atomically via tmp+rename.
+ * 持久化 onboarding 结果到统一 catalog(credentials + modelConnections +
+ * defaults.text)。Append-only:相同 instanceId 跳过。defaults.text 设为 activeId。
+ * 原子写(tmp+rename)。(旧版写 legacy model.* / models / providers / activeKey,已删)
  */
 export declare function appendOnboardingResult(opts: {
-    /** Alias key the engine should switch to after writing. Matches one of addedModels[].key. */
-    activeKey: string;
-    /** Active entry's fields, used to mirror into the legacy settings.model.* block. */
-    activeMirror: {
-        provider: string;
-        model: string;
-        apiKey: string;
-        baseUrl: string;
-    };
-    addedProvider?: {
-        key: string;
-        label?: string;
+    /** 本次新增的模型实例(每个成为一个 modelConnection + credential)。 */
+    models: Array<{
+        instanceId: string;
         kind: string;
-        baseUrl: string;
-        apiKey?: string;
-        protocol?: string;
-        modelsPath?: string;
-    };
-    addedModels: Array<{
-        key: string;
-        label?: string;
-        providerKey?: string;
-        /** LLM client/protocol ("openai"/"anthropic"). New canonical name. */
-        protocol?: string;
-        /** Legacy mirror of `protocol`. Both are written so legacy readers keep working. */
-        provider?: string;
         model: string;
-        baseUrl: string;
         apiKey?: string;
-        maxContextTokens?: number;
-        maxOutputTokens?: number;
+        baseUrl?: string;
     }>;
+    /** 选中的活跃实例 id(写入 defaults.text)。 */
+    activeId: string;
+    tag?: "text" | "image" | "video";
 }): void;
 export declare function saveArenaSettingsByKeys(keys: string[]): void;

package/dist/onboarding.js

@@ -4,137 +4,19 @@
  * (see src/ui/components/OnboardingPrompt.tsx); this module only exposes
  * pure(-ish) helpers it consumes, so there's a single input stack.
  */
-import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync, rmSync } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync, rmSync, chmodSync } from "node:fs";
 import { join } from "node:path";
 import { userHome } from "./settings/manager.js";
 import { getOpenRouterModels } from "./data/openrouter-models.js";
+import { KNOWN_MAX_OUTPUT, KNOWN_CONTEXT_WINDOWS, OPENROUTER_VENDORS, PROVIDERS, } from "./data/model-metadata.js";
+// Re-exported so existing importers (and tests) can keep importing from
+// onboarding; the catalog data itself now lives in data/model-metadata.json.
+export { PROVIDERS };
 import { sanitizeApiKey } from "./llm/api-key-sanitize.js";
-export const PROVIDERS = [
-    {
-        id: "openrouter",
-        name: "OpenRouter (推荐 — 支持所有模型)",
-        envKey: "OPENROUTER_API_KEY",
-        provider: "openai",
-        baseUrl: "https://openrouter.ai/api/v1",
-        keyUrl: "https://openrouter.ai/keys",
-        keyPrefix: "sk-or-",
-        // First entry is the zero-config default (auto-activated when the
-        // user starts with only an env key, no onboarding). Sonnet beats Opus
-        // here because it's ~5x cheaper and a safer pick for someone who
-        // hasn't picked yet — Opus stays one slot away for anyone who wants it.
-        models: [
-            "anthropic/claude-sonnet-4.6",
-            "anthropic/claude-opus-4.7",
-            "anthropic/claude-haiku-4.5",
-            "openai/gpt-5",
-            "openai/gpt-5-mini",
-            "openai/gpt-4o",
-            "openai/o4-mini",
-            "openai/o3",
-            "google/gemini-2.5-pro",
-            "google/gemini-2.5-flash",
-            "deepseek/deepseek-chat",
-            "deepseek/deepseek-reasoner",
-            "qwen/qwen3-coder",
-            "meta-llama/llama-4-maverick",
-        ],
-    },
-    {
-        id: "anthropic",
-        name: "Anthropic (直连 Claude API)",
-        envKey: "ANTHROPIC_API_KEY",
-        provider: "anthropic",
-        baseUrl: "https://api.anthropic.com",
-        keyUrl: "https://console.anthropic.com/settings/keys",
-        keyPrefix: "sk-ant-",
-        models: [
-            "claude-sonnet-4-6",
-            "claude-opus-4-7",
-            "claude-haiku-4-5",
-        ],
-    },
-    {
-        id: "openai",
-        name: "OpenAI",
-        envKey: "OPENAI_API_KEY",
-        provider: "openai",
-        baseUrl: "https://api.openai.com/v1",
-        keyUrl: "https://platform.openai.com/api-keys",
-        keyPrefix: "sk-",
-        models: ["gpt-5", "gpt-5-mini", "gpt-5-nano", "gpt-4o", "o4-mini", "o3"],
-    },
-    {
-        id: "deepseek",
-        name: "DeepSeek (官方直连)",
-        envKey: "DEEPSEEK_API_KEY",
-        provider: "openai",
-        baseUrl: "https://api.deepseek.com/v1",
-        keyUrl: "https://platform.deepseek.com/api_keys",
-        keyPrefix: "sk-",
-        models: ["deepseek-v4-pro", "deepseek-v4-flash", "deepseek-chat"],
-    },
-    {
-        id: "zai",
-        name: "Z.AI (GLM 官方)",
-        envKey: "ZAI_API_KEY",
-        provider: "openai",
-        baseUrl: "https://api.z.ai/api/paas/v4",
-        keyUrl: "https://z.ai/manage-apikey/apikey-list",
-        keyPrefix: "",
-        models: ["glm-5.1", "glm-4.6", "glm-4.5-air"],
-    },
-    {
-        id: "gemini",
-        name: "Google Gemini (官方直连)",
-        envKey: "GEMINI_API_KEY",
-        provider: "openai",
-        baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
-        keyUrl: "https://aistudio.google.com/apikey",
-        keyPrefix: "",
-        models: [
-            "gemini-2.5-pro",
-            "gemini-2.5-flash",
-            "gemini-2.0-flash",
-        ],
-    },
-    {
-        id: "ollama",
-        name: "Ollama (本地，无需 Key)",
-        envKey: "",
-        provider: "openai",
-        baseUrl: "http://localhost:11434/v1",
-        keyUrl: "https://ollama.com/library",
-        keyPrefix: "",
-        models: ["llama3.1", "qwen2.5-coder", "deepseek-r1", "mistral", "gemma3"],
-        noKey: true,
-    },
-    {
-        id: "custom",
-        name: "自定义 (任何 OpenAI 兼容 API)",
-        envKey: "",
-        provider: "openai",
-        baseUrl: "",
-        keyUrl: "",
-        keyPrefix: "",
-        models: [],
-    },
-];
+import { getMergedCatalog } from "./model-catalog/index.js";
+// ProviderDef 类型 + PROVIDERS 目录已外移到 data/model-metadata.json
+// (loader: data/model-metadata.ts),并在文件顶部 re-export。core 只读目录数据。
 // ─── Dynamic model list (OpenRouter snapshot) ────────────────────
-/**
- * Curated vendors and how many of their newest models to surface in the
- * onboarding picker. Order matters — first vendors appear first.
- * Tweak this if a new vendor becomes worth exposing in the picker.
- */
-const OPENROUTER_VENDORS = [
-    { prefix: "anthropic/", take: 4 },
-    { prefix: "openai/", take: 5 },
-    { prefix: "google/", take: 3 },
-    { prefix: "deepseek/", take: 3 },
-    { prefix: "x-ai/", take: 2 },
-    { prefix: "qwen/", take: 2 },
-    { prefix: "meta-llama/", take: 2 },
-    { prefix: "mistralai/", take: 1 },
-];
 /**
  * Build the OpenRouter model picker list from the bundled snapshot.
  * Filters out `:free`/preview variants for the default picker (still
@@ -226,9 +108,12 @@ export function detectProviderFromApiKey(apiKey, baseUrl) {
 // ─── API key validation ────────────────────────────────────────────
 export async function validateApiKey(baseUrl, apiKey) {
     try {
+        // 10s timeout so a hung/slow provider doesn't block the onboarding wizard
+        // until the OS socket timeout — AbortError is caught below → "let it pass".
         if (baseUrl.includes("openrouter")) {
             const res = await fetch("https://openrouter.ai/api/v1/auth/key", {
                 headers: { Authorization: `Bearer ${apiKey}` },
+                signal: AbortSignal.timeout(10_000),
             });
             const data = await res.json();
             return !data.error;
@@ -236,6 +121,7 @@ export async function validateApiKey(baseUrl, apiKey) {
         const url = baseUrl.replace(/\/$/, "") + "/models";
         const res = await fetch(url, {
             headers: { Authorization: `Bearer ${apiKey}` },
+            signal: AbortSignal.timeout(10_000),
         });
         return res.status !== 401 && res.status !== 403;
     }
@@ -267,87 +153,21 @@ export function resolveApiKey(optionsApiKey, settingsApiKey) {
     }
     return undefined;
 }
-/**
- * Look up a previously-persisted API key for a given provider in
- * ~/.code-shell/settings.json. Matches by baseUrl (each ProviderDef.baseUrl
- * is unique, while `provider` is a generic kind like "openai" shared across
- * multiple endpoints).
- *
- * Returns the first match found in: settings.models[] (preferred — newer),
- * then settings.model (legacy top-level). undefined when nothing matches.
- */
-export function findSavedKeyForProvider(provider) {
-    const file = join(userHome(), ".code-shell", "settings.json");
-    if (!existsSync(file))
-        return undefined;
-    let data;
-    try {
-        data = JSON.parse(readFileSync(file, "utf-8"));
-    }
-    catch {
-        return undefined;
-    }
-    if (Array.isArray(data?.models)) {
-        for (const m of data.models) {
-            if (m?.apiKey && m?.baseUrl === provider.baseUrl) {
-                return { apiKey: String(m.apiKey), baseUrl: String(m.baseUrl) };
-            }
-        }
-    }
-    if (data?.model?.apiKey && data?.model?.baseUrl === provider.baseUrl) {
-        return {
-            apiKey: String(data.model.apiKey),
-            baseUrl: String(data.model.baseUrl),
-        };
-    }
-    return undefined;
-}
-/**
- * Return the list of model IDs previously saved under this provider
- * (matched by baseUrl). Used by the onboarding wizard to pre-populate the
- * "model pool" step with the user's prior choices instead of resetting to
- * just the provider's first model.
- */
-export function loadSavedModelsForProvider(provider) {
-    const file = join(userHome(), ".code-shell", "settings.json");
-    if (!existsSync(file))
-        return [];
-    let data;
-    try {
-        data = JSON.parse(readFileSync(file, "utf-8"));
-    }
-    catch {
-        return [];
-    }
-    if (!Array.isArray(data?.models))
-        return [];
-    const out = [];
-    for (const m of data.models) {
-        if (m?.baseUrl === provider.baseUrl && typeof m?.model === "string") {
-            out.push(m.model);
-        }
-    }
-    return out;
-}
 export function hasApiKey() {
     // Env variables alone are NOT enough to skip onboarding — they're surfaced
     // as a one-click option on the provider page instead. We only skip when the
-    // user has explicitly persisted a config. Checks all three locations the
-    // wizard might write to: top-level model.apiKey (legacy), models[].apiKey
-    // (per-pool-entry), providers[].apiKey (per-provider — what the current
-    // ProviderModelFlow actually writes). Missing any one of these made
-    // /logout look like a no-op when the others still held credentials.
+    // user has explicitly persisted a config. Unified catalog: a credential with
+    // an apiKey, or any configured modelConnection, counts as "set up". The
+    // legacy model.apiKey / models[] / providers[] locations were removed.
     // Reads ~/.code-shell/ only — ~/.claude/ compat was dropped because Claude
     // Code's settings schema diverges and merging broke boot.
     const p = join(userHome(), ".code-shell", "settings.json");
     if (existsSync(p)) {
         try {
             const data = JSON.parse(readFileSync(p, "utf-8"));
-            if (data?.model?.apiKey)
-                return true;
-            if (Array.isArray(data?.models) && data.models.some((m) => m?.apiKey))
+            if (Array.isArray(data?.credentials) && data.credentials.some((c) => c?.apiKey))
                 return true;
-            if (Array.isArray(data?.providers) && data.providers.some((p) => p?.apiKey))
+            if (Array.isArray(data?.modelConnections) && data.modelConnections.length > 0)
                 return true;
         }
         catch { /* ignore */ }
@@ -355,54 +175,8 @@ export function hasApiKey() {
     return false;
 }
 // ─── Model pool helpers ───────────────────────────────────────────
-/** Known max output tokens for common models. */
-const KNOWN_MAX_OUTPUT = {
-    "anthropic/claude-opus-4.7": 32000,
-    "anthropic/claude-opus-4-7": 32000,
-    "claude-opus-4-7": 32000,
-    "anthropic/claude-sonnet-4.6": 16000,
-    "anthropic/claude-sonnet-4-6": 16000,
-    "claude-sonnet-4-6": 16000,
-    "anthropic/claude-haiku-4.5": 8192,
-    "anthropic/claude-haiku-4-5": 8192,
-    "claude-haiku-4-5": 8192,
-    "openai/gpt-5": 32000,
-    "openai/gpt-5-mini": 32000,
-    "openai/gpt-5-nano": 16000,
-    "gpt-5": 32000,
-    "gpt-5-mini": 32000,
-    "gpt-5-nano": 16000,
-    "openai/gpt-4o": 16384,
-    "gpt-4o": 16384,
-    "openai/o4-mini": 100000,
-    "o4-mini": 100000,
-    "openai/o3": 100000,
-    "o3": 100000,
-    "google/gemini-2.5-pro": 65536,
-    "google/gemini-2.5-flash": 65536,
-    "gemini-2.5-pro": 65536,
-    "gemini-2.5-flash": 65536,
-    "gemini-2.0-flash": 8192,
-    "deepseek/deepseek-v3.2": 8192,
-    "deepseek/deepseek-r1": 8192,
-    "deepseek-v4-flash": 8192,
-    "deepseek-v4-pro": 65536,
-    "deepseek-chat": 8192,
-    "qwen/qwen3-coder": 16384,
-    "meta-llama/llama-4-maverick": 32000,
-};
-/**
- * Known context window sizes for direct-provider models (not routed through OpenRouter).
- * These are the models whose IDs don't include a "vendor/" prefix.
- */
-const KNOWN_CONTEXT_WINDOWS = {
-    "deepseek-v4-pro": 1_000_000,
-    "deepseek-v4-flash": 1_000_000,
-    "deepseek-chat": 1_000_000,
-    "deepseek/deepseek-chat": 1_000_000,
-    "deepseek/deepseek-v4-pro": 1_000_000,
-    "deepseek/deepseek-v4-flash": 1_000_000,
-};
+// KNOWN_MAX_OUTPUT / KNOWN_CONTEXT_WINDOWS now live in data/model-metadata.json
+// (imported above) so they can be updated without a code change.
 /**
  * Resolve a model's max-output-token budget. Lookup order:
  *   1. KNOWN_MAX_OUTPUT (covers direct providers like Anthropic/DeepSeek
@@ -505,57 +279,22 @@ export function modelDisplayName(model) {
         return `Gemini ${parts.slice(1).join("-")}`;
     return base.charAt(0).toUpperCase() + base.slice(1);
 }
-export function saveSettings(result, providerDef, poolModels) {
-    const dir = join(userHome(), ".code-shell");
-    const file = join(dir, "settings.json");
-    mkdirSync(dir, { recursive: true });
-    let existing = {};
-    if (existsSync(file)) {
-        try {
-            existing = JSON.parse(readFileSync(file, "utf-8"));
-        }
-        catch { }
-    }
-    const updated = {
-        ...existing,
-        model: {
-            ...(typeof existing.model === "object" ? existing.model : {}),
-            provider: result.provider,
-            name: result.model,
-            apiKey: result.apiKey,
-            baseUrl: result.baseUrl,
-        },
-    };
-    // Merge model pool: keep entries from other providers (matched by baseUrl)
-    // and replace just the current provider's slice. A naive overwrite would
-    // wipe out every other provider's models every time the wizard runs.
-    if (providerDef && poolModels && poolModels.length > 0) {
-        const newEntries = buildModelPool(providerDef, result.apiKey).filter((e) => new Set(poolModels).has(e.model));
-        const existingModels = Array.isArray(existing.models)
-            ? existing.models
-            : [];
-        const otherProvider = existingModels.filter((e) => e?.baseUrl !== providerDef.baseUrl);
-        updated.models = [...otherProvider, ...newEntries];
-    }
-    writeFileSync(file, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+/**
+ * Map a provider kind → catalogId. If a builtin (or user) TEXT catalog entry
+ * with id===kind exists, use it; otherwise fall back to the generic "custom"
+ * OpenAI-compatible entry. resolveInstance() returns null for an unknown
+ * catalogId, so every connection's catalogId MUST exist in the merged catalog.
+ */
+function catalogIdForKind(kind) {
+    return getMergedCatalog().some((e) => e.id === kind && e.tag === "text") ? kind : "custom";
 }
 /**
- * Append-only persistence for the new ProviderModelFlow-based onboarding.
- *
- * Writes the new shape:
- *   - settings.activeKey      — primary source of truth for active model
- *   - settings.models[]       — self-describing entries (key, provider,
- *                                model, baseUrl, apiKey, maxOutput, maxContext)
- *   - settings.providers[]    — credential source for the wizard
- *   - settings.model.*        — legacy mirror of the active entry, kept in
- *                                sync so legacy boot paths (cli/main.ts,
- *                                repl.ts, run.ts) keep working without
- *                                each having to learn about activeKey
- *
- * Append-only: never removes existing entries. To start over use /logout.
- * Writes atomically via tmp+rename.
+ * 持久化 onboarding 结果到统一 catalog(credentials + modelConnections +
+ * defaults.text)。Append-only:相同 instanceId 跳过。defaults.text 设为 activeId。
+ * 原子写(tmp+rename)。(旧版写 legacy model.* / models / providers / activeKey,已删)
  */
 export function appendOnboardingResult(opts) {
+    const tag = opts.tag ?? "text";
     const dir = join(userHome(), ".code-shell");
     const file = join(dir, "settings.json");
     mkdirSync(dir, { recursive: true });
@@ -564,52 +303,44 @@ export function appendOnboardingResult(opts) {
         try {
             existing = JSON.parse(readFileSync(file, "utf-8"));
         }
-        catch {
-            /* ignore — corrupt file is replaced */
-        }
+        catch { /* corrupt → replace */ }
     }
-    // Append provider (skip if key already present).
-    const existingProviders = Array.isArray(existing.providers)
-        ? existing.providers
-        : [];
-    let providersOut = existingProviders;
-    if (opts.addedProvider) {
-        const has = existingProviders.some((p) => p?.key === opts.addedProvider.key);
-        if (!has)
-            providersOut = [...existingProviders, opts.addedProvider];
+    const creds = Array.isArray(existing.credentials)
+        ? [...existing.credentials] : [];
+    const conns = Array.isArray(existing.modelConnections)
+        ? [...existing.modelConnections] : [];
+    for (const m of opts.models) {
+        const catalogId = catalogIdForKind(m.kind);
+        const credId = `${m.instanceId}-key`;
+        if (!creds.some((c) => c?.id === credId)) {
+            creds.push({ id: credId, catalogId, apiKey: m.apiKey, baseUrl: m.baseUrl });
+        }
+        if (!conns.some((c) => c?.id === m.instanceId)) {
+            conns.push({
+                id: m.instanceId, catalogId, tag, model: m.model, credentialId: credId,
+                ...(m.baseUrl ? { baseUrl: m.baseUrl } : {}),
+            });
+        }
     }
-    // Append models (skip entries whose key already exists — the wizard
-    // already derives unique keys via deriveModelPoolKey, so a collision
-    // means the user re-added the exact same alias and we leave the older
-    // entry alone rather than silently overwriting credentials).
-    const existingModels = Array.isArray(existing.models)
-        ? existing.models
-        : [];
-    const existingKeys = new Set(existingModels.map((m) => m?.key));
-    const modelsToAppend = opts.addedModels.filter((m) => !existingKeys.has(m.key));
+    const existingDefaults = (typeof existing.defaults === "object" && existing.defaults)
+        ? existing.defaults : {};
     const updated = {
         ...existing,
-        activeKey: opts.activeKey,
-        model: {
-            ...(typeof existing.model === "object" && existing.model ? existing.model : {}),
-            provider: opts.activeMirror.provider,
-            name: opts.activeMirror.model,
-            apiKey: opts.activeMirror.apiKey,
-            baseUrl: opts.activeMirror.baseUrl,
-        },
-        providers: providersOut,
-        models: [...existingModels, ...modelsToAppend],
+        credentials: creds,
+        modelConnections: conns,
+        defaults: { ...existingDefaults, [tag]: opts.activeId },
     };
     // Atomic write: tmp file in the same dir, then rename (atomic on POSIX).
+    // mode 0o600 — settings.json holds plaintext API keys, must be owner-only.
     const tmp = `${file}.${process.pid}.tmp`;
-    writeFileSync(tmp, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+    writeFileSync(tmp, JSON.stringify(updated, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
     try {
         renameSync(tmp, file);
     }
     catch {
         // Fallback: best-effort direct write if rename fails (e.g. cross-device),
         // then remove the orphaned temp file the failed rename left behind.
-        writeFileSync(file, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+        writeFileSync(file, JSON.stringify(updated, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
         rmSync(tmp, { force: true });
     }
 }
@@ -628,5 +359,9 @@ export function saveArenaSettingsByKeys(keys) {
         ...existing,
         arena: { participants: keys },
     };
-    writeFileSync(file, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+    writeFileSync(file, JSON.stringify(updated, null, 2) + "\n", { encoding: "utf-8", mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch { /* best-effort */ }
 }

package/dist/plugins/gitOps.d.ts

@@ -21,6 +21,14 @@ export type GitResult = {
     ok: false;
     error: string;
 };
+/**
+ * On a fresh macOS without the Command Line Tools, `/usr/bin/git` is an `xcrun`
+ * stub that spawns fine (so `isGitAvailable()`'s findExecutable check is fooled)
+ * but exits non-zero with an xcrun error on stderr. Classify that as a
+ * missing-git condition so runGit returns GIT_NOT_FOUND and the host shows the
+ * friendly "install Git" guidance instead of leaking the raw xcrun error.
+ */
+export declare function isMissingDeveloperToolsStderr(stderr: string): boolean;
 /**
  * Force git to never prompt interactively. gitOps runs in headless contexts
  * (the Electron main process, the agent worker) that have no TTY, so a
@@ -47,10 +55,16 @@ export declare function nonInteractiveGitEnv(base: NodeJS.ProcessEnv): NodeJS.Pr
  * (.claude-plugin and .agents/plugins). On any failure of the sparse setup we
  * fall back to checking out the full tree, so correctness never depends on
  * sparse support being present.
+ *
+ * Pass `full: true` to skip sparse entirely and check out the whole tree. This
+ * is required when the caller reads arbitrary plugin content from the clone
+ * (installing a plugin or a plugin subdir), as opposed to a marketplace where
+ * only the manifest dirs are needed up front.
  */
 export declare function gitClone(url: string, destDir: string, options?: {
     ref?: string;
     sparsePaths?: string[];
+    full?: boolean;
 }): Promise<GitResult>;
 /**
  * Expand a sparse-checkout to include an additional path (a plugin subdir),
@@ -59,6 +73,11 @@ export declare function gitClone(url: string, destDir: string, options?: {
  */
 export declare function gitSparseCheckoutAdd(repoDir: string, relPath: string): Promise<GitResult>;
 export declare function gitRevParseHead(repoDir: string): Promise<GitResult>;
+/**
+ * Resolve a ref (default HEAD) on a remote git URL WITHOUT cloning — one
+ * cheap network round-trip. Returns the 40-char SHA on success.
+ */
+export declare function gitLsRemote(url: string, ref?: string): Promise<GitResult>;
 export declare function gitFetchAndReset(repoDir: string, ref?: string): Promise<GitResult>;
 /**
  * Github source helper: convert "owner/repo" to an https clone URL.