ai-spec-dev 0.1.0 → 0.17.0

package/dist/index.d.mts

@@ -1,5 +1,13 @@
 import OpenAI from 'openai';
 
+interface SharedConfigFile {
+    /** Relative path from project root */
+    path: string;
+    /** First 80 lines of the file */
+    preview: string;
+    /** Inferred category */
+    category: "i18n" | "constants" | "enums" | "config" | "route-index" | "store-index" | "other";
+}
 interface ProjectContext {
     techStack: string[];
     fileStructure: string[];
@@ -7,20 +15,55 @@ interface ProjectContext {
     apiStructure: string[];
     schema?: string;
     routeSummary?: string;
-    /** Contents of .ai-spec-constitution.md if present */
+    /**
+     * Effective constitution injected into prompts.
+     * If a global constitution was found it is merged in here (global first, project overrides).
+     */
     constitution?: string;
     /** Extracted error handling patterns from source */
     errorPatterns?: string;
+    /**
+     * Singleton/append-only config files that MUST be modified in-place,
+     * never recreated as a new parallel file (i18n, constants, enums, config indices, etc.)
+     */
+    sharedConfigFiles?: SharedConfigFile[];
 }
+/**
+ * Single source of truth for what counts as a "frontend" project.
+ * Import this constant (and isFrontendDeps) everywhere instead of
+ * repeating the inline array — one place to add Svelte, Solid, Qwik, etc.
+ */
+declare const FRONTEND_FRAMEWORKS: readonly ["react", "vue", "next", "nuxt", "react-native", "expo", "svelte", "solid-js", "qwik"];
+/**
+ * Returns true if any of the given dependency keys is a recognised frontend framework.
+ * Works on the raw key list from package.json / context.dependencies.
+ */
+declare function isFrontendDeps(deps: string[]): boolean;
 declare class ContextLoader {
     private projectRoot;
     constructor(projectRoot: string);
     loadProjectContext(): Promise<ProjectContext>;
+    /** Load PHP project context from composer.json */
+    private loadComposerJson;
+    /**
+     * Load PHP route files (routes/api.php, routes/web.php) as routeSummary.
+     * Lumen uses these files to register API endpoints.
+     */
+    private loadPhpRoutes;
+    /** Load Java project context from pom.xml or build.gradle */
+    private loadMavenOrGradle;
+    /** Scan Java controller files for API structure */
+    private loadJavaApiStructure;
     private loadPackageJson;
     private loadPrismaSchema;
     private loadFileStructure;
     private loadConstitution;
     private loadErrorPatterns;
+    /**
+     * Scan for "singleton" config files that should never be duplicated.
+     * These are append-only files: i18n bundles, constants, enums, config indices.
+     */
+    private loadSharedConfigFiles;
     private loadApiStructure;
 }
 
@@ -43,6 +86,17 @@ interface ProviderMeta {
      * Undefined means the provider has its own SDK (Gemini / Claude).
      */
     baseURL?: string;
+    /**
+     * Role to use for system instructions.
+     * OpenAI o1/o3 use "developer" instead of "system".
+     * Default: "system"
+     */
+    systemRole?: "system" | "developer";
+    /**
+     * Extra body params injected into every chat completion request.
+     * e.g. Qwen3 needs { enable_thinking: false } to suppress CoT noise.
+     */
+    extraBody?: Record<string, unknown>;
 }
 declare const PROVIDER_CATALOG: Record<string, ProviderMeta>;
 declare const SUPPORTED_PROVIDERS: string[];
@@ -66,7 +120,17 @@ declare class OpenAICompatibleProvider implements AIProvider {
     protected client: OpenAI;
     readonly providerName: string;
     readonly modelName: string;
-    constructor(providerName: string, apiKey: string, modelName: string, baseURL?: string);
+    private systemRole;
+    private extraBody?;
+    constructor(providerName: string, apiKey: string, modelName: string, baseURL?: string, systemRole?: "system" | "developer", extraBody?: Record<string, unknown>);
+    generate(prompt: string, systemInstruction?: string): Promise<string>;
+}
+declare class MiMoProvider implements AIProvider {
+    readonly providerName = "mimo";
+    readonly modelName: string;
+    private apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, modelName?: string);
     generate(prompt: string, systemInstruction?: string): Promise<string>;
 }
 declare function createProvider(providerName: string, apiKey: string, modelName?: string): AIProvider;
