ai-spec-dev 0.1.0 → 0.17.0

package/core/combined-generator.ts

@@ -0,0 +1,63 @@
+/**
+ * combined-generator.ts
+ *
+ * Generates Spec + Tasks in a single AI call instead of two sequential calls.
+ * Avoids the circular-dependency that would arise if spec-generator.ts imported
+ * from task-generator.ts (which already imports AIProvider from spec-generator).
+ */
+
+import { AIProvider } from "./spec-generator";
+import { ProjectContext } from "./context-loader";
+import { SpecTask, buildTaskPrompt } from "./task-generator";
+import { specPrompt } from "../prompts/spec.prompt";
+
+const TASKS_SEPARATOR = "---TASKS_JSON---";
+
+// Appended to specPrompt so the AI outputs spec + tasks in one response.
+const tasksInstruction = `
+
+---
+After outputting the complete spec above, append EXACTLY this line on its own (no extra text before or after it):
+${TASKS_SEPARATOR}
+Then output a valid JSON array of implementation tasks. Each element must have these exact fields:
+{"id":"TASK-001","title":"...","description":"1-2 sentences, specific","layer":"data|infra|service|api|test","filesToTouch":["src/..."],"acceptanceCriteria":["verifiable condition"],"dependencies":[],"priority":"high|medium|low"}
+Layer order: data → infra → service → api → test. 4-10 tasks total. filesToTouch must use real paths from the project context.`;
+
+export async function generateSpecWithTasks(
+  provider: AIProvider,
+  idea: string,
+  context?: ProjectContext
+): Promise<{ spec: string; tasks: SpecTask[] }> {
+  // Use buildTaskPrompt to get the full verified-inventory context,
+  // then prepend the idea so the spec generator also sees it.
+  const contextBlock = buildTaskPrompt("", context).trim();
+  const fullPrompt = [idea, contextBlock].filter(Boolean).join("\n\n");
+
+  const combinedSystemPrompt = specPrompt + tasksInstruction;
+  const raw = await provider.generate(fullPrompt, combinedSystemPrompt);
+  return parseSpecAndTasks(raw);
+}
+
+function parseSpecAndTasks(raw: string): { spec: string; tasks: SpecTask[] } {
+  const sepIdx = raw.indexOf(TASKS_SEPARATOR);
+
+  if (sepIdx === -1) {
+    // AI didn't output the separator — return full response as spec, no tasks
+    return { spec: raw.trim(), tasks: [] };
+  }
+
+  const spec = raw.slice(0, sepIdx).trim();
+  const tasksRaw = raw.slice(sepIdx + TASKS_SEPARATOR.length).trim();
+
+  let tasks: SpecTask[] = [];
+  try {
+    const jsonMatch = tasksRaw.match(/\[[\s\S]*\]/);
+    if (jsonMatch) {
+      tasks = JSON.parse(jsonMatch[0]);
+    }
+  } catch {
+    // Parse failed, return empty tasks — caller handles gracefully
+  }
+
+  return { spec, tasks };
+}

package/core/constitution-consolidator.ts

