specrails-desktop 2.29.4 → 2.30.0

package/server/dist/blueprint-draft-parser.js

@@ -0,0 +1,168 @@
+"use strict";
+// Parses ```blueprint-draft fenced JSON blocks emitted during a Project
+// Builder conversation (design D2). Unlike spec-draft (partial + merge), each
+// blueprint-draft block is a FULL snapshot: the LAST syntactically valid
+// block wins outright and there is no merging. Blocks are stripped from the
+// chat content before it reaches the WS so the user never sees raw JSON.
+//
+// Streaming tail cut: the fence regex only matches CLOSED fences, so an
+// unterminated trailing block is never parsed. `cutUnterminatedBlock` lets
+// stream renderers hide the raw open fence while it is still arriving.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coerceBlueprint = coerceBlueprint;
+exports.parseBlueprintDraftBlocks = parseBlueprintDraftBlocks;
+exports.cutUnterminatedBlock = cutUnterminatedBlock;
+const blueprint_types_1 = require("./blueprint-types");
+const FENCE_RE = /```blueprint-draft\s*\n([\s\S]*?)\n\s*```/g;
+const OPEN_FENCE_RE = /```blueprint-draft(?![\s\S]*?\n\s*```)/;
+function asString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function coerceStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === 'string');
+}
+function coerceProduct(value) {
+    const obj = (value && typeof value === 'object' && !Array.isArray(value) ? value : {});
+    return { name: asString(obj.name), pitch: asString(obj.pitch), audience: asString(obj.audience) };
+}
+function coerceStack(value) {
+    const obj = (value && typeof value === 'object' && !Array.isArray(value) ? value : {});
+    const stack = {
+        language: asString(obj.language),
+        framework: asString(obj.framework),
+        db: asString(obj.db),
+    };
+    if (typeof obj.notes === 'string' && obj.notes !== '')
+        stack.notes = obj.notes;
+    return stack;
+}
+function coerceMilestones(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            continue;
+        const obj = item;
+        const id = asString(obj.id);
+        const title = asString(obj.title);
+        if (id === '' && title === '')
+            continue;
+        const milestone = {
+            id,
+            title,
+            goal: asString(obj.goal),
+            status: (0, blueprint_types_1.isMilestoneStatus)(obj.status) ? obj.status : 'planned',
+            plannedSpecs: coerceStringArray(obj.plannedSpecs),
+        };
+        if (Array.isArray(obj.ticketIds)) {
+            const ids = obj.ticketIds.filter((n) => typeof n === 'number' && Number.isInteger(n));
+            if (ids.length > 0)
+                milestone.ticketIds = ids;
+        }
+        out.push(milestone);
+    }
+    return out;
+}
+function coerceM1Specs(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            continue;
+        const obj = item;
+        const title = asString(obj.title);
+        if (title === '')
+            continue;
+        const spec = {
+            kind: (0, blueprint_types_1.isBlueprintSpecKind)(obj.kind) ? obj.kind : 'feature',
+            title,
+            shortSummary: asString(obj.shortSummary),
+            description: asString(obj.description),
+            acceptanceCriteria: coerceStringArray(obj.acceptanceCriteria),
+            priority: (0, blueprint_types_1.isBlueprintSpecPriority)(obj.priority) ? obj.priority : 'medium',
+            labels: coerceStringArray(obj.labels),
+        };
+        if (typeof obj.dependsOnIndex === 'number' && Number.isInteger(obj.dependsOnIndex) && obj.dependsOnIndex >= 0) {
+            spec.dependsOnIndex = obj.dependsOnIndex;
+        }
+        out.push(spec);
+    }
+    return out;
+}
+/**
+ * Validate + normalise one parsed JSON payload into a Blueprint snapshot.
+ * Unknown keys are dropped; missing sub-objects default to empty values. A
+ * missing or non-integer `blueprintVersion` rejects the block (spec gate).
+ */
+function coerceBlueprint(parsed) {
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const obj = parsed;
+    if (typeof obj.blueprintVersion !== 'number' || !Number.isInteger(obj.blueprintVersion))
+        return null;
+    return {
+        blueprintVersion: obj.blueprintVersion,
+        product: coerceProduct(obj.product),
+        coreFlow: asString(obj.coreFlow),
+        platform: asString(obj.platform),
+        stack: coerceStack(obj.stack),
+        assumptions: coerceStringArray(obj.assumptions),
+        milestones: coerceMilestones(obj.milestones),
+        specsComplete: obj.specsComplete === true,
+        m1Specs: coerceM1Specs(obj.m1Specs),
+    };
+}
+/**
+ * Scan `text` for `blueprint-draft` fenced blocks. Returns the text with
+ * every block (valid or malformed) stripped, plus the LAST valid snapshot.
+ * Never throws.
+ */
+function parseBlueprintDraftBlocks(text) {
+    if (!text || !text.includes('```blueprint-draft')) {
+        return { stripped: text ?? '', blueprint: null, rawBlueprint: null, hadBlocks: false };
+    }
+    let blueprint = null;
+    let rawBlueprint = null;
+    let hadBlocks = false;
+    let stripped = '';
+    let cursor = 0;
+    FENCE_RE.lastIndex = 0;
+    let match;
+    while ((match = FENCE_RE.exec(text)) !== null) {
+        hadBlocks = true;
+        stripped += text.slice(cursor, match.index);
+        cursor = match.index + match[0].length;
+        let parsed;
+        try {
+            parsed = JSON.parse(match[1]);
+        }
+        catch {
+            continue; // malformed; drop silently, keep the previous valid snapshot
+        }
+        const candidate = coerceBlueprint(parsed);
+        if (candidate) {
+            blueprint = candidate;
+            rawBlueprint = parsed;
+        }
+    }
+    stripped += text.slice(cursor);
+    return { stripped, blueprint, rawBlueprint, hadBlocks };
+}
+/**
+ * For live stream rendering: cut an UNTERMINATED trailing `blueprint-draft`
+ * fence (and everything after it) so raw JSON never flashes on screen while
+ * the block is still arriving. Complete blocks are untouched — run the full
+ * parser on the settled text instead.
+ */
+function cutUnterminatedBlock(text) {
+    if (!text || !text.includes('```blueprint-draft'))
+        return text ?? '';
+    const match = OPEN_FENCE_RE.exec(text);
+    if (!match)
+        return text;
+    return text.slice(0, match.index);
+}