@@ -82,30 +146,88 @@ declare class SpecRefiner {
     refineLoop(initialSpec: string): Promise<string>;
 }
 
+declare function buildTaskPrompt(spec: string, context?: ProjectContext): string;
+type TaskLayer = "data" | "infra" | "service" | "api" | "test";
+type TaskPriority = "high" | "medium" | "low";
+type TaskStatus = "pending" | "done" | "failed";
+interface SpecTask {
+    id: string;
+    title: string;
+    description: string;
+    layer: TaskLayer;
+    filesToTouch: string[];
+    acceptanceCriteria: string[];
+    dependencies: string[];
+    priority: TaskPriority;
+    /** Runtime checkpoint — set by code generator, persisted to tasks file */
+    status?: TaskStatus;
+}
+declare class TaskGenerator {
+    private provider;
+    constructor(provider: AIProvider);
+    generateTasks(spec: string, context?: ProjectContext): Promise<SpecTask[]>;
+    saveTasks(tasks: SpecTask[], specFilePath: string): Promise<string>;
+    sortByLayer(tasks: SpecTask[]): SpecTask[];
+}
+declare function printTasks(tasks: SpecTask[]): void;
+declare function loadTasksForSpec(specFilePath: string): Promise<SpecTask[] | null>;
+/** Persist a single task's status to the tasks JSON file (checkpoint). */
+declare function updateTaskStatus(specFilePath: string, taskId: string, status: TaskStatus): Promise<void>;
+
 type CodeGenMode = "claude-code" | "api" | "plan";
 interface CodeGenOptions {
     /** Run claude non-interactively via -p flag (saves tokens, good for automation) */
     auto?: boolean;
+    /** Resume from last checkpoint — skip tasks already marked as done */
+    resume?: boolean;
+    /** Path to the DSL JSON file — if provided, structured context is injected into prompts */
+    dslFilePath?: string;
+    /** Repo language type — selects the appropriate codegen system prompt */
+    repoType?: string;
 }
 declare class CodeGenerator {
     private provider;
     private mode;
     constructor(provider: AIProvider, mode?: CodeGenMode);
-    generateCode(specFilePath: string, workingDir: string, context?: ProjectContext, options?: CodeGenOptions): Promise<void>;
+    /** Returns the list of file paths written to disk (useful for api-mode review). */
+    generateCode(specFilePath: string, workingDir: string, context?: ProjectContext, options?: CodeGenOptions): Promise<string[]>;
     private isClaudeCLIAvailable;
     private runClaudeCode;
+    /**
+     * Incremental claude-code execution: one `claude -p` call per task.
+     * Tasks marked as "done" are skipped (resume support).
+     * Progress is shown as a percentage bar.
+     */
+    private runClaudeCodeIncremental;
     private runApiMode;
     private runApiModeWithTasks;
     private generateFiles;
     private runPlanMode;
 }
+declare function printTaskProgress(completed: number, total: number, task: SpecTask, mode: "run" | "skip"): void;
 
 declare class CodeReviewer {
     private provider;
-    constructor(provider: AIProvider);
+    private projectRoot;
+    constructor(provider: AIProvider, projectRoot?: string);
     private getGitDiff;
     private getDiffStats;
-    reviewCode(specContent: string): Promise<string>;
+    /**
+     * Two-pass review:
+     *   Pass 1 — architecture (spec compliance, layer separation, auth)
+     *   Pass 2 — implementation details (validation, error handling, edge cases)
+     *             + historical issue recurrence check
+     *
+     * Falls back to single-pass if the two-pass flag is not set.
+     */
+    private runTwoPassReview;
+    reviewCode(specContent: string, specFile?: string): Promise<string>;
+    /**
+     * Review directly from generated file contents (for api mode where git diff is empty).
+     */
+    reviewFiles(specContent: string, filePaths: string[], workingDir: string, specFile?: string): Promise<string>;
+    /** Print score trend from history (last N reviews) */
+    printScoreTrend(limit?: number): Promise<void>;
 }
 
 declare const CONSTITUTION_FILE = ".ai-spec-constitution.md";