@@ -0,0 +1,141 @@
+import chalk from "chalk";
+import * as fs from "fs-extra";
+import * as path from "path";
+import { AIProvider } from "./spec-generator";
+import { CONSTITUTION_FILE } from "./constitution-generator";
+import {
+  consolidateSystemPrompt,
+  buildConsolidatePrompt,
+  parseConstitutionStats,
+  ConstitutionStats,
+} from "../prompts/consolidate.prompt";
+import { computeDiff, printDiff, printDiffSummary } from "./spec-versioning";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface ConsolidateOptions {
+  /** Preview the result without writing to disk */
+  dryRun?: boolean;
+  /** Skip interactive confirmation */
+  auto?: boolean;
+  /** Minimum number of §9 lessons before consolidation is useful (default: 5) */
+  minLessons?: number;
+}
+
+export interface ConsolidateResult {
+  /** Whether the file was actually written */
+  written: boolean;
+  /** Stats before consolidation */
+  before: ConstitutionStats;
+  /** Stats after consolidation */
+  after: ConstitutionStats;
+  /** Path to the backup file */
+  backupPath: string | null;
+}
+
+// ─── Threshold Warning ────────────────────────────────────────────────────────
+
+/**
+ * Check if §9 has grown past the warning threshold.
+ * Call this after appending lessons to warn the user when consolidation is needed.
+ */
+export function checkConsolidationNeeded(
+  projectRoot: string,
+  lessonCount: number,
+  warnAt = 8
+): void {
+  if (lessonCount >= warnAt) {
+    console.log(
+      chalk.yellow(
+        `\n  ⚠ §9 has ${lessonCount} accumulated lessons — consider running \`ai-spec init --consolidate\` to prune.`
+      )
+    );
+  }
+}
+
+// ─── Consolidator ─────────────────────────────────────────────────────────────
+
+export class ConstitutionConsolidator {
+  constructor(private provider: AIProvider) {}
+
+  async consolidate(
+    projectRoot: string,
+    opts: ConsolidateOptions = {}
+  ): Promise<ConsolidateResult> {
+    const minLessons = opts.minLessons ?? 5;
+    const constitutionPath = path.join(projectRoot, CONSTITUTION_FILE);
+
+    // ── Load constitution ───────────────────────────────────────────────────
+    if (!(await fs.pathExists(constitutionPath))) {
+      throw new Error(`No constitution file found at ${constitutionPath}. Run \`ai-spec init\` first.`);
+    }
+
+    const original = await fs.readFile(constitutionPath, "utf-8");
+    const before = parseConstitutionStats(original);
+
+    console.log(chalk.blue("\n─── Constitution Consolidation ──────────────────"));
+    console.log(chalk.gray(`  File    : ${CONSTITUTION_FILE}`));
+    console.log(chalk.gray(`  Size    : ${before.totalLines} lines`));
+    console.log(chalk.gray(`  §9 items: ${before.lessonCount} accumulated lessons`));
+
+    if (before.lessonCount < minLessons) {
+      console.log(
+        chalk.green(
+          `\n  ✔ §9 has only ${before.lessonCount} lesson(s) — no consolidation needed yet (threshold: ${minLessons}).`
+        )
+      );
+      return { written: false, before, after: before, backupPath: null };
+    }
+
+    // ── Generate consolidated version ───────────────────────────────────────
+    console.log(chalk.cyan(`\n  Consolidating ${before.lessonCount} lesson(s) with AI...`));
+
+    const prompt = buildConsolidatePrompt(original, before.lessonCount);
+    let consolidated: string;
+    try {
+      const raw = await this.provider.generate(prompt, consolidateSystemPrompt);
+      // Strip markdown fences if present
+      consolidated = raw
+        .replace(/^```(?:markdown|md)?\n?/im, "")
+        .replace(/\n?```\s*$/im, "")
+        .trim();
+    } catch (err) {
+      throw new Error(`AI consolidation failed: ${(err as Error).message}`);
+    }
+
+    const after = parseConstitutionStats(consolidated);
+
+    // ── Show diff ───────────────────────────────────────────────────────────
+    const diff = computeDiff(original, consolidated);
+    console.log(chalk.blue("\n  Changes preview:"));
+    printDiff(diff, 4);
+    printDiffSummary(diff);
+
+    console.log(chalk.cyan("\n  After consolidation:"));
+    console.log(chalk.gray(`  Size    : ${after.totalLines} lines (was ${before.totalLines})`));
+    console.log(chalk.gray(`  §9 items: ${after.lessonCount} remaining (was ${before.lessonCount})`));
+
+    const liftedCount = Math.max(0, before.lessonCount - after.lessonCount);
+    if (liftedCount > 0) {
+      console.log(chalk.green(`  ✔ ~${liftedCount} lesson(s) lifted into §1–§8 or removed`));
+    }
+
+    if (opts.dryRun) {
+      console.log(chalk.yellow("\n  [dry-run] No changes written."));
+      return { written: false, before, after, backupPath: null };
+    }
+
+    // ── Backup ──────────────────────────────────────────────────────────────
+    const timestamp = new Date().toISOString().slice(0, 19).replace(/[T:]/g, "-");
+    const backupName = `.ai-spec-constitution.backup-${timestamp}.md`;
+    const backupPath = path.join(projectRoot, backupName);
+    await fs.writeFile(backupPath, original, "utf-8");
+    console.log(chalk.gray(`\n  Backup  : ${backupName}`));
+
+    // ── Write ───────────────────────────────────────────────────────────────
+    await fs.writeFile(constitutionPath, consolidated, "utf-8");
+    console.log(chalk.green(`  ✔ Constitution updated: ${CONSTITUTION_FILE}`));
+
+    return { written: true, before, after, backupPath };
+  }
+}