package/server/dist/blueprint-operator-prompt.js

@@ -0,0 +1,149 @@
+"use strict";
+// ─── Single source of truth for the Project Builder day-0 prompts ───────────
+// BUILDER_INSTRUCTIONS is written to CLAUDE.md/AGENTS.md/GEMINI.md in
+// ~/.specrails/builder-cwd/ (the channel that reaches every provider).
+// BUILDER_SYSTEM_PROMPT is the compact equivalent passed via --system-prompt
+// to providers that support a dedicated system-prompt argument.
+//
+// BYTE-STABILITY CONTRACT: both constants must stay static (no timestamps, no
+// interpolation, no live data) so provider prompt caching can work on turn 2+.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILDER_SYSTEM_PROMPT = exports.BUILDER_INSTRUCTIONS = void 0;
+exports.BUILDER_INSTRUCTIONS = `# Specrails Project Builder
+
+You are the Specrails Project Builder: a conversational product architect in
+Specrails Desktop. Help the user turn a raw idea into an approved project
+blueprint and then a rich Milestone-1 backlog. No project or repository exists
+yet: you cannot inspect code, claim that paths exist, or create anything on
+disk. The app performs the commit after the user reviews the result.
+
+Conversational prose follows the user's language. Every generated spec field
+(\`title\`, \`shortSummary\`, \`description\`, \`acceptanceCriteria\`, and
+\`labels\`) is written in English.
+
+## The blueprint-draft protocol
+
+Communicate blueprint state exclusively through fenced \`blueprint-draft\` JSON
+blocks. Rules:
+
+- Every block is a FULL snapshot of the whole blueprint, never a delta. The
+  app uses the last valid block, so re-emit everything currently known.
+- Emit at most one block per message and put it at the END of the message.
+- Use valid JSON: double quotes, no comments, and no trailing commas.
+- All keys below are required except \`stack.notes\` and \`dependsOnIndex\`:
+
+\`\`\`json
+{
+  "blueprintVersion": 1,
+  "product": { "name": "...", "pitch": "...", "audience": "..." },
+  "coreFlow": "one-sentence primary user journey",
+  "platform": "web | mobile | desktop | cli | api",
+  "stack": { "language": "...", "framework": "...", "db": "...", "notes": "optional" },
+  "assumptions": ["every default chosen for the user"],
+  "milestones": [
+    { "id": "m1", "title": "...", "goal": "...", "status": "planned", "plannedSpecs": [] },
+    { "id": "m2", "title": "...", "goal": "...", "status": "planned", "plannedSpecs": ["English title"] }
+  ],
+  "specsComplete": false,
+  "m1Specs": [
+    {
+      "kind": "scaffold",
+      "title": "Scaffold the runnable project foundation",
+      "shortSummary": "Initialize a reproducible foundation that every later walking-skeleton slice can build on.",
+      "description": "## Problem Statement\\nThe approved project has a README and selected stack, but contributors cannot yet install, run, or verify a working application.\\n\\n## Proposed Solution\\nInitialize the selected stack with deterministic development, build, test, and CI commands while preserving the existing README.\\n\\n## Out of Scope\\n- Product features beyond a minimal runnable shell\\n- Production deployment and environment provisioning\\n\\n## Technical Considerations\\n- Pin compatible runtime and dependency versions for reproducible setup\\n- Keep the first application and test boundaries minimal but executable\\n\\n## Estimated Complexity\\nMedium - the foundation must align local development, automated tests, and CI without implementing product behavior.",
+      "acceptanceCriteria": ["A clean checkout installs successfully with the documented command.", "The development command starts the minimal application without an error.", "The automated test command passes from a clean checkout.", "CI executes the build and test commands on every proposed change."],
+      "priority": "high",
+      "labels": ["M1", "foundation"]
+    }
+  ]
+}
+\`\`\`
+
+## Interview and approval gate
+
+- Ask questions for at most three assistant turns. After that, propose concrete
+  choices with short rationales and invite correction instead of interrogating.
+- Before approval, fill product, core flow, platform, stack, assumptions, and
+  milestones, but ALWAYS emit \`m1Specs: []\` and \`specsComplete: false\`.
+- "Surprise me" follows the same rule: decide all five blueprint dimensions in
+  one turn, record every default in \`assumptions\`, keep \`m1Specs\` empty, and
+  ask the user to approve or correct the blueprint.
+- Generate detailed M1 specs only after explicit approval or a direct request
+  to generate the backlog/specs. Approval of the blueprint precedes generation;
+  do not create shallow placeholder specs during the interview.
+- Keep prose brief because the adjacent panel renders the full snapshot.
+
+## Milestone plan
+
+- Milestone 1 is a walking skeleton: 5–10 detailed specs that together produce
+  the thinnest runnable, testable end-to-end version of the core flow.
+- Milestones 2+ contain only shallow English \`plannedSpecs\` titles at day 0.
+  Never generate their descriptions or detailed payloads before that milestone
+  is opened against the real repository.
+- If an idea is beyond the walking skeleton, park it as an M2+ title rather
+  than expanding M1 into a waterfall.
+
+## Canonical detailed-spec contract
+
+Every detailed M1 spec must satisfy all of these rules:
+
+- \`kind\` is exactly \`scaffold\`, \`feature\`, or \`verification\`.
+- \`title\` is concise, action-oriented, unique in the batch, and in English.
+- \`shortSummary\` is one useful English sentence, no more than 240 characters.
+- \`description\` is English markdown with exactly these five \`##\` headings,
+  once each and in this order:
+  1. \`## Problem Statement\` — who has the problem, when, why it matters, and
+     the user or product value of solving it.
+  2. \`## Proposed Solution\` — the concrete behavior and planned components or
+     contracts that deliver the thin outcome.
+  3. \`## Out of Scope\` — at least two honest bullets naming adjacent work that
+     this spec deliberately defers.
+  4. \`## Technical Considerations\` — at least two bullets covering the selected stack,
+     planned components and interfaces, risks, invariants, testing strategy,
+     and dependencies on earlier specs where relevant.
+  5. \`## Estimated Complexity\` — Low, Medium, High, or Very High plus one
+     sentence explaining what drives the estimate.
+- Do NOT put an \`## Acceptance Criteria\` heading in \`description\`. Criteria
+  live only in the separate \`acceptanceCriteria\` array; the app folds them
+  into the ticket deterministically at commit time.
+- \`acceptanceCriteria\` contains 4–10 non-empty, independent, testable outcomes,
+  not implementation steps. Cover the intended behavior, observable failure or
+  edge cases, and relevant automated verification.
+- \`priority\` is exactly \`low\`, \`medium\`, \`high\`, or \`critical\` and
+  reflects delivery urgency/risk rather than implementation complexity.
+- \`labels\` includes \`M1\` plus at least one concise domain label such as
+  \`frontend\`, \`api\`, \`data\`, \`auth\`, \`testing\`, or \`infra\`.
+- \`m1Specs[0]\` is \`kind: "scaffold"\` and omits \`dependsOnIndex\`. It
+  states that the repository already contains a README and defines concrete
+  install, run, test, and CI outcomes for the selected stack.
+- A later spec may use \`dependsOnIndex\` only when it truly depends on another
+  item, and the integer must point strictly backward to an earlier array index.
+  Never point forward or to the same spec.
+
+## Day-0 grounding
+
+There is no codebase to inspect. Ground technical details in the selected
+stack, planned components, intended contracts/data shapes, known risks, and
+inter-spec dependencies. Never invent or imply existing repository paths,
+filenames, modules, functions, identifiers, migrations, or test files.
+
+## Generation and completion
+
+- After approval, generate the complete 5–10-spec walking skeleton in one
+  response and one FULL snapshot. Never expose a partial detailed-spec batch as
+  a result the user must manually ask you to continue.
+- If the complete batch cannot fit or cannot pass validation, keep
+  \`m1Specs: []\` and \`specsComplete: false\`, explain what prevented completion,
+  and wait for a fresh generation request. Do not emit partially generated specs.
+- Before setting \`specsComplete: true\`, self-audit the entire snapshot: schema
+  fields, exact five headings and order, English content, 4–10 criteria, valid
+  priority, M1 plus domain labels, unique titles, scaffold first, and strictly
+  backward dependencies. Set it true only if every spec passes. If anything
+  fails, keep it false and repair the snapshot first.
+
+## Boundaries
+
+- Never claim to have created files, repositories, tickets, or projects.
+- Never include secrets, real API keys, or license-restricted code in specs.
+`;
+exports.BUILDER_SYSTEM_PROMPT = `You are the Specrails Project Builder. No repository exists yet. Converse in the user's language, but write every spec field in English. Emit at most one final fenced blueprint-draft JSON FULL snapshot per message. Before explicit blueprint approval or a direct request to generate specs, populate product/coreFlow/platform/stack/assumptions/milestones but ALWAYS keep m1Specs: [] and specsComplete: false; "surprise me" also proposes dimensions only and asks for approval. After approval generate the complete 5-10-spec M1 walking skeleton in one response and one FULL snapshot; never expose a partial batch the user must ask you to continue. If the complete batch cannot be produced and audited, emit m1Specs: [] with specsComplete: false instead of partial specs. Each spec has kind (scaffold|feature|verification), unique action-oriented title, one-sentence shortSummary <=240 characters, description with exactly these headings once and in order: ## Problem Statement, ## Proposed Solution, ## Out of Scope, ## Technical Considerations, ## Estimated Complexity; Out of Scope and Technical Considerations each contain at least two bullets; a separate acceptanceCriteria array of 4-10 independent testable outcomes (never an ## Acceptance Criteria section in description); priority low|medium|high|critical; labels including M1 and a domain label; and optional dependsOnIndex pointing strictly backward. m1Specs[0] is kind scaffold, omits dependsOnIndex, notes the repo already contains a README, and defines install/run/test/CI outcomes. Ground day-0 content in the selected stack, planned components/contracts, risks, tests, and spec dependencies; NEVER invent paths or existing identifiers. M2+ keeps title-only plannedSpecs. Set specsComplete true only after auditing all fields, five headings, English content, 4-10 criteria, labels, scaffold, unique titles, and dependencies. Never claim disk changes.`;

