specrails-desktop 2.0.0

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

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERENA_MCP_ENTRY = exports.serenaManifest = void 0;
+exports.serenaManifest = {
+    name: 'serena',
+    version: '1.0.0',
+    description: 'Semantic code navigation via Language Server Protocol. Lets agents look up symbols, references, and definitions instead of grepping or reading whole files — typically cutting input tokens 40–60% on real workloads.',
+    whatItDoes: [
+        'Adds a Serena MCP server backed by uvx (Python).',
+        'Exposes find_symbol, find_referencing_symbols, find_declaration, find_implementations, get_symbols_overview, and replace_symbol_body to all agents.',
+        'Auto-detects project language; supports TS/JS, Python, Go, Rust, Java, and more.',
+        'Runs locally — your code never leaves your machine.',
+    ],
+    platformNotes: {
+        'darwin-arm64': 'On Apple Silicon, macOS may prompt to install Rosetta the first time Serena runs. Some Python language-server dependencies ship x86_64 only; click "Install" on the Apple prompt — it is safe and only happens once.',
+    },
+    category: 'code-navigation',
+    requirements: [
+        { name: 'uv', minVersion: '0.1.0' },
+    ],
+    owns: {
+        mcpServers: ['serena'],
+        agentFragments: ['.claude/agents/custom-serena.md'],
+    },
+    providerSupport: {
+        // claude: project-json `.mcp.json` merge (existing path).
+        claude: {
+            mcpEntry: {
+                command: 'uvx',
+                args: [
+                    '--from',
+                    'git+https://github.com/oraios/serena',
+                    'serena',
+                    'start-mcp-server',
+                    '--context',
+                    'ide-assistant',
+                    '--project',
+                    '.',
+                    '--enable-web-dashboard',
+                    'false',
+                ],
+            },
+        },
+        // codex: cli-add via `codex mcp add` with per-project CODEX_HOME.
+        // Same `uvx ...` command; the adapter just registers it differently.
+        codex: {
+            mcpEntry: {
+                command: 'uvx',
+                args: [
+                    '--from',
+                    'git+https://github.com/oraios/serena',
+                    'serena',
+                    'start-mcp-server',
+                    '--context',
+                    'ide-assistant',
+                    '--project',
+                    '.',
+                    '--enable-web-dashboard',
+                    'false',
+                ],
+            },
+        },
+    },
+    // Format: structured "when / tools / why / fallback" block. Lets generic
+    // agent prompts (specrails-core sr-* "Tool Selection — Honor Project-
+    // Documented MCP Tools" section) match the right entry to the task.
+    //
+    // Tool names below are verified against Serena's actual exposed tools
+    // (visible in Claude session init's tools list). Keep this list aligned
+    // with upstream — wrong names cause agents to mistrust the whole block.
+    claudeMdInstructions: `## Plugin: serena (semantic code navigation)
+
+**When to use**: Locating symbols, references, definitions, or implementations in source code; renaming or refactoring a single function in place; getting a file-level symbol skeleton without reading the whole file.
+
+**Tools** (all prefixed \`mcp__serena__\`):
+- \`find_symbol\` — locate a class, function, or method by name path.
+- \`find_referencing_symbols\` — list every caller / usage of a symbol.
+- \`find_declaration\` — jump to where a symbol is defined.
+- \`find_implementations\` — find concrete implementations of an interface or abstract method.
+- \`get_symbols_overview\` — file-level symbol skeleton (signatures only, no bodies).
+- \`replace_symbol_body\` — replace one function's body without re-reading or re-writing the rest of the file.
+- \`insert_before_symbol\` / \`insert_after_symbol\` — splice new code adjacent to a known symbol without rewriting the file.
+- \`rename_symbol\` — rename a symbol and update its references.
+- \`safe_delete_symbol\` — remove a symbol and its references.
+- \`replace_content\` — surgical text replace inside a single file when symbol-aware tools don't fit.
+- \`get_diagnostics_for_file\` — language-server diagnostics for a file.
+
+**Why prefer over built-ins**: Serena returns only the relevant symbol body, not whole files. Empirically cuts input tokens 40–60% on real workloads compared to \`Read\` / \`Grep\`.
+
+**Fallback to \`Read\` / \`Grep\` for**: binary files, free-form prose, structured data without symbols (logs, JSON without schema, plain Markdown).
+
+**Subagents**: MCP access is inherited from the parent Claude session; pass these tool names through when delegating via the \`Task\` tool.`,
+};
+exports.SERENA_MCP_ENTRY = {
+    command: 'uvx',
+    args: [
+        '--from',
+        'git+https://github.com/oraios/serena',
+        'serena',
+        'start-mcp-server',
+        '--context',
+        'ide-assistant',
+        '--project',
+        '.',
+        // Suppress the auto-opened web dashboard. Serena defaults to launching a
+        // local browser tab on start; users running rail jobs find the popup
+        // disruptive.
+        '--enable-web-dashboard',
+        'false',
+    ],
+};

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

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifySerena = verifySerena;
+const child_process_1 = require("child_process");
+const TIMEOUT_MS = 1800;
+/**
+ * Verify Serena availability. We only probe `uv --version` here — proxy for
+ * "uvx will be able to launch serena-mcp-server when claude actually calls it".
+ *
+ * We intentionally do NOT shell out to `uvx --from git+... serena-mcp-server`:
+ * that would download the git repo + dependencies on every verify, which is
+ * slow (multi-second) and would fail offline. The Claude CLI itself triggers
+ * the lazy install through uvx's own cache, so as long as `uv` is on PATH and
+ * executable, install + spawn-time verify can both pass quickly.
+ *
+ * Cross-platform spawn: on Windows we set `shell: true` so PATH resolution
+ * picks up `uv.exe` (or, if astral installed via winget, the .cmd shim) the
+ * same way it does in `setup-prerequisites.ts`.
+ */
+async function verifySerena() {
+    const checkedAt = new Date().toISOString();
+    const isWin = process.platform === 'win32';
+    return new Promise((resolve) => {
+        let settled = false;
+        let stderr = '';
+        let stdout = '';
+        let child;
+        try {
+            child = (0, child_process_1.spawn)('uv', ['--version'], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                shell: isWin,
+            });
+        }
+        catch {
+            resolve({ ok: false, reason: 'uv-not-on-path', checkedAt });
+            return;
+        }
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* ignore */ }
+            resolve({ ok: false, reason: 'verify-timeout', checkedAt });
+        }, TIMEOUT_MS);
+        child.stdout?.on('data', (b) => { stdout += b.toString(); });
+        child.stderr?.on('data', (b) => { stderr += b.toString(); });
+        child.on('error', (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const code = err.code;
+            if (code === 'ENOENT')
+                resolve({ ok: false, reason: 'uv-not-on-path', checkedAt });
+            else
+                resolve({ ok: false, reason: `verify-exception: ${err.message}`, checkedAt });
+        });
+        child.on('close', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (code === 0) {
+                resolve({ ok: true, reason: undefined, checkedAt });
+            }
+            else {
+                resolve({
+                    ok: false,
+                    reason: `uv-non-zero-exit: code=${code} ${stderr.trim().slice(0, 200) || stdout.trim().slice(0, 200)}`,
+                    checkedAt,
+                });
+            }
+        });
+    });
+}

