loopwork 0.3.0

package/src/contracts/plugin.ts

@@ -0,0 +1,82 @@
+/**
+ * Plugin Interface Contract
+ */
+
+import type { LoopworkConfig } from './config'
+
+/**
+ * Task metadata for external integrations
+ */
+export interface TaskMetadata {
+  asanaGid?: string
+  everhourId?: string
+  todoistId?: string
+  [key: string]: unknown
+}
+
+/**
+ * Task object passed to plugin hooks
+ */
+export interface PluginTask {
+  id: string
+  title: string
+  metadata?: TaskMetadata
+}
+
+/**
+ * Context passed to plugin hooks
+ */
+export interface PluginContext {
+  task: PluginTask
+  config: LoopworkConfig
+  namespace: string
+  iteration: number
+}
+
+/**
+ * Result passed to onTaskComplete
+ */
+export interface PluginTaskResult {
+  duration: number
+  success: boolean
+}
+
+/**
+ * Loop statistics passed to onLoopEnd
+ */
+export interface LoopStats {
+  completed: number
+  failed: number
+  duration: number
+}
+
+/**
+ * Plugin interface - implement to extend Loopwork
+ */
+export interface LoopworkPlugin {
+  /** Unique plugin name */
+  name: string
+
+  /** Called when config is loaded */
+  onConfigLoad?: (config: LoopworkConfig) => LoopworkConfig | Promise<LoopworkConfig>
+
+  /** Called when loop starts */
+  onLoopStart?: (namespace: string) => void | Promise<void>
+
+  /** Called when loop ends */
+  onLoopEnd?: (stats: LoopStats) => void | Promise<void>
+
+  /** Called when task starts */
+  onTaskStart?: (task: PluginTask) => void | Promise<void>
+
+  /** Called when task completes */
+  onTaskComplete?: (task: PluginTask, result: PluginTaskResult) => void | Promise<void>
+
+  /** Called when task fails */
+  onTaskFailed?: (task: PluginTask, error: string) => void | Promise<void>
+}
+
+/**
+ * Config wrapper function type
+ */
+export type ConfigWrapper = (config: LoopworkConfig) => LoopworkConfig

package/src/contracts/task.ts

