@wrongstack/core 0.4.0 → 0.5.0

package/dist/sdd/index.d.ts

@@ -1,7 +1,7 @@
-import { h as Specification, S as SpecAnalysis, g as SpecValidationResult, l as TaskGraph, m as TaskNode, k as TaskFilter, p as TaskSort, o as TaskProgress, r as TaskType, n as TaskPriority } from '../task-graph-BITvWt4t.js';
-import { E as EventBus } from '../events-BBaKeMfb.js';
-import { D as DoneCondition } from '../multi-agent-D5m66hzB.js';
-import '../context-B1kBj1lY.js';
+import { h as Specification, S as SpecAnalysis, g as SpecValidationResult, l as TaskGraph, m as TaskNode, k as TaskFilter, p as TaskSort, o as TaskProgress, r as TaskType, n as TaskPriority, e as SpecStatus, f as SpecTemplate, b as SpecRequirement } from '../task-graph-BITvWt4t.js';
+import { E as EventBus } from '../events-DYAbU84e.js';
+import { D as DoneCondition } from '../multi-agent-B1Nn9eC0.js';
+import '../context-P207fTpo.js';
 
 declare class SpecParser {
     parse(content: string): Specification;
@@ -203,4 +203,418 @@ declare class SpecDrivenDev {
     }[];
 }
 
