ai-spec-dev 0.35.0 → 0.37.0

package/dist/index.d.mts

@@ -183,6 +183,21 @@ declare function loadTasksForSpec(specFilePath: string): Promise<SpecTask[] | nu
 /** Persist a single task's status to the tasks JSON file (checkpoint). */
 declare function updateTaskStatus(specFilePath: string, taskId: string, status: TaskStatus): Promise<void>;
 
+/**
+ * Extract a behavioral contract summary from a generated file.
+ *
+ * Captures:
+ * - export interface / type / enum — full multi-line blocks (the actual TS contracts)
+ * - export function / const / class — opening signature line
+ * - Throw statements — error codes & validation constraints
+ *
+ * Multi-line blocks (interface, type alias with {}) are captured in full so
+ * downstream tasks see complete method signatures and field shapes, not just
+ * a single-line "export interface Foo {" that conveys nothing.
+ *
+ * Falls back to first 3000 chars for CommonJS files with no explicit exports.
+ */
+declare function extractBehavioralContract(content: string): string;
 type CodeGenMode = "claude-code" | "api" | "plan";
 interface CodeGenOptions {
     /** Run claude non-interactively via -p flag (saves tokens, good for automation) */
@@ -281,4 +296,4 @@ declare class GitWorktreeManager {
     createWorktree(idea: string): Promise<string | null>;
 }
 
-export { type AIProvider, CONSTITUTION_FILE, ClaudeProvider, type CodeGenMode, type CodeGenOptions, CodeGenerator, CodeReviewer, ConstitutionGenerator, ContextLoader, DEFAULT_MODELS, ENV_KEY_MAP, FRONTEND_FRAMEWORKS, GeminiProvider, GitWorktreeManager, MiMoProvider, OpenAICompatibleProvider, PROVIDER_CATALOG, type ProjectContext, type ProviderMeta, SUPPORTED_PROVIDERS, type SharedConfigFile, SpecGenerator, SpecRefiner, type SpecTask, TaskGenerator, type TaskLayer, type TaskPriority, type TaskStatus, buildTaskPrompt, createProvider, extractComplianceScore, extractMissingCount, generateSpecWithTasks, isFrontendDeps, loadConstitution, loadTasksForSpec, printConstitutionHint, printTaskProgress, printTasks, updateTaskStatus };
+export { type AIProvider, CONSTITUTION_FILE, ClaudeProvider, type CodeGenMode, type CodeGenOptions, CodeGenerator, CodeReviewer, ConstitutionGenerator, ContextLoader, DEFAULT_MODELS, ENV_KEY_MAP, FRONTEND_FRAMEWORKS, GeminiProvider, GitWorktreeManager, MiMoProvider, OpenAICompatibleProvider, PROVIDER_CATALOG, type ProjectContext, type ProviderMeta, SUPPORTED_PROVIDERS, type SharedConfigFile, SpecGenerator, SpecRefiner, type SpecTask, TaskGenerator, type TaskLayer, type TaskPriority, type TaskStatus, buildTaskPrompt, createProvider, extractBehavioralContract, extractComplianceScore, extractMissingCount, generateSpecWithTasks, isFrontendDeps, loadConstitution, loadTasksForSpec, printConstitutionHint, printTaskProgress, printTasks, updateTaskStatus };

package/dist/index.d.ts

@@ -183,6 +183,21 @@ declare function loadTasksForSpec(specFilePath: string): Promise<SpecTask[] | nu
 /** Persist a single task's status to the tasks JSON file (checkpoint). */
 declare function updateTaskStatus(specFilePath: string, taskId: string, status: TaskStatus): Promise<void>;
 
+/**
+ * Extract a behavioral contract summary from a generated file.
+ *
+ * Captures:
+ * - export interface / type / enum — full multi-line blocks (the actual TS contracts)
+ * - export function / const / class — opening signature line
+ * - Throw statements — error codes & validation constraints
+ *
+ * Multi-line blocks (interface, type alias with {}) are captured in full so
+ * downstream tasks see complete method signatures and field shapes, not just
+ * a single-line "export interface Foo {" that conveys nothing.
+ *
+ * Falls back to first 3000 chars for CommonJS files with no explicit exports.
+ */
+declare function extractBehavioralContract(content: string): string;
 type CodeGenMode = "claude-code" | "api" | "plan";
 interface CodeGenOptions {
     /** Run claude non-interactively via -p flag (saves tokens, good for automation) */
@@ -281,4 +296,4 @@ declare class GitWorktreeManager {
     createWorktree(idea: string): Promise<string | null>;
 }
 
-export { type AIProvider, CONSTITUTION_FILE, ClaudeProvider, type CodeGenMode, type CodeGenOptions, CodeGenerator, CodeReviewer, ConstitutionGenerator, ContextLoader, DEFAULT_MODELS, ENV_KEY_MAP, FRONTEND_FRAMEWORKS, GeminiProvider, GitWorktreeManager, MiMoProvider, OpenAICompatibleProvider, PROVIDER_CATALOG, type ProjectContext, type ProviderMeta, SUPPORTED_PROVIDERS, type SharedConfigFile, SpecGenerator, SpecRefiner, type SpecTask, TaskGenerator, type TaskLayer, type TaskPriority, type TaskStatus, buildTaskPrompt, createProvider, extractComplianceScore, extractMissingCount, generateSpecWithTasks, isFrontendDeps, loadConstitution, loadTasksForSpec, printConstitutionHint, printTaskProgress, printTasks, updateTaskStatus };
+export { type AIProvider, CONSTITUTION_FILE, ClaudeProvider, type CodeGenMode, type CodeGenOptions, CodeGenerator, CodeReviewer, ConstitutionGenerator, ContextLoader, DEFAULT_MODELS, ENV_KEY_MAP, FRONTEND_FRAMEWORKS, GeminiProvider, GitWorktreeManager, MiMoProvider, OpenAICompatibleProvider, PROVIDER_CATALOG, type ProjectContext, type ProviderMeta, SUPPORTED_PROVIDERS, type SharedConfigFile, SpecGenerator, SpecRefiner, type SpecTask, TaskGenerator, type TaskLayer, type TaskPriority, type TaskStatus, buildTaskPrompt, createProvider, extractBehavioralContract, extractComplianceScore, extractMissingCount, generateSpecWithTasks, isFrontendDeps, loadConstitution, loadTasksForSpec, printConstitutionHint, printTaskProgress, printTasks, updateTaskStatus };

package/dist/index.js

@@ -50,6 +50,7 @@ __export(index_exports, {
   TaskGenerator: () => TaskGenerator,
   buildTaskPrompt: () => buildTaskPrompt,
   createProvider: () => createProvider,
+  extractBehavioralContract: () => extractBehavioralContract,
   extractComplianceScore: () => extractComplianceScore,
   extractMissingCount: () => extractMissingCount,
   generateSpecWithTasks: () => generateSpecWithTasks,
@@ -196,14 +197,49 @@ function classifyError(err, label) {
   const e = err;
   const status = e.status ?? e.response?.status;
   if (status === 401 || status === 403)
-    return new ProviderError(`Auth error \u2014 check your API key (${label})`, "auth", err);
+    return new ProviderError(
+      `Auth error (${label}): API key is invalid or expired.
+  \u2192 Check that the correct API key is set in your environment or ~/.ai-spec-keys.json
+  \u2192 Run "ai-spec model" to reconfigure your provider and key`,
+      "auth",
+      err
+    );
   if (status === 429)
-    return new ProviderError(`Rate limit hit (${label}) \u2014 try again later or switch provider`, "rate_limit", err);
+    return new ProviderError(
+      `Rate limit hit (${label}): too many requests.
+  \u2192 Wait a few minutes and retry, or switch to a different provider/model
+  \u2192 Check your provider's billing dashboard for quota status`,
+      "rate_limit",
+      err
+    );
   if (e._timeout || e.message?.toLowerCase().includes("timed out"))
     return new ProviderError(`Request timed out (${label})`, "timeout", err);
   if (e.code === "ECONNRESET" || e.code === "ENOTFOUND" || e.code === "ECONNREFUSED")
-    return new ProviderError(`Network error \u2014 check connection/proxy (${label}): ${e.message}`, "network", err);
-  return new ProviderError(`Provider error (${label}): ${e.message}`, "provider", err);
+    return new ProviderError(
+      `Network error (${label}): ${e.message}
+  \u2192 Check your internet connection and proxy settings (HTTPS_PROXY)
+  \u2192 If behind a firewall, ensure the provider's API endpoint is reachable`,
+      "network",
+      err
+    );
+  const msg = e.message ?? "";
+  if (status === 404 || msg.includes("model") && (msg.includes("not found") || msg.includes("does not exist")))
+    return new ProviderError(
+      `Model not found (${label}): ${msg}
+  \u2192 Run "ai-spec model" to see available models for your provider
+  \u2192 The model name may have changed \u2014 check your provider's documentation`,
+      "provider",
+      err
+    );
+  if (msg.includes("insufficient") || msg.includes("quota") || msg.includes("balance"))
+    return new ProviderError(
+      `Quota/balance error (${label}): ${msg}
+  \u2192 Check your provider's billing dashboard
+  \u2192 Consider switching to a different provider with "ai-spec model"`,
+      "provider",
+      err
+    );
+  return new ProviderError(`Provider error (${label}): ${msg}`, "provider", err);
 }
 function isRetryable(err) {
   const e = err;
@@ -4765,6 +4801,21 @@ function validateDsl(raw) {
     for (let i = 0; i < Math.min(eps.length, MAX_ENDPOINTS); i++) {
       validateEndpoint(eps[i], `endpoints[${i}]`, errors);
     }
+    const seenEpIds = /* @__PURE__ */ new Set();
+    for (let i = 0; i < Math.min(eps.length, MAX_ENDPOINTS); i++) {
+      const ep = eps[i];
+      if (ep && typeof ep === "object" && typeof ep["id"] === "string") {
+        const id = ep["id"];
+        if (seenEpIds.has(id)) {
+          errors.push({
+            path: `endpoints[${i}].id`,
+            message: `Duplicate endpoint id "${id}" \u2014 each endpoint must have a unique id`
+          });
+        } else {
+          seenEpIds.add(id);
+        }
+      }
+    }
   }
   if (obj["behaviors"] !== void 0) {
     if (!Array.isArray(obj["behaviors"])) {
@@ -4821,6 +4872,21 @@ function validateModel(raw, path10, errors) {
     for (let j2 = 0; j2 < Math.min(fields.length, MAX_FIELDS_PER_MODEL); j2++) {
       validateModelField(fields[j2], `${path10}.fields[${j2}]`, errors);
     }
+    const seenFieldNames = /* @__PURE__ */ new Set();
+    for (let j2 = 0; j2 < Math.min(fields.length, MAX_FIELDS_PER_MODEL); j2++) {
+      const f = fields[j2];
+      if (f && typeof f === "object" && typeof f["name"] === "string") {
+        const name = f["name"];
+        if (seenFieldNames.has(name)) {
+          errors.push({
+            path: `${path10}.fields[${j2}].name`,
+            message: `Duplicate field name "${name}" \u2014 each field within a model must have a unique name`
+          });
+        } else {
+          seenFieldNames.add(name);
+        }
+      }
+    }
   }
   if (m["relations"] !== void 0) {
     if (!Array.isArray(m["relations"])) {
@@ -5851,9 +5917,10 @@ ${tasks.map((t) => `${t.id} [${t.layer}] ${t.title}
       console.log(import_chalk8.default.cyan(`  \u{1F916} Auto mode: running claude -p (non-interactive)...`));
       console.log(import_chalk8.default.gray(`  Spec: ${specFilePath}`));
       try {
-        (0, import_child_process.execSync)(`${claudeCmd} -p "${promptContent.replace(/"/g, '\\"')}"`, {
+        (0, import_child_process.spawnSync)(claudeCmd, ["-p", promptContent], {
           cwd: workingDir,
-          stdio: "inherit"
+          stdio: "inherit",
+          shell: false
         });
         console.log(import_chalk8.default.green("\n  \u2714 Claude Code completed."));
       } catch {
@@ -5905,9 +5972,10 @@ Full spec is at: ${specFilePath}
 Implement ONLY this task. Do not implement other tasks.`;
       let taskStatus = "done";
       try {
-        (0, import_child_process.execSync)(`${claudeCmd} -p "${taskPrompt.replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`, {
+        (0, import_child_process.spawnSync)(claudeCmd, ["-p", taskPrompt], {
           cwd: workingDir,
-          stdio: "inherit"
+          stdio: "inherit",
+          shell: false
         });
         completed++;
       } catch {
@@ -6909,6 +6977,7 @@ var GitWorktreeManager = class {
   TaskGenerator,
   buildTaskPrompt,
   createProvider,
+  extractBehavioralContract,
   extractComplianceScore,
   extractMissingCount,
   generateSpecWithTasks,