ai-spec-dev 0.38.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-dev",
-  "version": "0.38.0",
+  "version": "0.42.0",
   "description": "AI-driven Development Orchestrator SDK & CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,12 +27,12 @@
     "@google/generative-ai": "^0.21.0",
     "@inquirer/editor": "^5.0.10",
     "@inquirer/prompts": "^8.3.2",
+    "@rollup/rollup-darwin-arm64": "^4.60.1",
     "axios": "^1.13.6",
     "chalk": "^4.1.2",
     "commander": "^13.1.0",
     "dotenv": "^16.4.7",
     "fs-extra": "^11.3.0",
-    "inquirer": "^8.2.6",
     "openai": "^6.31.0",
     "undici": "^7.24.4"
   },

package/tests/auto-consolidation.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+import { maybeAutoConsolidate } from "../core/knowledge-memory";
+import { CONSTITUTION_FILE } from "../core/constitution-generator";
+
+const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+describe("maybeAutoConsolidate", () => {
+  let tmpDir: string;
+  const mockProvider = {
+    generate: vi.fn(),
+    providerName: "test",
+    modelName: "test-model",
+  };
+
+  beforeEach(async () => {
+    tmpDir = path.join(os.tmpdir(), `ac-test-${Date.now()}`);
+    await fs.ensureDir(tmpDir);
+    mockProvider.generate.mockReset();
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  it("returns false when no constitution file", async () => {
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir);
+    expect(result).toBe(false);
+    expect(mockProvider.generate).not.toHaveBeenCalled();
+  });
+
+  it("returns false when lesson count below threshold", async () => {
+    const lessons = Array.from({ length: 5 }, (_, i) =>
+      `- 📝 **[2026-01-0${i + 1}]** Lesson ${i + 1}`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir, { threshold: 12 });
+    expect(result).toBe(false);
+    expect(mockProvider.generate).not.toHaveBeenCalled();
+  });
+
+  it("triggers consolidation when lesson count meets threshold", async () => {
+    const lessons = Array.from({ length: 15 }, (_, i) =>
+      `- 📝 **[2026-01-${String(i + 1).padStart(2, "0")}]** Lesson number ${i + 1} with detail text`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockResolvedValueOnce(
+      "# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n- 📝 **[2026-04-02]** Consolidated lesson\n"
+    );
+
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir, { threshold: 12 });
+    expect(result).toBe(true);
+    expect(mockProvider.generate).toHaveBeenCalled();
+  });
+
+  it("returns false when consolidation fails", async () => {
+    const lessons = Array.from({ length: 15 }, (_, i) =>
+      `- 📝 **[2026-01-${String(i + 1).padStart(2, "0")}]** Lesson ${i + 1} detail`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockRejectedValueOnce(new Error("API error"));
+
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir, { threshold: 12 });
+    expect(result).toBe(false);
+  });
+
+  it("respects custom threshold", async () => {
+    const lessons = Array.from({ length: 4 }, (_, i) =>
+      `- 📝 **[2026-01-0${i + 1}]** Lesson ${i + 1} text`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockResolvedValueOnce("# Constitution\n## 9. 积累教训\n- consolidated\n");
+
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir, { threshold: 3 });
+    expect(result).toBe(true);
+  });
+
+  it("uses default threshold of 12", async () => {
+    const lessons = Array.from({ length: 10 }, (_, i) =>
+      `- 📝 **[2026-01-${String(i + 1).padStart(2, "0")}]** Lesson ${i + 1}`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir);
+    expect(result).toBe(false); // 10 < 12 default
+    expect(mockProvider.generate).not.toHaveBeenCalled();
+  });
+});

package/tests/combined-generator.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { generateSpecWithTasks } from "../core/combined-generator";
+
+const mockProvider = {
+  generate: vi.fn(),
+  providerName: "test",
+  modelName: "test-model",
+};
+
+beforeEach(() => {
+  mockProvider.generate.mockReset();
+});
+
+describe("generateSpecWithTasks", () => {
+  it("parses spec and tasks from combined output", async () => {
+    mockProvider.generate.mockResolvedValueOnce(
+      `# Feature Spec\n\nSome spec content.\n\n---TASKS_JSON---\n[{"id":"TASK-001","title":"Create model","description":"Create Order model","layer":"data","filesToTouch":["src/models/order.ts"],"acceptanceCriteria":["Model exists"],"verificationSteps":["Check file"],"dependencies":[],"priority":"high"}]`
+    );
+
+    const result = await generateSpecWithTasks(mockProvider, "Build order system");
+    expect(result.spec).toContain("Feature Spec");
+    expect(result.spec).not.toContain("TASKS_JSON");
+    expect(result.tasks).toHaveLength(1);
+    expect(result.tasks[0].id).toBe("TASK-001");
+    expect(result.tasks[0].layer).toBe("data");
+  });
+
+  it("returns empty tasks when separator is missing", async () => {
+    mockProvider.generate.mockResolvedValueOnce(
+      "# Feature Spec\n\nNo tasks separator here."
+    );
+
+    const result = await generateSpecWithTasks(mockProvider, "Build feature");
+    expect(result.spec).toContain("Feature Spec");
+    expect(result.tasks).toEqual([]);
+  });
+
+  it("returns empty tasks when JSON after separator is invalid", async () => {
+    mockProvider.generate.mockResolvedValueOnce(
+      "# Spec\n---TASKS_JSON---\nnot valid json"
+    );
+
+    const result = await generateSpecWithTasks(mockProvider, "Build feature");
+    expect(result.spec).toBe("# Spec");
+    expect(result.tasks).toEqual([]);
+  });
+
+  it("includes architecture decision in prompt when provided", async () => {
+    mockProvider.generate.mockResolvedValueOnce("# Spec\n---TASKS_JSON---\n[]");
+
+    await generateSpecWithTasks(mockProvider, "Build feature", undefined, "Use microservices");
+    const prompt = mockProvider.generate.mock.calls[0][0] as string;
+    expect(prompt).toContain("Architecture Decision");
+    expect(prompt).toContain("Use microservices");
+  });
+
+  it("includes context when ProjectContext is provided", async () => {
+    mockProvider.generate.mockResolvedValueOnce("# Spec\n---TASKS_JSON---\n[]");
+
+    const context = {
+      techStack: ["express", "prisma"],
+      dependencies: ["express", "prisma"],
+      apiStructure: ["src/routes/user.ts"],
+      fileStructure: ["src/index.ts"],
+    } as any;
+
+    await generateSpecWithTasks(mockProvider, "Build order feature", context);
+    const prompt = mockProvider.generate.mock.calls[0][0] as string;
+    expect(prompt).toContain("Build order feature");
+  });
+
+  it("trims spec and tasks", async () => {
+    mockProvider.generate.mockResolvedValueOnce(
+      "  \n# Spec  \n\n---TASKS_JSON---\n  [{\"id\":\"T1\",\"title\":\"t\",\"description\":\"d\",\"layer\":\"data\",\"filesToTouch\":[],\"acceptanceCriteria\":[],\"verificationSteps\":[],\"dependencies\":[],\"priority\":\"high\"}]  \n"
+    );
+
+    const result = await generateSpecWithTasks(mockProvider, "idea");
+    expect(result.spec).toBe("# Spec");
+    expect(result.tasks).toHaveLength(1);
+  });
+});

package/tests/constitution-consolidator.test.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+import {
+  ConstitutionConsolidator,
+  checkConsolidationNeeded,
+} from "../core/constitution-consolidator";
+import { CONSTITUTION_FILE } from "../core/constitution-generator";
+
+describe("checkConsolidationNeeded", () => {
+  it("prints warning when lessonCount >= threshold", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    checkConsolidationNeeded("/tmp", 10);
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("ai-spec init --consolidate"));
+    spy.mockRestore();
+  });
+
+  it("does not print when lessonCount < threshold", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    checkConsolidationNeeded("/tmp", 3);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it("uses custom threshold", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    checkConsolidationNeeded("/tmp", 5, 5);
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});
+
+describe("ConstitutionConsolidator", () => {
+  let tmpDir: string;
+  const mockProvider = {
+    generate: vi.fn(),
+    providerName: "test",
+    modelName: "test-model",
+  };
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+  beforeEach(async () => {
+    tmpDir = path.join(os.tmpdir(), `cc-test-${Date.now()}`);
+    await fs.ensureDir(tmpDir);
+    mockProvider.generate.mockReset();
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  it("throws when constitution file does not exist", async () => {
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    await expect(consolidator.consolidate(tmpDir)).rejects.toThrow("No constitution file");
+  });
+
+  it("skips when lesson count is below threshold", async () => {
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      "# Constitution\n## 1. Architecture\nSome rules.\n## 9. 积累教训 (Accumulated Lessons)\n- lesson 1\n- lesson 2\n"
+    );
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    const result = await consolidator.consolidate(tmpDir, { minLessons: 5 });
+    expect(result.written).toBe(false);
+    expect(mockProvider.generate).not.toHaveBeenCalled();
+  });
+
+  it("consolidates when lesson count meets threshold", async () => {
+    const lessons = Array.from({ length: 6 }, (_, i) =>
+      `- 📝 **[2026-03-0${i + 1}]** Lesson number ${i + 1} with enough detail`
+    ).join("\n");
+    const constitution = `# Constitution\n## 1. Architecture\nRules.\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`;
+    await fs.writeFile(path.join(tmpDir, CONSTITUTION_FILE), constitution);
+
+    mockProvider.generate.mockResolvedValueOnce(
+      "# Constitution\n## 1. Architecture\nRules + consolidated lessons.\n\n## 9. 积累教训 (Accumulated Lessons)\n- 📝 **[2026-04-02]** Consolidated lesson\n"
+    );
+
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    const result = await consolidator.consolidate(tmpDir, { minLessons: 5 });
+
+    expect(result.written).toBe(true);
+    expect(result.backupPath).not.toBeNull();
+    expect(await fs.pathExists(result.backupPath!)).toBe(true);
+    expect(result.before.lessonCount).toBe(6);
+  });
+
+  it("dry-run does not write changes", async () => {
+    const lessons = Array.from({ length: 6 }, (_, i) =>
+      `- 📝 **[2026-03-0${i + 1}]** Lesson ${i + 1} with detail text here`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockResolvedValueOnce("# Consolidated");
+
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    const result = await consolidator.consolidate(tmpDir, { dryRun: true, minLessons: 5 });
+
+    expect(result.written).toBe(false);
+    expect(result.backupPath).toBeNull();
+    const content = await fs.readFile(path.join(tmpDir, CONSTITUTION_FILE), "utf-8");
+    expect(content).toContain("积累教训"); // original unchanged
+  });
+
+  it("creates backup before writing", async () => {
+    const lessons = Array.from({ length: 6 }, (_, i) =>
+      `- 📝 **[2026-03-0${i + 1}]** Lesson ${i + 1} with details here`
+    ).join("\n");
+    const original = `# Constitution\n\n## 9. 积累教训\n${lessons}\n`;
+    await fs.writeFile(path.join(tmpDir, CONSTITUTION_FILE), original);
+
+    mockProvider.generate.mockResolvedValueOnce("# New constitution");
+
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    const result = await consolidator.consolidate(tmpDir, { minLessons: 5 });
+
+    expect(result.backupPath).not.toBeNull();
+    const backup = await fs.readFile(result.backupPath!, "utf-8");
+    expect(backup).toBe(original);
+  });
+
+  it("strips markdown fences from AI output", async () => {
+    const lessons = Array.from({ length: 6 }, (_, i) =>
+      `- 📝 **[2026-03-0${i + 1}]** Lesson ${i + 1} for testing fences`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockResolvedValueOnce("```markdown\n# Clean Constitution\n```");
+
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    const result = await consolidator.consolidate(tmpDir, { minLessons: 5 });
+
+    const content = await fs.readFile(path.join(tmpDir, CONSTITUTION_FILE), "utf-8");
+    expect(content).not.toContain("```");
+    expect(content).toContain("Clean Constitution");
+  });
+
+  it("throws when AI call fails", async () => {
+    const lessons = Array.from({ length: 6 }, (_, i) =>
+      `- 📝 **[2026-03-0${i + 1}]** Lesson ${i + 1} text for error test`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockRejectedValueOnce(new Error("API error"));
+
+    const consolidator = new ConstitutionConsolidator(mockProvider);
+    await expect(
+      consolidator.consolidate(tmpDir, { minLessons: 5 })
+    ).rejects.toThrow("AI consolidation failed");
+  });
+});

package/tests/constitution-generator.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+import {
+  ConstitutionGenerator,
+  CONSTITUTION_FILE,
+  loadConstitution,
+  printConstitutionHint,
+} from "../core/constitution-generator";
+
+describe("CONSTITUTION_FILE", () => {
+  it("is .ai-spec-constitution.md", () => {
+    expect(CONSTITUTION_FILE).toBe(".ai-spec-constitution.md");
+  });
+});
+
+describe("ConstitutionGenerator", () => {
+  let tmpDir: string;
+  const mockProvider = {
+    generate: vi.fn(),
+    providerName: "test",
+    modelName: "test-model",
+  };
+
+  beforeEach(async () => {
+    tmpDir = path.join(os.tmpdir(), `cg-test-${Date.now()}`);
+    await fs.ensureDir(tmpDir);
+    mockProvider.generate.mockReset();
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  it("generate() calls provider with context from project", async () => {
+    await fs.writeJson(path.join(tmpDir, "package.json"), {
+      dependencies: { express: "4.0.0" },
+    });
+    mockProvider.generate.mockResolvedValueOnce("# Constitution\n## 1. Architecture");
+
+    const gen = new ConstitutionGenerator(mockProvider);
+    const result = await gen.generate(tmpDir);
+    expect(result).toContain("Constitution");
+    expect(mockProvider.generate).toHaveBeenCalledOnce();
+  });
+
+  it("saveConstitution() writes file to project root", async () => {
+    const gen = new ConstitutionGenerator(mockProvider);
+    const filePath = await gen.saveConstitution(tmpDir, "# My Constitution");
+    expect(filePath).toBe(path.join(tmpDir, CONSTITUTION_FILE));
+    expect(await fs.readFile(filePath, "utf-8")).toBe("# My Constitution");
+  });
+});
+
+describe("loadConstitution", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = path.join(os.tmpdir(), `cg-load-${Date.now()}`);
+    await fs.ensureDir(tmpDir);
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  it("returns content when file exists", async () => {
+    await fs.writeFile(path.join(tmpDir, CONSTITUTION_FILE), "rules here");
+    const content = await loadConstitution(tmpDir);
+    expect(content).toBe("rules here");
+  });
+
+  it("returns undefined when file does not exist", async () => {
+    const content = await loadConstitution(tmpDir);
+    expect(content).toBeUndefined();
+  });
+});
+
+describe("printConstitutionHint", () => {
+  it("prints hint when exists is false", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    printConstitutionHint(false);
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("ai-spec init"));
+    spy.mockRestore();
+  });
+
+  it("does not print when exists is true", () => {
+    const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+    printConstitutionHint(true);
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});

package/tests/contract-bridge.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect } from "vitest";
+import { buildFrontendApiContract, buildContractContextSection } from "../core/contract-bridge";
+import { SpecDSL } from "../core/dsl-types";
+
+// ─── Minimal DSL fixture ─────────────────────────────────────────────────────
+
+function makeDsl(overrides?: Partial<SpecDSL>): SpecDSL {
+  return {
+    feature: { title: "Order Management", description: "CRUD for orders" },
+    models: [
+      {
+        name: "Order",
+        fields: [
+          { name: "id", type: "Int", required: true, unique: true },
+          { name: "total", type: "Float", required: true, unique: false },
+          { name: "status", type: "String", required: true, unique: false },
+          { name: "createdAt", type: "DateTime", required: false, unique: false },
+        ],
+      },
+    ],
+    endpoints: [
+      {
+        id: "createOrder",
+        method: "POST",
+        path: "/api/orders",
+        auth: true,
+        description: "Create a new order",
+        request: { body: { total: "number", items: "string[]" }, params: {}, query: {} },
+        successStatus: 201,
+        successDescription: "Created order with id",
+        errors: [
+          { status: 400, code: "INVALID_INPUT", description: "Bad request" },
+          { status: 401, code: "UNAUTHORIZED", description: "Not authenticated" },
+        ],
+      },
+      {
+        id: "listOrders",
+        method: "GET",
+        path: "/api/orders",
+        auth: true,
+        description: "List all orders",
+        request: { body: {}, params: {}, query: { page: "number", limit: "number" } },
+        successStatus: 200,
+        successDescription: "Returns list of orders",
+        errors: [],
+      },
+      {
+        id: "deleteOrder",
+        method: "DELETE",
+        path: "/api/orders/:id",
+        auth: true,
+        description: "Delete an order",
+        request: { body: {}, params: { id: "string" }, query: {} },
+        successStatus: 204,
+        successDescription: "No content",
+        errors: [{ status: 404, code: "NOT_FOUND", description: "Order not found" }],
+      },
+    ],
+    behaviors: [],
+    ...overrides,
+  } as SpecDSL;
+}
+
+// ─── buildFrontendApiContract ────────────────────────────────────────────────
+
+describe("buildFrontendApiContract", () => {
+  it("returns correct number of endpoints", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints).toHaveLength(3);
+  });
+
+  it("preserves method and path", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints[0].method).toBe("POST");
+    expect(contract.endpoints[0].path).toBe("/api/orders");
+  });
+
+  it("preserves auth flag", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints[0].auth).toBe(true);
+  });
+
+  it("extracts error codes", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints[0].errorCodes).toEqual(["INVALID_INPUT", "UNAUTHORIZED"]);
+    expect(contract.endpoints[2].errorCodes).toEqual(["NOT_FOUND"]);
+  });
+
+  it("generates request shape as TypeScript interface", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints[0].requestShape).toContain("interface");
+    expect(contract.endpoints[0].requestShape).toContain("total");
+    expect(contract.endpoints[0].requestShape).toContain("items");
+  });
+
+  it("generates response shape as TypeScript interface", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.endpoints[0].responseShape).toContain("interface");
+  });
+
+  it("uses model fields for GET response on matching path", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const listEndpoint = contract.endpoints[1]; // GET /api/orders
+    expect(listEndpoint.responseShape).toContain("id");
+    expect(listEndpoint.responseShape).toContain("total");
+    expect(listEndpoint.responseShape).toContain("status");
+  });
+
+  it("generates 204 No Content interface for DELETE", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const deleteEndpoint = contract.endpoints[2];
+    expect(deleteEndpoint.responseShape).toContain("204 No Content");
+  });
+
+  it("generates type definitions block", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.typeDefinitions).toContain("interface");
+    expect(contract.typeDefinitions.length).toBeGreaterThan(50);
+  });
+
+  it("generates summary with feature title", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.summary).toContain("Order Management");
+    expect(contract.summary).toContain("3"); // 3 endpoints
+    expect(contract.summary).toContain("Order"); // model name
+  });
+
+  it("summary shows auth label per endpoint", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    expect(contract.summary).toContain("[auth required]");
+  });
+
+  it("handles empty errors array", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const listEndpoint = contract.endpoints[1];
+    expect(listEndpoint.errorCodes).toEqual([]);
+  });
+
+  it("handles DSL with no models", () => {
+    const contract = buildFrontendApiContract(makeDsl({ models: [] }));
+    expect(contract.endpoints).toHaveLength(3);
+    expect(contract.summary).not.toContain("Data models:");
+  });
+
+  it("infers TS types correctly in request shape", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    // Query params — page and limit should be number
+    const listReq = contract.endpoints[1].requestShape;
+    expect(listReq).toContain("number");
+  });
+
+  it("handles endpoint with token response description", () => {
+    const dsl = makeDsl({
+      endpoints: [
+        {
+          id: "login",
+          method: "POST",
+          path: "/api/auth/login",
+          auth: false,
+          description: "Login",
+          request: { body: { email: "string", password: "string" }, params: {}, query: {} },
+          successStatus: 200,
+          successDescription: "Returns JWT token",
+          errors: [],
+        },
+      ],
+    });
+    const contract = buildFrontendApiContract(dsl);
+    expect(contract.endpoints[0].responseShape).toContain("token");
+  });
+});
+
+// ─── buildContractContextSection ─────────────────────────────────────────────
+
+describe("buildContractContextSection", () => {
+  it("wraps contract in boundary markers", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const section = buildContractContextSection(contract);
+    expect(section).toContain("=== Backend API Contract");
+    expect(section).toContain("=== End of Backend API Contract ===");
+  });
+
+  it("includes summary", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const section = buildContractContextSection(contract);
+    expect(section).toContain("Order Management");
+  });
+
+  it("includes TypeScript definitions", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const section = buildContractContextSection(contract);
+    expect(section).toContain("TypeScript Interface Definitions");
+    expect(section).toContain("interface");
+  });
+
+  it("includes instruction not to change paths/methods", () => {
+    const contract = buildFrontendApiContract(makeDsl());
+    const section = buildContractContextSection(contract);
+    expect(section).toContain("do NOT change paths");
+  });
+});