cartethyia 2.7.5 → 2.7.7

package/src/console/cli-tools/cartethyia-websearch-plugin.ts

@@ -0,0 +1,186 @@
+/**
+ * OpenCode websearch provider plugin generation.
+ *
+ * The Console writes `websearch.provider = "<provider>"` into the user's
+ * opencode.jsonc. That value resolves to a WebSearch provider the local plugin
+ * below registers with OpenCode. The plugin reads the gateway URL and API key
+ * from the matching provider entry in opencode.jsonc — the same provider block
+ * the injector writes — so the search route follows the configured provider.
+ *
+ * OpenCode loads every `.js` file under `~/.config/opencode/plugins/`
+ * (or `<config-dir>/plugins/`) as a plugin; no registration step is needed
+ * beyond writing the file.
+ */
+import { ensureDir, fileExists, join, removeFile, writeTextFileWithBackup } from "./fs-ops";
+
+const PLUGIN_FILENAME = (providerName: string) => `${providerName}-websearch.js`;
+
+/** Escapes the provider name for use inside a JS double-quoted string. */
+function jsStringLiteral(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+
+/**
+ * Renders the websearch plugin source for one provider name.
+ *
+ * `providerName` is the exact provider key written into opencode.jsonc (e.g.
+ * `Cartethyia`, `CarteLocal`). The plugin reads that block's `baseURL` and
+ * `apiKey` as the single source of truth, so no secret is duplicated anywhere.
+ */
+export function renderWebsearchPlugin(providerName: string): string {
+  const quoted = jsStringLiteral(providerName);
+  return `// ${quoted}-websearch — route OpenCode's built-in websearch tool through the
+// Cartethyia gateway's /v1/search native route, using the "${quoted}"
+// provider block in opencode.jsonc as the single source of truth.
+//
+// Generated by the Cartethyia console (CLI tools → OpenCode). Do not edit by
+// hand; re-apply the tool config to regenerate.
+//
+// Env overrides (all optional):
+//   CARTETHYIA_SEARCH_URL      (default: the provider's baseURL + /search)
+//   CARTETHYIA_SEARCH_API_KEY  (default: the provider's apiKey)
+//   CARTETHYIA_SEARCH_BACKEND  (default: "exa"; "parallel" also works)
+
+import { Plugin } from "@opencode/plugin";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+function pick(obj, keys) {
+  for (const k of keys) {
+    const v = obj?.[k];
+    if (v !== undefined && v !== null) return v;
+  }
+  return undefined;
+}
+
+// Pull the "${quoted}" provider's baseURL/apiKey out of opencode.jsonc.
+// The file is JSONC (comments allowed) so search for the provider block
+// loosely rather than parsing strictly.
+function readProviderSettings() {
+  const candidates = [
+    process.env.OPENCODE_CONFIG,
+    join(homedir(), ".config", "opencode", "opencode.jsonc"),
+    join(homedir(), ".config", "opencode", "opencode.json"),
+  ];
+  for (const path of candidates) {
+    if (!path) continue;
+    let text;
+    try {
+      text = readFileSync(path, "utf8");
+    } catch {
+      continue;
+    }
+    // Find the provider block, then the next provider block or closing brace.
+    const providerStart = text.indexOf(\`"\${PROVIDER_NAME}"\`);
+    if (providerStart < 0) continue;
+    const settingsMatch = text.slice(providerStart).match(/"settings"\\s*:\\s*\\{/);
+    if (!settingsMatch) continue;
+    const settingsStart = providerStart + settingsMatch.index + settingsMatch[0].length - 1;
+    let depth = 0;
+    let end = -1;
+    for (let i = settingsStart; i < text.length; i++) {
+      const ch = text[i];
+      if (ch === "{") depth += 1;
+      else if (ch === "}") {
+        depth -= 1;
+        if (depth === 0) {
+          end = i;
+          break;
+        }
+      }
+    }
+    if (end < 0) continue;
+    const settings = text.slice(settingsStart, end + 1);
+    const baseURL = settings.match(/"baseURL"\\s*:\\s*"([^"]+)"/)?.[1];
+    const apiKey = settings.match(/"apiKey"\\s*:\\s*"([^"]+)"/)?.[1];
+    if (baseURL) {
+      return { baseURL, apiKey };
+    }
+  }
+  return { baseURL: undefined, apiKey: undefined };
+}
+
+const PROVIDER_NAME = "${quoted}";
+const local = readProviderSettings();
+const BASE_URL = (process.env.CARTETHYIA_SEARCH_URL || (local.baseURL ? \`\${local.baseURL.replace(/\\/+$/, "")}/search\` : "")).replace(/\\/+$/, "");
+const API_KEY = process.env.CARTETHYIA_SEARCH_API_KEY || local.apiKey || "";
+const BACKEND = process.env.CARTETHYIA_SEARCH_BACKEND || "exa";
+
+export default Plugin.define({
+  id: "${quoted}-websearch",
+  async setup(ctx) {
+    await ctx.websearch.transform((editor) => {
+      editor.add({
+        id: "${quoted}",
+        name: "Cartethyia Search",
+        execute: async ({ query }, { signal }) => {
+          if (!BASE_URL) {
+            throw new Error(
+              "Cartethyia search gateway is not configured: set CARTETHYIA_SEARCH_URL or add a ${quoted} provider with baseURL in opencode.jsonc",
+            );
+          }
+          const response = await fetch(BASE_URL, {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              ...(API_KEY ? { authorization: \`Bearer \${API_KEY}\` } : {}),
+            },
+            body: JSON.stringify({
+              model: BACKEND,
+              query,
+              max_results: 8,
+            }),
+            signal,
+          });
+          if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            throw new Error(
+              \`Cartethyia search failed (HTTP \${response.status}): \${text.slice(0, 200)}\`,
+            );
+          }
+          const data = await response.json();
+          const results = Array.isArray(data?.results) ? data.results : [];
+          return results.map((item) => ({
+            url: String(item?.url ?? ""),
+            title: typeof item?.title === "string" && item.title ? item.title : undefined,
+            content: typeof item?.snippet === "string" && item.snippet ? item.snippet : undefined,
+            time:
+              typeof item?.published_at === "string" && item.published_at
+                ? { published: Date.parse(item.published_at) || undefined }
+                : {},
+          }));
+        },
+      });
+      editor.default.set("${quoted}");
+    });
+  },
+});
+`;
+}
+
+/** Writes the websearch plugin for a provider into the OpenCode config dir. */
+export async function writeWebsearchPlugin(
+  configDir: string,
+  providerName: string,
+): Promise<string> {
+  const pluginsDir = join(configDir, "plugins");
+  await ensureDir(pluginsDir);
+  const filename = PLUGIN_FILENAME(providerName);
+  const target = join(pluginsDir, filename);
+  await writeTextFileWithBackup(target, renderWebsearchPlugin(providerName));
+  return target;
+}
+
+/** Removes the websearch plugin for a provider from the OpenCode config dir. */
+export async function removeWebsearchPlugin(
+  configDir: string,
+  providerName: string,
+): Promise<boolean> {
+  const target = join(configDir, "plugins", PLUGIN_FILENAME(providerName));
+  if (await fileExists(target)) {
+    await removeFile(target);
+    return true;
+  }
+  return false;
+}

package/src/console/cli-tools/contracts.ts

@@ -6,12 +6,11 @@ import { ensureV1Suffix } from "./fs-ops";
  * CLI Tools type contracts — shared across registry, injectors, service,
  * dashboard, and API routes.
  *
- * Each supported CLI coding agent ([CC], Codex, Cline, etc.) has a `ToolDef`
- * with static metadata and (when `configType !== "guide"`) a paired
- * `ToolInjector` that reads and writes the tool's config files on the host
- * filesystem. The dashboard picks an API key + models, POSTs to the backend,
- * and the injector merges Cartethyia-specific fields into the tool's config
- * without clobbering user settings.
+ * Each supported CLI coding agent ([CC], Codex, Kilo, OpenCode) has a `ToolDef`
+ * with static metadata and a paired `ToolInjector` that reads and writes the
+ * tool's config files on the host filesystem. The dashboard picks an API key +
+ * models, POSTs to the backend, and the injector merges Cartethyia-specific
+ * fields into the tool's config without clobbering user settings.
  */
 
 /**
@@ -22,7 +21,7 @@ import { ensureV1Suffix } from "./fs-ops";
 type CliToolSurface = "chat" | "responses" | "messages";
 
 /** How the tool's config is managed. */
-type ConfigType = "env" | "custom" | "guide";
+type ConfigType = "env" | "custom";
 
 /** A native model slot exposed by a CLI tool. */
 interface ToolModelDef {
@@ -53,6 +52,13 @@ export interface CliMappingInput {
 /** The user-facing routing mode for a CLI tool: `remote` routes are resolved by the gateway, `local` routes are baked into the tool's own config file. */
 export type CliMappingMode = "remote" | "local";
 
+/**
+ * The default runtime SDK package for OpenCode: its native
+ * `@opencode/ai/providers/openai-compatible` package (bundled with OpenCode
+ * itself, not the AI SDK).
+ */
+export const DEFAULT_SDK: string = "@opencode/ai/providers/openai-compatible";
+
 /** Persisted mapping settings for one CLI tool + API key pair. */
 export interface CliMappingSettings {
   readonly toolId: string;
@@ -68,21 +74,6 @@ interface ToolNote {
   readonly text: string;
 }
 
-/** A guide step for guide-only tools. */
-interface GuideStep {
-  readonly step: number;
-  readonly title: string;
-  readonly desc?: string;
-  readonly value?: string;
-  readonly type?: "apiKeySelector" | "modelSelector";
-}
-
-/** A code block for guide-only tools. */
-interface GuideCodeBlock {
-  readonly language: string;
-  readonly code: string;
-}
-
 /** Static metadata for a CLI tool — consumed by both backend and frontend. */
 export interface ToolDef {
   readonly id: string;
@@ -95,8 +86,6 @@ export interface ToolDef {
   readonly settingsFile?: string;
   readonly docsUrl?: string;
   readonly notes?: readonly ToolNote[];
-  readonly guideSteps?: readonly GuideStep[];
-  readonly codeBlock?: GuideCodeBlock;
   /**
    * How this tool's slot→route mapping behaves, which also decides whether the
    * tool has a mapping surface at all.
@@ -109,9 +98,7 @@ export interface ToolDef {
    *   so a slot has one value (written to the file) rather than a separate
    *   target. There is nothing to persist; the model is baked into the file.
    *
-   * Absent means the tool exposes no configurable model slots at all (a
-   * guide-only tool). This replaces a separate `mappingSupported` flag that
-   * had to be kept consistent with the mode by hand — the mode already says it.
+   * Absent means the tool exposes no configurable model slots at all.
    */
   readonly mappingMode?: CliMappingMode;
 }
@@ -137,8 +124,6 @@ export type ToolRegistryEntry = Pick<
   | "settingsFile"
   | "docsUrl"
   | "notes"
-  | "guideSteps"
-  | "codeBlock"
 > & { readonly mappingSupported: boolean };
 
 /** Runtime status of a CLI tool on the host. */
@@ -175,6 +160,17 @@ export interface ApplyInput {
   readonly mapping?: CliMappingInput;
   /** Enables [CC]'s bypass-permissions (YOLO) mode when explicitly selected. */
   readonly bypassPermissions?: boolean;
+  /**
+   * The runtime SDK package to write into the tool's config (e.g. OpenCode's
+   * `provider.*.npm`). Absent = the tool's default.
+   */
+  readonly sdk?: string;
+  /**
+   * WebSearch provider selection written into OpenCode's config. "carte"
+   * routes search through the Cartethyia gateway; "native" (or absent) leaves
+   * OpenCode's own provider selection in place.
+   */
+  readonly websearch?: string;
 }
 
 /** Result of an apply or reset operation. */
@@ -182,6 +178,8 @@ export interface ApplyResult {
   readonly success: boolean;
   readonly settingsPath?: string;
   readonly message: string;
+  /** Non-fatal notes for the operator, e.g. preserved pre-existing providers. */
+  readonly warnings?: readonly string[];
 }
 
 /**
@@ -195,9 +193,9 @@ export interface ApplyResult {
  *   persisted routing rows on each `/v1/*` call. Works when the gateway is
  *   remote, containerised, or the CLI lives on another machine.
  * - `both` — the tool's config was written and a remote route was recorded.
- * - `none` — nothing ran: the tool has no injectable config (a guide tool) and
- *   the request asked for no remote route. Reported rather than folded into
- *   `file`, so the UI never claims a write that did not happen.
+ * - `none` — nothing ran: the tool has no injectable config and the request
+ *   asked for no remote route. Reported rather than folded into `file`, so
+ *   the UI never claims a write that did not happen.
  */
 export type ApplyOutcome = "file" | "remote" | "both" | "none";
 
@@ -210,6 +208,8 @@ export interface ApplyConfigResult {
   readonly savedRemoteRoute: boolean;
   readonly settingsPath?: string;
   readonly message: string;
+  /** Non-fatal notes for the operator (see `ApplyResult.warnings`). */
+  readonly warnings?: readonly string[];
 }
 
 /** Result of a download-config operation. */
@@ -220,8 +220,7 @@ export interface DownloadResult {
 }
 
 /**
- * Injector contract — one per file-based tool.
- * Guide-only tools share a single GuideInjector that generates config text.
+ * Injector contract — one per tool.
  */
 export interface ToolInjector {
   readonly toolId: string;
@@ -325,8 +324,12 @@ export interface InjectorSpec {
   /** Extract status details from existing settings file(s) */
   readonly readStatus: (path: string) => Promise<StatusDetails> | StatusDetails;
 
-  /** Apply Cartethyia configuration to the settings file(s) */
-  readonly apply: (input: ApplyInput, path: string) => Promise<void> | void;
+  /**
+   * Apply Cartethyia configuration to the settings file(s). Return an array of
+   * non-fatal warning strings to surface them to the operator (e.g. preserved
+   * pre-existing providers).
+   */
+  readonly apply: (input: ApplyInput, path: string) => Promise<readonly string[] | void> | readonly string[] | void;
 
   /**
    * Reset Cartethyia configuration from settings file(s).
@@ -449,32 +452,6 @@ export const TOOL_REGISTRY = {
     ],
   },
 
-  cline: {
-    id: "cline",
-    name: "Cline",
-    color: "#00D1B2",
-    description: "Cline AI Coding Assistant (VS Code)",
-    configType: "custom" as const,
-    surface: "chat" as const,
-    settingsFile: "~/.cline/data/globalState.json",
-    defaultModels: [
-      {
-        id: "claude/claude-sonnet-5",
-        name: "Claude Sonnet 5",
-        alias: "sonnet",
-        roleLabel: "Primary Agent",
-        roleKind: "primary",
-      },
-      {
-        id: "claude/claude-opus-4-8",
-        name: "Claude Opus",
-        alias: "opus",
-        roleLabel: "Advanced Agent",
-        roleKind: "secondary",
-      },
-    ],
-  },
-
   opencode: {
     id: "opencode",
     name: "OpenCode",
@@ -501,86 +478,6 @@ export const TOOL_REGISTRY = {
     ],
   },
 
-  droid: {
-    id: "droid",
-    name: "Factory Droid",
-    color: "#00D4FF",
-    description: "Factory Droid AI Assistant",
-    configType: "custom" as const,
-    surface: "chat" as const,
-    settingsFile: "~/.factory/settings.json",
-    defaultModels: [
-      { id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" },
-      { id: "gpt-5.6-sol", name: "GPT-5.6 Sol", alias: "gpt-5.6-sol" },
-    ],
-  },
-
-  hermes: {
-    id: "hermes",
-    name: "Hermes Agent",
-    color: "#8B5CF6",
-    description: "Nous Research self-improving AI agent",
-    configType: "custom" as const,
-    surface: "chat" as const,
-    settingsFile: "~/.hermes/config.yaml",
-    defaultModels: [{ id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" }],
-  },
-
-  "grok-build": {
-    id: "grok-build",
-    name: "Grok Build",
-    color: "#1DA1F2",
-    description: "xAI Grok Build CLI",
-    configType: "custom" as const,
-    surface: "chat" as const,
-    settingsFile: "~/.grok/config.toml",
-    defaultModels: [{ id: "grok/grok-4", name: "Grok 4", alias: "grok-4" }],
-  },
-
-  copilot: {
-    id: "copilot",
-    name: "GitHub Copilot",
-    color: "#1F6FEB",
-    description: "GitHub Copilot Chat (VS Code chatLanguageModels.json)",
-    configType: "custom" as const,
-    surface: "chat" as const,
-    settingsFile: "Code/User/chatLanguageModels.json",
-    defaultModels: [
-      { id: "gpt-5.6-sol", name: "GPT-5.6 Sol", alias: "gpt-5.6-sol" },
-      { id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" },
-    ],
-  },
-
-  "deepseek-tui": {
-    id: "deepseek-tui",
-    name: "DeepSeek TUI",
-    color: "#4D6BFE",
-    description: "DeepSeek Terminal Coding Agent (Rust TUI)",
-    configType: "custom" as const,
-    surface: "chat" as const,
-    settingsFile: "~/.deepseek/config.toml",
-    defaultModels: [
-      { id: "deepseek/deepseek-chat", name: "DeepSeek Chat", alias: "deepseek-chat" },
-      {
-        id: "deepseek/deepseek-reasoner",
-        name: "DeepSeek Reasoner",
-        alias: "deepseek-reasoner",
-      },
-    ],
-  },
-
-  jcode: {
-    id: "jcode",
-    name: "jcode",
-    color: "#FF6B35",
-    description: "High-performance Rust-based coding agent harness",
-    configType: "custom" as const,
-    surface: "chat" as const,
-    settingsFile: "~/.jcode/config.toml",
-    docsUrl: "https://github.com/1jehuang/jcode",
-    defaultModels: [{ id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" }],
-  },
-
   kilo: {
     id: "kilo",
     name: "Kilo Code",
@@ -591,159 +488,6 @@ export const TOOL_REGISTRY = {
     settingsFile: "~/.local/share/kilo/auth.json",
     defaultModels: [{ id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" }],
   },
-
-  openclaw: {
-    id: "openclaw",
-    name: "Open Claw",
-    color: "#FF6B35",
-    description: "Open Claw AI Assistant",
-    configType: "custom" as const,
-    surface: "messages" as const,
-    settingsFile: "~/.openclaw/openclaw.json",
-    defaultModels: [{ id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" }],
-  },
-
-  cowork: {
-    id: "cowork",
-    name: "Claude Cowork",
-    color: "#D97757",
-    description: "Claude Desktop Cowork (third-party inference)",
-    configType: "custom" as const,
-    surface: "messages" as const,
-    settingsFile: "Claude/configLibrary/_meta.json",
-    defaultModels: [{ id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" }],
-  },
-  // ── Guide-only tools (no fs injection — show steps + downloadable config) ──
-  roo: {
-    id: "roo",
-    name: "Roo",
-    color: "#FF6B6B",
-    description: "Roo AI Assistant",
-    configType: "guide" as const,
-    surface: "chat" as const,
-    defaultModels: [{ id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" }],
-    guideSteps: [
-      { step: 1, title: "Open Settings", desc: "Go to Roo Settings panel" },
-      { step: 2, title: "Select Provider", desc: "Choose API Provider → Ollama" },
-      { step: 3, title: "Base URL", value: "{{baseUrl}}" },
-      { step: 4, title: "API Key", type: "apiKeySelector" },
-      { step: 5, title: "Select Model", type: "modelSelector" },
-    ],
-  },
-
-  continue: {
-    id: "continue",
-    name: "Continue",
-    color: "#7C3AED",
-    description: "Continue AI Assistant",
-    configType: "guide" as const,
-    surface: "chat" as const,
-    defaultModels: [{ id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" }],
-    guideSteps: [
-      { step: 1, title: "Open Config", desc: "Open Continue configuration file" },
-      { step: 2, title: "API Key", type: "apiKeySelector" },
-      { step: 3, title: "Select Model", type: "modelSelector" },
-      {
-        step: 4,
-        title: "Add Model Config",
-        desc: "Add the following configuration to your models array:",
-      },
-    ],
-    codeBlock: {
-      language: "json",
-      code: `{
-  "apiBase": "{{baseUrl}}",
-  "title": "{{model}}",
-  "model": "{{model}}",
-  "provider": "openai",
-  "apiKey": "{{apiKey}}"
-}`,
-    },
-  },
-
-  amp: {
-    id: "amp",
-    name: "Amp CLI",
-    color: "#F97316",
-    description: "Sourcegraph Amp coding assistant CLI",
-    configType: "guide" as const,
-    surface: "chat" as const,
-    docsUrl: "/docs?section=cli-tools&tool=amp",
-    defaultModels: [{ id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" }],
-    notes: [
-      {
-        type: "info",
-        text: "Use Cartethyia model aliases to keep Amp shorthand mappings stable across provider updates.",
-      },
-    ],
-    guideSteps: [
-      {
-        step: 1,
-        title: "Install Amp",
-        desc: "Install the Amp CLI using the package manager supported by your environment.",
-      },
-      { step: 2, title: "API Key", type: "apiKeySelector" },
-      { step: 3, title: "Base URL", value: "{{baseUrl}}" },
-      { step: 4, title: "Select Model", type: "modelSelector" },
-      {
-        step: 5,
-        title: "Add Shorthands",
-        desc: "Map Amp shorthand names to Cartethyia aliases in your local config.",
-      },
-    ],
-    codeBlock: {
-      language: "bash",
-      code: `export OPENAI_API_KEY="{{apiKey}}"
-export OPENAI_BASE_URL="{{baseUrl}}"
-amp --model "{{model}}"`,
-    },
-  },
-
-  qwen: {
-    id: "qwen",
-    name: "Qwen Code",
-    color: "#10B981",
-    description: "Alibaba Qwen Code CLI — OpenAI-compatible via Cartethyia",
-    configType: "guide" as const,
-    surface: "chat" as const,
-    docsUrl: "https://qwenlm.github.io/qwen-code-docs/en/users/configuration/model-providers/",
-    defaultModels: [
-      { id: "claude/claude-sonnet-5", name: "Claude Sonnet 5", alias: "sonnet" },
-      { id: "gpt-5.6-sol", name: "GPT-5.6 Sol", alias: "gpt-5.6-sol" },
-    ],
-    notes: [
-      {
-        type: "warning",
-        text: "Config path: Linux/macOS ~/.qwen/settings.json - Windows %USERPROFILE%\\.qwen\\settings.json",
-      },
-    ],
-    guideSteps: [
-      { step: 1, title: "Install Qwen Code", desc: "npm install -g @qwen-code/qwen-code" },
-      { step: 2, title: "API Key", type: "apiKeySelector" },
-      { step: 3, title: "Base URL", value: "{{baseUrl}}" },
-      { step: 4, title: "Select Model", type: "modelSelector" },
-      {
-        step: 5,
-        title: "Save Config",
-        desc: "Copy the JSON below to your ~/.qwen/settings.json file.",
-      },
-    ],
-    codeBlock: {
-      language: "json",
-      code: `{
-  "security": {
-    "auth": {
-      "selectedType": "openai",
-      "apiKey": "{{apiKey}}",
-      "baseUrl": "{{baseUrl}}"
-    }
-  },
-  "model": {
-    "name": "{{model}}"
-  }
-}`,
-    },
-  },
 } satisfies Record<string, ToolDef>;
 
 export type ToolId = keyof typeof TOOL_REGISTRY;

package/src/console/cli-tools/fs-ops.ts

@@ -54,6 +54,17 @@ export async function writeJsonFile(path: string, data: unknown): Promise<void>
   await Bun.write(path, JSON.stringify(data, null, 2));
 }
 
+/**
+ * Write JSON to a file, but first preserve the current contents at `path.bak`
+ * when the file already exists. Callers use this for tools whose config is
+ * precious (anything the user hand-edited): a broken merge must never destroy
+ * the only copy of that file, and the operator can always restore `.bak`.
+ */
+export async function writeJsonFileWithBackup(path: string, data: unknown): Promise<void> {
+  await backupExistingFile(path);
+  await writeJsonFile(path, data);
+}
+
 /** Read a text file, returning null if it doesn't exist. */
 export async function readTextFile(path: string): Promise<string | null> {
   try {
@@ -68,6 +79,24 @@ export async function writeTextFile(path: string, content: string): Promise<void
   await Bun.write(path, content);
 }
 
+/**
+ * Write text to a file, preserving the current contents at `path.bak` first.
+ * See `writeJsonFileWithBackup`.
+ */
+export async function writeTextFileWithBackup(path: string, content: string): Promise<void> {
+  await backupExistingFile(path);
+  await writeTextFile(path, content);
+}
+
+/**
+ * Copy an existing file to `path.bak` (overwriting an old backup). Missing
+ * source files are skipped — there is nothing to protect yet.
+ */
+async function backupExistingFile(path: string): Promise<void> {
+  if (!(await fileExists(path))) return;
+  await Bun.write(`${path}.bak`, await Bun.file(path).text());
+}
+
 /** Remove a file if it exists. */
 export async function removeFile(path: string): Promise<void> {
   await rm(path, { force: true });

package/src/console/cli-tools/injectors/claude.ts

@@ -1,6 +1,6 @@
 import type {} from "../contracts";
 import { jsonDownload } from "../contracts";
-import { homeDir, isLocalEndpoint, readJsonFile, stripV1Suffix, writeJsonFile } from "../fs-ops";
+import { homeDir, isLocalEndpoint, readJsonFile, stripV1Suffix, writeJsonFileWithBackup } from "../fs-ops";
 import type { ApplyInput, InjectorSpec } from "../contracts";
 
 
@@ -94,7 +94,7 @@ export const claudeSpec: InjectorSpec = {
     settings.env = env;
     settings.model = claudeModel(input);
     for (const [key, value] of Object.entries(CLAUDE_BASELINE)) settings[key] = value;
-    await writeJsonFile(path, settings);
+    await writeJsonFileWithBackup(path, settings);
   },
 
   async reset(path) {
@@ -106,7 +106,7 @@ export const claudeSpec: InjectorSpec = {
     }
     delete settings.model;
     delete settings.smallModel;
-    await writeJsonFile(path, settings);
+    await writeJsonFileWithBackup(path, settings);
   },
 
   download(input) {