specrails-desktop 2.0.0

package/server/dist/plugins/json-mutation.js

@@ -0,0 +1,120 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFileLock = withFileLock;
+exports.atomicWriteFileSync = atomicWriteFileSync;
+exports.readJsonOr = readJsonOr;
+exports.surgicalMergeJson = surgicalMergeJson;
+exports.surgicalRemoveKeys = surgicalRemoveKeys;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * In-process mutex keyed by absolute file path. The app runs as a single
+ * Node process so cross-process locking (proper-lockfile, flock) is not
+ * required for v1: every install / uninstall path goes through this module.
+ *
+ * If the architecture ever moves to multi-process or parallel test workers
+ * sharing a project directory, swap this for an advisory file lock. The API
+ * surface (`withFileLock`) is intentionally narrow so the swap is mechanical.
+ */
+const _locks = new Map();
+async function withFileLock(filePath, fn) {
+    const key = path_1.default.resolve(filePath);
+    const previous = _locks.get(key) ?? Promise.resolve();
+    let release;
+    const next = new Promise((resolve) => { release = resolve; });
+    // B74: hold the SAME promise reference we store, so the finally can compare by
+    // identity. The old code rebuilt `previous.then(() => next)` in the finally — a
+    // fresh promise that never matched, so the cleanup never ran and `_locks` grew
+    // one entry per distinct file path forever.
+    const chained = previous.then(() => next);
+    _locks.set(key, chained);
+    try {
+        await previous;
+        return await fn();
+    }
+    finally {
+        release();
+        // Drop the entry only if no later caller has chained onto us (i.e. we are
+        // still the tail). Otherwise their chain depends on ours — leave it.
+        if (_locks.get(key) === chained) {
+            _locks.delete(key);
+        }
+    }
+}
+/** Atomically replace a file's bytes by writing a sibling temp file and renaming.
+ *  Accepts a raw Buffer for byte-identical restores (rollback of snapshots that
+ *  may contain non-UTF8 bytes); a string is written as UTF-8. */
+function atomicWriteFileSync(filePath, body, mode) {
+    fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    // Node ignores the encoding option for Buffer payloads; only set it for strings.
+    const opts = Buffer.isBuffer(body)
+        ? (mode != null ? { mode } : {})
+        : (mode != null ? { encoding: 'utf8', mode } : { encoding: 'utf8' });
+    fs_1.default.writeFileSync(tmp, body, opts);
+    fs_1.default.renameSync(tmp, filePath);
+}
+/** Read+parse JSON; returns `defaultValue` when the file is missing. Throws on malformed JSON. */
+function readJsonOr(filePath, defaultValue) {
+    if (!fs_1.default.existsSync(filePath))
+        return defaultValue;
+    const raw = fs_1.default.readFileSync(filePath, 'utf8');
+    if (!raw.trim())
+        return defaultValue;
+    return JSON.parse(raw);
+}
+/**
+ * Surgically merge a JSON file by passing the parsed object (or `null` when
+ * absent) to `mutator` and atomically writing back the result. The mutator
+ * MUST return the new object to write, or `null` to delete the file.
+ *
+ * Holds an in-process file lock for the whole read-modify-write round trip.
+ */
+async function surgicalMergeJson(filePath, mutator) {
+    await withFileLock(filePath, async () => {
+        let current = null;
+        if (fs_1.default.existsSync(filePath)) {
+            const raw = fs_1.default.readFileSync(filePath, 'utf8');
+            current = raw.trim() ? JSON.parse(raw) : null;
+        }
+        const next = mutator(current);
+        if (next === null) {
+            if (fs_1.default.existsSync(filePath))
+                fs_1.default.unlinkSync(filePath);
+            return;
+        }
+        atomicWriteFileSync(filePath, JSON.stringify(next, null, 2) + '\n');
+    });
+}
+/**
+ * Surgically remove top-level or nested keys from a JSON file. `paths` is a
+ * list of dot-separated paths (e.g., "mcpServers.serena"). Missing paths are
+ * a no-op. The file is not removed even when emptied — callers preserve the
+ * "state file always survives" invariant.
+ */
+async function surgicalRemoveKeys(filePath, paths) {
+    if (paths.length === 0)
+        return;
+    await surgicalMergeJson(filePath, (current) => {
+        if (!current)
+            return current;
+        for (const p of paths) {
+            const segments = p.split('.');
+            let cursor = current;
+            for (let i = 0; i < segments.length - 1; i++) {
+                const next = cursor?.[segments[i]];
+                if (typeof next !== 'object' || next === null) {
+                    cursor = undefined;
+                    break;
+                }
+                cursor = next;
+            }
+            if (cursor)
+                delete cursor[segments[segments.length - 1]];
+        }
+        return current;
+    });
+}

