specrails-desktop 2.16.0 → 2.17.0

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

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jiraTools = jiraTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Per-project Jira integration facade. Maps each action to the corresponding
+ * `/api/projects/:projectId/jira/*` route (server/jira-router.ts). Every op is
+ * project-scoped and external-network-bound (live HTTPS to the customer's Jira
+ * Cloud / Data Center instance with their stored or supplied credentials).
+ *
+ * SECURITY: the Jira API token / PAT is a high-value SECRET. It is passed as a
+ * plaintext `token` field on test / discover_projects / discover_statuses /
+ * connect; never log or echo it, and it is never returned on reads (GET
+ * /connection redacts it to `hasToken`).
+ *
+ * ID SCOPING: spec_details / discard_spec take the LOCAL monotonic ticket id
+ * (NOT a Jira `PROJ-123` key); retry_outbox takes the LOCAL outbox row id. Map
+ * Jira keys → local ids via the `links` action first.
+ */
+function jiraTools() {
+    return [
+        {
+            name: 'specrails_jira',
+            title: 'Jira integration',
+            description: 'Manage a project\'s Jira-backed specs (each project syncs with its own Jira board). Read connection/links/outbox, run the connect wizard, sync, and create/discard Jira-backed specs. ' +
+                'Actions: connection (get current connection, token redacted), test (validate creds), discover_projects, discover_statuses (with throwaway creds), connect (persist connection — write), update_connection (enable/disable hot-swap + statusMap/discardStatus — write), disconnect (remove connection + restore local write access — destructive), statuses (connected project\'s real statuses), sync (full re-fetch of the board — write, long-running on big boards), resume (drain parked outbox after re-auth — write), outbox (list ops + counts), retry_outbox (re-queue a dead-lettered op — write), create_spec (create a real Jira issue — write), discard_spec (move linked issue to discard status — write), spec_details (read-only Jira fields + dev panel), links (spec↔issue link map). ' +
+                'The `token` param is a SECRET (Jira API token / PAT) — only required for test/discover_projects/discover_statuses/connect; it is never returned on reads.',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (action === 'disconnect')
+                    return 'destructive';
+                if ([
+                    'connect',
+                    'update_connection',
+                    'sync',
+                    'resume',
+                    'retry_outbox',
+                    'create_spec',
+                    'discard_spec',
+                ].includes(action)) {
+                    return 'write';
+                }
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    'connection',
+                    'test',
+                    'discover_projects',
+                    'discover_statuses',
+                    'connect',
+                    'update_connection',
+                    'disconnect',
+                    'statuses',
+                    'sync',
+                    'resume',
+                    'outbox',
+                    'retry_outbox',
+                    'create_spec',
+                    'discard_spec',
+                    'spec_details',
+                    'links',
+                ])
+                    .describe('Jira operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                // Credential / probe fields (test, discover_projects, discover_statuses, connect)
+                baseUrl: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Jira base URL, e.g. https://acme.atlassian.net (test / discover_* / connect)'),
+                accountEmail: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Jira account email — required for Cloud Basic auth (test / discover_* / connect)'),
+                token: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('SECRET: Jira API token (Cloud) or PAT (Data Center). Required for test / discover_projects / discover_statuses / connect. Never returned on reads.'),
+                query: zod_1.z.string().optional().describe('Optional name filter for discover_projects'),
+                projectKey: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Jira project key to inspect statuses for (discover_statuses)'),
+                jiraProjectKey: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Jira project key to connect this project to (connect)'),
+                statusMap: zod_1.z
+                    .record(zod_1.z.string(), zod_1.z.string())
+                    .optional()
+                    .describe('Optional map of logical states (todo / in_progress / done / cancelled) → Jira status name (connect / update_connection)'),
+                discardStatus: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Jira status name the discard action moves an issue to; empty string clears it (connect / update_connection)'),
+                // update_connection
+                enabled: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('Hot-swap toggle: true re-arms Jira write-back (read-only local backlog), false restores local write access (update_connection)'),
+                // create_spec
+                title: zod_1.z.string().optional().describe('Issue summary/title (create_spec)'),
+                description: zod_1.z.string().optional().describe('Issue description (create_spec)'),
+                labels: zod_1.z.array(zod_1.z.string()).optional().describe('Issue labels (create_spec)'),
+                priority: zod_1.z.string().optional().describe('Jira priority name (create_spec)'),
+                issueType: zod_1.z.string().optional().describe('Jira issue type; defaults to Task (create_spec)'),
+                // discard_spec / spec_details
+                localId: zod_1.z
+                    .number()
+                    .optional()
+                    .describe('LOCAL monotonic ticket id (discard_spec / spec_details) — NOT a Jira key; map via the links action'),
+                comment: zod_1.z.string().optional().describe('Optional reason comment posted on discard (discard_spec)'),
+                // retry_outbox
+                opId: zod_1.z
+                    .number()
+                    .optional()
+                    .describe('LOCAL outbox row id of a dead-lettered op to re-queue (retry_outbox)'),
+                // outbox
+                state: zod_1.z
+                    .enum(['pending', 'inflight', 'done', 'dead'])
+                    .optional()
+                    .describe('Filter outbox ops by state (outbox); omit for all'),
+            },
+            async handler(ctx, args) {
+                const base = `${(0, types_1.projectPath)(ctx, args.projectId)}/jira`;
+                const action = args.action;
+                switch (action) {
+                    case 'connection':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/connection`);
+                    case 'test':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/test`, {
+                            baseUrl: args.baseUrl,
+                            accountEmail: args.accountEmail,
+                            token: args.token,
+                        });
+                    case 'discover_projects':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/discover-projects`, {
+                            baseUrl: args.baseUrl,
+                            accountEmail: args.accountEmail,
+                            token: args.token,
+                            query: args.query,
+                        });
+                    case 'discover_statuses':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/discover-statuses`, {
+                            baseUrl: args.baseUrl,
+                            accountEmail: args.accountEmail,
+                            token: args.token,
+                            projectKey: args.projectKey,
+                        });
+                    case 'connect':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/connect`, {
+                            baseUrl: args.baseUrl,
+                            accountEmail: args.accountEmail,
+                            token: args.token,
+                            jiraProjectKey: args.jiraProjectKey,
+                            statusMap: args.statusMap,
+                            discardStatus: args.discardStatus,
+                        });
+                    case 'update_connection':
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/connection`, {
+                            enabled: args.enabled,
+                            discardStatus: args.discardStatus,
+                            statusMap: args.statusMap,
+                        });
+                    case 'disconnect':
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/connection`);
+                    case 'statuses':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/statuses`);
+                    case 'sync':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/sync`);
+                    case 'resume':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/resume`);
+                    case 'outbox': {
+                        const state = args.state;
+                        const qs = state ? `?state=${encodeURIComponent(state)}` : '';
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/outbox${qs}`);
+                    }
+                    case 'retry_outbox': {
+                        const opId = args.opId;
+                        if (opId === undefined)
+                            throw new Error('retry_outbox requires an "opId" (local outbox row id).');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/outbox/${opId}/retry`);
+                    }
+                    case 'create_spec':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/specs`, {
+                            title: args.title,
+                            description: args.description,
+                            labels: args.labels,
+                            priority: args.priority,
+                            issueType: args.issueType,
+                        });
+                    case 'discard_spec': {
+                        const localId = args.localId;
+                        if (localId === undefined)
+                            throw new Error('discard_spec requires a "localId" (local ticket id).');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/specs/${localId}/discard`, {
+                            comment: args.comment,
+                        });
+                        // 202 accepted: the transition + optional comment drain asynchronously.
+                        return {
+                            ...(typeof r === 'object' && r !== null ? r : { result: r }),
+                            hint: 'Discard enqueued (202). Use action "outbox" to watch the transition/comment ops drain, or "connection" for live outbox counts.',
+                        };
+                    }
+                    case 'spec_details': {
+                        const localId = args.localId;
+                        if (localId === undefined)
+                            throw new Error('spec_details requires a "localId" (local ticket id).');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/specs/${localId}/details`);
+                    }
+                    case 'links':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/links`);
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}

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

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jobsTools = jobsTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+/**
+ * Jobs domain facade. Maps every in-scope jobs/queue action to its REST
+ * endpoint on the loopback API (server/project-router-jobs.ts, plus the
+ * diagnostic export in server/project-router-settings.ts).
+ *
+ * Rail-specific operations (launch/stop/set_* on /rails) live in a separate
+ * rails tool; this facade covers the project-level job queue and individual
+ * job lifecycle. Note: `spawn` here is the rail-bypass `/spawn` endpoint that
+ * enqueues an arbitrary slash-command job (incurs token cost, async 202).
+ */
+function jobsTools() {
+    return [
+        {
+            name: 'specrails_jobs',
+            title: 'Jobs & Queue',
+            description: 'Manage a project\'s AI-pipeline job queue and individual jobs. ' +
+                'Actions: list, get, queue, spawn (ai-spawn — enqueues an arbitrary slash-command job, returns {jobId,position}, async), ' +
+                'cancel (destructive — cancels a running/queued job or deletes a terminal one), ' +
+                'purge (destructive — bulk-delete persisted job rows in a date range), ' +
+                'pause / resume (queue), reorder (queued-job order), priority (change a queued job\'s priority), ' +
+                'compare (two jobs side-by-side), export (up to 10k rows as JSON/CSV), ' +
+                'diagnostic (binary ZIP — returns a note, not the bytes), run_state (project run state), ' +
+                'activity (recent activity feed), stats, metrics, default_spec_model, ' +
+                'interactive_turn (ai-spawn — send one more prompt to a running interactive ultracode job), ' +
+                'finalize (finalize a running interactive job).',
+            hintTier: 'read',
+            tier: (a) => {
+                const action = a.action;
+                if (['cancel', 'purge'].includes(action))
+                    return 'destructive';
+                if (['spawn', 'interactive_turn'].includes(action))
+                    return 'ai-spawn';
+                if (['pause', 'resume', 'reorder', 'priority', 'finalize'].includes(action))
+                    return 'write';
+                return 'read';
+            },
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    'list',
+                    'get',
+                    'queue',
+                    'spawn',
+                    'cancel',
+                    'purge',
+                    'pause',
+                    'resume',
+                    'reorder',
+                    'priority',
+                    'compare',
+                    'export',
+                    'diagnostic',
+                    'run_state',
+                    'activity',
+                    'stats',
+                    'metrics',
+                    'default_spec_model',
+                    'interactive_turn',
+                    'finalize',
+                ])
+                    .describe('Operation to perform'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                // ── job identity ──
+                jobId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Job id (for get / cancel / priority / diagnostic / interactive_turn / finalize)'),
+                // ── list / export pagination + filters ──
+                limit: zod_1.z.number().optional().describe('Page size for list (1-200, default 50) / activity (1-100, default 50)'),
+                offset: zod_1.z.number().optional().describe('Page offset for list'),
+                status: zod_1.z.string().optional().describe('Filter by job status (list)'),
+                from: zod_1.z.string().optional().describe('ISO date lower bound (list / export / purge)'),
+                to: zod_1.z.string().optional().describe('ISO date upper bound (list / export / purge)'),
+                before: zod_1.z.string().optional().describe('Activity cursor: return rows before this timestamp'),
+                // ── spawn (rail-bypass enqueue) ──
+                command: zod_1.z.string().optional().describe('Slash-command to enqueue (spawn), e.g. "/specrails:implement #5 --yes"'),
+                priority: zod_1.z
+                    .enum(['low', 'normal', 'high', 'critical'])
+                    .optional()
+                    .describe('Priority for spawn / priority action'),
+                dependsOnJobId: zod_1.z.string().optional().describe('Make the spawned job depend on this job id'),
+                pipelineId: zod_1.z.string().optional().describe('Group the spawned job into this pipeline'),
+                profileName: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Agent profile for spawn (omit = default resolution; pass empty/null upstream forces legacy)'),
+                aiEngine: zod_1.z.string().optional().describe('Per-job provider override for spawn (must be installed on the project)'),
+                // ── reorder ──
+                jobIds: zod_1.z
+                    .array(zod_1.z.string())
+                    .optional()
+                    .describe('reorder: exact set of currently-queued job ids in the desired order; compare: exactly 2 job ids'),
+                // ── interactive_turn ──
+                text: zod_1.z.string().optional().describe('Prompt text for interactive_turn'),
+                // ── export ──
+                format: zod_1.z.enum(['json', 'csv']).optional().describe('Export format (default json)'),
+                // ── default_spec_model ──
+                provider: zod_1.z.string().optional().describe('Provider to resolve the default spec model for (default_spec_model)'),
+            },
+            async handler(ctx, args) {
+                const base = (0, types_1.projectPath)(ctx, args.projectId);
+                const action = args.action;
+                switch (action) {
+                    case 'list': {
+                        const qs = new URLSearchParams();
+                        if (args.limit !== undefined)
+                            qs.set('limit', String(args.limit));
+                        if (args.offset !== undefined)
+                            qs.set('offset', String(args.offset));
+                        if (args.status)
+                            qs.set('status', args.status);
+                        if (args.from)
+                            qs.set('from', args.from);
+                        if (args.to)
+                            qs.set('to', args.to);
+                        const q = qs.toString();
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/jobs${q ? `?${q}` : ''}`);
+                    }
+                    case 'get': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('get requires a "jobId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/jobs/${encodeURIComponent(id)}`);
+                    }
+                    case 'queue':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/queue`);
+                    case 'spawn': {
+                        const command = args.command;
+                        if (!command || !command.trim())
+                            throw new Error('spawn requires a "command".');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/spawn`, {
+                            command,
+                            priority: args.priority,
+                            dependsOnJobId: args.dependsOnJobId,
+                            pipelineId: args.pipelineId,
+                            profileName: args.profileName,
+                            aiEngine: args.aiEngine,
+                        });
+                        return {
+                            ...r,
+                            hint: 'Spawned an AI CLI job (incurs token cost). Use specrails_watch with the returned jobId to await completion.',
+                        };
+                    }
+                    case 'cancel': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('cancel requires a "jobId".');
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/jobs/${encodeURIComponent(id)}`);
+                    }
+                    case 'purge':
+                        return (0, types_1.apiCall)(ctx, 'DELETE', `${base}/jobs`, {
+                            from: args.from,
+                            to: args.to,
+                        });
+                    case 'pause':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/queue/pause`);
+                    case 'resume':
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/queue/resume`);
+                    case 'reorder': {
+                        const jobIds = args.jobIds;
+                        if (!Array.isArray(jobIds))
+                            throw new Error('reorder requires "jobIds" (array of queued job ids).');
+                        return (0, types_1.apiCall)(ctx, 'PUT', `${base}/queue/reorder`, { jobIds });
+                    }
+                    case 'priority': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('priority requires a "jobId".');
+                        const priority = args.priority;
+                        if (!priority)
+                            throw new Error('priority requires a "priority" (low|normal|high|critical).');
+                        return (0, types_1.apiCall)(ctx, 'PATCH', `${base}/jobs/${encodeURIComponent(id)}/priority`, { priority });
+                    }
+                    case 'compare': {
+                        const jobIds = args.jobIds;
+                        if (!Array.isArray(jobIds) || jobIds.length !== 2) {
+                            throw new Error('compare requires exactly 2 ids in "jobIds".');
+                        }
+                        const qs = new URLSearchParams({ jobIds: jobIds.join(',') });
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/jobs/compare?${qs.toString()}`);
+                    }
+                    case 'export': {
+                        const qs = new URLSearchParams();
+                        qs.set('format', args.format ?? 'json');
+                        if (args.from)
+                            qs.set('from', args.from);
+                        if (args.to)
+                            qs.set('to', args.to);
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/jobs/export?${qs.toString()}`);
+                    }
+                    case 'diagnostic': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('diagnostic requires a "jobId".');
+                        // The diagnostic endpoint streams an application/zip (job-metadata.json,
+                        // telemetry.ndjson, logs.txt, summary.md, profile + plugin snapshot).
+                        // We do NOT inline binary bytes through the MCP text channel — return a
+                        // pointer the caller can fetch over the loopback REST API directly.
+                        return {
+                            note: 'Binary export (application/zip) — not inlined.',
+                            jobId: id,
+                            path: `${base}/jobs/${encodeURIComponent(id)}/diagnostic`,
+                            hint: 'Requires a telemetry blob to exist for the job (else 404). Fetch the ZIP via the REST endpoint at the given path.',
+                        };
+                    }
+                    case 'run_state':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/state`);
+                    case 'activity': {
+                        const qs = new URLSearchParams();
+                        if (args.limit !== undefined)
+                            qs.set('limit', String(args.limit));
+                        if (args.before)
+                            qs.set('before', args.before);
+                        const q = qs.toString();
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/activity${q ? `?${q}` : ''}`);
+                    }
+                    case 'stats':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/stats`);
+                    case 'metrics':
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/metrics`);
+                    case 'default_spec_model': {
+                        const qs = new URLSearchParams();
+                        if (args.provider)
+                            qs.set('provider', args.provider);
+                        const q = qs.toString();
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/default-spec-model${q ? `?${q}` : ''}`);
+                    }
+                    case 'interactive_turn': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('interactive_turn requires a "jobId".');
+                        const text = args.text;
+                        if (!text || !text.trim())
+                            throw new Error('interactive_turn requires "text".');
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/jobs/${encodeURIComponent(id)}/messages`, { text });
+                        return {
+                            ...r,
+                            hint: 'Queued an additional interactive turn (incurs token cost). Use specrails_watch with the jobId to follow the job.',
+                        };
+                    }
+                    case 'finalize': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('finalize requires a "jobId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/jobs/${encodeURIComponent(id)}/finalize`);
+                    }
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+            },
+        },
+    ];
+}