package/server/dist/blueprint-render.js

@@ -0,0 +1,105 @@
+"use strict";
+// Deterministic rendering + persistence of the Blueprint pair (design D5).
+//
+// `blueprint.json` is the source of truth; `blueprint.md` is a deterministic
+// render regenerated on EVERY json write and never hand-edited. Both live in
+// `<workspace>/.specrails/` — never in the project repo (pristine-repo
+// invariant). Writes are temp+rename so a crash never leaves a torn file.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BLUEPRINT_MD = exports.BLUEPRINT_JSON = void 0;
+exports.renderBlueprintMarkdown = renderBlueprintMarkdown;
+exports.blueprintJsonPath = blueprintJsonPath;
+exports.writeBlueprintPair = writeBlueprintPair;
+exports.readBlueprint = readBlueprint;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const blueprint_draft_parser_1 = require("./blueprint-draft-parser");
+exports.BLUEPRINT_JSON = 'blueprint.json';
+exports.BLUEPRINT_MD = 'blueprint.md';
+function renderMilestone(m, index) {
+    const lines = [];
+    lines.push(`### M${index + 1} — ${m.title}`);
+    lines.push('');
+    lines.push(`- **Status**: ${m.status}`);
+    if (m.goal !== '')
+        lines.push(`- **Goal**: ${m.goal}`);
+    if (m.plannedSpecs.length > 0) {
+        lines.push('- **Planned specs**:');
+        for (const spec of m.plannedSpecs)
+            lines.push(`  - ${spec}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Deterministic markdown render of a blueprint: same input bytes → same
+ * output bytes (no timestamps, no ordering surprises — arrays render in
+ * stored order).
+ */
+function renderBlueprintMarkdown(blueprint) {
+    const sections = [];
+    const name = blueprint.product.name !== '' ? blueprint.product.name : 'Untitled project';
+    sections.push(`# Blueprint — ${name}`);
+    const product = ['## Product', ''];
+    product.push(`- **Pitch**: ${blueprint.product.pitch !== '' ? blueprint.product.pitch : '_N/A_'}`);
+    product.push(`- **Audience**: ${blueprint.product.audience !== '' ? blueprint.product.audience : '_N/A_'}`);
+    product.push(`- **Core flow**: ${blueprint.coreFlow !== '' ? blueprint.coreFlow : '_N/A_'}`);
+    product.push(`- **Platform**: ${blueprint.platform !== '' ? blueprint.platform : '_N/A_'}`);
+    sections.push(product.join('\n'));
+    const stack = ['## Stack', ''];
+    stack.push(`- **Language**: ${blueprint.stack.language !== '' ? blueprint.stack.language : '_N/A_'}`);
+    stack.push(`- **Framework**: ${blueprint.stack.framework !== '' ? blueprint.stack.framework : '_N/A_'}`);
+    stack.push(`- **Database**: ${blueprint.stack.db !== '' ? blueprint.stack.db : '_N/A_'}`);
+    if (blueprint.stack.notes)
+        stack.push(`- **Notes**: ${blueprint.stack.notes}`);
+    sections.push(stack.join('\n'));
+    if (blueprint.assumptions.length > 0) {
+        sections.push(['## Assumptions', '', ...blueprint.assumptions.map((a) => `- ${a}`)].join('\n'));
+    }
+    if (blueprint.milestones.length > 0) {
+        sections.push(['## Milestones', '', blueprint.milestones.map(renderMilestone).join('\n\n')].join('\n'));
+    }
+    if (blueprint.m1Specs.length > 0) {
+        const specs = ['## Milestone 1 specs', ''];
+        blueprint.m1Specs.forEach((spec, i) => {
+            specs.push(`${i + 1}. **${spec.title}**${spec.labels.length > 0 ? ` (${spec.labels.join(', ')})` : ''}`);
+        });
+        sections.push(specs.join('\n'));
+    }
+    sections.push('---\n\n_Generated by Specrails Project Builder. Do not edit — regenerated from `blueprint.json`._');
+    return sections.join('\n\n') + '\n';
+}
+function writeAtomic(filePath, content) {
+    const tmp = `${filePath}.tmp`;
+    fs_1.default.writeFileSync(tmp, content, 'utf-8');
+    fs_1.default.renameSync(tmp, filePath);
+}
+/** Resolve the blueprint.json path inside a workspace. */
+function blueprintJsonPath(workspaceDir) {
+    return path_1.default.join(workspaceDir, '.specrails', exports.BLUEPRINT_JSON);
+}
+/**
+ * Write the blueprint pair (json + regenerated md) into
+ * `<workspaceDir>/.specrails/`. Atomic per file (temp+rename).
+ */
+function writeBlueprintPair(workspaceDir, blueprint) {
+    const dir = path_1.default.join(workspaceDir, '.specrails');
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    writeAtomic(path_1.default.join(dir, exports.BLUEPRINT_JSON), JSON.stringify(blueprint, null, 2) + '\n');
+    writeAtomic(path_1.default.join(dir, exports.BLUEPRINT_MD), renderBlueprintMarkdown(blueprint));
+}
+/**
+ * Read a workspace's blueprint.json. Returns null when absent or unreadable
+ * (a torn/corrupt file must never crash a route).
+ */
+function readBlueprint(workspaceDir) {
+    try {
+        const raw = fs_1.default.readFileSync(blueprintJsonPath(workspaceDir), 'utf-8');
+        return (0, blueprint_draft_parser_1.coerceBlueprint)(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}

package/server/dist/blueprint-router.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isProjectBuilderEnabled = isProjectBuilderEnabled;
+exports.createBlueprintRouter = createBlueprintRouter;
+const express_1 = require("express");
+const providers_1 = require("./providers");
+const blueprint_store_1 = require("./blueprint-store");
+function isProjectBuilderEnabled() {
+    return process.env.SPECRAILS_PROJECT_BUILDER !== 'false';
+}
+function validProvider(provider) {
+    if (typeof provider !== 'string' || !provider)
+        return null;
+    try {
+        (0, providers_1.getAdapter)(provider);
+        return provider;
+    }
+    catch {
+        return null;
+    }
+}
+function createBlueprintRouter(deps) {
+    const { manager, desktopDb, runCommit } = deps;
+    const router = (0, express_1.Router)();
+    router.use((_req, res, next) => {
+        if (!isProjectBuilderEnabled()) {
+            res.status(404).json({ error: 'project builder is disabled' });
+            return;
+        }
+        next();
+    });
+    router.get('/models', (req, res) => {
+        const provider = validProvider(req.query.provider) ?? 'claude';
+        const adapter = (0, providers_1.getAdapter)(provider);
+        res.json({
+            provider,
+            models: adapter.modelCatalog(),
+            defaultModel: adapter.defaultModel(),
+            efforts: adapter.capabilities.reasoningEfforts ?? [],
+        });
+    });
+    router.get('/conversations', (_req, res) => {
+        res.json({ conversations: (0, blueprint_store_1.listBlueprintConversations)(desktopDb) });
+    });
+    router.post('/conversations', (req, res) => {
+        const body = (req.body ?? {});
+        const provider = validProvider(body.provider) ?? 'claude';
+        const model = typeof body.model === 'string' && body.model ? body.model : null;
+        const conversation = (0, blueprint_store_1.createBlueprintConversation)(desktopDb, { provider, model });
+        res.status(201).json({ conversation });
+    });
+    router.get('/conversations/:id', (req, res) => {
+        const conversation = (0, blueprint_store_1.getBlueprintConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'conversation not found' });
+            return;
+        }
+        res.json({ conversation, messages: (0, blueprint_store_1.listBlueprintMessages)(desktopDb, conversation.id) });
+    });
+    router.patch('/conversations/:id', (req, res) => {
+        const conversation = (0, blueprint_store_1.getBlueprintConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'conversation not found' });
+            return;
+        }
+        const body = (req.body ?? {});
+        const patch = {};
+        if (body.provider !== undefined) {
+            const provider = validProvider(body.provider);
+            if (!provider) {
+                res.status(400).json({ error: 'invalid provider' });
+                return;
+            }
+            patch.provider = provider;
+            if (provider !== conversation.provider) {
+                // A session id is provider-local; a switch must reset it and the model.
+                patch.session_id = null;
+                patch.model = null;
+            }
+        }
+        if (body.model !== undefined) {
+            if (body.model !== null && typeof body.model !== 'string') {
+                res.status(400).json({ error: 'invalid model' });
+                return;
+            }
+            const effectiveProvider = patch.provider ?? conversation.provider;
+            if (typeof body.model === 'string' && body.model) {
+                const valid = new Set((0, providers_1.getAdapter)(effectiveProvider).modelCatalog().map((m) => m.value));
+                if (!valid.has(body.model)) {
+                    res.status(400).json({ error: 'model not in provider catalog' });
+                    return;
+                }
+                patch.model = body.model;
+            }
+            else {
+                patch.model = null;
+            }
+        }
+        if (body.title !== undefined) {
+            if (body.title !== null && typeof body.title !== 'string') {
+                res.status(400).json({ error: 'invalid title' });
+                return;
+            }
+            patch.title = typeof body.title === 'string' ? body.title.slice(0, 200) : null;
+        }
+        const updated = (0, blueprint_store_1.updateBlueprintConversation)(desktopDb, conversation.id, patch);
+        res.json({ conversation: updated });
+    });
+    router.delete('/conversations/:id', (req, res) => {
+        const conversation = (0, blueprint_store_1.getBlueprintConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'conversation not found' });
+            return;
+        }
+        manager.abort(conversation.id);
+        (0, blueprint_store_1.deleteBlueprintConversation)(desktopDb, conversation.id);
+        res.json({ ok: true });
+    });
+    router.post('/conversations/:id/send', (req, res) => {
+        const conversation = (0, blueprint_store_1.getBlueprintConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'conversation not found' });
+            return;
+        }
+        const body = (req.body ?? {});
+        const text = typeof body.text === 'string' ? body.text.trim() : '';
+        if (!text) {
+            res.status(400).json({ error: 'text is required' });
+            return;
+        }
+        if (manager.isStreaming(conversation.id)) {
+            res.status(409).json({ error: 'a turn is already streaming' });
+            return;
+        }
+        const model = typeof body.model === 'string' && body.model ? body.model : undefined;
+        let reasoningEffort;
+        if (body.reasoning_effort !== undefined) {
+            const allowedEfforts = (0, providers_1.getAdapter)(conversation.provider).capabilities.reasoningEfforts ?? [];
+            if (typeof body.reasoning_effort !== 'string'
+                || !allowedEfforts.includes(body.reasoning_effort)) {
+                res.status(400).json({ error: 'reasoning effort not in provider catalog' });
+                return;
+            }
+            reasoningEffort = body.reasoning_effort;
+        }
+        void manager.sendMessage(conversation.id, text, { model, reasoningEffort });
+        res.status(202).json({ accepted: true });
+    });
+    router.post('/conversations/:id/abort', (req, res) => {
+        const conversation = (0, blueprint_store_1.getBlueprintConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'conversation not found' });
+            return;
+        }
+        manager.abort(conversation.id);
+        res.json({ ok: true });
+    });
+    // Orchestrated commit (add-project-builder D3): validates synchronously,
+    // then 202 + streamed `blueprint.commit_progress` events. Delegation to
+    // `executeBlueprintCommit` keeps this handler thin and the orchestrator
+    // unit-testable via its DI bag.
+    router.post('/commit', (req, res) => {
+        const input = (req.body ?? {});
+        const validation = runCommit.validate(input);
+        if (!validation.ok) {
+            res.status(400).json({ error: validation.error, detail: validation.detail });
+            return;
+        }
+        const commitId = runCommit.start(input);
+        res.status(202).json({ accepted: true, commitId });
+    });
+    return router;
+}