package/server/dist/plugins/manager.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPluginManager = getPluginManager;
+exports.setPluginManagerForTesting = setPluginManagerForTesting;
+const plugin_manager_1 = require("../plugin-manager");
+const index_1 = require("./index");
+const setup_prerequisites_1 = require("../setup-prerequisites");
+const livePrerequisiteCheck = async (req) => {
+    const status = (0, setup_prerequisites_1.getSetupPrerequisitesStatus)({ includeUv: true });
+    const match = status.prerequisites.find((p) => p.command === req.name || p.key === req.name);
+    if (!match) {
+        return { installed: false, executable: false, meetsMinimum: false };
+    }
+    return {
+        installed: match.installed,
+        executable: match.executable,
+        version: match.version,
+        meetsMinimum: match.meetsMinimum,
+    };
+};
+let _instance = null;
+/** Lazily-built process-wide PluginManager (driven by BUNDLED_PLUGINS). */
+function getPluginManager() {
+    if (!_instance) {
+        _instance = new plugin_manager_1.PluginManager(index_1.BUNDLED_PLUGINS, { checkPrerequisite: livePrerequisiteCheck });
+    }
+    return _instance;
+}
+/** Test helper: replace the singleton. */
+function setPluginManagerForTesting(mgr) {
+    _instance = mgr;
+}

package/server/dist/plugins/ownership.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginOwnershipConflictError = void 0;
+exports.buildOwnershipMap = buildOwnershipMap;
+class PluginOwnershipConflictError extends Error {
+    conflicts;
+    constructor(conflicts) {
+        const lines = conflicts.map((c) => `  ${c.kind}.${c.key} claimed by: ${c.plugins.join(', ')}`);
+        super(`plugin ownership conflict:\n${lines.join('\n')}`);
+        this.name = 'PluginOwnershipConflictError';
+        this.conflicts = conflicts;
+    }
+}
+exports.PluginOwnershipConflictError = PluginOwnershipConflictError;
+/**
+ * Build a global ownership index from a registry of plugins. Fails fast when
+ * any two plugins claim the same key — that is the central guarantee that
+ * additivity holds: install/uninstall of plugin N can never corrupt plugin M
+ * because their owned keys are statically known to be disjoint.
+ *
+ * Also rejects plugins with duplicate names.
+ */
+function buildOwnershipMap(plugins) {
+    const byName = new Map();
+    const mcpServers = new Map();
+    const agentFragments = new Map();
+    const configKeys = new Map();
+    const conflicts = [];
+    // Tracks which plugins claim each key, for richer error reporting.
+    const claimMap = {
+        mcpServers: new Map(),
+        agentFragments: new Map(),
+        configKeys: new Map(),
+    };
+    for (const plugin of plugins) {
+        const m = plugin.manifest;
+        if (!m || !m.name) {
+            throw new Error('plugin manifest is missing required field: name');
+        }
+        if (!m.version) {
+            throw new Error(`plugin '${m.name}' is missing required field: version`);
+        }
+        if (!m.owns) {
+            throw new Error(`plugin '${m.name}' is missing required field: owns`);
+        }
+        if (byName.has(m.name)) {
+            throw new Error(`duplicate plugin name in registry: '${m.name}'`);
+        }
+        byName.set(m.name, plugin);
+        for (const key of m.owns.mcpServers ?? []) {
+            const list = claimMap.mcpServers.get(key) ?? [];
+            list.push(m.name);
+            claimMap.mcpServers.set(key, list);
+        }
+        for (const key of m.owns.agentFragments ?? []) {
+            const list = claimMap.agentFragments.get(key) ?? [];
+            list.push(m.name);
+            claimMap.agentFragments.set(key, list);
+        }
+        for (const key of m.owns.configKeys ?? []) {
+            const list = claimMap.configKeys.get(key) ?? [];
+            list.push(m.name);
+            claimMap.configKeys.set(key, list);
+        }
+    }
+    // Promote single-claimer entries; surface multi-claimer entries as conflicts.
+    for (const kind of ['mcpServers', 'agentFragments', 'configKeys']) {
+        for (const [key, owners] of claimMap[kind].entries()) {
+            if (owners.length === 1) {
+                if (kind === 'mcpServers')
+                    mcpServers.set(key, owners[0]);
+                else if (kind === 'agentFragments')
+                    agentFragments.set(key, owners[0]);
+                else
+                    configKeys.set(key, owners[0]);
+            }
+            else {
+                conflicts.push({ kind, key, plugins: owners });
+            }
+        }
+    }
+    if (conflicts.length > 0) {
+        throw new PluginOwnershipConflictError(conflicts);
+    }
+    return { mcpServers, agentFragments, configKeys, byName };
+}

