task-o-matic-core 0.1.0

package/src/types/options.ts

@@ -0,0 +1,165 @@
+import type { BTSConfig } from "./index";
+
+// Base interface for any command that can use AI
+export interface AIProviderOptions {
+  aiProvider?: string;
+  aiModel?: string;
+  aiKey?: string;
+  aiProviderUrl?: string;
+  aiReasoning?: string; // For OpenRouter
+}
+
+// For commands that can stream AI output
+export interface StreamingAIOptions extends AIProviderOptions {
+  stream?: boolean;
+}
+
+// tasks list
+export interface ListTasksOptions {
+  status?: string;
+  tag?: string;
+}
+
+// tasks create
+export interface CreateTaskOptions extends StreamingAIOptions {
+  title: string;
+  content?: string;
+  effort?: string;
+  parentId?: string;
+  aiEnhance?: boolean;
+  taskId?: string; // Internal use for pre-defining an ID
+}
+
+// tasks show
+export interface ShowTaskOptions {
+  id: string;
+}
+
+// tasks document
+export interface DocumentTaskOptions extends StreamingAIOptions {
+  taskId: string;
+  force?: boolean;
+}
+
+// tasks enhance
+export interface EnhanceTaskOptions extends StreamingAIOptions {
+  taskId: string;
+  all?: boolean; // Not passed to the function, handled in command
+}
+
+// tasks split
+export interface SplitTaskOptions extends StreamingAIOptions {
+  taskId: string;
+  all?: boolean; // Not passed to the function, handled in command
+  prompt?: string;
+  message?: string;
+}
+
+// tasks plan
+export interface PlanTaskOptions extends StreamingAIOptions {
+  id: string;
+}
+
+// tasks get-plan
+export interface GetPlanOptions {
+  id: string;
+}
+
+// tasks update
+export interface UpdateTaskOptions {
+  id: string;
+  title?: string;
+  description?: string;
+  status?: "todo" | "in-progress" | "completed";
+  effort?: "small" | "medium" | "large";
+  tags?: string; // Comes as a comma-separated string from the CLI
+}
+
+// tasks delete
+export interface DeleteTaskOptions {
+  id: string;
+  force?: boolean;
+  cascade?: boolean;
+}
+
+// tasks status
+export interface SetTaskStatusOptions {
+  id: string;
+  status: "todo" | "in-progress" | "completed";
+}
+
+// tasks add-tags / remove-tags
+export interface ManageTagsOptions {
+  id: string;
+  tags: string; // Comes as a comma-separated string from the CLI
+}
+
+// tasks delete-plan
+export interface DeletePlanOptions {
+  id: string;
+}
+
+// tasks subtasks
+export interface ListSubtasksOptions {
+  id: string;
+}
+
+// tasks tree
+export interface TaskTreeOptions {
+  id?: string;
+}
+
+// tasks get-next
+export interface GetNextTaskOptions {
+  status?: "todo" | "in-progress"; // Filter by status
+  tag?: string; // Filter by tag
+  effort?: "small" | "medium" | "large"; // Filter by effort
+  priority?: "newest" | "oldest" | "effort"; // Sort priority
+}
+
+// prd parse
+export interface ParsePrdOptions extends StreamingAIOptions {
+  file: string;
+  prompt?: string;
+  message?: string;
+}
+
+// prd rework
+export interface ReworkPrdOptions extends StreamingAIOptions {
+  file: string;
+  feedback: string;
+  output?: string;
+  prompt?: string;
+  message?: string;
+}
+
+// Workflow command types
+export type WorkflowStep =
+  | "initialize"
+  | "define-prd"
+  | "stack-suggestion"
+  | "bootstrap"
+  | "question-refine-prd"
+  | "refine-prd"
+  | "generate-tasks"
+  | "split-tasks"
+  | "complete";
+
+export interface AIAssistedChoice<T = any> {
+  userInput: string;
+  availableOptions: T[];
+  context: string;
+  recommendation?: T;
+}
+
+export interface InitConfigChoice {
+  projectName: string;
+  aiProvider: string;
+  aiModel: string;
+  aiProviderUrl?: string;
+  frontend?: string;
+  backend?: string;
+  database?: string;
+  auth?: boolean;
+  reasoning?: string;
+}

package/src/types/results.ts

