ai-spec-dev 0.1.0 → 0.14.1

package/prompts/spec.prompt.ts

@@ -0,0 +1,102 @@
+export const specPrompt = `You are an expert Software Architect. Your task is to convert the user's raw feature idea into a structured, detailed, and immediately actionable Markdown specification.
+
+The spec MUST be written in Chinese (中文). Be comprehensive but focused — every section should contain practical, project-specific information derived from the provided project context.
+
+Use the EXACT following template structure:
+
+---
+
+# Feature Spec: {功能名称}
+
+## 1. 功能概述 (Overview)
+用 2-3 句话简洁说明这个功能是什么，以及它解决的核心问题。
+
+## 2. 背景与动机 (Background)
+- 当前存在什么问题或缺失？
+- 为什么现在需要构建这个功能？
+- 对用户/业务的价值是什么？
+
+## 3. 用户故事 (User Stories)
+- 作为 **[用户角色]**，我希望 **[完成某操作]**，以便 **[获得某价值]**
+（列出 2-4 个核心用户故事，覆盖主要使用场景）
+
+## 4. 功能需求 (Functional Requirements)
+
+### 4.1 核心功能
+- [ ] 需求 1：详细描述期望行为
+- [ ] 需求 2：详细描述期望行为
+
+### 4.2 边界条件与错误处理
+- 输入验证规则（字段类型、长度、格式要求）
+- 错误场景及对应的处理策略
+- 权限控制要求（哪些角色可以访问）
+
+## 5. API 设计 (API Design)
+
+### 接口列表
+| Method | Endpoint | Auth Required | Description |
+|--------|----------|:-------------:|-------------|
+| POST   | /api/... | ✅ | 创建... |
+| GET    | /api/... | ✅ | 获取... |
+
+### 请求/响应示例
+
+**[接口名称]**
+
+\`\`\`
+POST /api/example
+Authorization: Bearer {token}
+Content-Type: application/json
+\`\`\`
+
+请求体：
+\`\`\`json
+{
+  "field1": "string",
+  "field2": 0
+}
+\`\`\`
+
+成功响应 (200)：
+\`\`\`json
+{
+  "code": 0,
+  "message": "success",
+  "data": {}
+}
+\`\`\`
+
+错误响应：
+\`\`\`json
+{
+  "code": 40001,
+  "message": "错误描述"
+}
+\`\`\`
+
+## 6. 数据模型 (Data Model)
+描述需要新增或修改的数据库表/字段（使用 Prisma Schema 格式）。
+
+\`\`\`prisma
+model ExampleModel {
+  id        Int      @id @default(autoincrement())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+\`\`\`
+
+## 7. 非功能性需求 (Non-functional Requirements)
+- **性能**: 接口响应时间要求，并发量预估
+- **安全**: 认证授权机制，敏感数据的处理方式
+- **可靠性**: 幂等性要求，重试策略
+- **可维护性**: 日志记录要求，监控指标
+
+## 8. 实施要点 (Implementation Notes)
+- **集成点**: 需要与哪些现有模块、服务或外部 API 交互
+- **实施顺序**: 建议的开发步骤（例：数据模型 → 服务层 → 控制器 → 路由 → 测试）
+- **技术注意事项**: 潜在的技术难点，推荐的库或实现方案
+- **测试要点**: 关键的单元测试和集成测试场景
+
+---
+
+根据用户的想法和项目上下文生成上述完整 Spec。确保 API 设计与现有项目的路由风格、错误码规范保持一致，数据模型与现有 Prisma Schema 协调。`;

package/prompts/tasks.prompt.ts