package/server/dist/plugins/paths.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginsDir = pluginsDir;
+exports.stateFilePath = stateFilePath;
+exports.snapshotsDir = snapshotsDir;
+exports.projectJobSnapshotPath = projectJobSnapshotPath;
+exports.homeJobSnapshotPath = homeJobSnapshotPath;
+exports.mcpJsonPath = mcpJsonPath;
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+/** `<project>/.specrails/plugins/` — base directory for app-managed plugin state. */
+function pluginsDir(projectPath) {
+    return path_1.default.join(projectPath, '.specrails', 'plugins');
+}
+/** `<project>/.specrails/plugins/state.json` — per-project plugin registry. */
+function stateFilePath(projectPath) {
+    return path_1.default.join(pluginsDir(projectPath), 'state.json');
+}
+/** `<project>/.specrails/plugins/snapshots/` — per-job plugin snapshots (project-local copy). */
+function snapshotsDir(projectPath) {
+    return path_1.default.join(pluginsDir(projectPath), 'snapshots');
+}
+/** `<project>/.specrails/plugins/snapshots/<jobId>.json` — per-job project-local snapshot. */
+function projectJobSnapshotPath(projectPath, jobId) {
+    return path_1.default.join(snapshotsDir(projectPath), `${jobId}.json`);
+}
+/** `~/.specrails/projects/<slug>/jobs/<jobId>/plugins.json` — chmod-400 spawn-time snapshot. */
+function homeJobSnapshotPath(slug, jobId) {
+    return path_1.default.join(os_1.default.homedir(), '.specrails', 'projects', slug, 'jobs', jobId, 'plugins.json');
+}
+/** `<project>/.mcp.json` — Claude CLI MCP config (managed surgically by the app). */
+function mcpJsonPath(projectPath) {
+    return path_1.default.join(projectPath, '.mcp.json');
+}

