@webpresso/agent-kit 3.1.30 → 3.3.0

package/dist/esm/cli/commands/init/scaffolders/opencode-plugin/index.js

@@ -1,5 +1,8 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { withScaffolderFileLock } from "#cli/commands/init/scaffolders/file-transaction.js";
+import { writeFileAtomicStrict } from "#shared-utils/write-json-file.js";
+import { agentKitMcpLaunchCommand, resolveWebpressoMcpEntry, WEBPRESSO_MCP_SPEC, } from "#cli/commands/init/mcp-spec.js";
 const STALE_OPENCODE_HOOK_PLUGIN_PATH_PARTS = [
     ".opencode",
     "plugins",
@@ -9,6 +12,22 @@ export const STALE_OPENCODE_HOOK_PLUGIN_RELATIVE_PATH = STALE_OPENCODE_HOOK_PLUG
 export const OPENCODE_PLUGIN_SUPPORT_LEVEL = "native-npm";
 export const OPENCODE_PLUGIN_PACKAGE = "@webpresso/opencode-plugin";
 const OPENCODE_PLUGIN_CONFIG_KEY = "plugin";
+export const OPENCODE_MCP_SERVER_NAME = WEBPRESSO_MCP_SPEC.name;
+/**
+ * The canonical OpenCode `mcp.webpresso` entry. OpenCode's local-server shape
+ * folds the launcher and its args into a single `command` array, keys env
+ * under `environment`, and gates activation with `enabled`. Projected from the
+ * one canonical {@link WEBPRESSO_MCP_SPEC}.
+ */
+export function opencodeWebpressoMcpEntry(entryPath) {
+    const launch = agentKitMcpLaunchCommand(entryPath);
+    return {
+        type: "local",
+        command: [launch.command, ...launch.args],
+        enabled: true,
+        environment: { ...WEBPRESSO_MCP_SPEC.env },
+    };
+}
 const LEGACY_WEBPRESSO_HOOK_PLUGIN_MARKERS = [
     "Generated by webpresso (`wp setup`).",
     "export const WebpressoHooksPlugin",
@@ -20,53 +39,36 @@ function isJsonRecord(value) {
 function isStringArray(value) {
     return Array.isArray(value) && value.every((entry) => typeof entry === "string");
 }
-function commandParts(value) {
-    if (!isJsonRecord(value))
-        return [];
-    const command = value.command;
-    if (typeof command === "string")
-        return [command];
-    if (Array.isArray(command)) {
-        return command.filter((part) => typeof part === "string");
-    }
-    return [];
-}
 function isPotentialWebpressoOpenCodeMcpAlias(name, value) {
-    return (name === "agent-kit" || name === "webpresso" || isWebpressoOwnedOpenCodeMcpAlias(name, value));
+    return isJsonRecord(value) && (name === "agent-kit" || name === "webpresso");
 }
-function isWebpressoOwnedOpenCodeMcpAlias(name, value) {
-    const parts = commandParts(value);
-    if (parts.length === 0)
-        return false;
-    const commandText = parts.join(" ");
-    const isNamedLegacyAlias = name === "agent-kit" || name === "webpresso";
-    return (parts.some((part) => /[/\\]agent-kit[/\\]/u.test(part) ||
-        part.includes("@webpresso/agent-kit") ||
-        part.includes("src/mcp/cli.ts")) ||
-        (isNamedLegacyAlias && /(?:^|\s)(?:vp\s+exec\s+)?wp\s+mcp(?:\s|$)/u.test(commandText)));
-}
-function collectPreservedLegacyMcpAliases(value, removeOwned) {
+function collectPreservedLegacyMcpAliases(value) {
     if (!isJsonRecord(value))
         return [];
     return Object.entries(value)
         .filter(([name, server]) => isPotentialWebpressoOpenCodeMcpAlias(name, server) &&
-        !(removeOwned && isWebpressoOwnedOpenCodeMcpAlias(name, server)))
+        !isKnownWebpressoOwnedLegacyMcpAlias(name, server))
         .map(([name]) => `mcp:${name}`)
         .toSorted();
 }
-function removeOwnedLegacyMcpAliases(value) {
+function commandWords(value) {
     if (!isJsonRecord(value))
-        return { nextMcp: undefined, removed: [] };
-    const nextMcp = {};
-    const removed = [];
-    for (const [name, server] of Object.entries(value)) {
-        if (isWebpressoOwnedOpenCodeMcpAlias(name, server)) {
-            removed.push(`mcp:${name}`);
-            continue;
-        }
-        nextMcp[name] = server;
+        return [];
+    const command = value.command;
+    return isStringArray(command) ? command : [];
+}
+function isKnownWebpressoOwnedLegacyMcpAlias(name, value) {
+    const command = commandWords(value);
+    const commandText = command.join(" ");
+    if (name === "webpresso") {
+        return command.join("\0") === ["vp", "exec", "wp", "mcp"].join("\0");
     }
-    return { nextMcp, removed: removed.toSorted() };
+    if (name !== "agent-kit")
+        return false;
+    return (commandText.includes("@webpresso/agent-kit") ||
+        commandText.includes(".claude/plugins/cache") ||
+        commandText.includes("/agent-kit/src/mcp/") ||
+        commandText.includes("\\agent-kit\\src\\mcp\\"));
 }
 function isWebpressoOwnedStaleHookPlugin(staleHookPluginPath) {
     if (!existsSync(staleHookPluginPath))
@@ -74,15 +76,488 @@ function isWebpressoOwnedStaleHookPlugin(staleHookPluginPath) {
     const staleHookPluginContent = readFileSync(staleHookPluginPath, "utf8");
     return LEGACY_WEBPRESSO_HOOK_PLUGIN_MARKERS.every((marker) => staleHookPluginContent.includes(marker));
 }
+function stripJsoncForParse(raw) {
+    let out = "";
+    let inString = false;
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < raw.length; i += 1) {
+        const ch = raw[i];
+        const next = raw[i + 1];
+        if (inString) {
+            out += ch;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (ch === "\\") {
+                escaped = true;
+            }
+            else if (ch === quote) {
+                inString = false;
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inString = true;
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < raw.length && raw[i] !== "\n")
+                i += 1;
+            out += "\n";
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/"))
+                i += 1;
+            i += 1;
+            continue;
+        }
+        out += ch;
+    }
+    return stripJsoncTrailingCommas(out);
+}
+function stripJsoncTrailingCommas(raw) {
+    let out = "";
+    let inString = false;
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < raw.length; i += 1) {
+        const ch = raw[i];
+        if (inString) {
+            out += ch;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (ch === "\\") {
+                escaped = true;
+            }
+            else if (ch === quote) {
+                inString = false;
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inString = true;
+            quote = ch;
+            out += ch;
+            continue;
+        }
+        if (ch === ",") {
+            let j = i + 1;
+            while (/\s/u.test(raw[j] ?? ""))
+                j += 1;
+            if (raw[j] === "}" || raw[j] === "]")
+                continue;
+        }
+        out += ch;
+    }
+    return out;
+}
+function parseOpenCodeConfig(existing, configPath) {
+    if (existing.trim().length === 0)
+        return {};
+    const parseInput = configPath.endsWith(".jsonc") ? stripJsoncForParse(existing) : existing;
+    return JSON.parse(parseInput);
+}
+function isJsoncConfigPath(configPath) {
+    return configPath.endsWith(".jsonc");
+}
+function findMatchingJsoncBracket(raw, openIndex) {
+    const open = raw[openIndex];
+    const close = open === "{" ? "}" : open === "[" ? "]" : null;
+    if (!close)
+        return -1;
+    let depth = 0;
+    let inString = false;
+    let quote = null;
+    let escaped = false;
+    for (let i = openIndex; i < raw.length; i += 1) {
+        const ch = raw[i];
+        const next = raw[i + 1];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === quote) {
+                inString = false;
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inString = true;
+            quote = ch;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < raw.length && raw[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/"))
+                i += 1;
+            i += 1;
+            continue;
+        }
+        if (ch === open)
+            depth += 1;
+        if (ch === close) {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function skipJsoncTrivia(raw, start) {
+    let i = start;
+    while (i < raw.length) {
+        const ch = raw[i];
+        const next = raw[i + 1];
+        if (/\s/u.test(ch)) {
+            i += 1;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < raw.length && raw[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < raw.length && !(raw[i] === "*" && raw[i + 1] === "/"))
+                i += 1;
+            i += 2;
+            continue;
+        }
+        break;
+    }
+    return i;
+}
+function parseJsoncStringToken(raw, start) {
+    if (raw[start] !== '"')
+        return null;
+    let json = '"';
+    for (let i = start + 1; i < raw.length; i += 1) {
+        const ch = raw[i];
+        json += ch;
+        if (ch === "\\") {
+            i += 1;
+            if (i < raw.length)
+                json += raw[i];
+            continue;
+        }
+        if (ch === '"') {
+            try {
+                return { value: JSON.parse(json), end: i + 1 };
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+function findJsoncValueEnd(raw, start, objectEnd) {
+    const ch = raw[start];
+    if (ch === "{" || ch === "[") {
+        const end = findMatchingJsoncBracket(raw, start);
+        return end === -1 ? objectEnd : end + 1;
+    }
+    if (ch === '"')
+        return parseJsoncStringToken(raw, start)?.end ?? objectEnd;
+    let i = start;
+    while (i < objectEnd) {
+        const current = raw[i];
+        const next = raw[i + 1];
+        if (current === "/" && next === "/") {
+            i += 2;
+            while (i < objectEnd && raw[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (current === "/" && next === "*") {
+            i += 2;
+            while (i < objectEnd && !(raw[i] === "*" && raw[i + 1] === "/"))
+                i += 1;
+            i = Math.min(i + 2, objectEnd);
+            continue;
+        }
+        if (current === "," || current === "}")
+            break;
+        i += 1;
+    }
+    return i;
+}
+function findJsoncObjectProperty(raw, objectStart, objectEnd, key) {
+    let i = objectStart + 1;
+    while (i < objectEnd) {
+        i = skipJsoncTrivia(raw, i);
+        if (i >= objectEnd || raw[i] === "}")
+            return null;
+        const keyToken = parseJsoncStringToken(raw, i);
+        if (!keyToken)
+            return null;
+        const colon = skipJsoncTrivia(raw, keyToken.end);
+        if (raw[colon] !== ":")
+            return null;
+        const valueStart = skipJsoncTrivia(raw, colon + 1);
+        const valueEnd = findJsoncValueEnd(raw, valueStart, objectEnd);
+        if (keyToken.value === key)
+            return { keyStart: i, valueStart, valueEnd };
+        i = skipJsoncTrivia(raw, valueEnd);
+        if (raw[i] === ",")
+            i += 1;
+    }
+    return null;
+}
+function countJsoncObjectProperties(raw, objectStart, objectEnd, key) {
+    let count = 0;
+    let i = objectStart + 1;
+    while (i < objectEnd) {
+        i = skipJsoncTrivia(raw, i);
+        if (i >= objectEnd || raw[i] === "}")
+            return count;
+        const keyToken = parseJsoncStringToken(raw, i);
+        if (!keyToken)
+            return count;
+        const colon = skipJsoncTrivia(raw, keyToken.end);
+        if (raw[colon] !== ":")
+            return count;
+        const valueStart = skipJsoncTrivia(raw, colon + 1);
+        const valueEnd = findJsoncValueEnd(raw, valueStart, objectEnd);
+        if (keyToken.value === key)
+            count += 1;
+        i = skipJsoncTrivia(raw, valueEnd);
+        if (raw[i] === ",")
+            i += 1;
+    }
+    return count;
+}
+function hasDuplicateManagedJsoncKeys(raw, configPath) {
+    if (!isJsoncConfigPath(configPath) || raw.trim().length === 0)
+        return false;
+    const rootStart = skipJsoncTrivia(raw, 0);
+    if (rootStart >= raw.length || raw[rootStart] !== "{")
+        return false;
+    const rootEnd = findMatchingJsoncBracket(raw, rootStart);
+    if (rootEnd === -1)
+        return false;
+    if (countJsoncObjectProperties(raw, rootStart, rootEnd, OPENCODE_PLUGIN_CONFIG_KEY) > 1)
+        return true;
+    if (countJsoncObjectProperties(raw, rootStart, rootEnd, "mcp") > 1)
+        return true;
+    const mcpProp = findJsoncObjectProperty(raw, rootStart, rootEnd, "mcp");
+    if (mcpProp === null)
+        return false;
+    const mcpEnd = findMatchingJsoncBracket(raw, mcpProp.valueStart);
+    if (mcpEnd === -1)
+        return false;
+    return countJsoncObjectProperties(raw, mcpProp.valueStart, mcpEnd, OPENCODE_MCP_SERVER_NAME) > 1;
+}
+function previousJsoncSignificantChar(raw, before) {
+    let last = "";
+    let inString = false;
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < before; i += 1) {
+        const ch = raw[i];
+        const next = raw[i + 1];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === quote) {
+                inString = false;
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inString = true;
+            quote = ch;
+            last = ch;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < before && raw[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < before && !(raw[i] === "*" && raw[i + 1] === "/"))
+                i += 1;
+            i += 1;
+            continue;
+        }
+        if (!/\s/u.test(ch))
+            last = ch;
+    }
+    return last;
+}
+function insertJsoncObjectProperty(raw, objectEnd, key, value, indent) {
+    const previous = previousJsoncSignificantChar(raw, objectEnd);
+    const needsComma = previous !== "{" && previous !== ",";
+    const prefix = needsComma ? "," : "";
+    const rendered = JSON.stringify(value, null, 2)
+        .split("\n")
+        .map((line, index) => (index === 0 ? line : `${indent}${line}`))
+        .join("\n");
+    return `${raw.slice(0, objectEnd)}${prefix}\n${indent}${JSON.stringify(key)}: ${rendered}\n${raw.slice(objectEnd)}`;
+}
+function removeJsoncObjectProperty(raw, property, objectStart) {
+    const afterValue = skipJsoncTrivia(raw, property.valueEnd);
+    if (raw[afterValue] === ",") {
+        return `${raw.slice(0, property.keyStart)}${raw.slice(afterValue + 1)}`;
+    }
+    let previousComma = -1;
+    let inString = false;
+    let quote = null;
+    let escaped = false;
+    for (let i = objectStart + 1; i < property.keyStart; i += 1) {
+        const ch = raw[i];
+        const next = raw[i + 1];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === quote) {
+                inString = false;
+                quote = null;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inString = true;
+            quote = ch;
+            continue;
+        }
+        if (ch === "/" && next === "/") {
+            while (i < property.keyStart && raw[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (ch === "/" && next === "*") {
+            i += 2;
+            while (i < property.keyStart && !(raw[i] === "*" && raw[i + 1] === "/"))
+                i += 1;
+            i += 1;
+            continue;
+        }
+        if (ch === ",")
+            previousComma = i;
+    }
+    if (previousComma !== -1) {
+        return `${raw.slice(0, previousComma)}${raw.slice(property.valueEnd)}`;
+    }
+    return `${raw.slice(0, property.keyStart)}${raw.slice(property.valueEnd)}`;
+}
+function appendJsoncArrayString(raw, arrayEnd, value, indent) {
+    const previous = previousJsoncSignificantChar(raw, arrayEnd);
+    const needsComma = previous !== "[" && previous !== ",";
+    const prefix = needsComma ? "," : "";
+    return `${raw.slice(0, arrayEnd)}${prefix}\n${indent}${JSON.stringify(value)}\n${raw.slice(arrayEnd)}`;
+}
+function renderOpenCodeConfig(existing, configPath, nextRoot, nextPlugins, hasPluginRegistration, mcpEntryPath, removedMcpServerNames) {
+    if (!isJsoncConfigPath(configPath))
+        return `${JSON.stringify(nextRoot, null, 2)}\n`;
+    if (existing.trim().length === 0)
+        return `${JSON.stringify(nextRoot, null, 2)}\n`;
+    let next = existing;
+    const rootStart = skipJsoncTrivia(next, 0);
+    if (rootStart >= next.length || next[rootStart] !== "{")
+        return `${JSON.stringify(nextRoot, null, 2)}\n`;
+    let rootEnd = findMatchingJsoncBracket(next, rootStart);
+    if (rootEnd === -1)
+        return `${JSON.stringify(nextRoot, null, 2)}\n`;
+    const pluginProp = findJsoncObjectProperty(next, rootStart, rootEnd, OPENCODE_PLUGIN_CONFIG_KEY);
+    if (pluginProp === null) {
+        next = insertJsoncObjectProperty(next, rootEnd, OPENCODE_PLUGIN_CONFIG_KEY, nextPlugins, "  ");
+    }
+    else {
+        const shouldAppendPlugin = !hasPluginRegistration && nextPlugins.includes(OPENCODE_PLUGIN_PACKAGE);
+        if (shouldAppendPlugin) {
+            const arrayEnd = findMatchingJsoncBracket(next, pluginProp.valueStart);
+            if (arrayEnd !== -1) {
+                next = appendJsoncArrayString(next, arrayEnd, OPENCODE_PLUGIN_PACKAGE, "    ");
+            }
+        }
+    }
+    rootEnd = findMatchingJsoncBracket(next, rootStart);
+    if (rootEnd === -1)
+        return next.endsWith("\n") ? next : `${next}\n`;
+    const mcpProp = findJsoncObjectProperty(next, rootStart, rootEnd, "mcp");
+    if (mcpProp === null) {
+        if (mcpEntryPath === null)
+            return next.endsWith("\n") ? next : `${next}\n`;
+        const mcpEntry = opencodeWebpressoMcpEntry(mcpEntryPath);
+        next = insertJsoncObjectProperty(next, rootEnd, "mcp", { [OPENCODE_MCP_SERVER_NAME]: mcpEntry }, "  ");
+        return next.endsWith("\n") ? next : `${next}\n`;
+    }
+    const mcpEnd = findMatchingJsoncBracket(next, mcpProp.valueStart);
+    if (mcpEnd === -1)
+        return next.endsWith("\n") ? next : `${next}\n`;
+    for (const name of removedMcpServerNames) {
+        const legacyProp = findJsoncObjectProperty(next, mcpProp.valueStart, mcpEnd, name);
+        if (legacyProp !== null) {
+            next = removeJsoncObjectProperty(next, legacyProp, mcpProp.valueStart);
+        }
+    }
+    const nextMcpEnd = findMatchingJsoncBracket(next, mcpProp.valueStart);
+    if (nextMcpEnd === -1)
+        return next.endsWith("\n") ? next : `${next}\n`;
+    if (mcpEntryPath === null)
+        return next.endsWith("\n") ? next : `${next}\n`;
+    const mcpEntry = opencodeWebpressoMcpEntry(mcpEntryPath);
+    const webpressoProp = findJsoncObjectProperty(next, mcpProp.valueStart, nextMcpEnd, OPENCODE_MCP_SERVER_NAME);
+    if (webpressoProp === null) {
+        next = insertJsoncObjectProperty(next, nextMcpEnd, OPENCODE_MCP_SERVER_NAME, mcpEntry, "    ");
+    }
+    else {
+        const rendered = JSON.stringify(mcpEntry, null, 2)
+            .split("\n")
+            .map((line, index) => (index === 0 ? line : `    ${line}`))
+            .join("\n");
+        next = `${next.slice(0, webpressoProp.valueStart)}${rendered}${next.slice(webpressoProp.valueEnd)}`;
+    }
+    return next.endsWith("\n") ? next : `${next}\n`;
+}
+function defaultOpenCodeConfigPath(repoRoot) {
+    const jsonPath = join(repoRoot, "opencode.json");
+    if (existsSync(jsonPath))
+        return jsonPath;
+    const jsoncPath = join(repoRoot, "opencode.jsonc");
+    if (existsSync(jsoncPath))
+        return jsoncPath;
+    return jsonPath;
+}
 export function ensureOpenCodeWebpressoPlugin(input) {
-    const configPath = input.configPath ?? join(input.repoRoot, "opencode.json");
+    const configPath = input.configPath ?? defaultOpenCodeConfigPath(input.repoRoot);
     if (input.options.dryRun) {
         return { kind: "opencode-webpresso-plugin-skipped-dry-run", path: configPath };
     }
+    return withScaffolderFileLock(configPath, () => ensureOpenCodeWebpressoPluginLocked(input, configPath));
+}
+function ensureOpenCodeWebpressoPluginLocked(input, configPath) {
     const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+    if (hasDuplicateManagedJsoncKeys(existing, configPath)) {
+        return { kind: "opencode-webpresso-plugin-invalid-config", path: configPath };
+    }
     let parsed;
     try {
-        parsed = existing.trim().length > 0 ? JSON.parse(existing) : {};
+        parsed = parseOpenCodeConfig(existing, configPath);
     }
     catch {
         return { kind: "opencode-webpresso-plugin-invalid-json", path: configPath };
@@ -93,15 +568,22 @@ export function ensureOpenCodeWebpressoPlugin(input) {
     if (parsed.mcp !== undefined && !isJsonRecord(parsed.mcp)) {
         return { kind: "opencode-webpresso-plugin-invalid-config", path: configPath };
     }
-    const staleHookPluginPath = join(input.repoRoot, STALE_OPENCODE_HOOK_PLUGIN_RELATIVE_PATH);
-    const ownsStaleHookPlugin = isWebpressoOwnedStaleHookPlugin(staleHookPluginPath);
-    const mcpCleanup = removeOwnedLegacyMcpAliases(parsed.mcp);
-    const preserved = [
-        ...(!ownsStaleHookPlugin && existsSync(staleHookPluginPath)
-            ? [`stale-hook-plugin:${STALE_OPENCODE_HOOK_PLUGIN_RELATIVE_PATH}`]
-            : []),
-        ...collectPreservedLegacyMcpAliases(parsed.mcp, true),
-    ].toSorted();
+    const resolution = input.entryPath === undefined ? resolveWebpressoMcpEntry(input.probe) : undefined;
+    const mcpEntryPath = input.entryPath ?? resolution?.entryPath ?? null;
+    // When we can author the canonical `mcp.webpresso` entry we OWN the alias:
+    // drop any prior copy silently (not a "removal") and re-author it below.
+    // When no launcher resolves, fall back to GC-only semantics on the prior mcp
+    // so a consumer's own entries (including a same-named one) stay untouched.
+    const priorMcp = isJsonRecord(parsed.mcp) ? parsed.mcp : {};
+    const mcpForCleanup = mcpEntryPath !== null
+        ? Object.fromEntries(Object.entries(priorMcp).filter(([name, value]) => name !== OPENCODE_MCP_SERVER_NAME &&
+            !isKnownWebpressoOwnedLegacyMcpAlias(name, value)))
+        : Object.fromEntries(Object.entries(priorMcp).filter(([name, value]) => !isKnownWebpressoOwnedLegacyMcpAlias(name, value)));
+    const removedMcpAliases = Object.entries(priorMcp)
+        .filter(([name, value]) => isKnownWebpressoOwnedLegacyMcpAlias(name, value))
+        .map(([name]) => `mcp:${name}`)
+        .toSorted();
+    const preserved = [...collectPreservedLegacyMcpAliases(mcpForCleanup)].toSorted();
     const pluginValue = parsed[OPENCODE_PLUGIN_CONFIG_KEY];
     if (pluginValue !== undefined && !isStringArray(pluginValue)) {
         return { kind: "opencode-webpresso-plugin-invalid-config", path: configPath };
@@ -115,30 +597,43 @@ export function ensureOpenCodeWebpressoPlugin(input) {
         ...parsed,
         [OPENCODE_PLUGIN_CONFIG_KEY]: nextPlugins,
     };
-    const removed = [
-        ...mcpCleanup.removed,
-        ...(ownsStaleHookPlugin
-            ? [`stale-hook-plugin:${STALE_OPENCODE_HOOK_PLUGIN_RELATIVE_PATH}`]
-            : []),
-    ];
-    const nextMcp = mcpCleanup.nextMcp ?? {};
+    const nextMcp = { ...mcpForCleanup };
+    if (mcpEntryPath !== null) {
+        nextMcp[OPENCODE_MCP_SERVER_NAME] = opencodeWebpressoMcpEntry(mcpEntryPath);
+    }
     nextRoot.mcp = nextMcp;
-    const next = `${JSON.stringify(nextRoot, null, 2)}\n`;
+    const next = renderOpenCodeConfig(existing, configPath, nextRoot, nextPlugins, dedupedExistingPlugins.includes(OPENCODE_PLUGIN_PACKAGE), mcpEntryPath, removedMcpAliases.map((alias) => alias.slice("mcp:".length)));
     const configChanged = next !== existing;
     if (configChanged) {
-        mkdirSync(dirname(configPath), { recursive: true });
-        writeFileSync(configPath, next, "utf8");
+        const mode = existsSync(configPath) ? statSync(configPath).mode & 0o777 : 0o600;
+        writeFileAtomicStrict(configPath, next, { encoding: "utf8", mode });
     }
-    if (ownsStaleHookPlugin) {
+    const staleHookPluginPath = join(input.repoRoot, STALE_OPENCODE_HOOK_PLUGIN_RELATIVE_PATH);
+    const staleCleanup = withScaffolderFileLock(staleHookPluginPath, () => {
+        if (!existsSync(staleHookPluginPath))
+            return { removed: [], preserved: [] };
+        if (!isWebpressoOwnedStaleHookPlugin(staleHookPluginPath)) {
+            return {
+                removed: [],
+                preserved: [`stale-hook-plugin:${STALE_OPENCODE_HOOK_PLUGIN_RELATIVE_PATH}`],
+            };
+        }
         rmSync(staleHookPluginPath, { force: true });
-    }
+        return {
+            removed: [`stale-hook-plugin:${STALE_OPENCODE_HOOK_PLUGIN_RELATIVE_PATH}`],
+            preserved: [],
+        };
+    });
+    const removed = [...removedMcpAliases, ...staleCleanup.removed].toSorted();
+    const finalPreserved = [...preserved, ...staleCleanup.preserved].toSorted();
     if (configChanged || removed.length > 0) {
         return {
             kind: "opencode-webpresso-plugin-written",
             path: configPath,
             pluginPackage: OPENCODE_PLUGIN_PACKAGE,
             removed: removed.toSorted(),
-            preserved,
+            preserved: finalPreserved,
+            mcpEntryPath,
         };
     }
     return {
@@ -146,6 +641,7 @@ export function ensureOpenCodeWebpressoPlugin(input) {
         path: configPath,
         pluginPackage: OPENCODE_PLUGIN_PACKAGE,
         removed: [],
-        preserved,
+        preserved: finalPreserved,
+        mcpEntryPath,
     };
 }