@@ -0,0 +1,78 @@
+/**
+ * Task Types and Constants
+ */
+
+export type TaskStatus = 'pending' | 'in-progress' | 'completed' | 'failed'
+export type Priority = 'high' | 'medium' | 'low'
+
+/**
+ * Unified task representation across all backends
+ */
+export interface Task {
+  id: string
+  title: string
+  description: string
+  status: TaskStatus
+  priority: Priority
+  feature?: string
+  parentId?: string
+  dependsOn?: string[]
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Task result after execution
+ */
+export interface TaskResult {
+  success: boolean
+  output: string
+  duration: number
+  error?: string
+}
+
+/**
+ * GitHub-specific types (for GitHub backend)
+ */
+export interface GitHubLabel {
+  name: string
+  color?: string
+  description?: string
+}
+
+export interface GitHubIssue {
+  number: number
+  title: string
+  body: string
+  state: 'open' | 'closed'
+  labels: GitHubLabel[]
+  url: string
+  createdAt: string
+  updatedAt: string
+}
+
+/**
+ * Label constants for GitHub backend
+ */
+export const LABELS = {
+  LOOPWORK_TASK: 'loopwork-task',
+  STATUS_PENDING: 'loopwork:pending',
+  STATUS_IN_PROGRESS: 'loopwork:in-progress',
+  STATUS_FAILED: 'loopwork:failed',
+  PRIORITY_HIGH: 'priority:high',
+  PRIORITY_MEDIUM: 'priority:medium',
+  PRIORITY_LOW: 'priority:low',
+  SUB_TASK: 'loopwork:sub-task',
+  BLOCKED: 'loopwork:blocked',
+} as const
+
+export const STATUS_LABELS = [
+  LABELS.STATUS_PENDING,
+  LABELS.STATUS_IN_PROGRESS,
+  LABELS.STATUS_FAILED,
+] as const
+
+export const PRIORITY_LABELS = [
+  LABELS.PRIORITY_HIGH,
+  LABELS.PRIORITY_MEDIUM,
+  LABELS.PRIORITY_LOW,
+] as const

package/src/core/cli.ts

@@ -0,0 +1,275 @@
+import { spawn, spawnSync, ChildProcess } from 'child_process'
+import fs from 'fs'
+import path from 'path'
+import { logger } from './utils'
+import type { Config } from './config'
+
+export interface CliConfig {
+  name: string
+  cli: 'opencode' | 'claude'
+  model: string
+}
+
+// Default model pools
+export const EXEC_MODELS: CliConfig[] = [
+  { name: 'sonnet-claude', cli: 'claude', model: 'sonnet' },
+  { name: 'sonnet-opencode', cli: 'opencode', model: 'google/antigravity-claude-sonnet-4-5' },
+  { name: 'gemini-3-flash', cli: 'opencode', model: 'google/antigravity-gemini-3-flash' },
+]
+
+export const FALLBACK_MODELS: CliConfig[] = [
+  { name: 'opus-claude', cli: 'claude', model: 'opus' },
+  { name: 'gemini-3-pro', cli: 'opencode', model: 'google/antigravity-gemini-3-pro' },
+]
+
+export class CliExecutor {
+  private cliPaths: Map<string, string> = new Map()
+  private currentSubprocess: ChildProcess | null = null
+  private execIndex = 0
+  private fallbackIndex = 0
+  private useFallback = false
+
+  constructor(private config: Config) {
+    this.detectClis()
+  }
+
+  private detectClis(): void {
+    const home = process.env.HOME || ''
+    const candidates: Record<string, string[]> = {
+      opencode: [`${home}/.opencode/bin/opencode`, '/usr/local/bin/opencode'],
+      claude: [
+        `${home}/.nvm/versions/node/v20.18.3/bin/claude`,
+        `${home}/.nvm/versions/node/v22.13.0/bin/claude`,
+        '/usr/local/bin/claude',
+        `${home}/.npm/bin/claude`,
+      ],
+    }
+
+    for (const [cli, paths] of Object.entries(candidates)) {
+      // Try PATH first
+      const whichResult = spawnSync('which', [cli], { encoding: 'utf-8' })
+      if (whichResult.status === 0 && whichResult.stdout?.trim()) {
+        this.cliPaths.set(cli, whichResult.stdout.trim())
+        continue
+      }
+
+      // Try known paths
+      for (const p of paths) {
+        if (fs.existsSync(p)) {
+          this.cliPaths.set(cli, p)
+          break
+        }
+      }
+    }
+
+    if (this.cliPaths.size === 0) {
+      throw new Error("No AI CLI found. Install 'opencode' or 'claude'.")
+    }
+
+    logger.info(`Available CLIs: ${Array.from(this.cliPaths.keys()).join(', ')}`)
+  }
+
+  getNextCliConfig(): CliConfig {
+    if (this.useFallback) {
+      const config = FALLBACK_MODELS[this.fallbackIndex % FALLBACK_MODELS.length]
+      this.fallbackIndex++
+      return config
+    }
+    const config = EXEC_MODELS[this.execIndex % EXEC_MODELS.length]
+    this.execIndex++
+    return config
+  }
+
+  switchToFallback(): void {
+    if (!this.useFallback) {
+      this.useFallback = true
+      logger.warn('Switching to fallback models')
+    }
+  }
+
+  resetFallback(): void {
+    this.useFallback = false
+  }
+
+  killCurrent(): void {
+    if (this.currentSubprocess) {
+      this.currentSubprocess.kill('SIGTERM')
+      this.currentSubprocess = null
+    }
+  }
+
+  async execute(
+    prompt: string,
+    outputFile: string,
+    timeoutSecs: number
+  ): Promise<number> {
+    const promptFile = path.join(path.dirname(outputFile), 'current-prompt.md')
+    fs.writeFileSync(promptFile, prompt)
+
+    const maxAttempts = EXEC_MODELS.length + FALLBACK_MODELS.length
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      const cliConfig = this.getNextCliConfig()
+      const cliPath = this.cliPaths.get(cliConfig.cli)
+
+      if (!cliPath) {
+        logger.debug(`CLI ${cliConfig.cli} not available, skipping`)
+        continue
+      }
+
+      const env = { ...process.env }
+      let args: string[]
+
+      if (cliConfig.cli === 'opencode') {
+        env['OPENCODE_PERMISSION'] = '{"*":"allow"}'
+        args = ['run', '--model', cliConfig.model, prompt]
+      } else {
+        args = ['-p', '--dangerously-skip-permissions', '--model', cliConfig.model]
+      }
+
+      // Show command being executed
+      const cmdDisplay = cliConfig.cli === 'opencode'
+        ? `opencode run --model ${cliConfig.model} "<prompt>"`
+        : `claude -p --dangerously-skip-permissions --model ${cliConfig.model}`
+
+      logger.info(`[${cliConfig.name}] Executing: ${cmdDisplay}`)
+      logger.info(`[${cliConfig.name}] Timeout: ${timeoutSecs}s`)
+      logger.info(`[${cliConfig.name}] Log file: ${outputFile}`)
+      logger.info('─────────────────────────────────────')
+      logger.info('📝 Streaming CLI output below...')
+      logger.info('─────────────────────────────────────')
+
+      const result = await this.spawnWithTimeout(
+        cliPath,
+        args,
+        { env, input: cliConfig.cli === 'claude' ? prompt : undefined },
+        outputFile,
+        timeoutSecs
+      )
+
+      if (result.timedOut) {
+        logger.error(`Timed out with ${cliConfig.name}`)
+        continue
+      }
+
+      // Check for rate limits
+      const output = fs.existsSync(outputFile)
+        ? fs.readFileSync(outputFile, 'utf-8').slice(-2000)
+        : ''
+
+      if (/rate.*limit|too.*many.*request|429|RESOURCE_EXHAUSTED/i.test(output)) {
+        logger.warn(`Rate limited on ${cliConfig.name}, waiting 30s...`)
+        await new Promise(r => setTimeout(r, 30000))
+        continue
+      }
+
+      if (/quota.*exceed|billing.*limit/i.test(output)) {
+        logger.warn(`Quota exhausted for ${cliConfig.name}`)
+        this.switchToFallback()
+        continue
+      }
+
+      if (result.exitCode === 0) {
+        return 0
+      }
+
+      // Non-zero exit, try next
+      if (attempt >= EXEC_MODELS.length - 1 && !this.useFallback) {
+        this.switchToFallback()
+      }
+    }
+
+    logger.error('All CLI configurations failed')
+    return 1
+  }
+
+  private spawnWithTimeout(
+    command: string,
+    args: string[],
+    options: { env?: NodeJS.ProcessEnv; input?: string },
+    outputFile: string,
+    timeoutSecs: number
+  ): Promise<{ exitCode: number; timedOut: boolean }> {
+    return new Promise((resolve) => {
+      const writeStream = fs.createWriteStream(outputFile)
+      let timedOut = false
+      const startTime = Date.now()
+
+      const child = spawn(command, args, {
+        env: options.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      })
+
+      this.currentSubprocess = child
+
+      // Progress logging every second
+      const progressInterval = setInterval(() => {
+        const elapsed = Math.floor((Date.now() - startTime) / 1000)
+        const remaining = Math.max(0, timeoutSecs - elapsed)
+
+        logger.update(`⏱️  Running for ${elapsed}s (timeout in ${remaining}s)`)
+      }, 1000)
+
+      child.stdout?.on('data', (data) => {
+        writeStream.write(data)
+        process.stdout.write(data)
+      })
+
+      child.stderr?.on('data', (data) => {
+        writeStream.write(data)
+        process.stderr.write(data)
+      })
+
+      if (child.stdin) {
+        if (options.input) {
+          child.stdin.write(options.input)
+        }
+        child.stdin.end()
+      }
+
+      const timer = setTimeout(() => {
+        timedOut = true
+        child.kill('SIGTERM')
+        setTimeout(() => child.kill('SIGKILL'), 5000)
+      }, timeoutSecs * 1000)
+
+      child.on('close', (code) => {
+        clearInterval(progressInterval)
+        clearTimeout(timer)
+        writeStream.end()
+        this.currentSubprocess = null
+        const totalTime = Math.floor((Date.now() - startTime) / 1000)
+        const minutes = Math.floor(totalTime / 60)
+        const seconds = totalTime % 60
+        const timeStr = minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`
+
+        // Get final file size
+        let finalSize = 'N/A'
+        try {
+          if (fs.existsSync(outputFile)) {
+            const stats = fs.statSync(outputFile)
+            const sizeKB = (stats.size / 1024).toFixed(1)
+            finalSize = `${sizeKB} KB`
+          }
+        } catch {}
+
+        logger.info('─────────────────────────────────────')
+        logger.info(`✓ CLI execution completed in ${timeStr}`)
+        logger.info(`Exit code: ${code ?? 1}`)
+        logger.info(`Output size: ${finalSize}`)
+        logger.info(`Log file: ${outputFile}`)
+        logger.info('─────────────────────────────────────')
+        resolve({ exitCode: code ?? 1, timedOut })
+      })
+
+      child.on('error', (err) => {
+        clearInterval(progressInterval)
+        clearTimeout(timer)
+        writeStream.end()
+        this.currentSubprocess = null
+        logger.error(`Spawn error: ${err.message}`)
+        resolve({ exitCode: 1, timedOut: false })
+      })
+    })
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,165 @@
+import { Command } from 'commander'
+import path from 'path'
+import fs from 'fs'
+import type { LoopworkConfig } from '../contracts'
+import { DEFAULT_CONFIG } from '../contracts'
+import type { BackendConfig } from './backends/types'
+import type { LoopworkConfig as LoopworkFileConfig } from '../contracts'
+
+export interface Config extends LoopworkConfig {
+  projectRoot: string
+  outputDir: string
+  sessionId: string
+  debug: boolean
+  resume: boolean
+  startTask?: string
+  backend: BackendConfig
+  namespace: string // For running multiple loops concurrently
+}
+
+/**
+ * Load configuration from loopwork.config.ts or loopwork.config.js
+ */
+async function loadConfigFile(projectRoot: string): Promise<Partial<LoopworkFileConfig> | null> {
+  const configPaths = [
+    path.join(projectRoot, 'loopwork.config.ts'),
+    path.join(projectRoot, 'loopwork.config.js'),
+    path.join(projectRoot, 'loopwork.config.mjs'),
+  ]
+
+  for (const configPath of configPaths) {
+    if (fs.existsSync(configPath)) {
+      try {
+        const module = await import(configPath)
+        return module.default || module
+      } catch (e) {
+        console.warn(`Warning: Failed to load config from ${configPath}`)
+      }
+    }
+  }
+
+  return null
+}
+
+export async function getConfig(cliOptions?: Partial<Config> & { config?: string, yes?: boolean, task?: string }): Promise<Config> {
+  // If cliOptions is an empty object, treat it as undefined so we parse CLI args
+  const hasCliOptions = cliOptions && Object.keys(cliOptions).length > 0
+
+  const rawOptions = (hasCliOptions ? cliOptions : null) || (() => {
+    const program = new Command()
+
+    program
+      .option('--backend <type>', 'Task backend: github or json (auto-detects if not specified)')
+      .option('--repo <owner/repo>', 'GitHub repository (defaults to current repo)')
+      .option('--tasks-file <path>', 'Path to tasks.json file (for json backend)')
+      .option('--feature <name>', 'Filter by feature label (feat:<name>)')
+      .option('--task <id>', 'Start from specific task ID')
+      .option('--max-iterations <number>', 'Maximum iterations before stopping')
+      .option('--timeout <seconds>', 'Timeout per task in seconds')
+      .option('--cli <name>', 'CLI to use (opencode, claude, gemini)')
+      .option('--model <id>', 'Specific model ID')
+      .option('--resume', 'Resume from last saved state')
+      .option('--dry-run', 'Show what would be done without executing')
+      .option('-y, --yes', 'Non-interactive mode, auto-continue on errors')
+      .option('--debug', 'Enable debug logging')
+      .option('--namespace <name>', 'Namespace for running multiple loops')
+      .option('--config <path>', 'Path to config file (loopwork.config.ts)')
+      .parse(process.argv)
+
+    return program.opts()
+  })()
+
+  const options = {
+    ...rawOptions,
+    yes: rawOptions.yes ?? rawOptions.autoConfirm,
+    task: rawOptions.task ?? rawOptions.startTask,
+    backend: typeof rawOptions.backend === 'string' ? rawOptions.backend : rawOptions.backend?.type,
+    tasksFile: rawOptions.tasksFile || (rawOptions.backend as any)?.tasksFile,
+    repo: rawOptions.repo || (rawOptions.backend as any)?.repo,
+  }
+
+  // Find project root
+  let currentDir = process.cwd()
+  let projectRoot = currentDir
+  while (currentDir !== '/' && currentDir.length > 1) {
+    if (
+      fs.existsSync(path.join(currentDir, '.git')) ||
+      fs.existsSync(path.join(currentDir, 'package.json'))
+    ) {
+      projectRoot = currentDir
+      break
+    }
+    currentDir = path.dirname(currentDir)
+  }
+
+  // Load config file (lowest priority)
+  const fileConfig = await loadConfigFile(options.config ? path.resolve(options.config) : projectRoot)
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+
+  // Priority: CLI args > env vars > config file > defaults
+  const namespace = options.namespace ||
+    process.env.LOOPWORK_NAMESPACE ||
+    fileConfig?.namespace ||
+    'default'
+
+  // Determine backend configuration
+  const backendType = options.backend ||
+    process.env.LOOPWORK_BACKEND ||
+    fileConfig?.backend?.type ||
+    detectBackendType(projectRoot, options.tasksFile || fileConfig?.backend?.tasksFile)
+
+  const backend: BackendConfig = backendType === 'json'
+    ? {
+        type: 'json',
+        tasksFile: options.tasksFile ||
+          fileConfig?.backend?.tasksFile ||
+          path.join(projectRoot, '.specs/tasks/tasks.json'),
+        tasksDir: path.dirname(
+          options.tasksFile ||
+          fileConfig?.backend?.tasksFile ||
+          path.join(projectRoot, '.specs/tasks/tasks.json')
+        ),
+      }
+    : {
+        type: 'github',
+        repo: options.repo || fileConfig?.backend?.repo,
+      }
+
+  return {
+    ...DEFAULT_CONFIG,
+    repo: options.repo || fileConfig?.backend?.repo,
+    feature: options.feature || fileConfig?.feature,
+    startTask: options.task,
+    maxIterations: parseInt(options.maxIterations, 10) || fileConfig?.maxIterations || 50,
+    timeout: parseInt(options.timeout, 10) || fileConfig?.timeout || 600,
+    cli: options.cli || fileConfig?.cli || 'opencode',
+    model: options.model || fileConfig?.model,
+    autoConfirm: options.yes ||
+      process.env.LOOPWORK_NON_INTERACTIVE === 'true' ||
+      fileConfig?.autoConfirm ||
+      false,
+    dryRun: options.dryRun || fileConfig?.dryRun || false,
+    resume: options.resume || false,
+    debug: options.debug ||
+      process.env.LOOPWORK_DEBUG === 'true' ||
+      fileConfig?.debug ||
+      false,
+    projectRoot,
+    outputDir: path.join(projectRoot, 'loopwork-runs', namespace, timestamp),
+    sessionId: `loopwork-${namespace}-${timestamp}-${process.pid}`,
+    backend,
+    namespace,
+  }
+}
+
+/**
+ * Auto-detect backend type based on files present
+ */
+function detectBackendType(projectRoot: string, tasksFile?: string): 'github' | 'json' {
+  const jsonPath = tasksFile || path.join(projectRoot, '.specs/tasks/tasks.json')
+  if (fs.existsSync(jsonPath)) {
+    return 'json'
+  }
+  return 'github'
+}