@@ -0,0 +1,216 @@
+import {
+  Task,
+  TaskAIMetadata,
+  DocumentationDetection,
+  BTSConfig,
+} from "./index";
+
+/**
+ * Generic operation result using discriminated union pattern.
+ * Prevents invalid states like { success: true, error: "..." }
+ *
+ * Note: This type uses discriminated unions for operations that may return
+ * either success or failure. Most task operations throw exceptions on error
+ * instead of returning error results.
+ *
+ * @example
+ * ```typescript
+ * const result: OperationResult<Task> =
+ *   condition
+ *     ? { success: true, data: task }
+ *     : { success: false, error: "Task not found" };
+ *
+ * if (result.success) {
+ *   console.log(result.data.title); // ✓ TypeScript knows data exists
+ * } else {
+ *   console.error(result.error); // ✓ TypeScript knows error exists
+ * }
+ * ```
+ */
+export type OperationResult<T = any> =
+  | {
+      success: true;
+      data: T;
+      stats?: Record<string, any>;
+      metadata?: Record<string, any>;
+    }
+  | {
+      success: false;
+      error: string;
+      stats?: Record<string, any>;
+      metadata?: Record<string, any>;
+    };
+
+/**
+ * Result of task creation operation.
+ * Always returns success; throws exception on error.
+ */
+export interface CreateTaskResult {
+  success: true;
+  task: Task;
+  aiMetadata?: TaskAIMetadata;
+}
+
+/**
+ * Result of task enhancement operation.
+ * Always returns success; throws exception on error.
+ */
+export interface EnhanceTaskResult {
+  success: true;
+  task: Task;
+  enhancedContent: string;
+  stats: {
+    originalLength: number;
+    enhancedLength: number;
+    duration: number;
+    tokenUsage?: {
+      prompt: number;
+      completion: number;
+      total: number;
+    };
+    timeToFirstToken?: number; // ms
+    cost?: number; // USD
+  };
+  metadata: {
+    aiProvider: string;
+    aiModel: string;
+    confidence: number;
+  };
+}
+
+/**
+ * Result of task splitting operation.
+ * Always returns success; throws exception on error.
+ */
+export interface SplitTaskResult {
+  success: true;
+  task: Task;
+  subtasks: Task[];
+  stats: {
+    subtasksCreated: number;
+    duration: number;
+    tokenUsage?: {
+      prompt: number;
+      completion: number;
+      total: number;
+    };
+    timeToFirstToken?: number; // ms
+    cost?: number; // USD
+  };
+  metadata: {
+    aiProvider: string;
+    aiModel: string;
+    confidence?: number;
+  };
+}
+
+/**
+ * Result of task planning operation.
+ * Always returns success; throws exception on error.
+ */
+export interface PlanTaskResult {
+  success: true;
+  task: Task;
+  plan: string;
+  stats: {
+    duration: number;
+    tokenUsage?: {
+      prompt: number;
+      completion: number;
+      total: number;
+    };
+    timeToFirstToken?: number; // ms
+    cost?: number; // USD
+  };
+  metadata: {
+    aiProvider: string;
+    aiModel: string;
+  };
+}
+
+/**
+ * Result of task documentation operation.
+ * Always returns success; throws exception on error.
+ */
+export interface DocumentTaskResult {
+  success: true;
+  task: Task;
+  analysis?: DocumentationDetection;
+  documentation?: any;
+  stats: {
+    duration: number;
+  };
+}
+
+/**
+ * Result of task deletion operation.
+ * Always returns success; throws exception on error.
+ */
+export interface DeleteTaskResult {
+  success: true;
+  deleted: Task[];
+  orphanedSubtasks: Task[];
+}
+
+/**
+ * Result of PRD parsing operation.
+ * Always returns success; throws exception on error.
+ */
+export interface PRDParseResult {
+  success: true;
+  prd: {
+    overview: string;
+    objectives: string[];
+    features: string[];
+  };
+  tasks: Task[];
+  stats: {
+    tasksCreated: number;
+    duration: number;
+    aiProvider: string;
+    aiModel: string;
+    tokenUsage?: {
+      prompt: number;
+      completion: number;
+      total: number;
+    };
+    timeToFirstToken?: number; // ms
+    cost?: number; // USD
+  };
+  steps: {
+    step: string;
+    status: "completed" | "failed";
+    duration: number;
+    details?: any;
+  }[];
+}
+
+/**
+ * AI response wrapper for stack suggestion.
+ * Contains the config and reasoning explanation.
+ */
+export interface StackSuggestionResponse {
+  config: BTSConfig;
+  reasoning: string;
+}
+
+/**
+ * Result of stack suggestion operation.
+ * Always returns success; throws exception on error.
+ */
+export interface SuggestStackResult {
+  success: true;
+  stack: BTSConfig;
+  reasoning: string;
+  savedPath?: string;
+  stats: {
+    duration: number;
+    tokenUsage?: {
+      prompt: number;
+      completion: number;
+      total: number;
+    };
+    timeToFirstToken?: number;
+    cost?: number;
+  };
+}