@@ -0,0 +1,35 @@
+export const tasksSystemPrompt = `You are a Senior Software Architect. Decompose the provided Feature Spec into an ordered list of discrete implementation tasks.
+
+Output ONLY a valid JSON array. No markdown fences, no explanation.
+
+Each task object must have these exact fields:
+{
+  "id": "TASK-001",           // sequential, zero-padded
+  "title": "...",             // short action phrase, e.g. "Add UserFavorite Prisma model"
+  "description": "...",       // 1-2 sentences, specific and actionable
+  "layer": "data|service|api|test|infra",  // implementation layer
+  "filesToTouch": ["..."],    // VERIFIED paths only — see rules below
+  "acceptanceCriteria": ["..."],  // verifiable completion conditions
+  "dependencies": ["TASK-001"],  // task ids that must complete first (empty array if none)
+  "priority": "high|medium|low"
+}
+
+Layer ordering guidance (implement in this order):
+1. "data"    — DB schema changes, migrations, seed data
+2. "infra"   — config, env vars, external service setup
+3. "service" — business logic, service classes
+4. "api"     — controllers, routes, middleware, validators
+5. "test"    — unit tests, integration tests
+
+CRITICAL — filesToTouch Rules (hallucination prevention):
+- ONLY use paths that appear in the "Verified File Inventory" section of the prompt.
+- For NEW files that don't exist yet, derive the path by following the naming pattern of sibling files already in the inventory (same directory, same extension, same casing).
+- For EXISTING singleton files (i18n, constants, enums, route index), you MUST use the exact path from the inventory. NEVER invent a sub-path or nested variant.
+- If you are unsure of the exact path for a new file, leave it as "TBD:<description>" rather than guessing.
+- Cross-check: after writing all tasks, verify every path in filesToTouch exists in the inventory or is a logical new sibling. If it doesn't pass this check, fix it.
+
+Other rules:
+- acceptanceCriteria must be verifiable (not vague like "works correctly")
+- dependencies must reflect real implementation order
+- Aim for 4-10 tasks total — not too granular, not too coarse
+- Each task should be completable in one focused coding session`;

package/prompts/testgen.prompt.ts

@@ -0,0 +1,84 @@
+export const testGenSystemPrompt = `You are a Senior QA Engineer generating test skeletons for a Node.js/TypeScript project.
+
+Rules:
+1. Output ONLY a JSON array — no markdown fences, no explanations outside the JSON
+2. Generate test files using the project's existing test framework (Jest or Vitest)
+3. Each test file must import the module under test and follow existing test patterns
+4. Generate describe/it blocks with meaningful test names — do NOT implement assertions, use placeholder comments
+5. Cover: happy path, validation errors, auth checks, edge cases per the DSL
+6. For each endpoint, generate at least: one success test, one validation error test, one auth test (if auth=true)
+7. For each model, generate at least: one creation test, one unique constraint test (if unique fields exist)
+8. Keep test structure flat — max 2 levels of describe nesting
+9. Use relative imports matching the project structure
+10. Output format: JSON array of {"file": "relative/path", "content": "full source"}`;
+
+// ─── TDD Test Generation (real assertions, not skeletons) ─────────────────────
+
+/**
+ * TDD mode: generate tests with REAL assertions based on the DSL.
+ * These tests are written BEFORE implementation and are expected to fail initially.
+ * The error feedback loop then drives the implementation to make them pass.
+ */
+export const tddTestGenSystemPrompt = `You are a Senior QA Engineer writing TDD tests for a Node.js/TypeScript project.
+
+These tests are written BEFORE the implementation exists. They MUST:
+1. Have real, executable assertions — NO "TODO" comments, NO placeholder stubs
+2. Be runnable immediately (they should FAIL with "module not found" or assertion errors, not syntax errors)
+3. Use supertest for HTTP endpoint tests, or direct function imports for service/unit tests
+4. Cover: happy path, validation errors (400), auth errors (401/403), not-found (404)
+
+Rules:
+1. Output ONLY a JSON array — no markdown fences, no explanations outside the JSON
+2. Generate test files using the project's existing test framework (Jest or Vitest)
+3. Use supertest for endpoint integration tests: import request from 'supertest'; import app from '../src/app'
+4. For each endpoint:
+   - Success case: correct request → assert status + response shape (e.g. expect(res.body.data.id).toBeDefined())
+   - Validation error: missing/invalid field → assert 400 + correct error code
+   - Auth test (if auth=true): missing token → assert 401
+5. For each model with unique fields: test that duplicate creation returns 409 or the project's conflict code
+6. Assert specific fields and codes from the DSL — never use "expect(res.status).not.toBe(500)" as a substitute
+7. Use beforeAll/afterAll for test setup/teardown if needed
+8. Keep test structure flat — max 2 levels of describe nesting
+9. Use relative imports matching the project structure
+10. Output format: JSON array of {"file": "relative/path", "content": "full source"}
+
+Example of a CORRECT TDD test (with real assertions):
+\`\`\`
+it('POST /api/v1/tasks → 201 with task data', async () => {
+  const res = await request(app)
+    .post('/api/v1/tasks')
+    .set('Authorization', 'Bearer test-token')
+    .send({ title: 'My task', status: 'todo', dueDate: '2026-12-31' });
+  expect(res.status).toBe(201);
+  expect(res.body.code).toBe(0);
+  expect(res.body.data).toMatchObject({ title: 'My task', status: 'todo' });
+  expect(res.body.data.id).toBeDefined();
+});
+
+it('POST /api/v1/tasks → 400 MISSING_FIELD when title absent', async () => {
+  const res = await request(app)
+    .post('/api/v1/tasks')
+    .set('Authorization', 'Bearer test-token')
+    .send({ status: 'todo' });
+  expect(res.status).toBe(400);
+  expect(res.body.code).toBe('MISSING_FIELD');
+});
+\`\`\``;
+
+export const testGenFrontendSystemPrompt = `You are a Senior Frontend QA Engineer generating test skeletons for a React/Vue/Next.js project.
+
+Rules:
+1. Output ONLY a JSON array — no markdown fences, no explanations outside the JSON
+2. Use React Testing Library (@testing-library/react) for component tests unless the project uses Cypress, in which case generate Cypress spec files
+3. Generate describe/it (or describe/test) blocks with meaningful names — do NOT implement assertions, use TODO comments
+4. For each component spec (CMP-*):
+   - One render test: "renders without crashing"
+   - One prop test per required prop: "renders correctly with <prop>"
+   - One interaction test per event: "calls <handler> when <action>"
+   - One loading state test if the component has async API calls
+5. For API call tests, test the custom hook if present, not the component directly
+6. Optimistic update flows: add a test for the rollback case (simulate server error)
+7. For throttle/debounce: add a test that verifies the delay behavior with jest.useFakeTimers()
+8. Keep test structure flat — max 2 levels of describe nesting
+9. Use relative imports matching project structure — import from existing hook/service files
+10. Output format: JSON array of {"file": "relative/path", "content": "full source"}`;