@@ -118,34 +240,32 @@ declare class ConstitutionGenerator {
 declare function loadConstitution(projectRoot: string): Promise<string | undefined>;
 declare function printConstitutionHint(exists: boolean): void;
 
-type TaskLayer = "data" | "infra" | "service" | "api" | "test";
-type TaskPriority = "high" | "medium" | "low";
-interface SpecTask {
-    id: string;
-    title: string;
-    description: string;
-    layer: TaskLayer;
-    filesToTouch: string[];
-    acceptanceCriteria: string[];
-    dependencies: string[];
-    priority: TaskPriority;
-}
-declare class TaskGenerator {
-    private provider;
-    constructor(provider: AIProvider);
-    generateTasks(spec: string, context?: ProjectContext): Promise<SpecTask[]>;
-    saveTasks(tasks: SpecTask[], specFilePath: string): Promise<string>;
-    sortByLayer(tasks: SpecTask[]): SpecTask[];
-}
-declare function printTasks(tasks: SpecTask[]): void;
-declare function loadTasksForSpec(specFilePath: string): Promise<SpecTask[] | null>;
+/**
+ * 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).
+ */
+
+declare function generateSpecWithTasks(provider: AIProvider, idea: string, context?: ProjectContext): Promise<{
+    spec: string;
+    tasks: SpecTask[];
+}>;
 
 declare class GitWorktreeManager {
     private baseDir;
     constructor(baseDir: string);
     private isGitRepo;
     private sanitizeFeatureName;
+    /**
+     * Symlink dependency directories from the base repo into the worktree so that
+     * tools like `vite`, `tsc`, etc. are available without re-installing.
+     *
+     * Handles: node_modules (npm/yarn/pnpm), vendor (PHP Composer)
+     */
+    private linkDependencies;
     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, GeminiProvider, GitWorktreeManager, OpenAICompatibleProvider, PROVIDER_CATALOG, type ProjectContext, type ProviderMeta, SUPPORTED_PROVIDERS, SpecGenerator, SpecRefiner, type SpecTask, TaskGenerator, type TaskLayer, type TaskPriority, createProvider, loadConstitution, loadTasksForSpec, printConstitutionHint, printTasks };
+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, generateSpecWithTasks, isFrontendDeps, loadConstitution, loadTasksForSpec, printConstitutionHint, printTaskProgress, printTasks, updateTaskStatus };

package/dist/index.d.ts

@@ -1,5 +1,13 @@
 import OpenAI from 'openai';
 