package/server/dist/plugins/prereq-installer.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installPrerequisite = installPrerequisite;
+const child_process_1 = require("child_process");
+/**
+ * Returns the official installer command for `name` on the current platform.
+ * Returns `null` for unsupported (name, platform) pairs — caller should treat
+ * as "tell the user to install manually".
+ */
+function resolveInstallerCommand(name) {
+    if (name !== 'uv')
+        return null;
+    if (process.platform === 'darwin' || process.platform === 'linux') {
+        return {
+            label: 'Astral uv installer (curl)',
+            shell: 'curl -LsSf https://astral.sh/uv/install.sh | sh',
+        };
+    }
+    if (process.platform === 'win32') {
+        // PowerShell installer is the cross-version path. winget would be nicer
+        // but isn't always present. The Astral installer adds uv to PATH for the
+        // user; the app's PATH augmentation on next start picks it up.
+        return {
+            label: 'Astral uv installer (PowerShell)',
+            shell: 'powershell -ExecutionPolicy ByPass -NoProfile -Command "irm https://astral.sh/uv/install.ps1 | iex"',
+        };
+    }
+    return null;
+}
+/**
+ * Run the platform-appropriate installer for `name` and stream stdout+stderr
+ * to `broadcast` as `plugin.prereq_install_progress` events. Resolves once the
+ * child exits — never throws.
+ */
+async function installPrerequisite(name, projectId, broadcast) {
+    const cmd = resolveInstallerCommand(name);
+    if (!cmd) {
+        return { ok: false, exitCode: null, reason: `no installer for '${name}' on ${process.platform}` };
+    }
+    const log = (line) => {
+        broadcast({
+            type: 'plugin.prereq_install_progress',
+            projectId,
+            prereq: name,
+            line,
+            timestamp: new Date().toISOString(),
+        });
+    };
+    log(`Running: ${cmd.label}`);
+    log(`> ${cmd.shell}`);
+    // Escape hatch for tests that exercise the router but don't want a real
+    // network installer to spawn. Set SPECRAILS_PREREQ_NOOP=1 to short-circuit.
+    if (process.env.SPECRAILS_PREREQ_NOOP === '1') {
+        log('(SPECRAILS_PREREQ_NOOP=1 — skipping real installer)');
+        return { ok: true, exitCode: 0, reason: 'noop' };
+    }
+    return new Promise((resolve) => {
+        const isWin = process.platform === 'win32';
+        // Use shell:true so pipes / irm / iex work. Inputs are not user-controlled.
+        const child = (0, child_process_1.spawn)(cmd.shell, [], {
+            shell: isWin ? 'powershell.exe' : true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: process.env,
+        });
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        child.stdout?.on('data', (b) => { for (const line of b.toString().split(/\r?\n/))
+            if (line)
+                log(line); });
+        child.stderr?.on('data', (b) => { for (const line of b.toString().split(/\r?\n/))
+            if (line)
+                log(line); });
+        child.on('error', (err) => {
+            log(`error: ${err.message}`);
+            finish({ ok: false, exitCode: null, reason: err.message });
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                log('Installer finished successfully.');
+                finish({ ok: true, exitCode: 0 });
+            }
+            else {
+                log(`Installer exited with code ${code}`);
+                finish({ ok: false, exitCode: code, reason: `exit-code-${code}` });
+            }
+        });
+        // Hard cap: 5 minutes. Long enough for slow networks, prevents hangs.
+        setTimeout(() => {
+            if (settled)
+                return;
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* ignore */ }
+            log('Installer timed out after 5 minutes');
+            finish({ ok: false, exitCode: null, reason: 'timeout' });
+        }, 5 * 60 * 1000).unref?.();
+    });
+}