package/src/types/workflow-options.ts

@@ -0,0 +1,113 @@
+import { StreamingAIOptions } from "./options";
+import type { BTSConfig } from "./index";
+
+/**
+ * Comprehensive options for workflow command automation.
+ * All options are optional - workflow remains fully interactive by default.
+ */
+export interface WorkflowAutomationOptions extends StreamingAIOptions {
+  // Global workflow control
+  skipAll?: boolean; // Skip all optional steps
+  autoAccept?: boolean; // Auto-accept all AI suggestions
+  configFile?: string; // Load options from JSON file
+
+  // Step 1: Initialize
+  skipInit?: boolean; // Skip initialization entirely
+  projectName?: string; // Pre-set project name
+  initMethod?: "quick" | "custom" | "ai"; // Initialization method
+  projectDescription?: string; // For AI-assisted init
+  useExistingConfig?: boolean; // Use existing config if found
+
+  // AI Configuration (inherited from StreamingAIOptions)
+  // aiProvider, aiModel, aiKey, aiProviderUrl, stream
+
+  // Stack Configuration
+  frontend?: string; // Frontend framework
+  backend?: string; // Backend framework
+  database?: string; // Database choice
+  auth?: boolean; // Include authentication
+  bootstrap?: boolean; // Bootstrap with Better-T-Stack
+  includeDocs?: boolean; // Include documentation in new project
+
+  // Step 2: Define PRD
+  skipPrd?: boolean; // Skip PRD definition
+  prdMethod?: "upload" | "manual" | "ai" | "skip"; // PRD creation method
+  prdFile?: string; // Path to existing PRD file
+  prdDescription?: string; // For AI-assisted PRD creation
+  prdContent?: string; // Direct PRD content (for automation)
+  prdMultiGeneration?: boolean; // Use multi-generation for PRD creation
+  skipPrdMultiGeneration?: boolean; // Skip PRD multi-generation
+  prdMultiGenerationModels?: string; // Comma-separated list of provider:model
+  prdCombine?: boolean; // Combine multiple PRDs into master
+  skipPrdCombine?: boolean; // Skip PRD combination
+  prdCombineModel?: string; // Model to use for combining (provider:model)
+
+  // Step 2.4: Stack Suggestion
+  skipStackSuggestion?: boolean; // Skip stack suggestion step
+  suggestStackFromPrd?: string | true; // PRD file path, or true = use current PRD
+
+  // Step 3: Bootstrap (moved after PRD and stack suggestion)
+  skipBootstrap?: boolean; // Skip bootstrap step
+
+  // Step 4: Refine PRD
+  skipRefine?: boolean; // Skip PRD refinement
+  refineMethod?: "manual" | "ai" | "skip"; // Refinement method
+  refineFeedback?: string; // Feedback for AI refinement
+
+  // Step 2.5: PRD Question/Refine (NEW)
+  skipPrdQuestionRefine?: boolean; // Skip PRD question/refine step
+  prdQuestionRefine?: boolean; // Use question-based PRD refinement
+  prdAnswerMode?: "user" | "ai"; // Who answers questions: user or AI
+  prdAnswerAiProvider?: string; // AI provider for answering (optional override)
+  prdAnswerAiModel?: string; // AI model for answering (optional override)
+  prdAnswerAiKey?: string; // AI API key for answering (optional override)
+  prdAnswerAiProviderUrl?: string; // AI provider URL for answering (optional override)
+  prdAnswerAiReasoning?: boolean; // Enable reasoning for AI answering model
+
+  // Step 4: Generate Tasks
+  skipGenerate?: boolean; // Skip task generation
+  generateMethod?: "standard" | "ai"; // Generation method
+  generateInstructions?: string; // Custom instructions for task generation
+
+  // Step 5: Split Tasks
+  skipSplit?: boolean; // Skip task splitting
+  splitTasks?: string; // Comma-separated task IDs to split
+  splitAll?: boolean; // Split all tasks
+  splitMethod?: "interactive" | "standard" | "custom"; // Split method
+  splitInstructions?: string; // Custom instructions for splitting
+
+  // Step 6: Execute Tasks
+  execute?: boolean; // Execute generated tasks immediately
+  executeTasks?: boolean; // Alias for execute
+  executeConcurrency?: number; // Number of concurrent tasks
+  autoCommit?: boolean; // Auto-commit changes during execution
+  executeTool?: string; // Executor tool (opencode, claude, etc.)
+  executeModel?: string; // Model override for execution
+  executeMaxRetries?: number; // Maximum retries per task
+  executePlan?: boolean; // Enable planning phase
+  executePlanModel?: string; // Model for planning
+  executeReview?: boolean; // Enable review phase
+  executeReviewModel?: string; // Model for review
+}
+
+export interface WorkflowState {
+  initialized: boolean;
+  currentStep:
+    | "initialize"
+    | "define-prd"
+    | "stack-suggestion"
+    | "bootstrap"
+    | "question-refine-prd"
+    | "refine-prd"
+    | "generate-tasks"
+    | "split-tasks"
+    | "execute-tasks"
+    | "complete";
+  projectName?: string;
+  projectDir?: string;
+  aiConfig?: any;
+  prdFile?: string;
+  prdContent?: string;
+  tasks?: Array<{ id: string; title: string; description?: string }>;
+  suggestedStack?: BTSConfig; // Accepted stack, used by bootstrap
+}