+interface SharedConfigFile {
+    /** Relative path from project root */
+    path: string;
+    /** First 80 lines of the file */
+    preview: string;
+    /** Inferred category */
+    category: "i18n" | "constants" | "enums" | "config" | "route-index" | "store-index" | "other";
+}
 interface ProjectContext {
     techStack: string[];
     fileStructure: string[];
@@ -7,20 +15,55 @@ interface ProjectContext {
     apiStructure: string[];
     schema?: string;
     routeSummary?: string;
-    /** Contents of .ai-spec-constitution.md if present */
+    /**
+     * Effective constitution injected into prompts.
+     * If a global constitution was found it is merged in here (global first, project overrides).
+     */
     constitution?: string;
     /** Extracted error handling patterns from source */
     errorPatterns?: string;
+    /**
+     * Singleton/append-only config files that MUST be modified in-place,
+     * never recreated as a new parallel file (i18n, constants, enums, config indices, etc.)
+     */
+    sharedConfigFiles?: SharedConfigFile[];
 }
+/**
+ * Single source of truth for what counts as a "frontend" project.
+ * Import this constant (and isFrontendDeps) everywhere instead of
+ * repeating the inline array — one place to add Svelte, Solid, Qwik, etc.
+ */
+declare const FRONTEND_FRAMEWORKS: readonly ["react", "vue", "next", "nuxt", "react-native", "expo", "svelte", "solid-js", "qwik"];
+/**
+ * Returns true if any of the given dependency keys is a recognised frontend framework.
+ * Works on the raw key list from package.json / context.dependencies.
+ */
+declare function isFrontendDeps(deps: string[]): boolean;
 declare class ContextLoader {
     private projectRoot;
     constructor(projectRoot: string);
     loadProjectContext(): Promise<ProjectContext>;
+    /** Load PHP project context from composer.json */
+    private loadComposerJson;
+    /**
+     * Load PHP route files (routes/api.php, routes/web.php) as routeSummary.
+     * Lumen uses these files to register API endpoints.
+     */
+    private loadPhpRoutes;
+    /** Load Java project context from pom.xml or build.gradle */
+    private loadMavenOrGradle;
+    /** Scan Java controller files for API structure */
+    private loadJavaApiStructure;
     private loadPackageJson;
     private loadPrismaSchema;
     private loadFileStructure;
     private loadConstitution;
     private loadErrorPatterns;
+    /**
+     * Scan for "singleton" config files that should never be duplicated.
+     * These are append-only files: i18n bundles, constants, enums, config indices.
+     */
+    private loadSharedConfigFiles;
     private loadApiStructure;
 }
 
@@ -43,6 +86,17 @@ interface ProviderMeta {
      * Undefined means the provider has its own SDK (Gemini / Claude).
      */
     baseURL?: string;
+    /**
+     * Role to use for system instructions.
+     * OpenAI o1/o3 use "developer" instead of "system".
+     * Default: "system"
+     */
+    systemRole?: "system" | "developer";
+    /**
+     * Extra body params injected into every chat completion request.
+     * e.g. Qwen3 needs { enable_thinking: false } to suppress CoT noise.
+     */
+    extraBody?: Record<string, unknown>;
 }
 declare const PROVIDER_CATALOG: Record<string, ProviderMeta>;
 declare const SUPPORTED_PROVIDERS: string[];
@@ -66,7 +120,17 @@ declare class OpenAICompatibleProvider implements AIProvider {
     protected client: OpenAI;
     readonly providerName: string;
     readonly modelName: string;
-    constructor(providerName: string, apiKey: string, modelName: string, baseURL?: string);
+    private systemRole;
+    private extraBody?;
+    constructor(providerName: string, apiKey: string, modelName: string, baseURL?: string, systemRole?: "system" | "developer", extraBody?: Record<string, unknown>);
+    generate(prompt: string, systemInstruction?: string): Promise<string>;
+}
+declare class MiMoProvider implements AIProvider {
+    readonly providerName = "mimo";
+    readonly modelName: string;
+    private apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, modelName?: string);
     generate(prompt: string, systemInstruction?: string): Promise<string>;
 }
 declare function createProvider(providerName: string, apiKey: string, modelName?: string): AIProvider;
@@ -82,30 +146,88 @@ declare class SpecRefiner {
     refineLoop(initialSpec: string): Promise<string>;
 }
 
+declare function buildTaskPrompt(spec: string, context?: ProjectContext): string;
+type TaskLayer = "data" | "infra" | "service" | "api" | "test";
+type TaskPriority = "high" | "medium" | "low";
+type TaskStatus = "pending" | "done" | "failed";
+interface SpecTask {
+    id: string;
+    title: string;
+    description: string;
+    layer: TaskLayer;
+    filesToTouch: string[];
+    acceptanceCriteria: string[];
+    dependencies: string[];
+    priority: TaskPriority;
+    /** Runtime checkpoint — set by code generator, persisted to tasks file */
+    status?: TaskStatus;
+}
+declare class TaskGenerator {
+    private provider;
+    constructor(provider: AIProvider);
+    generateTasks(spec: string, context?: ProjectContext): Promise<SpecTask[]>;
+    saveTasks(tasks: SpecTask[], specFilePath: string): Promise<string>;
+    sortByLayer(tasks: SpecTask[]): SpecTask[];
+}
+declare function printTasks(tasks: SpecTask[]): void;
+declare function loadTasksForSpec(specFilePath: string): Promise<SpecTask[] | null>;
+/** Persist a single task's status to the tasks JSON file (checkpoint). */
+declare function updateTaskStatus(specFilePath: string, taskId: string, status: TaskStatus): Promise<void>;
+
 type CodeGenMode = "claude-code" | "api" | "plan";
 interface CodeGenOptions {
     /** Run claude non-interactively via -p flag (saves tokens, good for automation) */
     auto?: boolean;
+    /** Resume from last checkpoint — skip tasks already marked as done */
+    resume?: boolean;
+    /** Path to the DSL JSON file — if provided, structured context is injected into prompts */
+    dslFilePath?: string;
+    /** Repo language type — selects the appropriate codegen system prompt */
+    repoType?: string;
 }
 declare class CodeGenerator {
     private provider;
     private mode;
     constructor(provider: AIProvider, mode?: CodeGenMode);
-    generateCode(specFilePath: string, workingDir: string, context?: ProjectContext, options?: CodeGenOptions): Promise<void>;
+    /** Returns the list of file paths written to disk (useful for api-mode review). */
+    generateCode(specFilePath: string, workingDir: string, context?: ProjectContext, options?: CodeGenOptions): Promise<string[]>;
     private isClaudeCLIAvailable;
     private runClaudeCode;
+    /**
+     * Incremental claude-code execution: one `claude -p` call per task.
+     * Tasks marked as "done" are skipped (resume support).
+     * Progress is shown as a percentage bar.
+     */
+    private runClaudeCodeIncremental;
     private runApiMode;
     private runApiModeWithTasks;
     private generateFiles;
     private runPlanMode;
 }