package/server/dist/plugins/rail-integration.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePluginsForSpawn = resolvePluginsForSpawn;
+exports.snapshotPluginsForJob = snapshotPluginsForJob;
+exports.snapshotPluginsForJobProjectLocal = snapshotPluginsForJobProjectLocal;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const manager_1 = require("./manager");
+const paths_1 = require("./paths");
+const json_mutation_1 = require("./json-mutation");
+/**
+ * Resolves the project's installed plugins for a rail spawn. For each entry
+ * in `state.json`, runs `verify` (timeout-bounded) and classifies into
+ * `active` (verify ok) or `degraded` (verify failed / timed out / threw).
+ *
+ * Side effect: `verify` persists a plugin's health to `state.json` only when it
+ * actually changed since the last check (no churn on the steady-state path).
+ * Otherwise this performs no project-file mutation.
+ */
+async function resolvePluginsForSpawn(projectPath, projectId, _jobId) {
+    const mgr = (0, manager_1.getPluginManager)();
+    const state = mgr.getProjectState(projectPath);
+    const active = [];
+    const degraded = [];
+    // Run verify in parallel for all installed plugins. Each verify is
+    // already timeout-wrapped inside PluginManager.
+    const checks = await Promise.all(Object.entries(state.plugins).map(async ([name, entry]) => {
+        // Skip orphans — they are not in the registry, so verify cannot run.
+        if (!mgr.registry.byName.has(name))
+            return { name, version: entry.version, result: { ok: false, reason: 'orphan', checkedAt: new Date().toISOString() } };
+        const result = await mgr.verify(projectPath, projectId, name);
+        return { name, version: entry.version, result };
+    }));
+    for (const c of checks) {
+        if (c.result.ok)
+            active.push({ name: c.name, version: c.version });
+        else
+            degraded.push({ name: c.name, reason: c.result.reason ?? 'unknown' });
+    }
+    return { active, degraded };
+}
+/**
+ * Writes the per-job plugin snapshot to:
+ *   - `~/.specrails/projects/<slug>/jobs/<jobId>/plugins.json` (chmod 400)
+ *   - `<project>/.specrails/plugins/snapshots/<jobId>.json` (project-local mirror)
+ * Returns the absolute path of the home-side snapshot (used for env var).
+ */
+function snapshotPluginsForJob(slug, jobId, projectId, active, degraded) {
+    const body = JSON.stringify({
+        jobId,
+        projectId,
+        capturedAt: new Date().toISOString(),
+        active,
+        degraded,
+    }, null, 2) + '\n';
+    // Home-side snapshot — chmod 400, source of truth for diagnostic export.
+    const homeSnap = (0, paths_1.homeJobSnapshotPath)(slug, jobId);
+    fs_1.default.mkdirSync(path_1.default.dirname(homeSnap), { recursive: true });
+    (0, json_mutation_1.atomicWriteFileSync)(homeSnap, body, 0o400);
+    return homeSnap;
+}
+/**
+ * Project-local mirror snapshot, kept alongside `state.json`. Best-effort —
+ * never fails the rail spawn. Used for in-app inspection.
+ */
+function snapshotPluginsForJobProjectLocal(projectPath, jobId, projectId, active, degraded) {
+    try {
+        const body = JSON.stringify({ jobId, projectId, capturedAt: new Date().toISOString(), active, degraded }, null, 2) + '\n';
+        const p = (0, paths_1.projectJobSnapshotPath)(projectPath, jobId);
+        fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
+        (0, json_mutation_1.atomicWriteFileSync)(p, body);
+    }
+    catch {
+        // Non-fatal.
+    }
+}

package/server/dist/plugins/serena/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serenaPlugin = void 0;
+const manifest_1 = require("./manifest");
+const install_1 = require("./install");
+const verify_1 = require("./verify");
+exports.serenaPlugin = {
+    manifest: manifest_1.serenaManifest,
+    install: install_1.installSerena,
+    uninstall: install_1.uninstallSerena,
+    verify: verify_1.verifySerena,
+    expectedMcpEntry: () => manifest_1.SERENA_MCP_ENTRY,
+};