package/core/constitution-generator.ts

@@ -0,0 +1,89 @@
+import chalk from "chalk";
+import * as fs from "fs-extra";
+import * as path from "path";
+import { AIProvider } from "./spec-generator";
+import { ContextLoader, ProjectContext } from "./context-loader";
+import { constitutionSystemPrompt } from "../prompts/constitution.prompt";
+
+export const CONSTITUTION_FILE = ".ai-spec-constitution.md";
+
+export class ConstitutionGenerator {
+  constructor(private provider: AIProvider) {}
+
+  async generate(projectRoot: string): Promise<string> {
+    const loader = new ContextLoader(projectRoot);
+    const context = await loader.loadProjectContext();
+
+    const prompt = buildConstitutionPrompt(context, projectRoot);
+    return this.provider.generate(prompt, constitutionSystemPrompt);
+  }
+
+  async saveConstitution(projectRoot: string, content: string): Promise<string> {
+    const filePath = path.join(projectRoot, CONSTITUTION_FILE);
+    await fs.writeFile(filePath, content, "utf-8");
+    return filePath;
+  }
+}
+
+function buildConstitutionPrompt(context: ProjectContext, projectRoot: string): string {
+  const parts: string[] = [
+    "Analyze this project and generate its Project Constitution.\n",
+    `=== Tech Stack ===\n${context.techStack.join(", ") || "unknown"}\n`,
+    `=== Dependencies (top 30) ===\n${context.dependencies.slice(0, 30).join(", ")}\n`,
+  ];
+
+  if (context.apiStructure.length > 0) {
+    parts.push(`=== API/Route Files ===\n${context.apiStructure.join("\n")}\n`);
+  }
+
+  if (context.routeSummary) {
+    parts.push(`=== Route Code Samples ===\n${context.routeSummary}\n`);
+  }
+
+  if (context.schema) {
+    parts.push(`=== Prisma Schema ===\n${context.schema.slice(0, 4000)}\n`);
+  }
+
+  if (context.errorPatterns) {
+    parts.push(`=== Error Handling Patterns ===\n${context.errorPatterns}\n`);
+  }
+
+  if (context.sharedConfigFiles && context.sharedConfigFiles.length > 0) {
+    const grouped = context.sharedConfigFiles.reduce(
+      (acc, f) => {
+        (acc[f.category] ??= []).push(f);
+        return acc;
+      },
+      {} as Record<string, typeof context.sharedConfigFiles>
+    );
+
+    const sections: string[] = [];
+    for (const [category, files] of Object.entries(grouped)) {
+      sections.push(`--- ${category} ---`);
+      for (const f of files!) {
+        sections.push(`File: ${f.path}\n${f.preview.slice(0, 600)}\n`);
+      }
+    }
+    parts.push(`=== Existing Shared Config Files (Append-Only — NEVER Recreate) ===\n${sections.join("\n")}\n`);
+  }
+
+  return parts.join("\n");
+}
+
+export async function loadConstitution(projectRoot: string): Promise<string | undefined> {
+  const filePath = path.join(projectRoot, CONSTITUTION_FILE);
+  if (await fs.pathExists(filePath)) {
+    return fs.readFile(filePath, "utf-8");
+  }
+  return undefined;
+}
+
+export function printConstitutionHint(exists: boolean): void {
+  if (!exists) {
+    console.log(
+      chalk.yellow(
+        "  ⚡ Tip: Run `ai-spec init` to generate a Project Constitution for better spec quality."
+      )
+    );
+  }
+}