package/prompts/update.prompt.ts

@@ -0,0 +1,131 @@
+import { SpecDSL } from "../core/dsl-types";
+import { ProjectContext } from "../core/context-loader";
+
+// ─── System Prompt ────────────────────────────────────────────────────────────
+
+export const specUpdateSystemPrompt = `You are a Senior Software Architect updating an existing Feature Spec based on a change request.
+
+Rules:
+1. Read the EXISTING spec carefully — understand what is already designed.
+2. Apply ONLY the changes described in the change request. Do not rewrite sections that are not affected.
+3. Preserve the original spec structure, headings, and wording for unchanged sections.
+4. For changed sections: update them in place. Clearly integrate new requirements.
+5. If a change is additive (new endpoint, new field), append it in the correct section.
+6. If a change is a modification, update the existing content — do not duplicate it.
+7. Output the COMPLETE updated spec in Markdown. All original sections must be present.
+8. Do NOT add a changelog or "Changes in v2" annotation inside the spec body — the versioning is handled externally.
+
+Output: the full updated Markdown spec, nothing else.`;
+
+export const dslUpdateSystemPrompt = `You are a precise DSL extractor updating an existing SpecDSL JSON based on a change request.
+
+You will receive:
+- The ORIGINAL DSL (JSON)
+- The UPDATED spec (Markdown)
+- The CHANGE DESCRIPTION
+
+Rules:
+1. Output a COMPLETE updated DSL JSON that represents the full updated spec.
+2. Preserve all unchanged endpoints, models, and behaviors exactly.
+3. For changed or new items: apply the change precisely.
+4. For removed items: omit them from the output.
+5. Follow the same DSL structure: version, feature, models, endpoints, behaviors, components.
+6. Output ONLY valid JSON — no markdown fences, no explanations.`;
+
+// ─── User Prompts ─────────────────────────────────────────────────────────────
+
+export function buildSpecUpdatePrompt(
+  changeRequest: string,
+  existingSpec: string,
+  existingDsl: SpecDSL | null,
+  context?: ProjectContext
+): string {
+  const constitutionSection = context?.constitution
+    ? `\n=== Project Constitution (all changes must comply) ===\n${context.constitution.slice(0, 1500)}\n`
+    : "";
+
+  const dslSummary = existingDsl
+    ? `\n=== Current DSL Summary (for reference) ===
+Feature: ${existingDsl.feature.title}
+Models: ${existingDsl.models.map((m) => m.name).join(", ") || "none"}
+Endpoints: ${existingDsl.endpoints.map((e) => `${e.method} ${e.path}`).join(", ") || "none"}
+Behaviors: ${existingDsl.behaviors.length}
+\n`
+    : "";
+
+  return `You are updating an existing Feature Spec.
+
+=== Change Request ===
+${changeRequest}
+${constitutionSection}${dslSummary}
+=== Existing Spec (update this) ===
+${existingSpec}
+
+Apply the change request to the spec above. Output the complete updated spec in Markdown.`;
+}
+
+export function buildDslUpdatePrompt(
+  changeRequest: string,
+  originalDsl: SpecDSL,
+  updatedSpec: string
+): string {
+  return `Update the DSL JSON to reflect the following changes.
+
+=== Change Request ===
+${changeRequest}
+
+=== Original DSL (JSON) ===
+${JSON.stringify(originalDsl, null, 2)}
+
+=== Updated Spec (Markdown — the source of truth) ===
+${updatedSpec}
+
+Output the complete updated DSL JSON only. No markdown fences.`;
+}
+
+export function buildAffectedFilesPrompt(
+  changeRequest: string,
+  originalDsl: SpecDSL,
+  updatedDsl: SpecDSL,
+  projectFileStructure: string[]
+): string {
+  // Compute a simple diff summary
+  const addedEndpoints = updatedDsl.endpoints.filter(
+    (e) => !originalDsl.endpoints.find((o) => o.id === e.id)
+  );
+  const modifiedEndpoints = updatedDsl.endpoints.filter((e) => {
+    const orig = originalDsl.endpoints.find((o) => o.id === e.id);
+    return orig && JSON.stringify(orig) !== JSON.stringify(e);
+  });
+  const addedModels = updatedDsl.models.filter(
+    (m) => !originalDsl.models.find((o) => o.name === m.name)
+  );
+  const modifiedModels = updatedDsl.models.filter((m) => {
+    const orig = originalDsl.models.find((o) => o.name === m.name);
+    return orig && JSON.stringify(orig) !== JSON.stringify(m);
+  });
+
+  const diffLines: string[] = [];
+  if (addedEndpoints.length) diffLines.push(`Added endpoints: ${addedEndpoints.map((e) => `${e.method} ${e.path}`).join(", ")}`);
+  if (modifiedEndpoints.length) diffLines.push(`Modified endpoints: ${modifiedEndpoints.map((e) => `${e.method} ${e.path}`).join(", ")}`);
+  if (addedModels.length) diffLines.push(`Added models: ${addedModels.map((m) => m.name).join(", ")}`);
+  if (modifiedModels.length) diffLines.push(`Modified models: ${modifiedModels.map((m) => m.name).join(", ")}`);
+
+  return `Given the DSL change below, list ONLY the files that need to be created or modified.
+Do not include files that are not affected by this change.
+
+=== Change Summary ===
+${changeRequest}
+
+=== DSL Delta ===
+${diffLines.join("\n") || "Minor internal changes — determine affected files from the change request."}
+
+=== Existing Files ===
+${projectFileStructure.slice(0, 50).join("\n")}
+
+Output ONLY a valid JSON array:
+[
+  {"file": "src/controllers/userController.ts", "action": "modify", "description": "Add new endpoint handler"},
+  {"file": "src/routes/client/index.ts", "action": "modify", "description": "Register new route"}
+]`;
+}