specrails-desktop 2.16.0 → 2.18.0

package/server/dist/mcp/tools/plugins.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginsTools = pluginsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Plugins (Integrations) domain facade. Per-project marketplace of MCP-based
+ * integrations (bundled-only in v1). Maps each action to the matching REST
+ * endpoint under `/api/projects/:projectId/plugins`.
+ *
+ * Excluded by design (v1 out of scope): the `uv` prerequisite installer
+ * (`/plugins/_prerequisites/:prereq/install`) and the marketplace
+ * global-settings mutation (`/plugins/_marketplace/disable`).
+ */
+function pluginsTools() {
+    return [
+        {
+            name: 'specrails_plugins',
+            title: 'Plugins',
+            description: 'List and manage a project\'s MCP-based integration plugins (Integrations). ' +
+                'Actions: list (catalog with status/health/version/drift), preview (dry-run install diff + requirements), ' +
+                'install (write — runs the installer + verify, surgically merges .mcp.json, streams plugin.install_progress; long-running), ' +
+                'uninstall (destructive — reverts contributors, removes owned mcpServers + installed files, drops state), ' +
+                'activate (re-enable an installed-but-off plugin), deactivate (toggle off without uninstalling), ' +
+                'update (apply manifest drift — re-merge owned mcpServers + re-apply contributors), ' +
+                'health (on-demand verify of an installed plugin).',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (action === 'uninstall')
+                    return 'destructive';
+                if (['install', 'activate', 'deactivate', 'update'].includes(action))
+                    return 'write';
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum(['list', 'preview', 'install', 'uninstall', 'activate', 'deactivate', 'update', 'health'])
+                    .describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                name: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Bundled plugin name (required for preview/install/uninstall/activate/deactivate/update/health)'),
+            },
+            async handler(ctx, args) {
+                const base = `${(0, types_1.projectPath)(ctx, args.projectId)}/plugins`;
+                const action = args.action;
+                const name = args.name;
+                const requireName = () => {
+                    if (!name)
+                        throw new Error(`Action "${action}" requires a "name" (bundled plugin name).`);
+                    return encodeURIComponent(name);
+                };
+                switch (action) {
+                    case 'list':
+                        return (0, types_1.apiCall)(ctx, 'GET', base);
+                    case 'preview':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/${requireName()}/preview-install`);
+                    case 'install': {
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/${requireName()}/install`);
+                        return {
+                            ...(typeof r === 'object' && r !== null ? r : { result: r }),
+                            hint: 'Install runs the plugin installer + verify and streams plugin.install_progress / plugin.installed WS events. Use specrails_watch to observe progress, or call action="health" to confirm the plugin verified.',
+                        };
+                    }
+                    case 'uninstall':
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/${requireName()}`);
+                    case 'activate':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${requireName()}/activate`);
+                    case 'deactivate':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${requireName()}/deactivate`);
+                    case 'update':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${requireName()}/update`);
+                    case 'health':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/${requireName()}/health`);
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

package/server/dist/mcp/tools/projects.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeProject = serializeProject;
+exports.projectsTools = projectsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+function serializeProject(p) {
+    return {
+        id: p.id,
+        slug: p.slug,
+        name: p.name,
+        path: p.path,
+        provider: p.provider,
+        providers: p.providers,
+        addedAt: p.added_at,
+        lastSeenAt: p.last_seen_at,
+    };
+}
+function projectsTools() {
+    return [
+        {
+            name: 'specrails_projects',
+            title: 'Projects',
+            description: 'List and inspect registered Specrails projects, resolve a project by filesystem path, or unregister one. ' +
+                'Actions: list, get, resolve (by path), unregister (destructive — removes the project and its workspace).',
+            hintTier: 'read',
+            tier: (args) => (args.action === 'unregister' ? 'destructive' : 'read'),
+            inputSchema: {
+                action: zod_1.z.enum(['list', 'get', 'resolve', 'unregister']).describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (for get / unregister)'),
+                path: zod_1.z.string().optional().describe('Filesystem path (for resolve)'),
+            },
+            handler: (ctx, args) => {
+                const action = args.action;
+                switch (action) {
+                    case 'list':
+                        return ctx.registry.listContexts().map((c) => serializeProject(c.project));
+                    case 'get':
+                        return serializeProject((0, types_1.requireProject)(ctx, args.projectId).project);
+                    case 'resolve': {
+                        const p = args.path;
+                        if (!p)
+                            throw new Error('resolve requires a "path".');
+                        const pc = ctx.registry.getContextByPath(p);
+                        return pc ? serializeProject(pc.project) : { resolved: false };
+                    }
+                    case 'unregister': {
+                        const id = args.projectId;
+                        if (!id)
+                            throw new Error('unregister requires a "projectId".');
+                        if (!ctx.registry.getContext(id))
+                            throw new Error(`Unknown projectId "${id}".`);
+                        ctx.registry.removeProject(id);
+                        return { ok: true, unregistered: id };
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

package/server/dist/mcp/tools/rails.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.railsTools = railsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Rails domain facade. A "rail" is a numbered launch slot per project: it holds
+ * a set of assigned ticket IDs plus a mode/profile/engine/name, and launching it
+ * spawns the AI pipeline (claude/codex/gemini) over those tickets.
+ *
+ * Every operation is per-project under /api/projects/:projectId/rails. The
+ * launch action is the only cost-incurring / repo-mutating one (ai-spawn, 202);
+ * stop is destructive (kills running child process trees + cancels queued jobs).
+ */
+function railsTools() {
+    return [
+        {
+            name: 'specrails_rails',
+            title: 'Rails',
+            description: 'List and configure a project\'s rail launch slots, then launch or stop the AI pipeline for a rail. ' +
+                'A rail holds assigned ticket IDs plus a mode/profile/engine/name. ' +
+                'Actions: list (rails + active jobs/loop runs), set_tickets (assign ticket IDs), set_profile (default agent profile, null=legacy), ' +
+                'set_engine (provider override, null=primary), set_name (display label, null clears), ' +
+                'launch (ai-spawn — spawns claude/codex/gemini CLI job(s) that WRITE CODE, RUN TESTS, COMMIT, and INCUR TOKEN COST; returns 202 with jobId/jobIds/loopRunIds), ' +
+                'stop (destructive — kills all active jobs and loop runs for the rail).',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (action === 'stop')
+                    return 'destructive';
+                if (action === 'launch')
+                    return 'ai-spawn';
+                if (action === 'set_tickets' || action === 'set_profile' || action === 'set_engine' || action === 'set_name')
+                    return 'write';
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum(['list', 'set_tickets', 'set_profile', 'set_engine', 'set_name', 'launch', 'stop'])
+                    .describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                railIndex: zod_1.z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe('Rail slot index (required for every action except list)'),
+                // set_tickets
+                ticketIds: zod_1.z
+                    .array(zod_1.z.number().int())
+                    .optional()
+                    .describe('Ticket IDs to assign to the rail (set_tickets — replaces the existing set)'),
+                // set_profile
+                profileName: zod_1.z
+                    .string()
+                    .nullable()
+                    .optional()
+                    .describe('Agent profile name; null forces legacy/no-profile mode (set_profile; also optional override for launch)'),
+                // set_engine / launch
+                aiEngine: zod_1.z
+                    .string()
+                    .nullable()
+                    .optional()
+                    .describe('AI engine/provider override; null = project primary (set_engine; also optional override for launch). Must be an installed provider.'),
+                // set_name
+                name: zod_1.z
+                    .string()
+                    .nullable()
+                    .optional()
+                    .describe('Rail display label (<=60 chars); null/empty clears to default (set_name)'),
+                // launch
+                mode: zod_1.z
+                    .enum(['implement', 'batch-implement', 'ultracode', 'loop'])
+                    .optional()
+                    .describe('Launch mode (launch; default "implement"). ultracode is Claude-only and runs one job per ticket; loop runs an app-driven loop per ticket.'),
+                model: zod_1.z
+                    .enum(['haiku', 'sonnet', 'opus'])
+                    .optional()
+                    .describe('Ultracode Claude model (launch, ultracode mode only). For loop mode, a provider-valid model string.'),
+                interactive: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('Interactive ultracode session (launch, ultracode + Claude only; requires the interactive-jobs feature)'),
+                loopId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Loop id to run (launch). Factory ids (e.g. "factory:implement") map to a legacy mode; a custom published loop id keeps mode="loop".'),
+                reasoning_effort: zod_1.z
+                    .enum(['low', 'medium', 'high'])
+                    .optional()
+                    .describe('Reasoning-effort tier for loop launches (launch, loop mode)'),
+            },
+            async handler(ctx, args) {
+                const base = `${(0, types_1.projectPath)(ctx, args.projectId)}/rails`;
+                const action = args.action;
+                const requireRailIndex = () => {
+                    const idx = args.railIndex;
+                    if (typeof idx !== 'number' || !Number.isInteger(idx) || idx < 0) {
+                        throw new Error(`Action "${action}" requires a non-negative integer "railIndex".`);
+                    }
+                    return idx;
+                };
+                switch (action) {
+                    case 'list':
+                        return (0, types_1.apiCall)(ctx, 'GET', base);
+                    case 'set_tickets': {
+                        const railIndex = requireRailIndex();
+                        const ticketIds = args.ticketIds;
+                        if (!Array.isArray(ticketIds)) {
+                            throw new Error('set_tickets requires "ticketIds" (an array of numbers).');
+                        }
+                        const body = { ticketIds };
+                        if (args.mode !== undefined)
+                            body.mode = args.mode;
+                        if ('profileName' in args && args.profileName !== undefined)
+                            body.profileName = args.profileName;
+                        if ('aiEngine' in args && args.aiEngine !== undefined)
+                            body.aiEngine = args.aiEngine;
+                        return (0, types_1.apiCall)(ctx, 'PUT', `${base}/${railIndex}/tickets`, body);
+                    }
+                    case 'set_profile': {
+                        const railIndex = requireRailIndex();
+                        if (!('profileName' in args)) {
+                            throw new Error('set_profile requires "profileName" (string or null).');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'PUT', `${base}/${railIndex}/profile`, {
+                            profileName: (args.profileName ?? null),
+                        });
+                    }
+                    case 'set_engine': {
+                        const railIndex = requireRailIndex();
+                        if (!('aiEngine' in args)) {
+                            throw new Error('set_engine requires "aiEngine" (string or null).');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'PUT', `${base}/${railIndex}/engine`, {
+                            aiEngine: (args.aiEngine ?? null),
+                        });
+                    }
+                    case 'set_name': {
+                        const railIndex = requireRailIndex();
+                        if (!('name' in args)) {
+                            throw new Error('set_name requires "name" (string or null).');
+                        }
+                        return (0, types_1.apiCall)(ctx, 'PUT', `${base}/${railIndex}/name`, {
+                            name: (args.name ?? null),
+                        });
+                    }
+                    case 'launch': {
+                        const railIndex = requireRailIndex();
+                        const body = {};
+                        if (args.mode !== undefined)
+                            body.mode = args.mode;
+                        if ('profileName' in args && args.profileName !== undefined)
+                            body.profileName = args.profileName;
+                        if ('aiEngine' in args && args.aiEngine !== undefined)
+                            body.aiEngine = args.aiEngine;
+                        if (args.model !== undefined)
+                            body.model = args.model;
+                        if (args.interactive !== undefined)
+                            body.interactive = args.interactive;
+                        if (args.loopId !== undefined)
+                            body.loopId = args.loopId;
+                        if (args.reasoning_effort !== undefined)
+                            body.reasoning_effort = args.reasoning_effort;
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/${railIndex}/launch`, body);
+                        return {
+                            ...r,
+                            hint: 'Launch accepted (202). Use specrails_watch with the returned jobId/jobIds (or loopRunIds for loop mode) to await completion. Live output streams over the job WS.',
+                        };
+                    }
+                    case 'stop': {
+                        const railIndex = requireRailIndex();
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/${railIndex}/stop`);
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

package/server/dist/mcp/tools/setup.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupTools = setupTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * The setup-wizard domain facade. Mixes APP-LEVEL operations (prerequisites,
+ * available_providers, add_project — mounted at `/api` with NO `:projectId`)
+ * with PER-PROJECT operations (install-config, install, checkpoints, abort,
+ * integration-contract — under `/api/projects/:projectId/*`).
+ *
+ * QUICK-only: the agent path provisions the quick (offline) tier and installs
+ * every registered provider in ONE `install` call (the server chains them). The
+ * legacy full/enrich AI flow is intentionally NOT exposed through the MCP.
+ *
+ * LIFECYCLE the caller must respect:
+ *   1. prerequisites → must be ok before adding a project
+ *   2. add_project   → creates the ProjectContext + slug + registry mirror + workspace
+ *   3. install_config (one POST per provider for multi-provider projects; tier forced to quick)
+ *   4. install        → 202 async; installs ALL providers; result arrives via WS / checkpoints
+ *   5. poll checkpoints (or stream WS) until isInstalling === false
+ *
+ * The async `install` action returns immediately (HTTP 202) and does the real,
+ * long-running work in a detached child whose only output channel is WebSocket —
+ * so it returns a hint to poll `checkpoints` (which also exposes
+ * isInstalling/logLines/summary) for true completion.
+ */
+function setupTools() {
+    return [
+        {
+            name: 'specrails_setup',
+            title: 'Setup & Project Provisioning',
+            description: 'Add and provision Specrails projects via the setup wizard, and inspect setup prerequisites/providers. ' +
+                'App-level actions ignore projectId: prerequisites (probe node/npm/npx/git + provider CLIs), ' +
+                'available_providers (which AI CLIs are detected + install tiers), add_project (register a repo path). ' +
+                'Per-project actions: install_config (persist install-config.yaml), install (spawn offline framework scaffold — async/202), ' +
+                'checkpoints (poll live setup/install state — the canonical completion signal when not streaming WS), ' +
+                'abort (SIGTERM/SIGKILL the in-progress install child), integration_contract (read the ticket-provider contract). ' +
+                'Install is QUICK-only and provisions every registered provider in one shot; the legacy full/enrich AI flow is not exposed here.',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (action === 'abort')
+                    return 'destructive';
+                if (action === 'install')
+                    return 'ai-spawn';
+                if (action === 'add_project' || action === 'install_config')
+                    return 'write';
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    'prerequisites',
+                    'available_providers',
+                    'add_project',
+                    'install_config',
+                    'install',
+                    'checkpoints',
+                    'abort',
+                    'integration_contract',
+                ])
+                    .describe('Setup operation to perform'),
+                projectId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Project id for per-project actions (install_config/install/checkpoints/abort/integration_contract). Ignored by app-level actions.'),
+                // prerequisites
+                diagnostic: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('prerequisites: when true, include the resolved PATH segments/sources + per-tool which results'),
+                // add_project
+                path: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('add_project: filesystem path of the repo to register (required for add_project)'),
+                name: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('add_project: display name (defaults to the directory basename)'),
+                provider: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('add_project: legacy single primary provider; install: which per-provider install-config to read'),
+                providers: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('add_project: providers to install (first = primary/default); de-duped server-side'),
+                // install_config
+                config: zod_1.z
+                    .record(zod_1.z.unknown())
+                    .optional()
+                    .describe('install_config: the install-config object to serialize (e.g. { tier:"quick", provider, agents }); required for install_config'),
+            },
+            async handler(ctx, args) {
+                const action = args.action;
+                switch (action) {
+                    // ─── App-level (no projectId) ───────────────────────────────────────
+                    case 'prerequisites': {
+                        const qs = args.diagnostic === true ? '?diagnostic=1' : '';
+                        return (0, types_1.apiCall)(ctx, 'GET', `/setup-prerequisites${qs}`);
+                    }
+                    case 'available_providers':
+                        return (0, types_1.apiCall)(ctx, 'GET', '/available-providers');
+                    case 'add_project': {
+                        const path = args.path;
+                        if (!path)
+                            throw new Error('add_project requires a "path".');
+                        const body = { path };
+                        if (typeof args.name === 'string')
+                            body.name = args.name;
+                        if (typeof args.provider === 'string')
+                            body.provider = args.provider;
+                        if (Array.isArray(args.providers))
+                            body.providers = args.providers;
+                        return (0, types_1.apiCall)(ctx, 'POST', '/projects', body);
+                    }
+                    // ─── Per-project ────────────────────────────────────────────────────
+                    case 'install_config': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        const config = args.config;
+                        if (config === undefined || typeof config !== 'object' || Array.isArray(config)) {
+                            throw new Error('install_config requires a "config" object.');
+                        }
+                        // The MCP/agent path is QUICK-only — force the tier so a full/enrich
+                        // install can never be provisioned through the agent (deprecated).
+                        const quickConfig = { ...config, tier: 'quick' };
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/setup/install-config`, quickConfig);
+                    }
+                    case 'install': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        // Quick-only, all-provider install: by default provision EVERY provider
+                        // the project is registered with in one shot (server chains them). An
+                        // explicit `providers` list narrows it; a single `provider` still works.
+                        const body = {};
+                        if (Array.isArray(args.providers))
+                            body.providers = args.providers;
+                        else if (typeof args.provider === 'string')
+                            body.provider = args.provider;
+                        else
+                            body.all = true;
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/setup/install`, body);
+                        return {
+                            ...(typeof r === 'object' && r !== null ? r : { result: r }),
+                            hint: 'Install is async (HTTP 202). Installs ALL registered providers (quick tier) in one shot; poll specrails_setup(checkpoints) until isInstalling === false, or stream the setup_install_done / setup_error WS events.',
+                        };
+                    }
+                    case 'checkpoints': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/setup/checkpoints`);
+                    }
+                    case 'abort': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/setup/abort`, {});
+                    }
+                    case 'integration_contract': {
+                        const base = (0, types_1.projectPath)(ctx, args.projectId);
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/integration-contract`);
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}