package/server/dist/plugins-router.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPluginsRouter = createPluginsRouter;
+const express_1 = require("express");
+const plugin_manager_1 = require("./plugin-manager");
+const manager_1 = require("./plugins/manager");
+const prereq_installer_1 = require("./plugins/prereq-installer");
+const path_resolver_1 = require("./path-resolver");
+const claude_approval_1 = require("./plugins/claude-approval");
+function pluginsSectionEnabled() {
+    return process.env.SPECRAILS_PLUGINS_SECTION !== 'false';
+}
+function handleError(res, err) {
+    if (err instanceof plugin_manager_1.PluginNotFoundError) {
+        res.status(404).json({ error: err.message });
+        return;
+    }
+    if (err instanceof plugin_manager_1.PluginNotInstalledError) {
+        res.status(404).json({ error: err.message });
+        return;
+    }
+    if (err instanceof plugin_manager_1.PluginAlreadyInstalledError) {
+        res.status(409).json({ error: err.message });
+        return;
+    }
+    if (err instanceof plugin_manager_1.PluginInstallError) {
+        res.status(409).json({ error: err.message });
+        return;
+    }
+    const message = err instanceof Error ? err.message : 'unknown error';
+    res.status(500).json({ error: message });
+}
+function createPluginsRouter() {
+    const router = (0, express_1.Router)({ mergeParams: true });
+    function ctx(req) {
+        return req.projectCtx;
+    }
+    router.use((_req, res, next) => {
+        if (!pluginsSectionEnabled()) {
+            res.status(404).json({ error: 'Plugins section disabled on this server' });
+            return;
+        }
+        next();
+    });
+    // GET /api/projects/:projectId/plugins — catalog
+    router.get('/', async (req, res) => {
+        try {
+            const { project } = ctx(req);
+            const list = await (0, manager_1.getPluginManager)().listAvailable(project.path, project.provider);
+            res.json({ plugins: list });
+        }
+        catch (err) {
+            handleError(res, err);
+        }
+    });
+    // GET /api/projects/:projectId/plugins/:name/preview-install
+    router.get('/:name/preview-install', async (req, res) => {
+        try {
+            const { project } = ctx(req);
+            const result = await (0, manager_1.getPluginManager)().previewInstall(project.path, project.id, req.params.name);
+            res.json(result);
+        }
+        catch (err) {
+            handleError(res, err);
+        }
+    });
+    // POST /api/projects/:projectId/plugins/:name/install
+    router.post('/:name/install', async (req, res) => {
+        try {
+            const { project, broadcast } = ctx(req);
+            await (0, manager_1.getPluginManager)().install(project.path, project.id, req.params.name, broadcast, project.provider);
+            res.status(200).json({ ok: true });
+        }
+        catch (err) {
+            handleError(res, err);
+        }
+    });
+    // DELETE /api/projects/:projectId/plugins/:name — uninstall (or orphan removal)
+    router.delete('/:name', async (req, res) => {
+        try {
+            const { project, broadcast } = ctx(req);
+            await (0, manager_1.getPluginManager)().uninstall(project.path, project.id, req.params.name, broadcast, project.provider);
+            res.status(200).json({ ok: true });
+        }
+        catch (err) {
+            handleError(res, err);
+        }
+    });
+    // POST /api/projects/:projectId/plugins/_prerequisites/:prereq/install
+    // Streams installer output via the project broadcast as
+    // `plugin.prereq_install_progress`; emits `plugin.prereq_installed` on done.
+    router.post('/_prerequisites/:prereq/install', async (req, res) => {
+        const { project, broadcast } = ctx(req);
+        const prereq = req.params.prereq;
+        const allowed = ['uv'];
+        if (!allowed.includes(prereq)) {
+            res.status(404).json({ error: `unknown prerequisite '${prereq}'` });
+            return;
+        }
+        res.status(202).json({ ok: true, message: 'install started' });
+        try {
+            const result = await (0, prereq_installer_1.installPrerequisite)(prereq, project.id, broadcast);
+            // After a successful install, the new binary lives in `~/.local/bin`
+            // (POSIX) or `%USERPROFILE%\.local\bin` (Windows). Refresh the app's
+            // PATH from a login shell so the next verify spawn finds it without a
+            // app restart. On Windows this is a no-op — surface the hint as part
+            // of the reason field instead.
+            let hint;
+            if (result.ok) {
+                if (process.platform === 'win32') {
+                    hint = 'Installed. If verify still fails, restart Specrails so Windows refreshes PATH.';
+                }
+                else {
+                    try {
+                        await (0, path_resolver_1.augmentPathFromLoginShell)({ timeoutMs: 3000 });
+                        hint = 'Installed. PATH refreshed.';
+                    }
+                    catch {
+                        hint = 'Installed. If verify still fails, restart Specrails.';
+                    }
+                }
+            }
+            broadcast({
+                type: 'plugin.prereq_installed',
+                projectId: project.id,
+                prereq,
+                ok: result.ok,
+                reason: result.ok ? hint : result.reason,
+                timestamp: new Date().toISOString(),
+            });
+        }
+        catch (err) {
+            broadcast({
+                type: 'plugin.prereq_installed',
+                projectId: project.id,
+                prereq,
+                ok: false,
+                reason: err?.message ?? 'unknown error',
+                timestamp: new Date().toISOString(),
+            });
+        }
+    });
+    // POST /api/projects/:projectId/plugins/_marketplace/disable
+    // Body: { key: "<plugin-name>@<source>" } — sets enabledPlugins[key]=false
+    // in `~/.claude/settings.json`. The only place the app mutates Claude's
+    // per-user config; surfaced via an explicit user action.
+    router.post('/_marketplace/disable', async (req, res) => {
+        const { project, broadcast } = ctx(req);
+        const key = req.body?.key;
+        if (!key || typeof key !== 'string' || !key.includes('@')) {
+            res.status(400).json({ error: 'body must be { key: "<plugin>@<source>" }' });
+            return;
+        }
+        const result = (0, claude_approval_1.disableMarketplacePlugin)(key);
+        if (!result.ok) {
+            res.status(500).json({ error: result.reason ?? 'unknown' });
+            return;
+        }
+        // Refetch catalog so UI updates conflicts/status without manual refresh.
+        broadcast({
+            type: 'plugin.health_changed',
+            projectId: project.id,
+            name: key.split('@')[0],
+            status: 'unknown',
+            reason: 'marketplace-disabled',
+            timestamp: new Date().toISOString(),
+        });
+        res.json({ ok: true });
+    });
+    // POST /api/projects/:projectId/plugins/:name/activate
+    router.post('/:name/activate', async (req, res) => {
+        try {
+            const { project, broadcast } = ctx(req);
+            await (0, manager_1.getPluginManager)().setActive(project.path, project.id, req.params.name, true, broadcast, project.provider);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            handleError(res, err);
+        }
+    });
+    // POST /api/projects/:projectId/plugins/:name/deactivate
+    router.post('/:name/deactivate', async (req, res) => {
+        try {
+            const { project, broadcast } = ctx(req);
+            await (0, manager_1.getPluginManager)().setActive(project.path, project.id, req.params.name, false, broadcast, project.provider);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            handleError(res, err);
+        }
+    });
+    // POST /api/projects/:projectId/plugins/:name/update — apply manifest drift
+    router.post('/:name/update', async (req, res) => {
+        try {
+            const { project, broadcast } = ctx(req);
+            await (0, manager_1.getPluginManager)().updateMcpEntry(project.path, project.id, req.params.name, broadcast, project.provider);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            handleError(res, err);
+        }
+    });
+    // GET /api/projects/:projectId/plugins/:name/health
+    router.get('/:name/health', async (req, res) => {
+        try {
+            const { project, broadcast } = ctx(req);
+            const result = await (0, manager_1.getPluginManager)().verify(project.path, project.id, req.params.name, broadcast);
+            res.json(result);
+        }
+        catch (err) {
+            handleError(res, err);
+        }
+    });
+    return router;
+}

