specrails-desktop 2.0.0

package/server/dist/plugin-manager.js

@@ -0,0 +1,617 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginManager = exports.PluginInstallError = exports.PluginAlreadyInstalledError = exports.PluginNotInstalledError = exports.PluginNotFoundError = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const ownership_1 = require("./plugins/ownership");
+const claude_approval_1 = require("./plugins/claude-approval");
+const drift_1 = require("./plugins/drift");
+const providers_1 = require("./providers");
+const paths_1 = require("./plugins/paths");
+function readMcpServersMap(projectPath) {
+    try {
+        if (!fs_1.default.existsSync((0, paths_1.mcpJsonPath)(projectPath)))
+            return {};
+        const raw = fs_1.default.readFileSync((0, paths_1.mcpJsonPath)(projectPath), 'utf8');
+        if (!raw.trim())
+            return {};
+        const parsed = JSON.parse(raw);
+        return parsed.mcpServers ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+const json_mutation_1 = require("./plugins/json-mutation");
+const contributors_1 = require("./plugins/contributors");
+class PluginNotFoundError extends Error {
+    constructor(name) {
+        super(`plugin not found in registry: ${name}`);
+        this.name = 'PluginNotFoundError';
+    }
+}
+exports.PluginNotFoundError = PluginNotFoundError;
+class PluginNotInstalledError extends Error {
+    constructor(name) {
+        super(`plugin is not installed: ${name}`);
+        this.name = 'PluginNotInstalledError';
+    }
+}
+exports.PluginNotInstalledError = PluginNotInstalledError;
+class PluginAlreadyInstalledError extends Error {
+    constructor(name) {
+        super(`plugin is already installed: ${name}`);
+        this.name = 'PluginAlreadyInstalledError';
+    }
+}
+exports.PluginAlreadyInstalledError = PluginAlreadyInstalledError;
+class PluginInstallError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'PluginInstallError';
+        this.cause = cause;
+    }
+}
+exports.PluginInstallError = PluginInstallError;
+const DEFAULT_VERIFY_TIMEOUT_MS = 2000;
+class PluginManager {
+    registry;
+    _options;
+    constructor(plugins, options = {}) {
+        this.registry = (0, ownership_1.buildOwnershipMap)(plugins);
+        this._options = {
+            defaultVerifyTimeoutMs: options.defaultVerifyTimeoutMs ?? DEFAULT_VERIFY_TIMEOUT_MS,
+            checkPrerequisite: options.checkPrerequisite,
+            claudeApprovalChecker: options.claudeApprovalChecker ?? claude_approval_1.getClaudeApprovalState,
+        };
+    }
+    // ─── State helpers ─────────────────────────────────────────────────────────
+    getProjectState(projectPath) {
+        return (0, json_mutation_1.readJsonOr)((0, paths_1.stateFilePath)(projectPath), {
+            schemaVersion: 1,
+            plugins: {},
+        });
+    }
+    async _writeProjectState(projectPath, state) {
+        fs_1.default.mkdirSync((0, paths_1.pluginsDir)(projectPath), { recursive: true });
+        await (0, json_mutation_1.withFileLock)((0, paths_1.stateFilePath)(projectPath), async () => {
+            (0, json_mutation_1.atomicWriteFileSync)((0, paths_1.stateFilePath)(projectPath), JSON.stringify(state, null, 2) + '\n');
+        });
+    }
+    // ─── Catalog ───────────────────────────────────────────────────────────────
+    async listAvailable(projectPath, providerId) {
+        const state = this.getProjectState(projectPath);
+        const entries = [];
+        // Bundled plugins, regardless of install state.
+        for (const plugin of this.registry.byName.values()) {
+            const m = plugin.manifest;
+            const stateEntry = state.plugins[m.name];
+            let status;
+            // Provider applicability: a plugin is `not-applicable` when the
+            // project's provider is registered, providerSupport is declared, and
+            // there's no entry for this provider. Plugins that don't declare
+            // providerSupport at all default to claude-compatible (preserves
+            // pre-§14 behaviour for unchanged manifests).
+            const supportsThisProvider = providerId === undefined
+                ? true
+                : m.providerSupport === undefined
+                    ? providerId === 'claude'
+                    : providerId in m.providerSupport;
+            if (!supportsThisProvider) {
+                status = 'not-applicable';
+            }
+            else if (!stateEntry) {
+                status = 'not-installed';
+            }
+            else if (stateEntry.health === 'degraded') {
+                status = 'degraded';
+            }
+            else {
+                // Plugin install lives in two files:
+                //   (a) state.json — the app's record that the plugin is installed
+                //   (b) .mcp.json  — the actual contract with Claude (loaded blindly)
+                // Active = both present. Deactivated = (a) without the (b) keys
+                // (user toggled off; install survives). For codex projects the
+                // (b) check is skipped because the registration lives outside the
+                // project filesystem (CODEX_HOME).
+                let allKeysPresent = true;
+                if (providerId === 'codex') {
+                    // For codex we trust state.json — `codex mcp list` against the
+                    // per-project CODEX_HOME is the source of truth, but it requires a
+                    // subprocess which is too expensive for a catalog listing call.
+                    allKeysPresent = true;
+                }
+                else {
+                    const mcpServers = readMcpServersMap(projectPath);
+                    for (const server of m.owns.mcpServers ?? []) {
+                        if (!(server in mcpServers)) {
+                            allKeysPresent = false;
+                            break;
+                        }
+                    }
+                }
+                status = allKeysPresent ? 'installed' : 'deactivated';
+            }
+            // Surface marketplace conflicts so UI can offer a "Disable global"
+            // affordance when our project-scoped install is being shadowed.
+            const conflicts = [];
+            const cachedDisabled = [];
+            for (const server of m.owns.mcpServers ?? []) {
+                for (const key of (0, claude_approval_1.findEnabledMarketplaceKeys)(server)) {
+                    if (!conflicts.includes(key))
+                        conflicts.push(key);
+                }
+                for (const key of (0, claude_approval_1.findInstalledButNotEnabledMarketplaceKeys)(server)) {
+                    if (!cachedDisabled.includes(key))
+                        cachedDisabled.push(key);
+                }
+            }
+            // Drift detection: only meaningful when actually installed.
+            const updateAvailable = stateEntry ? (0, drift_1.detectMcpDrift)(projectPath, plugin) : false;
+            entries.push({
+                name: m.name,
+                version: m.version,
+                description: m.description,
+                whatItDoes: m.whatItDoes,
+                category: m.category,
+                requirements: m.requirements ?? [],
+                owns: m.owns,
+                status,
+                installedAt: stateEntry?.installedAt,
+                health: stateEntry?.health,
+                healthReason: stateEntry?.healthReason,
+                marketplaceConflicts: conflicts.length > 0 ? conflicts : undefined,
+                marketplaceCachedButDisabled: cachedDisabled.length > 0 ? cachedDisabled : undefined,
+                updateAvailable: updateAvailable || undefined,
+            });
+        }
+        // Orphan plugins: present in state.json but not in the bundled registry.
+        for (const [name, entry] of Object.entries(state.plugins)) {
+            if (this.registry.byName.has(name))
+                continue;
+            entries.push({
+                name,
+                version: entry.version,
+                description: '(plugin no longer bundled)',
+                whatItDoes: [],
+                requirements: [],
+                owns: {},
+                status: 'orphan',
+                installedAt: entry.installedAt,
+                health: entry.health,
+                healthReason: entry.healthReason,
+            });
+        }
+        return entries.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    // ─── Preview install ───────────────────────────────────────────────────────
+    async previewInstall(projectPath, projectId, name) {
+        const plugin = this.registry.byName.get(name);
+        if (!plugin)
+            throw new PluginNotFoundError(name);
+        let files;
+        if (plugin.previewInstall) {
+            files = await plugin.previewInstall({ projectPath, projectId });
+        }
+        else {
+            files = this._derivePreviewFiles(projectPath, plugin);
+        }
+        const requirements = await Promise.all((plugin.manifest.requirements ?? []).map(async (req) => {
+            if (this._options.checkPrerequisite) {
+                const r = await this._options.checkPrerequisite(req);
+                return { name: req.name, ...r };
+            }
+            return { name: req.name, installed: true, executable: true, meetsMinimum: true };
+        }));
+        const hostKey = `${process.platform}-${process.arch}`;
+        const platformNote = plugin.manifest.platformNotes?.[hostKey];
+        return {
+            pluginName: name,
+            files,
+            requirements,
+            platformNote,
+        };
+    }
+    _derivePreviewFiles(projectPath, plugin) {
+        const out = [];
+        const m = plugin.manifest;
+        // .mcp.json
+        if ((m.owns.mcpServers ?? []).length > 0) {
+            const mcpExists = fs_1.default.existsSync((0, paths_1.mcpJsonPath)(projectPath));
+            out.push({
+                path: '.mcp.json',
+                op: mcpExists ? 'modify' : 'create',
+                summary: `+ mcpServers.${(m.owns.mcpServers ?? []).join(', mcpServers.')}`,
+            });
+        }
+        // Agent fragments
+        for (const frag of m.owns.agentFragments ?? []) {
+            const exists = fs_1.default.existsSync(path_1.default.join(projectPath, frag));
+            out.push({ path: frag, op: exists ? 'modify' : 'create' });
+        }
+        // Shared-file contributors (CLAUDE.md today, more in the future).
+        for (const rel of (0, contributors_1.contributorPaths)(plugin)) {
+            const exists = fs_1.default.existsSync(path_1.default.join(projectPath, rel));
+            out.push({
+                path: rel,
+                op: exists ? 'modify' : 'create',
+                summary: `+ <!-- specrails-desktop-managed:${m.name} --> block`,
+            });
+        }
+        // State file
+        const stateExists = fs_1.default.existsSync((0, paths_1.stateFilePath)(projectPath));
+        out.push({
+            path: '.specrails/plugins/state.json',
+            op: stateExists ? 'modify' : 'create',
+            summary: `+ plugins.${m.name}`,
+        });
+        return out;
+    }
+    // ─── Install ───────────────────────────────────────────────────────────────
+    async install(projectPath, projectId, name, broadcast, providerId) {
+        const plugin = this.registry.byName.get(name);
+        if (!plugin)
+            throw new PluginNotFoundError(name);
+        // Provider applicability gate: refuse to install a plugin that has no
+        // providerSupport entry for this project's provider. Plugins that omit
+        // providerSupport altogether default to claude-compatible.
+        if (providerId !== undefined && providerId !== 'claude') {
+            const declared = plugin.manifest.providerSupport;
+            if (declared !== undefined && !(providerId in declared)) {
+                throw new PluginInstallError(`plugin '${name}' is not applicable for provider '${providerId}'. Declared providers: ${Object.keys(declared).join(', ')}.`);
+            }
+        }
+        const state = this.getProjectState(projectPath);
+        if (state.plugins[name])
+            throw new PluginAlreadyInstalledError(name);
+        // Check for ownership conflicts with user-authored `.mcp.json` entries.
+        // Only meaningful for `project-json` MCP registration providers (claude
+        // today). Codex registers via `codex mcp add` against per-project
+        // CODEX_HOME, which the plugin's install path checks via `codex mcp list`.
+        const adapter = providerId !== undefined && (0, providers_1.hasAdapter)(providerId)
+            ? (0, providers_1.getAdapter)(providerId)
+            : null;
+        const usesProjectJsonMcp = adapter === null || adapter.mcpRegistration === 'project-json';
+        if (usesProjectJsonMcp) {
+            const mcpFile = (0, paths_1.mcpJsonPath)(projectPath);
+            if (fs_1.default.existsSync(mcpFile)) {
+                const raw = fs_1.default.readFileSync(mcpFile, 'utf8');
+                let parsed;
+                try {
+                    parsed = raw.trim() ? JSON.parse(raw) : {};
+                }
+                catch {
+                    // A hand-edited / broken `.mcp.json` should yield an actionable 409,
+                    // not an opaque 500 with a raw "Unexpected token" SyntaxError.
+                    throw new PluginInstallError(`cannot install '${name}': '${(0, paths_1.mcpJsonPath)(projectPath)}' is not valid JSON; fix it first.`);
+                }
+                const servers = parsed.mcpServers ?? {};
+                for (const key of plugin.manifest.owns.mcpServers ?? []) {
+                    if (key in servers) {
+                        throw new PluginInstallError(`cannot install '${name}': '${(0, paths_1.mcpJsonPath)(projectPath)}' already has a 'mcpServers.${key}' entry. Remove it first.`);
+                    }
+                }
+            }
+        }
+        // Snapshot pre-install state of every file the plugin might touch — we
+        // need exact bytes to roll back if install/verify fails.
+        const targetPaths = [
+            (0, paths_1.mcpJsonPath)(projectPath),
+            (0, paths_1.stateFilePath)(projectPath),
+            ...(plugin.manifest.owns.agentFragments ?? []).map((f) => path_1.default.join(projectPath, f)),
+            // Include the shared instructions file (CLAUDE.md / AGENTS.md) so a failed
+            // install rolls it back too — otherwise an applyContributors write that
+            // survives a later failure leaves an orphaned managed block with no state
+            // entry, which uninstall can never remove (breaks byte-identical restore).
+            ...(0, contributors_1.contributorPaths)(plugin, providerId).map((rel) => path_1.default.join(projectPath, rel)),
+        ];
+        const preState = new Map();
+        for (const p of targetPaths) {
+            preState.set(p, fs_1.default.existsSync(p) ? fs_1.default.readFileSync(p) : null);
+        }
+        const installedFiles = [];
+        const onLog = (line) => {
+            const msg = {
+                type: 'plugin.install_progress',
+                projectId,
+                name,
+                line,
+                timestamp: new Date().toISOString(),
+            };
+            broadcast(msg);
+        };
+        const ctx = {
+            projectPath,
+            projectId,
+            providerId,
+            recordInstalledFile: (rel) => { installedFiles.push(rel); },
+            log: onLog,
+        };
+        try {
+            await plugin.install(ctx);
+            // Verify immediately. A degraded result also triggers rollback because
+            // the spec requires verify-pass before we commit state.
+            const verify = await this._runVerify(plugin, projectPath, projectId);
+            if (!verify.ok) {
+                throw new PluginInstallError(`verify failed after install: ${verify.reason ?? 'unknown'}`);
+            }
+            // Commit: write state.json with the install record.
+            const stateNow = this.getProjectState(projectPath);
+            stateNow.plugins[name] = {
+                version: plugin.manifest.version,
+                installedAt: new Date().toISOString(),
+                installedFiles,
+                health: 'ok',
+            };
+            await this._writeProjectState(projectPath, stateNow);
+            // No additional approval write needed: any server in `.mcp.json` loads
+            // automatically when Claude opens the project. Install IS active.
+            // Apply shared-file contributors (CLAUDE.md block today, more in the
+            // future). Each contributor is per-plugin and idempotent.
+            const sharedTouched = await (0, contributors_1.applyContributors)(plugin, projectPath, providerId);
+            if (sharedTouched.length > 0) {
+                for (const p of sharedTouched) {
+                    if (!installedFiles.includes(p))
+                        installedFiles.push(p);
+                }
+                const stateNow2 = this.getProjectState(projectPath);
+                if (stateNow2.plugins[name])
+                    stateNow2.plugins[name].installedFiles = installedFiles;
+                await this._writeProjectState(projectPath, stateNow2);
+            }
+        }
+        catch (err) {
+            // Roll back every file we snapshotted. Byte-identical restore.
+            for (const [p, bytes] of preState.entries()) {
+                try {
+                    if (bytes === null) {
+                        if (fs_1.default.existsSync(p))
+                            fs_1.default.unlinkSync(p);
+                    }
+                    else {
+                        // Write the raw Buffer (not .toString('utf8')) so a snapshot with
+                        // non-UTF8 bytes restores byte-for-byte.
+                        (0, json_mutation_1.atomicWriteFileSync)(p, bytes);
+                    }
+                }
+                catch {
+                    // Best-effort rollback; any failure here will surface via verify on
+                    // the next install attempt.
+                }
+            }
+            throw err instanceof PluginInstallError ? err : new PluginInstallError(`install of '${name}' failed: ${err?.message ?? String(err)}`, err);
+        }
+        const msg = {
+            type: 'plugin.installed',
+            projectId,
+            name,
+            version: plugin.manifest.version,
+            timestamp: new Date().toISOString(),
+        };
+        broadcast(msg);
+    }
+    // ─── Uninstall ─────────────────────────────────────────────────────────────
+    async uninstall(projectPath, projectId, name, broadcast, providerId) {
+        const state = this.getProjectState(projectPath);
+        const entry = state.plugins[name];
+        if (!entry)
+            throw new PluginNotInstalledError(name);
+        const plugin = this.registry.byName.get(name);
+        const onLog = (line) => {
+            broadcast({
+                type: 'plugin.install_progress',
+                projectId,
+                name,
+                line,
+                timestamp: new Date().toISOString(),
+            });
+        };
+        if (plugin) {
+            // Revert shared-file contributors first so a partial uninstall doesn't
+            // leave dangling instructions referencing missing tools.
+            await (0, contributors_1.revertContributors)(plugin, projectPath, providerId);
+            await plugin.uninstall({
+                projectPath,
+                projectId,
+                providerId,
+                recordInstalledFile: () => { },
+                log: onLog,
+            });
+        }
+        else {
+            // Orphan removal: no plugin code available. Best-effort cleanup of
+            // recorded installedFiles + drop the state entry. We cannot know which
+            // mcpServers keys belonged to this plugin, so we leave .mcp.json alone.
+            const root = path_1.default.resolve(projectPath);
+            for (const rel of entry.installedFiles ?? []) {
+                const abs = path_1.default.resolve(projectPath, rel);
+                // M5: installedFiles comes from state.json, which a hostile repo can
+                // ship. Without containment, `rel` of "../../../Users/victim/x" (or an
+                // absolute path) turns orphan removal into an arbitrary-file-deletion
+                // primitive. Skip anything that resolves outside the project root.
+                const within = path_1.default.relative(root, abs);
+                if (within === '' || within.startsWith('..') || path_1.default.isAbsolute(within)) {
+                    console.warn(`[plugin-manager] skipping out-of-project installedFile during orphan removal: ${rel}`);
+                    continue;
+                }
+                try {
+                    if (fs_1.default.existsSync(abs))
+                        fs_1.default.unlinkSync(abs);
+                }
+                catch { /* ignore */ }
+            }
+        }
+        const stateNow = this.getProjectState(projectPath);
+        delete stateNow.plugins[name];
+        await this._writeProjectState(projectPath, stateNow);
+        broadcast({
+            type: 'plugin.uninstalled',
+            projectId,
+            name,
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Re-write the project's `.mcp.json` entries owned by this plugin to match
+     * the bundled manifest's canonical shape. Surgical: only the plugin's
+     * `owns.mcpServers` keys are touched; user entries are preserved. Used to
+     * resolve drift surfaced by `updateAvailable`.
+     */
+    async updateMcpEntry(projectPath, projectId, name, broadcast, providerId) {
+        const plugin = this.registry.byName.get(name);
+        if (!plugin)
+            throw new PluginNotFoundError(name);
+        const state = this.getProjectState(projectPath);
+        if (!state.plugins[name])
+            throw new PluginNotInstalledError(name);
+        const expected = plugin.expectedMcpEntry?.();
+        if (!expected) {
+            throw new PluginInstallError(`'${name}' does not declare expectedMcpEntry; cannot update`);
+        }
+        const owned = plugin.manifest.owns.mcpServers ?? [];
+        const entries = {};
+        for (const key of owned)
+            entries[key] = expected;
+        await PluginManager.mergeMcpServers(projectPath, entries);
+        // Refresh shared-file contributions too: a drift may exist in CLAUDE.md
+        // even when the .mcp.json entry matches.
+        await (0, contributors_1.applyContributors)(plugin, projectPath, providerId);
+        broadcast({
+            type: 'plugin.health_changed',
+            projectId,
+            name,
+            status: 'unknown',
+            reason: 'updated',
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /**
+     * Toggle a plugin between active and deactivated. Reality of Claude's MCP
+     * loading: any server present in `<project>/.mcp.json` is loaded by Claude
+     * regardless of `enabledMcpjsonServers` flags. So:
+     *
+     *   - active=true   → re-write the canonical mcpServers entry (from the
+     *                     plugin's `expectedMcpEntry`) into `.mcp.json`
+     *   - active=false  → remove only the owned mcpServers keys; preserve
+     *                     state.json so `installed` memory survives, and
+     *                     preserve any user-authored sibling entries
+     *
+     * Plugin install state survives across toggles. Uninstall is the only
+     * action that clears state.json + custom-*.md fragments.
+     */
+    async setActive(projectPath, projectId, name, active, broadcast, providerId) {
+        const plugin = this.registry.byName.get(name);
+        if (!plugin)
+            throw new PluginNotFoundError(name);
+        const state = this.getProjectState(projectPath);
+        if (!state.plugins[name])
+            throw new PluginNotInstalledError(name);
+        const owned = plugin.manifest.owns.mcpServers ?? [];
+        if (owned.length === 0) {
+            throw new PluginInstallError(`'${name}' owns no mcpServers; cannot toggle activation`);
+        }
+        if (active) {
+            const expected = plugin.expectedMcpEntry?.();
+            if (!expected) {
+                throw new PluginInstallError(`'${name}' does not declare expectedMcpEntry; cannot activate`);
+            }
+            const entries = {};
+            for (const k of owned)
+                entries[k] = expected;
+            await PluginManager.mergeMcpServers(projectPath, entries);
+            await (0, contributors_1.applyContributors)(plugin, projectPath, providerId);
+        }
+        else {
+            await PluginManager.removeMcpServers(projectPath, owned);
+            await (0, contributors_1.revertContributors)(plugin, projectPath, providerId);
+        }
+        broadcast({
+            type: 'plugin.health_changed',
+            projectId,
+            name,
+            status: active ? 'ok' : 'unknown',
+            reason: active ? 'activated' : 'deactivated',
+            timestamp: new Date().toISOString(),
+        });
+    }
+    /** Drop a state.json entry for a plugin no longer in the registry. */
+    async removeOrphan(projectPath, projectId, name, broadcast) {
+        if (this.registry.byName.has(name)) {
+            throw new PluginInstallError(`'${name}' is not orphan; it is still bundled. Use uninstall instead.`);
+        }
+        return this.uninstall(projectPath, projectId, name, broadcast);
+    }
+    // ─── Verify ────────────────────────────────────────────────────────────────
+    async verify(projectPath, projectId, name, broadcast) {
+        const plugin = this.registry.byName.get(name);
+        if (!plugin)
+            throw new PluginNotFoundError(name);
+        const result = await this._runVerify(plugin, projectPath, projectId);
+        await this._cacheHealth(projectPath, projectId, name, result, broadcast);
+        return result;
+    }
+    async _runVerify(plugin, projectPath, projectId) {
+        const timeout = plugin.manifest.verifyTimeoutMs ?? this._options.defaultVerifyTimeoutMs;
+        const checkedAt = new Date().toISOString();
+        try {
+            const result = await Promise.race([
+                plugin.verify({ projectPath, projectId }),
+                new Promise((resolve) => setTimeout(() => resolve({ __timeout: true }), timeout).unref?.()),
+            ]);
+            if ('__timeout' in result) {
+                return { ok: false, reason: 'verify-timeout', checkedAt };
+            }
+            return { ok: result.ok, reason: result.reason, checkedAt: result.checkedAt ?? checkedAt };
+        }
+        catch (err) {
+            return { ok: false, reason: `verify-exception: ${err?.message ?? String(err)}`, checkedAt };
+        }
+    }
+    async _cacheHealth(projectPath, projectId, name, result, broadcast) {
+        const state = this.getProjectState(projectPath);
+        const entry = state.plugins[name];
+        if (!entry)
+            return;
+        const newHealth = result.ok ? 'ok' : 'degraded';
+        const changed = entry.health !== newHealth || entry.healthReason !== result.reason;
+        if (!changed)
+            return; // nothing to persist — avoids per-spawn write churn (verify runs on every rail spawn)
+        entry.health = newHealth;
+        entry.healthReason = result.reason;
+        await this._writeProjectState(projectPath, state);
+        if (broadcast) {
+            const msg = {
+                type: 'plugin.health_changed',
+                projectId,
+                name,
+                status: newHealth,
+                reason: result.reason,
+                timestamp: new Date().toISOString(),
+            };
+            broadcast(msg);
+        }
+    }
+    // ─── Surgical helpers exposed to plugins ───────────────────────────────────
+    /** Helper: surgically merge `mcpServers.<key>` entries into .mcp.json. */
+    static async mergeMcpServers(projectPath, entries) {
+        await (0, json_mutation_1.surgicalMergeJson)((0, paths_1.mcpJsonPath)(projectPath), (current) => {
+            const next = (current ?? {});
+            const servers = (next.mcpServers ?? {});
+            for (const [k, v] of Object.entries(entries))
+                servers[k] = v;
+            next.mcpServers = servers;
+            return next;
+        });
+    }
+    /** Helper: remove specific `mcpServers.<key>` entries from .mcp.json. */
+    static async removeMcpServers(projectPath, keys) {
+        if (keys.length === 0)
+            return;
+        await (0, json_mutation_1.surgicalRemoveKeys)((0, paths_1.mcpJsonPath)(projectPath), keys.map((k) => `mcpServers.${k}`));
+    }
+}
+exports.PluginManager = PluginManager;