specrails-desktop 2.0.0

package/server/dist/contract-refine-runner.js

@@ -0,0 +1,521 @@
+"use strict";
+/**
+ * Contract Refine Runner
+ *
+ * Standalone runner that spawns a single Claude turn to produce the
+ * Contract Layer for a just-committed Explore Spec ticket. Lives outside the
+ * ChatManager lifecycle for now (design.md D3 — "thin sibling helper" option):
+ * the refine is fire-and-forget, single-attempt, 60 s budget, no idle-kill /
+ * crash-respawn semantics.
+ *
+ * See openspec/changes/explore-spec-contract-refine.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareContractRefineSpawn = prepareContractRefineSpawn;
+exports.readRefineChildOutput = readRefineChildOutput;
+exports.applyContractLayerToTicket = applyContractLayerToTicket;
+exports.runContractRefine = runContractRefine;
+exports.runContractRefineForQuick = runContractRefineForQuick;
+const node_crypto_1 = require("node:crypto");
+const node_readline_1 = require("node:readline");
+const cli_prompt_1 = require("./util/cli-prompt");
+const explore_contract_refine_1 = require("./explore-contract-refine");
+const db_1 = require("./db");
+const explore_cwd_manager_1 = require("./explore-cwd-manager");
+const ai_invocations_1 = require("./ai-invocations");
+const result_event_1 = require("./result-event");
+const ticket_store_1 = require("./ticket-store");
+const REFINE_TIMEOUT_MS = 60_000;
+function normalizeClaudeCodeModel(model) {
+    if (!model || typeof model !== 'string')
+        return 'sonnet';
+    return model;
+}
+function buildRefineArgs(model, systemPrompt, sessionId) {
+    return [
+        '--model', normalizeClaudeCodeModel(model),
+        '--dangerously-skip-permissions',
+        '--output-format', 'stream-json',
+        '--verbose',
+        '--system-prompt', systemPrompt,
+        '--disallowedTools', 'Read,Grep,Glob,Bash',
+        '--resume', sessionId,
+        '--max-turns', '1',
+        '-p', explore_contract_refine_1.CONTRACT_MARKER_USER_MESSAGE,
+    ];
+}
+/**
+ * Build the spawn argv + cwd for the refine turn. Exported for tests.
+ */
+function prepareContractRefineSpawn(deps, conversation) {
+    const systemPrompt = (0, explore_contract_refine_1.buildContractRefineSystemPrompt)();
+    let mcpEnabled = false;
+    if (conversation.context_scope) {
+        try {
+            const scope = JSON.parse(conversation.context_scope);
+            mcpEnabled = !!scope?.mcp;
+        }
+        catch {
+            /* default false */
+        }
+    }
+    let cwd = deps.projectPath;
+    if (!mcpEnabled) {
+        try {
+            cwd = (0, explore_cwd_manager_1.ensureExploreCwd)({
+                slug: deps.projectSlug,
+                projectPath: deps.projectPath,
+                projectName: deps.projectName,
+            });
+        }
+        catch {
+            cwd = deps.projectPath;
+        }
+    }
+    const args = buildRefineArgs(conversation.model ?? 'sonnet', systemPrompt, conversation.session_id ?? '');
+    return { args, cwd, systemPrompt };
+}
+/**
+ * Test-friendly inner runner: takes a child-like object and returns the parsed
+ * outcome (text + result event + close code). Does NOT touch the DB or the
+ * file system — the caller wires those.
+ */
+function readRefineChildOutput(child, timeoutMs) {
+    return new Promise((resolve) => {
+        let fullText = '';
+        let resultEvent = null;
+        let timedOut = false;
+        let settled = false;
+        if (!child.stdout) {
+            resolve({ fullText, resultEvent, code: -1, timedOut: false });
+            return;
+        }
+        let stderrBuf = '';
+        if (child.stderr) {
+            child.stderr.on('data', (chunk) => {
+                const s = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+                stderrBuf += s;
+                if (stderrBuf.length > 8192)
+                    stderrBuf = stderrBuf.slice(-8192);
+            });
+        }
+        const reader = (0, node_readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+        reader.on('line', (line) => {
+            let parsed = null;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (!parsed)
+                return;
+            const type = parsed.type;
+            if (type === 'result') {
+                resultEvent = parsed;
+            }
+            else if (type === 'assistant') {
+                const message = parsed.message;
+                const blocks = message?.content ?? [];
+                for (const b of blocks) {
+                    if (b.type === 'text' && typeof b.text === 'string')
+                        fullText += b.text;
+                }
+            }
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                child.kill('SIGTERM');
+            }
+            catch { /* best effort */ }
+            if (!settled) {
+                settled = true;
+                resolve({ fullText, resultEvent, code: null, timedOut: true });
+            }
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (settled)
+                return;
+            settled = true;
+            if (code !== 0 && stderrBuf) {
+                console.log(`[contract-refine-runner] child stderr: ${JSON.stringify(stderrBuf.slice(-2000))}`);
+            }
+            resolve({ fullText, resultEvent, code, timedOut });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            console.log(`[contract-refine-runner] child error: ${err.message}; stderr=${JSON.stringify(stderrBuf.slice(-2000))}`);
+            if (settled)
+                return;
+            settled = true;
+            resolve({ fullText, resultEvent, code: -1, timedOut });
+        });
+    });
+}
+/**
+ * Patch a ticket's description in place: append the rendered Contract Layer
+ * markdown to the user-authored body. Returns the updated Ticket, or null
+ * when the ticket id is unknown.
+ */
+function applyContractLayerToTicket(filePath, ticketId, layer, nowIso) {
+    let updated = null;
+    (0, ticket_store_1.mutateStore)(filePath, (s) => {
+        const t = s.tickets[String(ticketId)];
+        if (!t)
+            return;
+        t.description = (0, explore_contract_refine_1.appendContractLayerToDescription)(t.description, layer);
+        t.updated_at = nowIso;
+        updated = t;
+    });
+    return updated;
+}
+/**
+ * Fire a single Contract Refine attempt for the given conversation + ticket.
+ *
+ * Returns a Promise that resolves with the outcome. Side effects:
+ *  - On success: patches the ticket's description, broadcasts `ticket_updated`
+ *    (in the caller-supplied shape via broadcast), records `ai_invocations`.
+ *  - On failure: broadcasts `explore.contract_refine_failed`, records
+ *    `ai_invocations` with status=failed/aborted.
+ *
+ * Early-returns with `reason='disabled'` when the per-project toggle is off,
+ * the kill switch is active, the conversation is not Explore, or no
+ * `session_id` exists yet (no parent turn to --resume).
+ */
+async function runContractRefine(deps, conversationId, ticketId) {
+    const now = deps.now ?? (() => new Date());
+    const timeoutMs = deps.timeoutMs ?? REFINE_TIMEOUT_MS;
+    const spawn = deps.spawn ?? cli_prompt_1.spawnAiCli;
+    console.log(`[contract-refine-runner] entry conv=${conversationId} ticket=${ticketId}`);
+    if ((0, explore_contract_refine_1.isExploreContractRefineKillSwitchActive)()) {
+        console.log(`[contract-refine-runner] skip: kill switch active`);
+        return { ok: false, reason: 'disabled', ticketId, conversationId };
+    }
+    const conversation = (0, db_1.getConversation)(deps.db, conversationId);
+    if (!conversation || conversation.kind !== 'explore') {
+        console.log(`[contract-refine-runner] skip: conversation missing or not explore (kind=${conversation?.kind})`);
+        return { ok: false, reason: 'not-explore', ticketId, conversationId };
+    }
+    // Contract Layer refinement is a Claude-only capability (it `--resume`s the
+    // Explore session and invokes the `/specrails:contract-refine` slash command,
+    // neither of which Codex supports). Skip defensively when the conversation
+    // ran on a non-claude engine; the Add Spec UI already hides the toggle for
+    // those, but a manually-crafted scope must never spawn the wrong CLI.
+    if (conversation.provider && conversation.provider !== 'claude') {
+        console.log(`[contract-refine-runner] skip: provider '${conversation.provider}' does not support contract refine`);
+        return { ok: false, reason: 'provider-unsupported', ticketId, conversationId };
+    }
+    // Per-conversation gating: contractRefine on the conversation's stored
+    // context_scope is the only source of truth. Legacy null/missing scope or
+    // a malformed JSON blob is treated as opted out.
+    if (!deps.ignoreConversationScope) {
+        let convoOptIn = false;
+        if (conversation.context_scope) {
+            try {
+                const scope = JSON.parse(conversation.context_scope);
+                if (typeof scope?.contractRefine === 'boolean')
+                    convoOptIn = scope.contractRefine;
+            }
+            catch { /* malformed scope; treat as opted out */ }
+        }
+        if (!convoOptIn) {
+            console.log(`[contract-refine-runner] skip: conversation scope opted out (contractRefine!=true)`);
+            return { ok: false, reason: 'scope-disabled', ticketId, conversationId };
+        }
+    }
+    if (!conversation.session_id) {
+        console.log(`[contract-refine-runner] skip: no session_id on conversation ${conversationId}`);
+        return { ok: false, reason: 'no-session', ticketId, conversationId };
+    }
+    console.log(`[contract-refine-runner] spawning refine model=${conversation.model} session=${conversation.session_id}`);
+    deps.broadcast({
+        type: 'explore.contract_refine_started',
+        projectId: deps.projectId,
+        ticketId,
+        timestamp: now().toISOString(),
+    });
+    const { args, cwd } = prepareContractRefineSpawn({
+        projectSlug: deps.projectSlug,
+        projectPath: deps.projectPath,
+        projectName: deps.projectName,
+    }, conversation);
+    const startedAt = now().toISOString();
+    let child;
+    try {
+        child = spawn('claude', args, {
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            cwd,
+        });
+    }
+    catch (err) {
+        recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, now().toISOString(), 'failed', null);
+        deps.broadcast({
+            type: 'explore.contract_refine_failed',
+            projectId: deps.projectId,
+            ticketId,
+            reason: 'crashed',
+            timestamp: now().toISOString(),
+        });
+        return { ok: false, reason: 'crashed', ticketId, conversationId };
+    }
+    const result = await readRefineChildOutput(child, timeoutMs);
+    const finishedAt = now().toISOString();
+    console.log(`[contract-refine-runner] spawn done code=${result.code} timedOut=${result.timedOut} hasResult=${!!result.resultEvent} textBytes=${result.fullText.length}`);
+    if (result.timedOut) {
+        recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, finishedAt, 'aborted', result.resultEvent);
+        deps.broadcast({
+            type: 'explore.contract_refine_failed',
+            projectId: deps.projectId,
+            ticketId,
+            reason: 'timeout',
+            timestamp: finishedAt,
+        });
+        return { ok: false, reason: 'timeout', ticketId, conversationId };
+    }
+    if (result.code !== 0 || !result.resultEvent) {
+        const r = result.resultEvent;
+        console.log(`[contract-refine-runner] non-zero exit code=${result.code} ` +
+            `subtype=${r?.subtype ?? '-'} is_error=${r?.is_error ?? '-'} ` +
+            `num_turns=${r?.num_turns ?? '-'} ` +
+            `textTail=${JSON.stringify(result.fullText.slice(-400))}`);
+        if (r)
+            console.log(`[contract-refine-runner] result event: ${JSON.stringify(r).slice(0, 2000)}`);
+        recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, finishedAt, 'failed', result.resultEvent);
+        deps.broadcast({
+            type: 'explore.contract_refine_failed',
+            projectId: deps.projectId,
+            ticketId,
+            reason: result.resultEvent ? 'model_error' : 'crashed',
+            timestamp: finishedAt,
+        });
+        return { ok: false, reason: result.resultEvent ? 'model_error' : 'crashed', ticketId, conversationId };
+    }
+    const parse = (0, explore_contract_refine_1.parseContractLayerBlock)(result.fullText);
+    console.log(`[contract-refine-runner] parse ok=${parse.ok} reason=${!parse.ok ? parse.reason : '-'} firstChars=${JSON.stringify(result.fullText.slice(0, 200))}`);
+    if (!parse.ok) {
+        const reason = parse.reason === 'parser-error'
+            ? 'parser_error'
+            : 'malformed';
+        recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, finishedAt, 'failed', result.resultEvent);
+        deps.broadcast({
+            type: 'explore.contract_refine_failed',
+            projectId: deps.projectId,
+            ticketId,
+            reason,
+            timestamp: finishedAt,
+        });
+        return { ok: false, reason, ticketId, conversationId };
+    }
+    // Patch the ticket description.
+    let updated = null;
+    try {
+        const filePath = (0, ticket_store_1.resolveTicketStoragePath)(deps.projectPath);
+        updated = applyContractLayerToTicket(filePath, ticketId, parse.value, finishedAt);
+    }
+    catch (err) {
+        console.error('[contract-refine-runner] PATCH failed:', err);
+        recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, finishedAt, 'failed', result.resultEvent);
+        deps.broadcast({
+            type: 'explore.contract_refine_failed',
+            projectId: deps.projectId,
+            ticketId,
+            reason: 'parser_error',
+            timestamp: finishedAt,
+        });
+        return { ok: false, reason: 'parser_error', ticketId, conversationId };
+    }
+    recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, finishedAt, 'success', result.resultEvent);
+    if (updated) {
+        deps.broadcast({
+            type: 'ticket_updated',
+            ticket: updated,
+            projectId: deps.projectId,
+            timestamp: finishedAt,
+        });
+    }
+    deps.broadcast({ type: 'spending.invalidated', projectId: deps.projectId });
+    return { ok: true, ticketId, conversationId };
+}
+/**
+ * Quick-mode variant: fire a single Contract Refine attempt with no parent
+ * Explore conversation (no `--resume`). The runner seeds the model with the
+ * just-generated spec body inside the system prompt as one-shot context.
+ *
+ * Used by `POST /tickets/generate-spec` when `contractRefine: true` is on the
+ * request body and the project setting + kill switch permit it.
+ */
+async function runContractRefineForQuick(deps, ticketId, generatedTitle, generatedDescription, model = null) {
+    const now = deps.now ?? (() => new Date());
+    const timeoutMs = deps.timeoutMs ?? REFINE_TIMEOUT_MS;
+    const spawn = deps.spawn ?? cli_prompt_1.spawnAiCli;
+    console.log(`[contract-refine-runner] quick-entry ticket=${ticketId}`);
+    if ((0, explore_contract_refine_1.isExploreContractRefineKillSwitchActive)()) {
+        console.log(`[contract-refine-runner] quick skip: kill switch active`);
+        return { ok: false, reason: 'disabled', ticketId, conversationId: '' };
+    }
+    const systemPrompt = [
+        (0, explore_contract_refine_1.buildContractRefineSystemPrompt)(),
+        '',
+        '## Spec under refinement',
+        '',
+        `### Title`,
+        generatedTitle,
+        '',
+        `### Description`,
+        generatedDescription,
+    ].join('\n');
+    const args = [
+        '--model', model ?? 'sonnet',
+        '--dangerously-skip-permissions',
+        '--output-format', 'stream-json',
+        '--verbose',
+        '--system-prompt', systemPrompt,
+        '--disallowedTools', 'Read,Grep,Glob,Bash',
+        '--max-turns', '1',
+        '-p', explore_contract_refine_1.CONTRACT_MARKER_USER_MESSAGE,
+    ];
+    const startedAt = now().toISOString();
+    deps.broadcast({
+        type: 'explore.contract_refine_started',
+        projectId: deps.projectId,
+        ticketId,
+        timestamp: startedAt,
+    });
+    let child;
+    try {
+        child = spawn('claude', args, {
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            cwd: deps.projectPath,
+        });
+    }
+    catch (err) {
+        recordSafelyQuick(deps, ticketId, model, startedAt, now().toISOString(), 'failed', null);
+        deps.broadcast({
+            type: 'explore.contract_refine_failed',
+            projectId: deps.projectId,
+            ticketId,
+            reason: 'crashed',
+            timestamp: now().toISOString(),
+        });
+        return { ok: false, reason: 'crashed', ticketId, conversationId: '' };
+    }
+    const result = await readRefineChildOutput(child, timeoutMs);
+    const finishedAt = now().toISOString();
+    console.log(`[contract-refine-runner] quick spawn done code=${result.code} timedOut=${result.timedOut} textBytes=${result.fullText.length}`);
+    if (result.timedOut) {
+        recordSafelyQuick(deps, ticketId, model, startedAt, finishedAt, 'aborted', result.resultEvent);
+        deps.broadcast({
+            type: 'explore.contract_refine_failed',
+            projectId: deps.projectId,
+            ticketId,
+            reason: 'timeout',
+            timestamp: finishedAt,
+        });
+        return { ok: false, reason: 'timeout', ticketId, conversationId: '' };
+    }
+    if (result.code !== 0 || !result.resultEvent) {
+        const r = result.resultEvent;
+        console.log(`[contract-refine-runner] quick non-zero exit code=${result.code} ` +
+            `subtype=${r?.subtype ?? '-'} is_error=${r?.is_error ?? '-'} ` +
+            `num_turns=${r?.num_turns ?? '-'} ` +
+            `textTail=${JSON.stringify(result.fullText.slice(-400))}`);
+        recordSafelyQuick(deps, ticketId, model, startedAt, finishedAt, 'failed', result.resultEvent);
+        deps.broadcast({
+            type: 'explore.contract_refine_failed',
+            projectId: deps.projectId,
+            ticketId,
+            reason: result.resultEvent ? 'model_error' : 'crashed',
+            timestamp: finishedAt,
+        });
+        return { ok: false, reason: result.resultEvent ? 'model_error' : 'crashed', ticketId, conversationId: '' };
+    }
+    const parse = (0, explore_contract_refine_1.parseContractLayerBlock)(result.fullText);
+    if (!parse.ok) {
+        const reason = parse.reason === 'parser-error' ? 'parser_error' : 'malformed';
+        recordSafelyQuick(deps, ticketId, model, startedAt, finishedAt, 'failed', result.resultEvent);
+        deps.broadcast({
+            type: 'explore.contract_refine_failed',
+            projectId: deps.projectId,
+            ticketId,
+            reason,
+            timestamp: finishedAt,
+        });
+        return { ok: false, reason, ticketId, conversationId: '' };
+    }
+    let updated = null;
+    try {
+        const filePath = (0, ticket_store_1.resolveTicketStoragePath)(deps.projectPath);
+        updated = applyContractLayerToTicket(filePath, ticketId, parse.value, finishedAt);
+    }
+    catch (err) {
+        console.error('[contract-refine-runner] quick PATCH failed:', err);
+        recordSafelyQuick(deps, ticketId, model, startedAt, finishedAt, 'failed', result.resultEvent);
+        deps.broadcast({
+            type: 'explore.contract_refine_failed',
+            projectId: deps.projectId,
+            ticketId,
+            reason: 'parser_error',
+            timestamp: finishedAt,
+        });
+        return { ok: false, reason: 'parser_error', ticketId, conversationId: '' };
+    }
+    recordSafelyQuick(deps, ticketId, model, startedAt, finishedAt, 'success', result.resultEvent);
+    if (updated) {
+        deps.broadcast({
+            type: 'ticket_updated',
+            ticket: updated,
+            projectId: deps.projectId,
+            timestamp: finishedAt,
+        });
+    }
+    deps.broadcast({ type: 'spending.invalidated', projectId: deps.projectId });
+    return { ok: true, ticketId, conversationId: '' };
+}
+function recordSafelyQuick(deps, ticketId, model, startedAt, finishedAt, status, resultEvent) {
+    try {
+        const normalised = resultEvent ? (0, result_event_1.normaliseResultEvent)(resultEvent, 'claude') : {};
+        (0, ai_invocations_1.recordInvocation)(deps.db, {
+            id: (0, node_crypto_1.randomUUID)(),
+            project_id: deps.projectId,
+            provider: 'claude',
+            surface: 'quick-spec',
+            surface_ref_id: `contract-refine:${ticketId}`,
+            conversation_id: null,
+            ticket_id: ticketId,
+            status,
+            started_at: startedAt,
+            finished_at: finishedAt,
+            ...normalised,
+            model: resultEvent?.model ?? model ?? undefined,
+        });
+    }
+    catch (err) {
+        console.error('[contract-refine-runner] quick recordInvocation failed:', err);
+    }
+}
+function recordSafely(deps, conversationId, ticketId, model, startedAt, finishedAt, status, resultEvent) {
+    try {
+        const normalised = resultEvent ? (0, result_event_1.normaliseResultEvent)(resultEvent, 'claude') : {};
+        (0, ai_invocations_1.recordInvocation)(deps.db, {
+            id: (0, node_crypto_1.randomUUID)(),
+            project_id: deps.projectId,
+            provider: 'claude',
+            surface: 'explore-spec',
+            surface_ref_id: `contract-refine:${conversationId}`,
+            conversation_id: conversationId,
+            ticket_id: ticketId,
+            status,
+            started_at: startedAt,
+            finished_at: finishedAt,
+            ...normalised,
+            model: resultEvent?.model ?? model ?? undefined,
+        });
+    }
+    catch (err) {
+        console.error('[contract-refine-runner] recordInvocation failed:', err);
+    }
+}