+declare function printTaskProgress(completed: number, total: number, task: SpecTask, mode: "run" | "skip"): void;
 
 declare class CodeReviewer {
     private provider;
-    constructor(provider: AIProvider);
+    private projectRoot;
+    constructor(provider: AIProvider, projectRoot?: string);
     private getGitDiff;
     private getDiffStats;
-    reviewCode(specContent: string): Promise<string>;
+    /**
+     * Two-pass review:
+     *   Pass 1 — architecture (spec compliance, layer separation, auth)
+     *   Pass 2 — implementation details (validation, error handling, edge cases)
+     *             + historical issue recurrence check
+     *
+     * Falls back to single-pass if the two-pass flag is not set.
+     */
+    private runTwoPassReview;
+    reviewCode(specContent: string, specFile?: string): Promise<string>;
+    /**
+     * Review directly from generated file contents (for api mode where git diff is empty).
+     */
+    reviewFiles(specContent: string, filePaths: string[], workingDir: string, specFile?: string): Promise<string>;
+    /** Print score trend from history (last N reviews) */
+    printScoreTrend(limit?: number): Promise<void>;
 }
 
 declare const CONSTITUTION_FILE = ".ai-spec-constitution.md";
@@ -118,34 +240,32 @@ declare class ConstitutionGenerator {
 declare function loadConstitution(projectRoot: string): Promise<string | undefined>;
 declare function printConstitutionHint(exists: boolean): void;
 
-type TaskLayer = "data" | "infra" | "service" | "api" | "test";
-type TaskPriority = "high" | "medium" | "low";
-interface SpecTask {
-    id: string;
-    title: string;
-    description: string;
-    layer: TaskLayer;
-    filesToTouch: string[];
-    acceptanceCriteria: string[];
-    dependencies: string[];
-    priority: TaskPriority;
-}
-declare class TaskGenerator {
-    private provider;
-    constructor(provider: AIProvider);
-    generateTasks(spec: string, context?: ProjectContext): Promise<SpecTask[]>;
-    saveTasks(tasks: SpecTask[], specFilePath: string): Promise<string>;
-    sortByLayer(tasks: SpecTask[]): SpecTask[];
-}
-declare function printTasks(tasks: SpecTask[]): void;
-declare function loadTasksForSpec(specFilePath: string): Promise<SpecTask[] | null>;
+/**
+ * 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).
+ */
+
+declare function generateSpecWithTasks(provider: AIProvider, idea: string, context?: ProjectContext): Promise<{
+    spec: string;
+    tasks: SpecTask[];
+}>;
 
 declare class GitWorktreeManager {
     private baseDir;
     constructor(baseDir: string);
     private isGitRepo;
     private sanitizeFeatureName;
+    /**
+     * Symlink dependency directories from the base repo into the worktree so that
+     * tools like `vite`, `tsc`, etc. are available without re-installing.
+     *
+     * Handles: node_modules (npm/yarn/pnpm), vendor (PHP Composer)
+     */
+    private linkDependencies;
     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, GeminiProvider, GitWorktreeManager, OpenAICompatibleProvider, PROVIDER_CATALOG, type ProjectContext, type ProviderMeta, SUPPORTED_PROVIDERS, SpecGenerator, SpecRefiner, type SpecTask, TaskGenerator, type TaskLayer, type TaskPriority, createProvider, loadConstitution, loadTasksForSpec, printConstitutionHint, printTasks };
+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, generateSpecWithTasks, isFrontendDeps, loadConstitution, loadTasksForSpec, printConstitutionHint, printTaskProgress, printTasks, updateTaskStatus };