package/server/dist/pricing.js

@@ -0,0 +1,89 @@
+"use strict";
+// Local pricing table for providers whose CLI does NOT report `total_cost_usd`
+// natively. The app uses this to populate `ai_invocations.total_cost_usd` from
+// captured token usage so the Spending dashboard, daily-budget enforcement, and
+// cost alerts continue to function uniformly across providers.
+//
+// IMPORTANT — review cadence:
+//
+// Every quarter, the maintainer is expected to:
+//   1. Confirm each entry's per-1M-token prices against the provider's
+//      published rate card (https://openai.com/pricing for OpenAI / Codex).
+//   2. Bump the entry's `lastReviewedAt` to the verification date.
+//   3. Add new models that have shipped since the last review.
+//
+// If a model is encountered at runtime that is NOT in the table,
+// `estimateCostUsd` returns `null` and the consuming row is persisted with
+// `total_cost_usd = NULL`. This is the deliberate fail-soft behaviour: never
+// fabricate a cost from an unknown rate card.
+//
+// Spec: openspec/changes/add-multi-provider-support/specs/project-spending/spec.md
+//   - "Pricing-table fallback for non-native-cost providers"
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRICING = void 0;
+exports.estimateCostUsd = estimateCostUsd;
+exports.lastReviewedAt = lastReviewedAt;
+exports.providerNeedsCostEstimation = providerNeedsCostEstimation;
+const registry_1 = require("./providers/registry");
+/** Key shape: `<providerId>:<model>` (case-sensitive). */
+exports.PRICING = {
+    // Codex (OpenAI). Reference: https://openai.com/pricing
+    'codex:gpt-5.5': { inputPer1M: 1.25, outputPer1M: 10.00, cacheReadPer1M: 0.125, lastReviewedAt: '2026-05-17' },
+    'codex:gpt-5.4': { inputPer1M: 2.50, outputPer1M: 10.00, cacheReadPer1M: 0.25, lastReviewedAt: '2026-05-17' },
+    'codex:gpt-5.4-mini': { inputPer1M: 0.25, outputPer1M: 2.00, cacheReadPer1M: 0.025, lastReviewedAt: '2026-05-17' },
+    'codex:gpt-5.3-codex': { inputPer1M: 1.50, outputPer1M: 6.00, cacheReadPer1M: 0.15, lastReviewedAt: '2026-05-17' },
+};
+/**
+ * Estimate cost in USD from a token usage breakdown. Returns `null` when:
+ *   - the model is null/empty,
+ *   - the `${providerId}:${model}` key is not in the pricing table.
+ *
+ * Cache-creation tokens are not modelled (OpenAI does not surface a separate
+ * cache-write tier as of 2026-05-17). When `tokens_cache_create` is present we
+ * silently ignore it — including it as ordinary input tokens would double-count
+ * against the rate card.
+ */
+function estimateCostUsd(providerId, model, usage) {
+    if (!model)
+        return null;
+    const entry = exports.PRICING[`${providerId}:${model}`];
+    if (!entry)
+        return null;
+    // `tokens_in` is the TOTAL prompt token count and `tokens_cache_read` is a
+    // SUBSET already inside it (OpenAI/codex usage semantics: input_tokens
+    // includes cached_input_tokens). Bill the cached portion at the cache rate
+    // ONLY, and the remaining fresh input at the full input rate. Charging the
+    // full input rate over the whole `tokens_in` AND a separate cache-read cost
+    // would double-charge every cached token. Clamp at 0 to guard a malformed
+    // payload where the reported cache subset exceeds the total.
+    const freshInput = Math.max(0, (usage.tokens_in ?? 0) - (usage.tokens_cache_read ?? 0));
+    const inputCost = freshInput * entry.inputPer1M / 1_000_000;
+    const outputCost = (usage.tokens_out ?? 0) * entry.outputPer1M / 1_000_000;
+    const cacheReadCost = (usage.tokens_cache_read ?? 0) * entry.cacheReadPer1M / 1_000_000;
+    return inputCost + outputCost + cacheReadCost;
+}
+/**
+ * Returns the oldest `lastReviewedAt` date across the table. Surfaced by an
+ * optional diagnostic endpoint so the maintainer can spot staleness quickly.
+ */
+function lastReviewedAt() {
+    let oldest = null;
+    for (const entry of Object.values(exports.PRICING)) {
+        if (oldest === null || entry.lastReviewedAt < oldest)
+            oldest = entry.lastReviewedAt;
+    }
+    return oldest ?? '0000-00-00';
+}
+/**
+ * Returns true when the resolved adapter for the given provider id declares
+ * `capabilities.nativeCostUsd === false`. Used by callsites to decide whether
+ * to fall back to estimation vs trust the provider's terminal event.
+ *
+ * Returns false for unknown ids (defensive: do not call the estimator for an
+ * unrecognised provider).
+ */
+function providerNeedsCostEstimation(providerId) {
+    if (!(0, registry_1.hasAdapter)(providerId))
+        return false;
+    return (0, registry_1.getAdapter)(providerId).capabilities.nativeCostUsd === false;
+}