package/src/types/workflow-results.ts

@@ -0,0 +1,87 @@
+import { Task, AIConfig } from "./index";
+
+/**
+ * Result types for workflow service operations
+ */
+
+export interface InitializeResult {
+  success: boolean;
+  projectDir: string;
+  projectName: string;
+  aiConfig: {
+    provider: string;
+    model: string;
+    key: string;
+  };
+  stackConfig?: {
+    projectName: string;
+    aiProvider: string;
+    aiModel: string;
+    frontend?: string;
+    backend?: string;
+    database?: string;
+    auth?: boolean;
+    reasoning?: string;
+  };
+  bootstrapped: boolean;
+}
+
+export interface DefinePRDResult {
+  success: boolean;
+  prdFile: string;
+  prdContent: string;
+  method: "upload" | "manual" | "ai" | "skip";
+  stats?: {
+    duration: number;
+    tokenUsage?: {
+      prompt: number;
+      completion: number;
+      total: number;
+    };
+    timeToFirstToken?: number; // ms
+    cost?: number; // USD
+  };
+}
+
+export interface RefinePRDResult {
+  success: boolean;
+  prdFile: string;
+  prdContent: string;
+  questions?: string[];
+  answers?: Record<string, string>;
+  stats?: {
+    duration: number;
+    tokenUsage?: {
+      prompt: number;
+      completion: number;
+      total: number;
+    };
+    timeToFirstToken?: number; // ms
+    cost?: number; // USD
+  };
+}
+
+export interface GenerateTasksResult {
+  success: boolean;
+  tasks: Task[];
+  stats: {
+    tasksCreated: number;
+    duration: number;
+    tokenUsage?: {
+      prompt: number;
+      completion: number;
+      total: number;
+    };
+    timeToFirstToken?: number; // ms
+    cost?: number; // USD
+  };
+}
+
+export interface SplitTasksResult {
+  success: boolean;
+  results: Array<{
+    taskId: string;
+    subtasks: Task[];
+    error?: string;
+  }>;
+}

package/src/utils/ai-config-builder.ts

@@ -0,0 +1,33 @@
+import { AIConfig } from "../types";
+
+export interface AIOptions {
+  aiProvider?: string;
+  aiModel?: string;
+  aiKey?: string;
+  aiProviderUrl?: string;
+  aiReasoning?: string;
+}
+
+/**
+ * Builds an AI configuration object from CLI options
+ * This eliminates the duplication of this pattern across 10+ files
+ */
+export function buildAIConfig(options?: AIOptions): Partial<AIConfig> {
+  if (!options) return {};
+
+  return {
+    ...(options.aiProvider && {
+      provider: options.aiProvider as
+        | "openrouter"
+        | "openai"
+        | "anthropic"
+        | "custom",
+    }),
+    ...(options.aiModel && { model: options.aiModel }),
+    ...(options.aiKey && { apiKey: options.aiKey }),
+    ...(options.aiProviderUrl && { baseURL: options.aiProviderUrl }),
+    ...(options.aiReasoning && {
+      reasoning: { maxTokens: parseInt(options.aiReasoning, 10) },
+    }),
+  };
+}