-export { DefaultTaskStore, type GeneratedTask, SpecDrivenDev, type SpecDrivenDevOptions, SpecParser, TaskFlow, type TaskFlowEventMap, type TaskFlowEventName, type TaskFlowExecutionContext, type TaskFlowOptions, type TaskFlowPhase, TaskGenerator, type TaskGeneratorOptions, type TaskStore, TaskTracker, type TaskTrackerOptions, type TaskTransition };
+interface SpecStoreOptions {
+    /** Directory where spec files are stored. Defaults to `.wrongstack/specs`. */
+    baseDir: string;
+}
+interface SpecIndexEntry {
+    id: string;
+    title: string;
+    version: string;
+    status: SpecStatus;
+    updatedAt: number;
+    filePath: string;
+}
+/**
+ * File-backed spec storage. Each spec is a JSON file under `baseDir/`.
+ * An index file (`_index.json`) tracks all specs for fast listing.
+ */
+declare class SpecStore {
+    private readonly baseDir;
+    private readonly indexPath;
+    constructor(opts: SpecStoreOptions);
+    save(spec: Specification): Promise<void>;
+    load(id: string): Promise<Specification | null>;
+    list(): Promise<SpecIndexEntry[]>;
+    delete(id: string): Promise<boolean>;
+    exists(id: string): Promise<boolean>;
+    /** Create a new spec with defaults, assign ID, and persist. */
+    createDraft(title: string, overview?: string): Promise<Specification>;
+    /** Update spec fields and persist. */
+    update(id: string, patch: Partial<Omit<Specification, 'id' | 'createdAt'>>): Promise<Specification | null>;
+    private filePath;
+    private readIndex;
+    private updateIndex;
+    private removeFromIndex;
+}
+
+interface TaskGraphStoreOptions {
+    /** Directory where task graph files are stored. Defaults to `.wrongstack/task-graphs`. */
+    baseDir: string;
+}
+interface TaskGraphIndexEntry {
+    id: string;
+    specId: string;
+    title: string;
+    nodeCount: number;
+    completedCount: number;
+    updatedAt: number;
+    filePath: string;
+}
+/**
+ * File-backed task graph storage. Each graph is a JSON file under `baseDir/`.
+ * An index file (`_index.json`) tracks all graphs for fast listing.
+ */
+declare class TaskGraphStore {
+    private readonly baseDir;
+    private readonly indexPath;
+    constructor(opts: TaskGraphStoreOptions);
+    save(graph: TaskGraph): Promise<void>;
+    load(id: string): Promise<TaskGraph | null>;
+    list(): Promise<TaskGraphIndexEntry[]>;
+    delete(id: string): Promise<boolean>;
+    exists(id: string): Promise<boolean>;
+    private filePath;
+    private readIndex;
+    private updateIndex;
+    private removeFromIndex;
+}
+
+type AISpecPhase = 'questioning' | 'spec_review' | 'implementation' | 'task_review' | 'executing' | 'done';
+interface CollectedAnswer {
+    question: string;
+    answer: string;
+    timestamp: number;
+}
+interface AISpecSession {
+    id: string;
+    phase: AISpecPhase;
+    title: string;
+    userIntent: string;
+    projectContext: string;
+    answers: CollectedAnswer[];
+    questionCount: number;
+    spec?: Specification;
+    implementation?: string;
+    taskGraphId?: string;
+    approved: boolean;
+    createdAt: number;
+    updatedAt: number;
+}
+interface AISpecBuilderOptions {
+    store: SpecStore;
+    /** Minimum questions the AI should ask. Default: 2 */
+    minQuestions?: number;
+    /** Maximum questions before forcing spec generation. Default: 10 */
+    maxQuestions?: number;
+    /** Project context string (package.json, file structure, etc.) */
+    projectContext?: string;
+    /** Path to persist session state. If set, session survives process restarts. */
+    sessionPath?: string;
+}
+/**
+ * AI-driven specification builder. Instead of static questions, this builder
+ * tracks conversation state and generates prompts that instruct the AI agent
+ * to ask contextual questions and build specifications interactively.
+ */
+declare class AISpecBuilder {
+    private session;
+    private readonly store;
+    private readonly minQuestions;
+    private readonly maxQuestions;
+    private readonly sessionPath?;
+    constructor(opts: AISpecBuilderOptions);
+    /** Save session state to disk. */
+    saveSession(): Promise<void>;
+    /** Load session state from disk. Returns true if a session was loaded. */
+    loadSession(): Promise<boolean>;
+    /** Delete saved session from disk. */
+    deleteSession(): Promise<void>;
+    /** Auto-save helper — calls saveSession() but never throws. */
+    private autoSave;
+    /** Start a new session with a title and optional intent. */
+    startSession(title: string, intent?: string): void;
+    /** Get current session state (readonly). */
+    getSession(): Readonly<AISpecSession>;
+    /** Get the current phase. */
+    getPhase(): AISpecPhase;
+    /**
+     * Get the AI prompt for the current phase.
+     * This prompt is injected into the conversation so the AI agent knows
+     * what to do next (ask a question, generate a spec, etc.).
+     */
+    getAIPrompt(): string;
+    /**
+     * Record a question/answer pair from the AI conversation.
+     * Call this when the AI asks a question and the user responds.
+     */
+    addAnswer(question: string, answer: string): void;
+    /**
+     * Check if more questions should be asked.
+     * Returns false if max reached or if the AI has signaled it has enough info.
+     */
+    shouldContinueQuestioning(): boolean;
+    /**
+     * Check if minimum questions have been asked.
+     */
+    hasMetMinimumQuestions(): boolean;
+    /**
+     * Set the generated specification and move to spec_review phase.
+     */
+    setSpec(spec: Specification): void;
+    /**
+     * Approve the current phase and advance to the next.
+     * questioning → spec_review (requires spec to be set)
+     * spec_review → implementation
+     * implementation → task_review (requires implementation to be set)
+     * task_review → executing
+     * executing → done
+     */
+    approve(): AISpecPhase;
+    /**
+     * Set the implementation plan text.
+     */
+    setImplementation(plan: string): void;
+    /**
+     * Mark session as done.
+     */
+    markDone(): void;
+    /**
+     * Set the task graph ID for this session.
+     */
+    setTaskGraphId(graphId: string): void;
+    /**
+     * Get the task graph ID for this session.
+     */
+    getTaskGraphId(): string | undefined;
+    /**
+     * Save the current spec to the store.
+     */
+    saveSpec(): Promise<Specification>;
+    /**
+     * Parse a spec from a JSON string (from AI output).
+     * Validates and normalizes the structure.
+     */
+    parseSpecFromJSON(jsonStr: string): Specification;
+    /**
+     * Extract JSON from AI output (handles ```json blocks and raw JSON).
+     */
+    extractJSON(text: string): string | null;
+    /**
+     * Detect if AI output contains a spec (JSON block).
+     */
+    hasSpecInOutput(text: string): boolean;
+    /**
+     * Try to parse a spec from AI output text.
+     * Returns null if no valid spec found.
+     */
+    tryParseSpecFromOutput(text: string): Specification | null;
+    /**
+     * Extract a JSON array from AI output (for task lists).
+     */
+    extractJSONArray(text: string): string | null;
+}
+
+/**
+ * Built-in spec templates for common development scenarios.
+ */
+declare const SPEC_TEMPLATES: SpecTemplate[];
+/**
+ * Get a template by ID.
+ */
+declare function getTemplate(id: string): SpecTemplate | undefined;
+/**
+ * List all available templates.
+ */
+declare function listTemplates(): Array<{
+    id: string;
+    name: string;
+    description: string;
+}>;
+/**
+ * Generate a markdown skeleton from a template.
+ */
+declare function templateToMarkdown(template: SpecTemplate, title?: string): string;
+
+/**
+ * Render a task graph as ASCII art for terminal display.
+ */
+declare function renderTaskGraph(graph: TaskGraph, opts?: {
+    compact?: boolean;
+}): string;
+/**
+ * Render a progress bar.
+ */
+declare function renderProgress(progress: TaskProgress): string;
+/**
+ * Render a compact task list (for quick status checks).
+ */
+declare function renderTaskList(graph: TaskGraph): string;
+/**
+ * Render spec analysis summary.
+ */
+declare function renderSpecAnalysis(spec: Specification, analysis: {
+    completeness: number;
+    gaps: string[];
+    risks: string[];
+    suggestions: string[];
+}): string;
+
+/**
+ * Enhanced critical path analysis with bottleneck detection,
+ * parallel execution groups, and time estimation.
+ */
+interface CriticalPathAnalysis {
+    /** Ordered list of critical path task IDs. */
+    criticalPath: string[];
+    /** Total estimated hours for the critical path. */
+    totalHours: number;
+    /** Tasks that block the most downstream work. */
+    bottlenecks: BottleneckTask[];
+    /** Groups of tasks that can run in parallel. */
+    parallelGroups: string[][];
+    /** Recommended execution order respecting dependencies. */
+    executionOrder: string[];
+    /** Tasks with no blockers (can start immediately). */
+    readyTasks: string[];
+    /** Tasks that are blocked and cannot start. */
+    blockedTasks: string[];
+}
+interface BottleneckTask {
+    taskId: string;
+    title: string;
+    /** Number of tasks directly or transitively blocked by this task. */
+    blockedCount: number;
+    /** Total estimated hours of blocked downstream work. */
+    blockedHours: number;
+    /** Severity score (0-100). */
+    severity: number;
+}
+/**
+ * Analyze a task graph and return critical path analysis.
+ */
+declare function analyzeCriticalPath(graph: TaskGraph): CriticalPathAnalysis;
+
+interface SpecVersion {
+    version: string;
+    spec: Specification;
+    timestamp: number;
+    changeDescription?: string;
+}
+interface SpecDiff {
+    added: SpecRequirement[];
+    removed: SpecRequirement[];
+    modified: Array<{
+        requirement: SpecRequirement;
+        previousVersion: SpecRequirement;
+        changes: string[];
+    }>;
+    summary: string;
+}
+/**
+ * Track spec versions and compute diffs between versions.
+ */
+declare class SpecVersioning {
+    private versions;
+    /** Record a new version of a spec. */
+    recordVersion(spec: Specification, changeDescription?: string): SpecVersion;
+    /** Get version history for a spec. */
+    getHistory(specId: string): SpecVersion[];
+    /** Get a specific version of a spec. */
+    getVersion(specId: string, version: string): SpecVersion | undefined;
+    /** Get the latest version of a spec. */
+    getLatest(specId: string): SpecVersion | undefined;
+    /** Compute diff between two versions of a spec. */
+    diff(oldSpec: Specification, newSpec: Specification): SpecDiff;
+    /**
+     * Update a task graph incrementally based on spec changes.
+     * - Added requirements → new tasks
+     * - Removed requirements → remove tasks
+     * - Modified requirements → update task descriptions
+     * Returns the updated graph and list of changes made.
+     */
+    updateTaskGraph(graph: TaskGraph, oldSpec: Specification, newSpec: Specification): {
+        graph: TaskGraph;
+        changes: string[];
+    };
+    private compareRequirements;
+    private buildTaskDescription;
+    private mapReqType;
+}
+
+interface AutoExecutorOptions {
+    tracker: TaskTracker;
+    events: EventBus;
+    /** Maximum concurrent tasks. Defaults to 1 (sequential). */
+    maxConcurrent?: number;
+    /** Maximum retry attempts for failed tasks. */
+    maxRetries?: number;
+    /** Custom task executor function. */
+    executeTask: (task: TaskNode, context: TaskExecutionContext) => Promise<TaskExecutionResult>;
+    /** Called before each task starts. */
+    onTaskStart?: (task: TaskNode) => void;
+    /** Called after each task completes. */
+    onTaskComplete?: (task: TaskNode, result: TaskExecutionResult) => void;
+    /** Called when a task fails. */
+    onTaskFail?: (task: TaskNode, error: Error, retryCount: number) => void;
+    /** Called when all tasks are done or no more can execute. */
+    onDone?: (summary: ExecutionSummary) => void;
+}
+interface TaskExecutionContext {
+    /** The spec being implemented. */
+    spec: Specification;
+    /** The full task graph. */
+    graph: TaskGraph;
+    /** The current task being executed. */
+    task: TaskNode;
+    /** Tasks that this task depends on. */
+    dependencies: TaskNode[];
+    /** Tasks that depend on this task. */
+    dependents: TaskNode[];
+    /** Retry count for this task (0 = first attempt). */
+    retryCount: number;
+}
+interface TaskExecutionResult {
+    success: boolean;
+    output?: string;
+    error?: string;
+    /** If true, the task will be retried. */
+    retry?: boolean;
+}
+interface ExecutionSummary {
+    total: number;
+    completed: number;
+    failed: number;
+    skipped: number;
+    retried: number;
+    duration: number;
+    criticalPath: string[];
+}
+/**
+ * Auto-executor that drives task execution with dependency resolution,
+ * retry logic, and critical path awareness.
+ */
+declare class AutoExecutor {
+    private readonly opts;
+    private stopped;
+    private retryMap;
+    constructor(opts: AutoExecutorOptions);
+    /**
+     * Execute all tasks in the graph, respecting dependencies.
+     */
+    execute(graph: TaskGraph, spec: Specification): Promise<ExecutionSummary>;
+    /** Stop execution. */
+    stop(): void;
+    /** Get tasks that are ready to execute (all dependencies completed). */
+    private getReadyTasks;
+    /** Execute a single task with retry logic. */
+    private executeTaskWithRetry;
+    /** Get tasks that this task depends on. */
+    private getTaskDependencies;
+    /** Get tasks that depend on this task. */
+    private getTaskDependents;
+    /** Detect deadlock: all remaining tasks are blocked by failed tasks. */
+    private detectDeadlock;
+}
+/**
+ * Create an auto-executor that works with TaskFlow.
+ */
+declare function createAutoExecutor(opts: {
+    tracker: TaskTracker;
+    events: EventBus;
+    executeTask: AutoExecutorOptions['executeTask'];
+    maxConcurrent?: number;
+    maxRetries?: number;
+}): AutoExecutor;
+
+export { AISpecBuilder, type AISpecBuilderOptions, type AISpecPhase, type AISpecSession, AutoExecutor, type AutoExecutorOptions, type BottleneckTask, type CollectedAnswer, type CriticalPathAnalysis, DefaultTaskStore, type ExecutionSummary, type GeneratedTask, SPEC_TEMPLATES, type SpecDiff, SpecDrivenDev, type SpecDrivenDevOptions, type SpecIndexEntry, SpecParser, SpecStore, type SpecStoreOptions, type SpecVersion, SpecVersioning, type TaskExecutionContext, type TaskExecutionResult, TaskFlow, type TaskFlowEventMap, type TaskFlowEventName, type TaskFlowExecutionContext, type TaskFlowOptions, type TaskFlowPhase, TaskGenerator, type TaskGeneratorOptions, type TaskGraphIndexEntry, TaskGraphStore, type TaskGraphStoreOptions, type TaskStore, TaskTracker, type TaskTrackerOptions, type TaskTransition, analyzeCriticalPath, createAutoExecutor, getTemplate, listTemplates, renderProgress, renderSpecAnalysis, renderTaskGraph, renderTaskList, templateToMarkdown };