package/server/dist/plugins/serena/install.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installSerena = installSerena;
+exports.uninstallSerena = uninstallSerena;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const plugin_manager_1 = require("../../plugin-manager");
+const manifest_1 = require("./manifest");
+const instructions_content_1 = require("./instructions-content");
+const codex_mcp_1 = require("../codex-mcp");
+const providers_1 = require("../../providers");
+/** Claude fragment lives in the core-protected `.claude/agents/custom-*.md`
+ *  namespace; only written on claude projects. Codex doesn't honour that
+ *  file convention, and the per-project AGENTS.md block (written by the
+ *  shared-file contributor in plugin-manager) is the codex equivalent. */
+const CLAUDE_FRAGMENT_REL = '.claude/agents/custom-serena.md';
+function isCodex(ctx) {
+    if (!ctx.providerId)
+        return false;
+    if (!(0, providers_1.hasAdapter)(ctx.providerId))
+        return false;
+    return (0, providers_1.getAdapter)(ctx.providerId).mcpRegistration === 'cli-add';
+}
+/** Project slug used by codex-mcp helpers — derived from the project path's
+ *  basename. The app maintains the canonical slug elsewhere (ProjectRegistry);
+ *  for the install context we don't have the registry, but the basename is a
+ *  stable per-project identifier sufficient for CODEX_HOME isolation. */
+function slugFromProjectPath(projectPath) {
+    return path_1.default.basename(projectPath);
+}
+async function installSerena(ctx) {
+    if (isCodex(ctx)) {
+        // Codex path: `codex mcp add` against per-project CODEX_HOME. The
+        // declarative entry comes from the manifest's providerSupport.codex
+        // so future plugins can declare their own without touching this file.
+        const entry = manifest_1.serenaManifest.providerSupport?.codex?.mcpEntry;
+        if (!entry) {
+            throw new Error('serena manifest is missing providerSupport.codex.mcpEntry');
+        }
+        const slug = slugFromProjectPath(ctx.projectPath);
+        ctx.log(`Registering serena MCP via 'codex mcp add' (CODEX_HOME=~/.specrails/projects/${slug}/codex-home/)`);
+        const result = (0, codex_mcp_1.codexMcpAdd)(slug, 'serena', entry);
+        if (!result.ok) {
+            const detail = result.stderr.trim() || result.stdout.trim() || '(no output)';
+            throw new Error(`codex mcp add serena failed: ${detail}`);
+        }
+        return;
+    }
+    // Claude path: surgical merge of project's `.mcp.json` + custom agent
+    // fragment. Unchanged from the pre-§14 behaviour.
+    ctx.log('Adding mcpServers.serena to .mcp.json');
+    await plugin_manager_1.PluginManager.mergeMcpServers(ctx.projectPath, { serena: manifest_1.SERENA_MCP_ENTRY });
+    ctx.log(`Writing ${CLAUDE_FRAGMENT_REL}`);
+    const fragmentDest = path_1.default.join(ctx.projectPath, CLAUDE_FRAGMENT_REL);
+    fs_1.default.mkdirSync(path_1.default.dirname(fragmentDest), { recursive: true });
+    fs_1.default.writeFileSync(fragmentDest, instructions_content_1.SERENA_INSTRUCTIONS_MD, 'utf8');
+    ctx.recordInstalledFile(CLAUDE_FRAGMENT_REL);
+}
+async function uninstallSerena(ctx) {
+    if (isCodex(ctx)) {
+        const slug = slugFromProjectPath(ctx.projectPath);
+        // Probe first so removing an already-removed server doesn't surface as an
+        // error (e.g. the user uninstalled via terminal then via the app).
+        const listing = (0, codex_mcp_1.codexMcpList)(slug);
+        if (listing.ok && !listing.servers.includes('serena')) {
+            ctx.log('serena not present in codex mcp list — nothing to remove');
+            return;
+        }
+        ctx.log(`Removing serena via 'codex mcp remove' (CODEX_HOME=~/.specrails/projects/${slug}/codex-home/)`);
+        const result = (0, codex_mcp_1.codexMcpRemove)(slug, 'serena');
+        if (!result.ok) {
+            // Removal failures are warnings — the state.json entry is gone either
+            // way and a subsequent install will overwrite. Don't block uninstall.
+            ctx.log(`codex mcp remove warning: ${result.stderr.trim() || '(no output)'}`);
+        }
+        return;
+    }
+    ctx.log('Removing mcpServers.serena from .mcp.json');
+    await plugin_manager_1.PluginManager.removeMcpServers(ctx.projectPath, ['serena']);
+    const fragmentDest = path_1.default.join(ctx.projectPath, CLAUDE_FRAGMENT_REL);
+    if (fs_1.default.existsSync(fragmentDest)) {
+        ctx.log(`Removing ${CLAUDE_FRAGMENT_REL}`);
+        try {
+            fs_1.default.unlinkSync(fragmentDest);
+        }
+        catch { /* best-effort */ }
+    }
+}

package/server/dist/plugins/serena/instructions-content.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERENA_INSTRUCTIONS_MD = void 0;
+/* Embedded so the plugin survives bundling/packaging without external assets. */
+exports.SERENA_INSTRUCTIONS_MD = `---
+name: serena-helper
+description: "Serena MCP semantic-navigation hints (auto-installed by Specrails). Prefer Serena tools over raw Read/Grep when locating symbols, references, or definitions."
+color: violet
+memory: project
+---
+
+# Serena MCP — usage hints
+
+When working in a repository where Serena is installed:
+
+- Prefer \`find_symbol\`, \`get_references\`, \`get_definition\`, and \`get_symbols_overview\` over \`Read\` and \`Grep\` when you only need a function, class, or callsites.
+- Use \`replace_symbol_body\` to edit a function or method without re-reading or re-writing the rest of the file.
+- Fall back to \`Read\` / \`Grep\` only when Serena cannot handle the request (e.g., binary files, free-form text, JSON/Markdown without symbols).
+
+These tools are added to every agent on this project automatically; no further configuration is needed.
+`;