ai-spec-dev 0.33.0 → 0.36.1

package/core/run-logger.ts

@@ -4,6 +4,86 @@ import chalk from "chalk";
 
 const LOG_DIR = ".ai-spec-logs";
 
+// ─── JSONL helpers ────────────────────────────────────────────────────────────
+// Each event is synchronously appended as one JSON line to a `.jsonl` shadow
+// file alongside the full `.json`. If the process crashes mid-run the `.json`
+// may be empty or stale, but every line written to the `.jsonl` is durable.
+// `loadRunLogs` (run-trend.ts) can reconstruct a RunLog from orphan `.jsonl`
+// files for crash recovery.
+
+function appendJsonlLine(filePath: string, record: Record<string, unknown>): void {
+  try {
+    fs.appendFileSync(filePath, JSON.stringify(record) + "\n");
+  } catch {
+    // JSONL write must never crash the pipeline
+  }
+}
+
+/** Reconstruct a RunLog from a `.jsonl` file (crash recovery path). */
+export function reconstructRunLogFromJsonl(jsonlPath: string): RunLog | null {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(jsonlPath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const log: Partial<RunLog> & { entries: LogEntry[]; filesWritten: string[]; errors: string[] } = {
+    entries: [],
+    filesWritten: [],
+    errors: [],
+    runId: "",
+    startedAt: "",
+    workingDir: "",
+  };
+
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const rec = JSON.parse(trimmed) as Record<string, unknown>;
+      switch (rec["type"]) {
+        case "header":
+          log.runId      = rec["runId"]      as string;
+          log.startedAt  = rec["startedAt"]  as string;
+          log.workingDir = rec["workingDir"] as string;
+          if (rec["provider"]) log.provider = rec["provider"] as string;
+          if (rec["model"])    log.model    = rec["model"]    as string;
+          if (rec["specPath"]) log.specPath  = rec["specPath"] as string;
+          break;
+        case "meta":
+          if (rec["key"] === "promptHash")  log.promptHash  = rec["value"] as string;
+          if (rec["key"] === "harnessScore") log.harnessScore = rec["value"] as number;
+          break;
+        case "entry":
+          log.entries.push({
+            ts: rec["ts"] as string,
+            event: rec["event"] as string,
+            ...(rec["durationMs"] !== undefined ? { durationMs: rec["durationMs"] as number } : {}),
+            ...(rec["data"] ? { data: rec["data"] as Record<string, unknown> } : {}),
+          });
+          break;
+        case "file":
+          if (rec["path"]) log.filesWritten.push(rec["path"] as string);
+          break;
+        case "error":
+          if (rec["message"]) log.errors.push(rec["message"] as string);
+          break;
+        case "footer":
+          if (rec["endedAt"])        log.endedAt        = rec["endedAt"]        as string;
+          if (rec["totalDurationMs"]) log.totalDurationMs = rec["totalDurationMs"] as number;
+          if (rec["harnessScore"])   log.harnessScore   = rec["harnessScore"]   as number;
+          break;
+      }
+    } catch {
+      // corrupt line — skip
+    }
+  }
+
+  if (!log.runId || !log.startedAt) return null;
+  return log as RunLog;
+}
+
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 export interface LogEntry {
@@ -42,6 +122,7 @@ export class RunLogger {
   private log: RunLog;
   private readonly startMs: number;
   private readonly logPath: string;
+  private readonly jsonlPath: string;
   private readonly stageStartMs = new Map<string, number>();
 
   constructor(
@@ -50,7 +131,8 @@ export class RunLogger {
     meta?: { provider?: string; model?: string; specPath?: string }
   ) {
     this.startMs = Date.now();
-    this.logPath = path.join(workingDir, LOG_DIR, `${runId}.json`);
+    this.logPath  = path.join(workingDir, LOG_DIR, `${runId}.json`);
+    this.jsonlPath = path.join(workingDir, LOG_DIR, `${runId}.jsonl`);
     this.log = {
       runId,
       startedAt: new Date().toISOString(),
@@ -60,6 +142,16 @@ export class RunLogger {
       filesWritten: [],
       errors: [],
     };
+    // Write JSONL header immediately — ensures the file exists even on early crash
+    fs.ensureDir(path.dirname(this.jsonlPath)).then(() => {
+      appendJsonlLine(this.jsonlPath, {
+        type: "header",
+        runId,
+        startedAt: this.log.startedAt,
+        workingDir,
+        ...meta,
+      });
+    }).catch(() => {});
     this.flush();
   }
 
@@ -78,25 +170,30 @@ export class RunLogger {
     const start = this.stageStartMs.get(event);
     const durationMs = start !== undefined ? Date.now() - start : undefined;
     this.push(`${event}:failed`, { ...data, error, durationMs });
-    this.log.errors.push(`[${event}] ${error}`);
+    const errorMsg = `[${event}] ${error}`;
+    this.log.errors.push(errorMsg);
+    appendJsonlLine(this.jsonlPath, { type: "error", message: errorMsg });
     this.flush();
   }
 
   /** Record the prompt hash for this run (call once at run start). */
   setPromptHash(hash: string): void {
     this.log.promptHash = hash;
+    appendJsonlLine(this.jsonlPath, { type: "meta", key: "promptHash", value: hash });
     this.flush();
   }
 
   /** Record the harness self-eval score (call once at run end). */
   setHarnessScore(score: number): void {
     this.log.harnessScore = score;
+    appendJsonlLine(this.jsonlPath, { type: "meta", key: "harnessScore", value: score });
     this.flush();
   }
 
   fileWritten(filePath: string): void {
     if (!this.log.filesWritten.includes(filePath)) {
       this.log.filesWritten.push(filePath);
+      appendJsonlLine(this.jsonlPath, { type: "file", path: filePath });
       this.flush();
     }
   }
@@ -104,6 +201,12 @@ export class RunLogger {
   finish(): void {
     this.log.endedAt = new Date().toISOString();
     this.log.totalDurationMs = Date.now() - this.startMs;
+    appendJsonlLine(this.jsonlPath, {
+      type: "footer",
+      endedAt: this.log.endedAt,
+      totalDurationMs: this.log.totalDurationMs,
+      harnessScore: this.log.harnessScore,
+    });
     this.flush();
   }
 
@@ -123,7 +226,10 @@ export class RunLogger {
   }
 
   private push(event: string, data?: Record<string, unknown>): void {
-    this.log.entries.push({ ts: new Date().toISOString(), event, ...( data ? { data } : {}) });
+    const entry: LogEntry = { ts: new Date().toISOString(), event, ...(data ? { data } : {}) };
+    this.log.entries.push(entry);
+    // Append to JSONL synchronously — durable even on crash
+    appendJsonlLine(this.jsonlPath, { type: "entry", ...entry });
     this.flush();
   }
 

package/core/run-trend.ts

@@ -1,7 +1,7 @@
 import * as fs from "fs-extra";
 import * as path from "path";
 import chalk from "chalk";
-import { RunLog } from "./run-logger";
+import { RunLog, reconstructRunLogFromJsonl } from "./run-logger";
 
 const LOG_DIR = ".ai-spec-logs";
 
@@ -49,20 +49,40 @@ export async function loadRunLogs(workingDir: string): Promise<RunLog[]> {
   if (!(await fs.pathExists(logDir))) return [];
 
   const files = await fs.readdir(logDir);
-  const jsonFiles = files.filter((f) => f.endsWith(".json")).sort().reverse();
+  const jsonFiles  = new Set(files.filter((f) => f.endsWith(".json")));
+  const jsonlFiles = files.filter((f) => f.endsWith(".jsonl")).sort().reverse();
 
   const logs: RunLog[] = [];
-  for (const file of jsonFiles) {
+  const seenRunIds = new Set<string>();
+
+  // Primary path: read complete .json files (newest-first)
+  for (const file of [...jsonFiles].sort().reverse()) {
     try {
       const log: RunLog = await fs.readJson(path.join(logDir, file));
-      // only include runs that have a startedAt (minimal validity check)
       if (log.runId && log.startedAt) {
         logs.push(log);
+        seenRunIds.add(log.runId);
       }
     } catch {
       // corrupt file — skip silently
     }
   }
+
+  // Crash-recovery path: reconstruct from orphan .jsonl files (no matching .json)
+  for (const file of jsonlFiles) {
+    const runId = file.replace(/\.jsonl$/, "");
+    if (seenRunIds.has(runId)) continue; // already loaded via .json
+    const correspondingJson = `${runId}.json`;
+    if (jsonFiles.has(correspondingJson)) continue; // .json exists, prefer it
+    const log = reconstructRunLogFromJsonl(path.join(logDir, file));
+    if (log) {
+      logs.push(log);
+      seenRunIds.add(log.runId);
+    }
+  }
+
+  // Sort newest-first by startedAt
+  logs.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
   return logs;
 }
 

package/core/self-evaluator.ts

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 import { SpecDSL } from "./dsl-types";
 import { RunLogger } from "./run-logger";
+import { extractComplianceScore } from "./reviewer";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -11,6 +12,8 @@ export interface SelfEvalResult {
   compileScore: number;
   /** 0-10 extracted from 3-pass review text, or null when review was skipped */
   reviewScore: number | null;
+  /** 0-10 from Pass 0 spec compliance check, or null when skipped/unavailable */
+  complianceScore: number | null;
   /** 0-10 weighted overall — the "Harness Score" recorded in RunLog */
   harnessScore: number;
   /** Prompt hash at the time this run executed */
@@ -191,15 +194,35 @@ export function runSelfEval(opts: {
   // ── Review Score ──────────────────────────────────────────────────────────
   const reviewScore = reviewText ? extractReviewScore(reviewText) : null;
 
+  // ── Compliance Score (Pass 0) ──────────────────────────────────────────────
+  const rawCompliance = reviewText ? extractComplianceScore(reviewText) : 0;
+  const complianceScore: number | null = rawCompliance > 0 ? rawCompliance : null;
+
   // ── Harness Score (weighted average) ──────────────────────────────────────
-  const harnessScore = reviewScore !== null
-    ? Math.round((dslCoverageScore * 0.4 + compileScore * 0.3 + reviewScore * 0.3) * 10) / 10
-    : Math.round((dslCoverageScore * 0.55 + compileScore * 0.45) * 10) / 10;
+  // Weights reflect importance: compliance (did we build the right thing?) > dsl > review > compile
+  //
+  //  compliance + review available  → 0.30 compliance + 0.25 dsl + 0.20 compile + 0.25 review
+  //  review only                    → 0.40 dsl + 0.30 compile + 0.30 review  (unchanged)
+  //  compliance only                → 0.35 compliance + 0.35 dsl + 0.30 compile
+  //  neither                        → 0.55 dsl + 0.45 compile                (unchanged)
+  let harnessScore: number;
+  if (complianceScore !== null && reviewScore !== null) {
+    harnessScore = Math.round(
+      (complianceScore * 0.30 + dslCoverageScore * 0.25 + compileScore * 0.20 + reviewScore * 0.25) * 10
+    ) / 10;
+  } else if (reviewScore !== null) {
+    harnessScore = Math.round((dslCoverageScore * 0.4 + compileScore * 0.3 + reviewScore * 0.3) * 10) / 10;
+  } else if (complianceScore !== null) {
+    harnessScore = Math.round((complianceScore * 0.35 + dslCoverageScore * 0.35 + compileScore * 0.30) * 10) / 10;
+  } else {
+    harnessScore = Math.round((dslCoverageScore * 0.55 + compileScore * 0.45) * 10) / 10;
+  }
 
   const result: SelfEvalResult = {
     dslCoverageScore,
     compileScore,
     reviewScore,
+    complianceScore,
     harnessScore,
     promptHash,
     detail: {
@@ -221,6 +244,7 @@ export function runSelfEval(opts: {
     dslCoverageScore,
     compileScore,
     reviewScore: reviewScore ?? undefined,
+    complianceScore: complianceScore ?? undefined,
     promptHash,
     modelNameCoverage: result.detail.modelNameCoverage,
     modelNameMatched:  result.detail.modelNameMatched,
@@ -244,9 +268,16 @@ export function printSelfEval(result: SelfEvalResult): void {
   const compileTag = result.compileScore === 10
     ? chalk.green("pass")
     : chalk.yellow("partial");
-  const reviewTag  = result.reviewScore !== null
+  const reviewTag = result.reviewScore !== null
     ? `Review: ${result.reviewScore}/10`
     : chalk.gray("Review: skipped");
+  const complianceTag = result.complianceScore !== null
+    ? (result.complianceScore >= 8
+        ? chalk.green(`Compliance: ${result.complianceScore}/10`)
+        : result.complianceScore >= 6
+          ? chalk.yellow(`Compliance: ${result.complianceScore}/10`)
+          : chalk.red(`Compliance: ${result.complianceScore}/10 ⚠`))
+    : chalk.gray("Compliance: skipped");
 
   // Model coverage tag (only shown when there are declared models)
   let modelCoverageTag = "";
@@ -262,15 +293,12 @@ export function printSelfEval(result: SelfEvalResult): void {
 
   console.log(chalk.cyan("\n─── Harness Self-Eval ───────────────────────────"));
   console.log(`  Score  : ${scoreColor(`[${bar}] ${result.harnessScore}/10`)}`);
+  console.log(`  ${complianceTag}  Compile: ${compileTag}  ${reviewTag}`);
   console.log(
-    `  DSL    : ${scoreColor(String(result.dslCoverageScore) + "/10")}  ` +
-    `Compile: ${compileTag}  ${reviewTag}`
+    `  DSL    : ${scoreColor(String(result.dslCoverageScore) + "/10")}` +
+    (modelCoverageTag ? `  ${modelCoverageTag}` : "") +
+    chalk.gray(`  Endpoints: ${result.detail.endpointsTotal}  Files: ${result.detail.filesWritten}`)
   );
-  if (modelCoverageTag) {
-    console.log(`  Detail : ${modelCoverageTag}  ` +
-      chalk.gray(`Endpoints: ${result.detail.endpointsTotal}  Files: ${result.detail.filesWritten}`)
-    );
-  }
   console.log(chalk.gray(`  Prompt : ${result.promptHash}`));
   console.log(chalk.cyan("─".repeat(49)));
 }

package/core/spec-generator.ts

@@ -145,15 +145,16 @@ export const PROVIDER_CATALOG: Record<string, ProviderMeta> = {
   },
   glm: {
     displayName: "智谱 GLM (Zhipu AI)",
-    description: "智谱 AI — GLM-5 / GLM-4 series + Z1 reasoning",
+    description: "智谱 AI — GLM-5.1 / GLM-5 / GLM-4 series",
     models: [
-      "glm-5",               // GLM-5 flagship (如不可用请确认最新 model ID)
-      "glm-5-flash",
-      "glm-z1",              // GLM-Z1 reasoning model
+      "glm-5.1",             // GLM-5.1 — latest flagship (2026)
+      "glm-5",               // GLM-5 — premium (Max/Pro plans)
+      "glm-5-turbo",         // GLM-5-Turbo — fast & cost-efficient
+      "glm-4.7",             // GLM-4.7
+      "glm-4.6",             // GLM-4.6
+      "glm-4.5-air",         // GLM-4.5-Air — lightweight
+      "glm-z1",              // GLM-Z1 — reasoning model
       "glm-z1-flash",
-      "glm-4-plus",
-      "glm-4-flash",
-      "glm-4-long",
     ],
     envKey: "ZHIPU_API_KEY",
     baseURL: "https://open.bigmodel.cn/api/paas/v4/",
@@ -405,8 +406,13 @@ export function createProvider(
 export class SpecGenerator {
   constructor(private provider: AIProvider) {}
 
-  async generateSpec(idea: string, context?: ProjectContext): Promise<string> {
+  async generateSpec(idea: string, context?: ProjectContext, architectureDecision?: string): Promise<string> {
     const parts: string[] = [idea];
+    if (architectureDecision) {
+      parts.push(
+        `\n=== Architecture Decision (MUST follow this approach in the spec) ===\n${architectureDecision}`
+      );
+    }
 
     if (context) {
       // Constitution is highest priority — put it first so the AI respects it

package/core/task-generator.ts

@@ -76,6 +76,15 @@ export interface SpecTask {
   layer: TaskLayer;
   filesToTouch: string[];
   acceptanceCriteria: string[];
+  /**
+   * Concrete, runnable verification steps — each entry is a specific command
+   * or action with an expected observable outcome.
+   * Examples:
+   *   "POST /api/orders with body {...} → HTTP 201, body contains {id, status:'pending'}"
+   *   "npm run build exits 0 with no TypeScript errors"
+   *   "GET /api/orders/:id returns 404 when id does not exist"
+   */
+  verificationSteps: string[];
   dependencies: string[];
   priority: TaskPriority;
   /** Runtime checkpoint — set by code generator, persisted to tasks file */
@@ -148,6 +157,14 @@ export function printTasks(tasks: SpecTask[]): void {
     const badge = color(`[${task.layer}]`);
     const prio = task.priority === "high" ? chalk.red("●") : task.priority === "medium" ? chalk.yellow("●") : chalk.gray("●");
     console.log(`  ${prio} ${chalk.bold(task.id)} ${badge} ${task.title}`);
+    if (task.verificationSteps?.length) {
+      for (const step of task.verificationSteps.slice(0, 2)) {
+        console.log(chalk.gray(`       ✓ ${step}`));
+      }
+      if (task.verificationSteps.length > 2) {
+        console.log(chalk.gray(`       + ${task.verificationSteps.length - 2} more verification step(s)`));
+      }
+    }
   }
 }
 

package/core/types-generator.ts

@@ -0,0 +1,219 @@
+import * as path from "path";
+import * as fs from "fs-extra";
+import { SpecDSL, ModelField, ApiEndpoint } from "./dsl-types";
+
+// ─── Type Mapping ─────────────────────────────────────────────────────────────
+
+const PRIMITIVE_MAP: Record<string, string> = {
+  String: "string",
+  string: "string",
+  Int: "number",
+  int: "number",
+  Float: "number",
+  float: "number",
+  Number: "number",
+  number: "number",
+  Boolean: "boolean",
+  boolean: "boolean",
+  DateTime: "string",
+  Date: "string",
+  Json: "Record<string, unknown>",
+  JSON: "Record<string, unknown>",
+  Any: "unknown",
+  any: "unknown",
+};
+
+function mapFieldType(raw: string): string {
+  const trimmed = raw.trim();
+  // Array types: "String[]" or "User[]"
+  if (trimmed.endsWith("[]")) {
+    return `${mapFieldType(trimmed.slice(0, -2))}[]`;
+  }
+  // Nullable / optional markers
+  const base = trimmed.replace(/[?!]$/, "");
+  if (PRIMITIVE_MAP[base]) return PRIMITIVE_MAP[base];
+  // PascalCase → treat as model reference (stays as-is)
+  if (/^[A-Z]/.test(base)) return base;
+  return "string";
+}
+
+// ─── Model → Interface ────────────────────────────────────────────────────────
+
+function renderModelInterface(
+  name: string,
+  fields: ModelField[],
+  description?: string
+): string {
+  const lines: string[] = [];
+  if (description) lines.push(`/** ${description} */`);
+  lines.push(`export interface ${name} {`);
+  for (const f of fields) {
+    const optional = f.required ? "" : "?";
+    const tsType = mapFieldType(f.type);
+    if (f.description) lines.push(`  /** ${f.description} */`);
+    lines.push(`  ${f.name}${optional}: ${tsType};`);
+  }
+  lines.push("}");
+  return lines.join("\n");
+}
+
+// ─── Endpoint → Request/Response types ───────────────────────────────────────
+
+function sanitizeName(str: string): string {
+  // "/users/:id" → "UsersById", "POST /auth/login" → "PostAuthLogin"
+  return str
+    .replace(/^\//, "")
+    .replace(/:([a-zA-Z]+)/g, "By$1")
+    .split(/[\/\-_]/)
+    .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+    .join("");
+}
+
+function endpointTypeName(ep: ApiEndpoint): string {
+  return ep.method.charAt(0) + ep.method.slice(1).toLowerCase() + sanitizeName(ep.path);
+}
+
+function renderEndpointTypes(ep: ApiEndpoint): string | null {
+  const baseName = endpointTypeName(ep);
+  const parts: string[] = [];
+
+  parts.push(`// ${ep.method} ${ep.path}${ep.description ? ` — ${ep.description}` : ""}`);
+
+  let hasRequest = false;
+
+  // Request body
+  if (ep.request?.body && Object.keys(ep.request.body).length > 0) {
+    hasRequest = true;
+    parts.push(`export interface ${baseName}Request {`);
+    for (const [key, typeDesc] of Object.entries(ep.request.body)) {
+      const tsType = mapFieldType(typeDesc);
+      parts.push(`  ${key}: ${tsType};`);
+    }
+    parts.push("}");
+  }
+
+  // Query params
+  if (ep.request?.query && Object.keys(ep.request.query).length > 0) {
+    parts.push(`export interface ${baseName}Query {`);
+    for (const [key, typeDesc] of Object.entries(ep.request.query)) {
+      const tsType = mapFieldType(typeDesc);
+      parts.push(`  ${key}?: ${tsType};`);
+    }
+    parts.push("}");
+  }
+
+  // Path params
+  if (ep.request?.params && Object.keys(ep.request.params).length > 0) {
+    parts.push(`export interface ${baseName}Params {`);
+    for (const [key, typeDesc] of Object.entries(ep.request.params)) {
+      const tsType = mapFieldType(typeDesc);
+      parts.push(`  ${key}: ${tsType};`);
+    }
+    parts.push("}");
+  }
+
+  if (parts.length === 1) return null; // only comment, no types to emit
+  return parts.join("\n");
+}
+
+// ─── Endpoint map constant ───────────────────────────────────────────────────
+
+function renderEndpointMap(endpoints: ApiEndpoint[]): string {
+  const lines: string[] = [];
+  lines.push("export const API_ENDPOINTS = {");
+  for (const ep of endpoints) {
+    const key = endpointTypeName(ep);
+    const keyLower = key.charAt(0).toLowerCase() + key.slice(1);
+    lines.push(`  ${keyLower}: { method: '${ep.method}', path: '${ep.path}', auth: ${ep.auth} },`);
+  }
+  lines.push("} as const;");
+  lines.push("");
+  lines.push("export type ApiEndpointKey = keyof typeof API_ENDPOINTS;");
+  return lines.join("\n");
+}
+
+// ─── Main generator ───────────────────────────────────────────────────────────
+
+export interface TypesGeneratorOptions {
+  /** Include endpoint request/response types (default: true) */
+  includeEndpointTypes?: boolean;
+  /** Include API_ENDPOINTS constant map (default: true) */
+  includeEndpointMap?: boolean;
+  /** Header comment to inject */
+  header?: string;
+}
+
+export function generateTypescriptTypes(
+  dsl: SpecDSL,
+  opts: TypesGeneratorOptions = {}
+): string {
+  const {
+    includeEndpointTypes = true,
+    includeEndpointMap = true,
+  } = opts;
+
+  const sections: string[] = [];
+
+  // Header
+  const header = opts.header ?? `// Generated by ai-spec — DO NOT EDIT\n// Feature: ${dsl.feature.title}\n// Generated at: ${new Date().toISOString()}`;
+  sections.push(header);
+
+  // Data Models
+  if (dsl.models.length > 0) {
+    sections.push("// ─── Data Models " + "─".repeat(57));
+    for (const model of dsl.models) {
+      sections.push(renderModelInterface(model.name, model.fields, model.description));
+    }
+  }
+
+  // Frontend Components (props only)
+  if (dsl.components && dsl.components.length > 0) {
+    sections.push("// ─── Component Props " + "─".repeat(53));
+    for (const comp of dsl.components) {
+      const lines: string[] = [];
+      if (comp.description) lines.push(`/** ${comp.description} */`);
+      lines.push(`export interface ${comp.name}Props {`);
+      for (const prop of comp.props) {
+        const optional = prop.required ? "" : "?";
+        const tsType = mapFieldType(prop.type);
+        if (prop.description) lines.push(`  /** ${prop.description} */`);
+        lines.push(`  ${prop.name}${optional}: ${tsType};`);
+      }
+      lines.push("}");
+      sections.push(lines.join("\n"));
+    }
+  }
+
+  // Endpoint request/response types
+  if (includeEndpointTypes && dsl.endpoints.length > 0) {
+    sections.push("// ─── API Request Types " + "─".repeat(51));
+    for (const ep of dsl.endpoints) {
+      const rendered = renderEndpointTypes(ep);
+      if (rendered) sections.push(rendered);
+    }
+  }
+
+  // Endpoint map
+  if (includeEndpointMap && dsl.endpoints.length > 0) {
+    sections.push("// ─── Endpoint Map " + "─".repeat(55));
+    sections.push(renderEndpointMap(dsl.endpoints));
+  }
+
+  return sections.join("\n\n") + "\n";
+}
+
+// ─── File save ────────────────────────────────────────────────────────────────
+
+export async function saveTypescriptTypes(
+  dsl: SpecDSL,
+  projectDir: string,
+  opts: TypesGeneratorOptions & { outputPath?: string } = {}
+): Promise<string> {
+  const outputPath =
+    opts.outputPath ?? path.join(projectDir, ".ai-spec", `${dsl.feature.title.replace(/\s+/g, "-").toLowerCase()}.types.ts`);
+
+  await fs.ensureDir(path.dirname(outputPath));
+  const content = generateTypescriptTypes(dsl, opts);
+  await fs.writeFile(outputPath, content, "utf-8");
+  return outputPath;
+}