specrails-desktop 2.29.4 → 2.30.0

package/server/dist/blueprint-spec-quality.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILDER_SPEC_HEADINGS = void 0;
+exports.analyzeBuilderSpecBatch = analyzeBuilderSpecBatch;
+exports.firstBuilderSpecQualityDetail = firstBuilderSpecQualityDetail;
+exports.analyzeTypedBuilderSpecs = analyzeTypedBuilderSpecs;
+exports.BUILDER_SPEC_HEADINGS = [
+    'Problem Statement',
+    'Proposed Solution',
+    'Out of Scope',
+    'Technical Considerations',
+    'Estimated Complexity',
+];
+const VALID_KINDS = new Set(['scaffold', 'feature', 'verification']);
+const VALID_PRIORITIES = new Set(['critical', 'high', 'medium', 'low']);
+const PLACEHOLDER_CRITERION = /^(?:todo|tbd|n\/?a|works?|test(?: it)?|criterion|acceptance criterion)$/i;
+function issue(issues, specIndex, field, code, message) {
+    issues.push({ specIndex, field, code, message });
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function normalized(value) {
+    return value.trim().toLocaleLowerCase('en-US');
+}
+function h2Sections(description) {
+    const matches = [...description.matchAll(/^##[ \t]+(.+?)[ \t]*$/gm)];
+    const headings = matches.map((match) => match[1].trim());
+    const bodies = new Map();
+    matches.forEach((match, index) => {
+        const start = (match.index ?? 0) + match[0].length;
+        const end = index + 1 < matches.length ? (matches[index + 1].index ?? description.length) : description.length;
+        bodies.set(headings[index], description.slice(start, end).trim());
+    });
+    return { headings, bodies };
+}
+function bulletCount(body) {
+    return body.split(/\r?\n/).filter((line) => /^\s*[-*+]\s+\S/.test(line)).length;
+}
+/**
+ * Strict readiness gate for detailed Project Builder specs. Parsing stays
+ * permissive so interview/stream snapshots and old persisted blueprints remain
+ * readable; this gate runs only before a batch can mutate project state.
+ */
+function analyzeBuilderSpecBatch(input, options) {
+    const issues = [];
+    const label = options.milestoneLabel.trim().toUpperCase();
+    if (input.specsComplete !== true) {
+        issue(issues, null, 'specsComplete', 'batch_incomplete', 'generation is not marked complete');
+    }
+    if (input.specs.length < options.minSpecs || input.specs.length > options.maxSpecs) {
+        issue(issues, null, 'm1Specs', 'spec_count', `requires ${options.minSpecs}-${options.maxSpecs} specs (received ${input.specs.length})`);
+    }
+    const titles = new Map();
+    input.specs.forEach((raw, specIndex) => {
+        const spec = record(raw);
+        const humanIndex = specIndex + 1;
+        if (!spec) {
+            issue(issues, specIndex, 'spec', 'invalid_shape', `spec ${humanIndex} must be an object`);
+            return;
+        }
+        const kind = typeof spec.kind === 'string' ? spec.kind : '';
+        if (!VALID_KINDS.has(kind)) {
+            issue(issues, specIndex, 'kind', 'invalid_kind', `spec ${humanIndex} kind must be scaffold, feature, or verification`);
+        }
+        if (options.requireScaffold && specIndex === 0 && kind !== 'scaffold') {
+            issue(issues, specIndex, 'kind', 'scaffold_first', 'spec 1 must be the project scaffold');
+        }
+        if (options.requireScaffold && specIndex > 0 && kind === 'scaffold') {
+            issue(issues, specIndex, 'kind', 'duplicate_scaffold', `spec ${humanIndex} cannot be another scaffold`);
+        }
+        const title = typeof spec.title === 'string' ? spec.title.trim() : '';
+        if (!title) {
+            issue(issues, specIndex, 'title', 'required', `spec ${humanIndex} title is required`);
+        }
+        else {
+            const key = normalized(title);
+            const prior = titles.get(key);
+            if (prior !== undefined) {
+                issue(issues, specIndex, 'title', 'duplicate', `spec ${humanIndex} duplicates spec ${prior + 1} title`);
+            }
+            else {
+                titles.set(key, specIndex);
+            }
+        }
+        const shortSummary = typeof spec.shortSummary === 'string' ? spec.shortSummary.trim() : '';
+        if (!shortSummary) {
+            issue(issues, specIndex, 'shortSummary', 'required', `spec ${humanIndex} shortSummary is required`);
+        }
+        else if (shortSummary.length > 240 || /[\r\n]/.test(shortSummary)) {
+            issue(issues, specIndex, 'shortSummary', 'invalid_length', `spec ${humanIndex} shortSummary must be one line and at most 240 characters`);
+        }
+        const priority = typeof spec.priority === 'string' ? spec.priority : '';
+        if (!VALID_PRIORITIES.has(priority)) {
+            issue(issues, specIndex, 'priority', 'invalid_priority', `spec ${humanIndex} priority must be critical, high, medium, or low`);
+        }
+        const labels = Array.isArray(spec.labels)
+            ? spec.labels.filter((value) => typeof value === 'string').map((value) => value.trim()).filter(Boolean)
+            : [];
+        const normalizedLabels = new Set(labels.map((value) => value.toUpperCase()));
+        if (!normalizedLabels.has(label)) {
+            issue(issues, specIndex, 'labels', 'milestone_label', `spec ${humanIndex} labels must include ${label}`);
+        }
+        if (labels.every((value) => value.toUpperCase() === label)) {
+            issue(issues, specIndex, 'labels', 'domain_label', `spec ${humanIndex} requires at least one domain label besides ${label}`);
+        }
+        const description = typeof spec.description === 'string' ? spec.description.trim() : '';
+        const sections = h2Sections(description);
+        if (!/^## Problem Statement(?:\r?\n|$)/.test(description)
+            || sections.headings.length !== exports.BUILDER_SPEC_HEADINGS.length
+            || sections.headings.some((heading, index) => heading !== exports.BUILDER_SPEC_HEADINGS[index])) {
+            issue(issues, specIndex, 'description', 'canonical_sections', `spec ${humanIndex} description must contain exactly the five canonical sections in order`);
+        }
+        for (const heading of exports.BUILDER_SPEC_HEADINGS) {
+            if (!(sections.bodies.get(heading) ?? '').trim()) {
+                issue(issues, specIndex, 'description', 'empty_section', `spec ${humanIndex} section "${heading}" cannot be empty`);
+            }
+        }
+        for (const heading of ['Out of Scope', 'Technical Considerations']) {
+            const body = sections.bodies.get(heading) ?? '';
+            if (body && bulletCount(body) < 2) {
+                issue(issues, specIndex, 'description', 'section_bullets', `spec ${humanIndex} section "${heading}" requires at least two bullets`);
+            }
+        }
+        const complexity = sections.bodies.get('Estimated Complexity') ?? '';
+        if (complexity && !/^(?:Low|Medium|High|Very High)\s*(?:[—\-:]\s*)\S/i.test(complexity)) {
+            issue(issues, specIndex, 'description', 'complexity_format', `spec ${humanIndex} Estimated Complexity needs a level and justification`);
+        }
+        if (options.requireScaffold && specIndex === 0 && description && !/\bREADME\b/i.test(description)) {
+            issue(issues, specIndex, 'description', 'scaffold_readme', 'spec 1 must note that the repository already contains a README');
+        }
+        const criteria = Array.isArray(spec.acceptanceCriteria) ? spec.acceptanceCriteria : [];
+        if (criteria.length < 4 || criteria.length > 10) {
+            issue(issues, specIndex, 'acceptanceCriteria', 'criteria_count', `spec ${humanIndex} acceptanceCriteria requires 4-10 items`);
+        }
+        const seenCriteria = new Set();
+        criteria.forEach((criterion, criterionIndex) => {
+            const text = typeof criterion === 'string' ? criterion.trim() : '';
+            if (text.length < 10 || PLACEHOLDER_CRITERION.test(text)) {
+                issue(issues, specIndex, 'acceptanceCriteria', 'criterion_quality', `spec ${humanIndex} criterion ${criterionIndex + 1} must be a concrete testable outcome`);
+                return;
+            }
+            const key = normalized(text);
+            if (seenCriteria.has(key)) {
+                issue(issues, specIndex, 'acceptanceCriteria', 'duplicate_criterion', `spec ${humanIndex} criterion ${criterionIndex + 1} is duplicated`);
+            }
+            seenCriteria.add(key);
+        });
+        const dependency = spec.dependsOnIndex;
+        if (dependency !== undefined && (!Number.isInteger(dependency) || dependency < 0 || dependency >= specIndex)) {
+            issue(issues, specIndex, 'dependsOnIndex', 'invalid_dependency', `spec ${humanIndex} dependency must point to an earlier spec`);
+        }
+        if (options.requireScaffold && specIndex === 0 && dependency !== undefined) {
+            issue(issues, specIndex, 'dependsOnIndex', 'scaffold_dependency', 'spec 1 scaffold must not declare a dependency');
+        }
+    });
+    return { valid: issues.length === 0, issues };
+}
+function firstBuilderSpecQualityDetail(report) {
+    return report.issues[0]?.message;
+}
+/** Typed convenience for already-coerced callers and tests. */
+function analyzeTypedBuilderSpecs(specs, specsComplete, options) {
+    return analyzeBuilderSpecBatch({ specs, specsComplete }, options);
+}

package/server/dist/blueprint-store.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBlueprintConversation = createBlueprintConversation;
+exports.getBlueprintConversation = getBlueprintConversation;
+exports.listBlueprintConversations = listBlueprintConversations;
+exports.updateBlueprintConversation = updateBlueprintConversation;
+exports.deleteBlueprintConversation = deleteBlueprintConversation;
+exports.addBlueprintMessage = addBlueprintMessage;
+exports.listBlueprintMessages = listBlueprintMessages;
+const crypto_1 = require("crypto");
+function createBlueprintConversation(db, input = {}) {
+    const id = (0, crypto_1.randomUUID)();
+    db.prepare('INSERT INTO blueprint_conversations (id, provider, model) VALUES (?, ?, ?)').run(id, input.provider ?? 'claude', input.model ?? null);
+    return getBlueprintConversation(db, id);
+}
+function getBlueprintConversation(db, id) {
+    return db.prepare('SELECT * FROM blueprint_conversations WHERE id = ?').get(id);
+}
+function listBlueprintConversations(db, limit = 50) {
+    return db
+        .prepare('SELECT * FROM blueprint_conversations ORDER BY updated_at DESC LIMIT ?')
+        .all(limit);
+}
+/** Patch a conversation. Only provided fields change; `updated_at` always bumps. */
+function updateBlueprintConversation(db, id, patch) {
+    const sets = [];
+    const vals = [];
+    for (const [k, v] of Object.entries(patch)) {
+        sets.push(`${k} = ?`);
+        vals.push(v);
+    }
+    sets.push("updated_at = datetime('now')");
+    db.prepare(`UPDATE blueprint_conversations SET ${sets.join(', ')} WHERE id = ?`).run(...vals, id);
+    return getBlueprintConversation(db, id);
+}
+function deleteBlueprintConversation(db, id) {
+    db.prepare('DELETE FROM blueprint_conversations WHERE id = ?').run(id);
+}
+function addBlueprintMessage(db, input) {
+    const id = (0, crypto_1.randomUUID)();
+    db.prepare('INSERT INTO blueprint_messages (id, conversation_id, role, content) VALUES (?, ?, ?, ?)').run(id, input.conversationId, input.role, input.content);
+    db.prepare("UPDATE blueprint_conversations SET updated_at = datetime('now') WHERE id = ?").run(input.conversationId);
+    return db.prepare('SELECT * FROM blueprint_messages WHERE id = ?').get(id);
+}
+function listBlueprintMessages(db, conversationId) {
+    return db
+        .prepare('SELECT * FROM blueprint_messages WHERE conversation_id = ? ORDER BY created_at, rowid')
+        .all(conversationId);
+}

package/server/dist/blueprint-types.js

@@ -0,0 +1,29 @@
+"use strict";
+// Shared Blueprint schema types for the Project Builder (design D2).
+//
+// A Blueprint is the full structured snapshot the day-0 Builder conversation
+// converges on: the five interview dimensions (product, core flow, platform,
+// stack, M1 constraints via milestones) plus the detailed Milestone-1 specs.
+// It travels as fenced ```blueprint-draft JSON blocks during the conversation
+// and persists as `<workspace>/.specrails/blueprint.json` after the commit.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.M1_SPECS_MAX = exports.M1_SPECS_MIN = exports.BLUEPRINT_VERSION = void 0;
+exports.isMilestoneStatus = isMilestoneStatus;
+exports.isBlueprintSpecKind = isBlueprintSpecKind;
+exports.isBlueprintSpecPriority = isBlueprintSpecPriority;
+exports.BLUEPRINT_VERSION = 1;
+/** Milestone-1 walking-skeleton bounds (proposal: 5–10 specs, scaffold first). */
+exports.M1_SPECS_MIN = 5;
+exports.M1_SPECS_MAX = 10;
+const MILESTONE_STATUSES = new Set(['planned', 'committed', 'done']);
+const SPEC_KINDS = new Set(['scaffold', 'feature', 'verification']);
+const SPEC_PRIORITIES = new Set(['critical', 'high', 'medium', 'low']);
+function isMilestoneStatus(value) {
+    return typeof value === 'string' && MILESTONE_STATUSES.has(value);
+}
+function isBlueprintSpecKind(value) {
+    return typeof value === 'string' && SPEC_KINDS.has(value);
+}
+function isBlueprintSpecPriority(value) {
+    return typeof value === 'string' && SPEC_PRIORITIES.has(value);
+}

package/server/dist/builder-cwd-manager.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.builderCwdPath = builderCwdPath;
+exports.ensureBuilderCwd = ensureBuilderCwd;
+exports.removeBuilderCwd = removeBuilderCwd;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const blueprint_operator_prompt_1 = require("./blueprint-operator-prompt");
+// ─── Project Builder working directory (add-project-builder D1) ──────────────
+//
+// Day-0 Builder turns spawn the AI CLI from an app-owned cwd so no project
+// CLAUDE.md is auto-loaded (there IS no project yet). Unlike agent-cwd there is
+// never a `./project` symlink and never any MCP configuration — the Builder
+// only converses and emits fenced blueprint-draft JSON.
+function homeDir() {
+    return process.env.SPECRAILS_REGISTRY_HOME || os_1.default.homedir();
+}
+function builderCwdPath() {
+    return path_1.default.join(homeDir(), '.specrails', 'builder-cwd');
+}
+const INSTRUCTION_FILES = ['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'];
+/**
+ * Ensures the Builder cwd exists with instruction files. App-owned files are
+ * always (re)written so prompt updates take effect immediately. Idempotent;
+ * safe to call on every turn.
+ */
+function ensureBuilderCwd() {
+    const dir = builderCwdPath();
+    fs_1.default.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        fs_1.default.chmodSync(dir, 0o700);
+    }
+    catch { /* best-effort on platforms without chmod */ }
+    for (const name of INSTRUCTION_FILES) {
+        fs_1.default.writeFileSync(path_1.default.join(dir, name), blueprint_operator_prompt_1.BUILDER_INSTRUCTIONS, 'utf-8');
+    }
+    // Defence-in-depth: the Builder must never inherit MCP config from a stale
+    // file someone dropped here — this dir is wholly app-owned.
+    try {
+        fs_1.default.unlinkSync(path_1.default.join(dir, '.mcp.json'));
+    }
+    catch { /* absent */ }
+    return dir;
+}
+/** Removes the Builder cwd (full teardown / reset). Best-effort. */
+function removeBuilderCwd() {
+    try {
+        fs_1.default.rmSync(builderCwdPath(), { recursive: true, force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}