task-o-matic-core 0.1.0

package/src/lib/context-builder.ts

@@ -0,0 +1,383 @@
+import { join } from "path";
+import { Task, TaskContext, BTSConfig, TaskDocumentation } from "../types";
+import { TaskRepository } from "./storage/types";
+import { configManager } from "./config";
+import { readFileSync, existsSync, readdirSync, statSync } from "fs";
+import { logger } from "./logger";
+
+export interface FileStats {
+  mtime: number;
+  isDirectory: boolean;
+}
+
+export interface ContextCallbacks {
+  readFile: (path: string) => Promise<string | null>;
+  fileExists: (path: string) => Promise<boolean>;
+  listFiles: (dir: string) => Promise<string[]>;
+  stat: (path: string) => Promise<FileStats | null>;
+}
+
+export function createDefaultContextCallbacks(): ContextCallbacks {
+  return {
+    readFile: async (path: string) => {
+      if (existsSync(path)) {
+        return readFileSync(path, "utf-8");
+      }
+      return null;
+    },
+    fileExists: async (path: string) => {
+      return existsSync(path);
+    },
+    listFiles: async (dir: string) => {
+      if (existsSync(dir) && statSync(dir).isDirectory()) {
+        return readdirSync(dir);
+      }
+      return [];
+    },
+    stat: async (path: string) => {
+      if (existsSync(path)) {
+        const stats = statSync(path);
+        return {
+          mtime: stats.mtime.getTime(),
+          isDirectory: stats.isDirectory(),
+        };
+      }
+      return null;
+    },
+  };
+}
+
+export class ContextBuilder {
+  private storage: TaskRepository;
+  private callbacks: ContextCallbacks;
+  private taskOMatic: string | null = null;
+  private initialized = false;
+
+  constructor(storage: TaskRepository, callbacks?: ContextCallbacks) {
+    this.storage = storage;
+    this.callbacks = callbacks || createDefaultContextCallbacks();
+  }
+
+  private ensureInitialized(): void {
+    if (this.initialized) {
+      return;
+    }
+
+    this.taskOMatic = configManager.getTaskOMaticDir();
+    this.initialized = true;
+  }
+
+  /**
+   * Build comprehensive context for AI operations
+   */
+  async buildContext(taskId: string): Promise<TaskContext> {
+    this.ensureInitialized();
+
+    const task = await this.storage.getTask(taskId);
+    if (!task) {
+      throw new Error(`Task with ID ${taskId} not found`);
+    }
+
+    const stack = await this.getStackConfig();
+    const documentation = this.getTaskDocumentation(task);
+    const fullContent = await this.getTaskFullContent(task);
+    const prdContent = task.prdFile
+      ? await this.getPRDContent(task.prdFile)
+      : await this.getRelevantPRDContent(task.title, task.description);
+
+    return {
+      task: {
+        id: task.id,
+        title: task.title,
+        description: task.description ?? "",
+        fullContent,
+      },
+      stack,
+      documentation: documentation
+        ? {
+            recap: documentation.recap,
+            files: documentation.files.map((file) => ({
+              path: file,
+              // Content loading is skipped as per original code comment
+            })),
+          }
+        : undefined,
+      existingContent: documentation?.recap,
+      prdContent,
+      existingResearch: documentation?.research || {},
+    };
+  }
+
+  /**
+   * Build context for new tasks (without requiring existing task)
+   */
+  async buildContextForNewTask(
+    title: string,
+    description?: string,
+    prdFile?: string
+  ): Promise<TaskContext> {
+    this.ensureInitialized();
+
+    const stack = await this.getStackConfig();
+    const prdContent = prdFile
+      ? await this.getPRDContent(prdFile)
+      : await this.getRelevantPRDContent(title, description);
+
+    return {
+      task: {
+        id: "new-task",
+        title,
+        description: description ?? "",
+        fullContent: undefined,
+      },
+      stack,
+      documentation: undefined, // New tasks don't have documentation yet
+      existingContent: undefined,
+      prdContent,
+    };
+  }
+
+  /**
+   * Get stack configuration from project (set by bootstrap)
+   */
+  private async getStackConfig(): Promise<BTSConfig | undefined> {
+    if (!this.taskOMatic) {
+      return undefined;
+    }
+
+    // Return sensible defaults for Better-T-Stack
+    const fallbackConfig: BTSConfig = {
+      projectName: "default",
+      frontend: "next",
+      backend: "convex",
+      database: "none", // Convex has its own database
+      auth: "better-auth",
+      runtime: "none",
+      api: "none",
+      payments: "none",
+      orm: "none", // Convex doesn't use ORM
+      dbSetup: "none",
+      packageManager: "npm",
+      git: true,
+      webDeploy: "none",
+      serverDeploy: "none",
+      install: true,
+      addons: ["turborepo"],
+      examples: [],
+    };
+    try {
+      const stackFile = join(this.taskOMatic, "stack.json");
+      const content = await this.callbacks.readFile(stackFile);
+
+      if (content) {
+        const config = JSON.parse(content) as BTSConfig;
+        config._source = "file"; // Track source
+        return config;
+      }
+      fallbackConfig._source = "fallback"; // Track source
+      return fallbackConfig;
+    } catch (error) {
+      logger.warn(
+        `Failed to load stack configuration, using defaults: ${error}`
+      );
+      fallbackConfig._source = "fallback"; // Track source
+      return fallbackConfig;
+    }
+  }
+
+  /**
+   * Get task documentation references
+   */
+  private getTaskDocumentation(task: Task): TaskDocumentation | undefined {
+    return task.documentation;
+  }
+
+  /**
+   * Get full task content from MD file
+   */
+  private async getTaskFullContent(task: Task): Promise<string | undefined> {
+    if (!task.contentFile || !this.taskOMatic) {
+      return undefined;
+    }
+
+    try {
+      const contentPath = join(this.taskOMatic, task.contentFile);
+      return (await this.callbacks.readFile(contentPath)) || undefined;
+    } catch (error) {
+      logger.warn(
+        `Failed to read task content file ${task.contentFile}: ${error}`
+      );
+    }
+    return undefined;
+  }
+
+  /**
+   * Read documentation file content
+   */
+  private async readDocumentationFile(filePath: string): Promise<string> {
+    if (!this.taskOMatic) {
+      return `# ContextBuilder Not Initialized\n\nFile: ${filePath}\n\nContextBuilder has not been properly initialized.`;
+    }
+
+    try {
+      const fullPath = join(this.taskOMatic, filePath);
+      const content = await this.callbacks.readFile(fullPath);
+      if (content) {
+        return content;
+      }
+      return `# Documentation File Not Found\n\nFile: ${filePath}\n\nThis documentation file could not be found on disk.`;
+    } catch (error) {
+      return `# Error Reading Documentation\n\nFile: ${filePath}\n\nError: ${
+        error instanceof Error ? error.message : "Unknown error"
+      }`;
+    }
+  }
+
+  /**
+   * Check if documentation is fresh (less than 7 days old)
+   */
+  isDocumentationFresh(documentation: TaskDocumentation): boolean {
+    const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
+    return documentation.lastFetched > sevenDaysAgo;
+  }
+
+  /**
+   * Check if documentation is stale (more than 30 days old)
+   */
+  isDocumentationStale(documentation: TaskDocumentation): boolean {
+    const thirtyDaysAgo = Date.now() - 30 * 24 * 60 * 60 * 1000;
+    return documentation.lastFetched < thirtyDaysAgo;
+  }
+
+  /**
+   * Get PRD content from file path
+   */
+  private async getPRDContent(prdFile: string): Promise<string | undefined> {
+    if (!this.taskOMatic) {
+      return undefined;
+    }
+
+    try {
+      // Handle relative paths from .task-o-matic directory
+      const fullPath = prdFile.startsWith("/")
+        ? prdFile
+        : join(this.taskOMatic, prdFile);
+
+      return (await this.callbacks.readFile(fullPath)) || undefined;
+    } catch (error) {
+      logger.warn(`Failed to read PRD file ${prdFile}: ${error}`);
+      return undefined;
+    }
+  }
+
+  /**
+   * Get relevant PRD content based on task title/description
+   */
+  private async getRelevantPRDContent(
+    taskTitle?: string,
+    taskDescription?: string
+  ): Promise<string | undefined> {
+    if (!this.taskOMatic) return undefined;
+
+    // Look for PRD files in known locations
+    const prdPaths = [
+      join(this.taskOMatic, "prd"),
+      join(this.taskOMatic, "..", "docs"),
+      join(configManager.getWorkingDirectory(), ".task-o-matic", "prd"),
+      join(configManager.getWorkingDirectory(), "prd"),
+      join(configManager.getWorkingDirectory(), "docs"),
+    ];
+
+    for (const prdPath of prdPaths) {
+      if (await this.callbacks.fileExists(prdPath)) {
+        try {
+          // Look for ANY text files in PRD directory
+          const files = await this.callbacks.listFiles(prdPath);
+          const prdFiles = files.filter(
+            (f) => f.endsWith(".md") || f.endsWith(".txt")
+          );
+
+          if (prdFiles.length > 0) {
+            // Get the MOST RECENT PRD file by modification time
+            const prdFilesWithStats = await Promise.all(
+              prdFiles.map(async (file) => {
+                const path = join(prdPath, file);
+                const stats = await this.callbacks.stat(path);
+                return {
+                  file,
+                  path,
+                  mtime: stats ? stats.mtime : 0,
+                };
+              })
+            );
+
+            prdFilesWithStats.sort((a, b) => b.mtime - a.mtime); // Sort by newest first
+            const mostRecentPrd = prdFilesWithStats[0];
+            return (
+              (await this.callbacks.readFile(mostRecentPrd.path)) || undefined
+            );
+          }
+        } catch (error) {
+          logger.warn(`Failed to read PRD directory ${prdPath}: ${error}`);
+        }
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Format context for AI prompts
+   */
+  formatContextForAI(context: TaskContext): string {
+    let formatted = `# Task Context\n\n`;
+
+    formatted += `## Task Information\n`;
+    formatted += `- **ID**: ${context.task.id}\n`;
+    formatted += `- **Title**: ${context.task.title}\n`;
+    formatted += `- **Description**: ${context.task.description}\n`;
+
+    if (context.task.fullContent) {
+      formatted += `- **Full Content**:\n${context.task.fullContent}\n\n`;
+    }
+
+    if (context.prdContent) {
+      formatted += `## Product Requirements Document\n`;
+      formatted += `${context.prdContent}\n\n`;
+    }
+
+    if (context.stack) {
+      formatted += `## Technology Stack\n`;
+      formatted += `- **Project**: ${context.stack.projectName}\n`;
+      formatted += `- **Frontend**: ${context.stack.frontend}\n`;
+      formatted += `- **Backend**: ${context.stack.backend}\n`;
+      if (context.stack.database !== "none") {
+        formatted += `- **Database**: ${context.stack.database}\n`;
+      }
+      if (context.stack.orm !== "none") {
+        formatted += `- **ORM**: ${context.stack.orm}\n`;
+      }
+      formatted += `- **Auth**: ${context.stack.auth}\n`;
+      if (context.stack.addons.length > 0) {
+        formatted += `- **Addons**: ${context.stack.addons.join(", ")}\n`;
+      }
+      formatted += `- **Package Manager**: ${context.stack.packageManager}\n`;
+      formatted += `\n`;
+    }
+
+    if (context.documentation) {
+      formatted += `## Available Documentation\n`;
+      formatted += `**Recap**: ${context.documentation.recap}\n\n`;
+
+      if (context.documentation.files.length > 0) {
+        formatted += `### Documentation Files\n\n`;
+        context.documentation.files.forEach((file, index) => {
+          formatted += `#### ${index + 1}. ${file.path}\n`;
+          // formatted += `${file.content}\n\n`;
+        });
+      }
+    }
+
+    return formatted;
+  }
+}

package/src/lib/executors/claude-code-executor.ts

@@ -0,0 +1,83 @@
+import { spawn } from "node:child_process";
+
+import type { ExecutorConfig, ExternalExecutor } from "../../types";
+import { logger } from "../logger";
+
+export class ClaudeCodeExecutor implements ExternalExecutor {
+  name = "claude";
+  private config?: ExecutorConfig;
+
+  constructor(config?: ExecutorConfig) {
+    this.config = config;
+  }
+
+  supportsSessionResumption(): boolean {
+    return true;
+  }
+
+  async execute(
+    message: string,
+    dry: boolean = false,
+    config?: ExecutorConfig
+  ): Promise<void> {
+    // Merge constructor config with execution config (execution takes precedence)
+    const finalConfig = { ...this.config, ...config };
+
+    // Build arguments array
+    const args: string[] = [];
+
+    // Add model if specified
+    if (finalConfig.model) {
+      args.push("--model", finalConfig.model);
+      logger.progress(`🤖 Using model: ${finalConfig.model}`);
+    }
+
+    // Add session resumption if specified
+    if (finalConfig.continueLastSession) {
+      args.push("-c");
+      logger.progress("🔄 Continuing last session");
+    } else if (finalConfig.sessionId) {
+      args.push("-r", finalConfig.sessionId);
+      logger.progress(`🔄 Resuming session: ${finalConfig.sessionId}`);
+    }
+
+    // Add --print for non-interactive mode (required for automation)
+    // args.push("-p");
+
+    // Auto-approve file edits for automation
+    args.push("--permission-mode", "acceptEdits");
+
+    // Add prompt as positional argument
+    args.push(message);
+
+    if (dry) {
+      logger.progress(`🔧 Using executor: ${this.name}`);
+      logger.progress(`claude ${args.join(" ")}`);
+      return;
+    }
+
+    // Launch claude and wait for it to complete
+    const child = spawn("claude", args, {
+      stdio: "inherit", // Give tool full terminal control
+    });
+
+    // Wait for completion (blocking)
+    await new Promise<void>((resolve, reject) => {
+      child.on("close", (code: number) => {
+        if (code === 0) {
+          logger.success("✅ Claude Code execution completed successfully");
+          resolve();
+        } else {
+          const error = new Error(`Claude Code exited with code ${code}`);
+          logger.error(`❌ ${error.message}`);
+          reject(error);
+        }
+      });
+
+      child.on("error", (error: Error) => {
+        logger.error(`❌ Failed to launch Claude Code: ${error.message}`);
+        reject(error);
+      });
+    });
+  }
+}

package/src/lib/executors/codex-executor.ts

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+
+import type { ExecutorConfig, ExternalExecutor } from "../../types";
+import { logger } from "../logger";
+
+export class CodexExecutor implements ExternalExecutor {
+  name = "codex";
+  private config?: ExecutorConfig;
+
+  constructor(config?: ExecutorConfig) {
+    this.config = config;
+  }
+
+  supportsSessionResumption(): boolean {
+    return true;
+  }
+
+  async execute(
+    message: string,
+    dry: boolean = false,
+    config?: ExecutorConfig
+  ): Promise<void> {
+    // Merge constructor config with execution config (execution takes precedence)
+    const finalConfig = { ...this.config, ...config };
+
+    // Build arguments array - structure depends on session resumption
+    const args: string[] = [];
+
+    // Add model via config if specified (codex uses -c for config overrides)
+    if (finalConfig.model) {
+      args.push("-c", `model="${finalConfig.model}"`);
+      logger.progress(`🤖 Using model: ${finalConfig.model}`);
+    }
+
+    // Session resumption uses different subcommand
+    if (finalConfig.continueLastSession) {
+      // Use 'exec resume --last' subcommand
+      args.push("exec", "resume", "--last");
+      logger.progress("🔄 Continuing last session");
+    } else if (finalConfig.sessionId) {
+      // Use 'exec resume <session-id>' subcommand
+      args.push("exec", "resume", finalConfig.sessionId);
+      logger.progress(`🔄 Resuming session: ${finalConfig.sessionId}`);
+    } else {
+      // Normal execution
+      args.push("exec");
+    }
+
+    // Add full write access for automation
+    args.push("--sandbox", "workspace-write");
+
+    // Add prompt as positional argument
+    args.push(message);
+
+    if (dry) {
+      logger.progress(`🔧 Using executor: ${this.name}`);
+      logger.progress(`codex ${args.join(" ")}`);
+      return;
+    }
+
+    // Launch codex and wait for it to complete
+    const child = spawn("codex", args, {
+      stdio: "inherit", // Give tool full terminal control
+    });
+
+    // Wait for completion (blocking)
+    await new Promise<void>((resolve, reject) => {
+      child.on("close", (code: number) => {
+        if (code === 0) {
+          logger.success("✅ Codex CLI execution completed successfully");
+          resolve();
+        } else {
+          const error = new Error(`Codex CLI exited with code ${code}`);
+          logger.error(`❌ ${error.message}`);
+          reject(error);
+        }
+      });
+
+      child.on("error", (error: Error) => {
+        logger.error(`❌ Failed to launch Codex CLI: ${error.message}`);
+        reject(error);
+      });
+    });
+  }
+}

package/src/lib/executors/executor-factory.ts

@@ -0,0 +1,28 @@
+import { ExternalExecutor, ExecutorTool, ExecutorConfig } from "../../types";
+import { OpencodeExecutor } from "./opencode-executor";
+import { ClaudeCodeExecutor } from "./claude-code-executor";
+import { GeminiExecutor } from "./gemini-executor";
+import { CodexExecutor } from "./codex-executor";
+import { KiloExecutor } from "./kilo-executor";
+
+export class ExecutorFactory {
+  static create(
+    tool: ExecutorTool = "opencode",
+    config?: ExecutorConfig
+  ): ExternalExecutor {
+    switch (tool) {
+      case "opencode":
+        return new OpencodeExecutor(config);
+      case "claude":
+        return new ClaudeCodeExecutor(config);
+      case "gemini":
+        return new GeminiExecutor(config);
+      case "codex":
+        return new CodexExecutor(config);
+      case "kilo":
+        return new KiloExecutor(config);
+      default:
+        throw new Error(`Unknown executor tool: ${tool}`);
+    }
+  }
+}

package/src/lib/executors/gemini-executor.ts

@@ -0,0 +1,80 @@
+import { spawn } from "node:child_process";
+
+import type { ExecutorConfig, ExternalExecutor } from "../../types";
+import { logger } from "../logger";
+
+export class GeminiExecutor implements ExternalExecutor {
+  name = "gemini";
+  private config?: ExecutorConfig;
+
+  constructor(config?: ExecutorConfig) {
+    this.config = config;
+  }
+
+  supportsSessionResumption(): boolean {
+    return true;
+  }
+
+  async execute(
+    message: string,
+    dry: boolean = false,
+    config?: ExecutorConfig
+  ): Promise<void> {
+    // Merge constructor config with execution config (execution takes precedence)
+    const finalConfig = { ...this.config, ...config };
+
+    // Build arguments array
+    const args: string[] = [];
+
+    // Add model if specified
+    if (finalConfig.model) {
+      args.push("-m", finalConfig.model);
+      logger.progress(`🤖 Using model: ${finalConfig.model}`);
+    }
+
+    // Add session resumption if specified
+    if (finalConfig.continueLastSession) {
+      args.push("-r", "latest");
+      logger.progress("🔄 Continuing last session");
+    } else if (finalConfig.sessionId) {
+      args.push("-r", finalConfig.sessionId);
+      logger.progress(`🔄 Resuming session: ${finalConfig.sessionId}`);
+    }
+
+    // Enable auto-approval of all tools (yolo mode) - required for file writes
+    args.push("--yolo");
+
+    // Add prompt as positional argument (the -p flag is deprecated)
+    args.push(message);
+
+    if (dry) {
+      logger.progress(`🔧 Using executor: ${this.name}`);
+      logger.progress(`gemini ${args.join(" ")}`);
+      return;
+    }
+
+    // Launch gemini and wait for it to complete
+    const child = spawn("gemini", args, {
+      stdio: "inherit", // Give tool full terminal control
+    });
+
+    // Wait for completion (blocking)
+    await new Promise<void>((resolve, reject) => {
+      child.on("close", (code: number) => {
+        if (code === 0) {
+          logger.success("✅ Gemini CLI execution completed successfully");
+          resolve();
+        } else {
+          const error = new Error(`Gemini CLI exited with code ${code}`);
+          logger.error(`❌ ${error.message}`);
+          reject(error);
+        }
+      });
+
+      child.on("error", (error: Error) => {
+        logger.error(`❌ Failed to launch Gemini CLI: ${error.message}`);
+        reject(error);
+      });
+    });
+  }
+}