loopwork 0.3.0

package/examples/basic-json-backend/.specs/tasks/TASK-003.md

@@ -0,0 +1,37 @@
+# TASK-003: Create README Documentation
+
+## Goal
+Write a simple README.md file for the project
+
+## Requirements
+- Create a `README.md` file in the project root
+- Include a project title
+- Add a brief description
+- List the functions available
+- Show usage examples
+
+## Example Structure
+```markdown
+# My Project
+
+A simple TypeScript project with basic utility functions.
+
+## Functions
+
+### sayHello()
+Returns a greeting message.
+
+### sum(a, b)
+Adds two numbers together.
+
+## Usage
+
+`npm install`
+`npm test`
+```
+
+## Success Criteria
+- README.md exists
+- Contains all required sections
+- Examples are clear and accurate
+- Proper markdown formatting

package/examples/basic-json-backend/.specs/tasks/tasks.json

@@ -0,0 +1,19 @@
+{
+  "tasks": [
+    {
+      "id": "TASK-001",
+      "status": "completed",
+      "priority": "high"
+    },
+    {
+      "id": "TASK-002",
+      "status": "completed",
+      "priority": "medium"
+    },
+    {
+      "id": "TASK-003",
+      "status": "completed",
+      "priority": "low"
+    }
+  ]
+}

package/examples/basic-json-backend/README.md

@@ -0,0 +1,32 @@
+# Basic JSON Backend
+
+A simple TypeScript project with basic utility functions.
+
+## Functions
+
+### sayHello()
+Returns a greeting message.
+
+### sum(a, b)
+Adds two numbers together.
+
+## Usage
+
+### Install dependencies
+```bash
+bun install
+```
+
+### Run tests
+```bash
+bun test
+```
+
+## Example
+```typescript
+import { sayHello } from './hello'
+import { sum } from './math'
+
+console.log(sayHello()) // 'Hello, World!'
+console.log(sum(2, 3))  // 5
+```

package/examples/basic-json-backend/TESTING.md

@@ -0,0 +1,184 @@
+# Testing Guide
+
+This document explains how to test the loopwork example.
+
+## Quick Start
+
+### Option 1: Interactive Menu
+
+```bash
+./quick-start.sh
+```
+
+Choose from:
+1. **Dry Run** - Preview tasks without executing
+2. **Run Loopwork** - Execute tasks with AI
+3. **Reset tasks** - Reset all tasks to pending status
+4. **View task details** - See task descriptions
+
+### Option 2: Direct Commands
+
+```bash
+# Dry run (preview)
+bun run dry-run
+
+# Actually execute
+bun run start
+
+# With explicit flags
+bun ../../src/index.ts --dry-run
+bun ../../src/index.ts --cli claude --timeout 600
+```
+
+## Testing Checklist
+
+### 1. Config Loading
+
+```bash
+bun ../../src/index.ts --dry-run 2>&1 | grep "CLI:"
+# Should show: CLI: claude (from config)
+
+bun ../../src/index.ts --dry-run 2>&1 | grep "Max Iterations:"
+# Should show: Max Iterations: 10 (from config)
+```
+
+### 2. Dry Run Mode
+
+```bash
+bun ../../src/index.ts --dry-run 2>&1 | grep "Dry Run:"
+# Should show: Dry Run: true
+
+bun ../../src/index.ts 2>&1 | grep "Dry Run:"
+# Should show: Dry Run: false
+```
+
+### 3. Task Priority
+
+```bash
+bun ../../src/index.ts --dry-run 2>&1 | grep "Task:" | head -1
+# Should show: Task: TASK-001 (high priority first)
+```
+
+### 4. Config Override
+
+```bash
+bun ../../src/index.ts --cli opencode --dry-run 2>&1 | grep "CLI:"
+# Should show: CLI: opencode (CLI arg overrides config)
+```
+
+## Manual Testing
+
+### Test 1: Complete Workflow
+
+1. Reset tasks: `echo "3" | ./quick-start.sh`
+2. Check status: `cat .specs/tasks/tasks.json`
+3. Run dry-run: `bun run dry-run`
+4. Verify output shows all 3 tasks
+
+### Test 2: Task Execution
+
+⚠️ **Warning**: This will actually execute AI commands!
+
+```bash
+# Make sure you want to run this
+bun run start
+
+# Monitor in another terminal
+tail -f loopwork-runs/basic-example/*/logs/iteration-*.txt
+```
+
+### Test 3: State Management
+
+```bash
+# Start execution
+bun run start
+
+# In another terminal, send SIGINT
+kill -INT <pid>
+
+# Should save state and show:
+# "State saved. Resume with: --resume"
+
+# Resume
+bun ../../src/index.ts --resume
+```
+
+## Debugging
+
+### Enable Debug Mode
+
+```bash
+# Method 1: Environment variable
+LOOPWORK_DEBUG=true bun ../../src/index.ts --dry-run
+
+# Method 2: CLI flag
+bun ../../src/index.ts --debug --dry-run
+```
+
+### Check Command Being Executed
+
+```bash
+bun ../../src/index.ts --debug --dry-run 2>&1 | grep "Executing:"
+# Shows: [model-name] Executing: <command>
+```
+
+### Verify Config File Loading
+
+```bash
+# Should NOT show warning about failed config load
+bun ../../src/index.ts --dry-run 2>&1 | head -5
+```
+
+## Common Issues
+
+### "No pending tasks found"
+
+Tasks have been completed. Reset them:
+```bash
+echo "3" | ./quick-start.sh
+```
+
+### "Another loopwork is running"
+
+Remove the lock file:
+```bash
+rm -rf .loopwork-*.lock
+```
+
+### Config not loading
+
+Make sure you're in the correct directory:
+```bash
+pwd
+# Should be: .../examples/basic-json-backend
+
+ls loopwork.config.js
+# Should exist
+```
+
+### --dry-run not working
+
+This was a known issue that's now fixed. Update to latest code:
+```bash
+git pull origin main
+```
+
+## Success Criteria
+
+All of these should pass:
+
+- ✅ `./quick-start.sh` shows interactive menu
+- ✅ `bun run dry-run` shows 3 pending tasks
+- ✅ Config values are loaded (claude CLI, 10 max iterations, 300s timeout)
+- ✅ `--dry-run` flag shows "Dry Run: true"
+- ✅ Tasks are shown in priority order (TASK-001 first)
+- ✅ Command being executed is displayed
+
+## Next Steps
+
+After testing the basic example:
+
+1. Try modifying the config (change CLI, timeouts, etc.)
+2. Create your own tasks in `.specs/tasks/`
+3. Experiment with task dependencies
+4. Add plugins (Telegram, cost tracking, etc.)

package/examples/basic-json-backend/hello.test.ts

@@ -0,0 +1,9 @@
+import { describe, it, expect } from 'bun:test'
+import { sayHello } from './hello'
+
+describe('sayHello', () => {
+  it('should return "Hello, World!"', () => {
+    const result = sayHello()
+    expect(result).toBe('Hello, World!')
+  })
+})

package/examples/basic-json-backend/hello.ts

@@ -0,0 +1,3 @@
+export function sayHello(): string {
+  return 'Hello, World!'
+}

package/examples/basic-json-backend/loopwork.config.js

@@ -0,0 +1,35 @@
+/**
+ * Basic Loopwork Configuration Example
+ *
+ * This is a minimal configuration for testing loopwork with JSON backend.
+ * Tasks are stored in .specs/tasks/tasks.json
+ */
+
+export default {
+  // Backend configuration
+  backend: {
+    type: 'json',
+    tasksFile: '.specs/tasks/tasks.json',
+    tasksDir: '.specs/tasks',
+  },
+
+  // CLI tool to use: 'opencode' or 'claude'
+  cli: 'claude',
+
+  // Loop settings
+  maxIterations: 10,
+  timeout: 300, // 5 minutes per task
+
+  // Optional settings
+  // dryRun: false,       // Set to true to test without executing (use --dry-run flag instead)
+  debug: true,         // Enable debug logging
+  // autoConfirm: false,  // Set to true to skip confirmations (use -y flag instead)
+
+  // Retry settings
+  maxRetries: 2,
+  retryDelay: 3000,    // Wait 3 seconds before retry
+  taskDelay: 2000,     // Wait 2 seconds between tasks
+
+  // Namespace for concurrent runs
+  namespace: 'basic-example',
+}

package/examples/basic-json-backend/math.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'bun:test'
+import { sum } from './math'
+
+describe('sum', () => {
+  it('should add two positive integers', () => {
+    const result = sum(2, 3)
+    expect(result).toBe(5)
+  })
+
+  it('should add two negative integers', () => {
+    const result = sum(-2, -3)
+    expect(result).toBe(-5)
+  })
+
+  it('should add positive and negative integers', () => {
+    const result = sum(5, -3)
+    expect(result).toBe(2)
+  })
+
+  it('should handle decimal numbers', () => {
+    const result = sum(2.5, 3.7)
+    expect(result).toBe(6.2)
+  })
+
+  it('should handle zero', () => {
+    const result = sum(0, 5)
+    expect(result).toBe(5)
+  })
+})

package/examples/basic-json-backend/math.ts

@@ -0,0 +1,3 @@
+export function sum(a: number, b: number): number {
+  return a + b
+}

package/examples/basic-json-backend/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "loopwork-example-basic",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Basic example of using Loopwork with JSON backend",
+  "scripts": {
+    "start": "bun run ../../src/index.ts",
+    "dry-run": "bun run ../../src/index.ts --dry-run",
+    "build": "echo 'No build needed for example'"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/examples/basic-json-backend/quick-start.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Quick Start Script for Basic JSON Backend Example
+
+set -e
+
+echo "🚀 Loopwork Basic Example - Quick Start"
+echo "========================================"
+echo ""
+
+# Check if we're in the right directory
+if [ ! -f "loopwork.config.js" ] && [ ! -f "loopwork.config.ts" ]; then
+    echo "❌ Error: Please run this script from the examples/basic-json-backend directory"
+    exit 1
+fi
+
+echo "📋 Current Tasks:"
+cat .specs/tasks/tasks.json | grep -A 2 '"id"'
+echo ""
+
+echo "Choose an option:"
+echo "1) Dry Run (preview without executing)"
+echo "2) Run Loopwork (execute tasks)"
+echo "3) Reset tasks to pending"
+echo "4) View task details"
+echo ""
+
+read -p "Enter your choice (1-4): " choice
+
+case $choice in
+    1)
+        echo ""
+        echo "🔍 Running dry-run..."
+        bun run ../../src/index.ts --dry-run
+        ;;
+    2)
+        echo ""
+        echo "⚡ Running Loopwork..."
+        bun run ../../src/index.ts
+        ;;
+    3)
+        echo ""
+        echo "🔄 Resetting all tasks to pending..."
+        cat > .specs/tasks/tasks.json << 'EOF'
+{
+  "tasks": [
+    {
+      "id": "TASK-001",
+      "status": "pending",
+      "priority": "high"
+    },
+    {
+      "id": "TASK-002",
+      "status": "pending",
+      "priority": "medium"
+    },
+    {
+      "id": "TASK-003",
+      "status": "pending",
+      "priority": "low"
+    }
+  ]
+}
+EOF
+        echo "✅ Tasks reset!"
+        ;;
+    4)
+        echo ""
+        echo "📄 Task Details:"
+        echo ""
+        for task in .specs/tasks/TASK-*.md; do
+            echo "----------------------------------------"
+            head -5 "$task"
+            echo ""
+        done
+        ;;
+    *)
+        echo "❌ Invalid choice"
+        exit 1
+        ;;
+esac

package/loopwork.config.ts

@@ -0,0 +1,164 @@
+import {
+  defineConfig,
+  withTelegram,
+  withCostTracking,
+  withJSON,
+  withGitHub,
+  withPlugin,
+  withAsana,
+  withEverhour,
+  withTodoist,
+  withDiscord,
+  compose,
+} from './src/loopwork-config-types'
+import { withJSONBackend, withGitHubBackend } from './src/backend-plugin'
+
+/**
+ * Loopwork Configuration
+ *
+ * This file configures the Loopwork task runner.
+ * Similar to next.config.js, you can use plugin wrappers to add functionality.
+ *
+ * Backends are now plugins:
+ * - withJSONBackend({ tasksFile: 'tasks.json' })
+ * - withGitHubBackend({ repo: 'owner/repo' })
+ */
+
+// =============================================================================
+// Full Example with All Plugins
+// =============================================================================
+
+export default compose(
+  // Backend plugins (choose one)
+  withJSONBackend({ tasksFile: '.specs/tasks/tasks.json' }),
+  // withGitHubBackend({ repo: 'owner/repo' }),
+
+  // Legacy backend config (still supported)
+  // withJSON({ tasksFile: '.specs/tasks/tasks.json' }),
+  // withGitHub({ repo: 'owner/repo' }),
+
+  // Telegram notifications on task events
+  withTelegram({
+    botToken: process.env.TELEGRAM_BOT_TOKEN,
+    chatId: process.env.TELEGRAM_CHAT_ID,
+    silent: false,
+  }),
+
+  // Asana integration: sync task status to Asana project
+  // Tasks should have metadata.asanaGid set in the tasks file
+  // withAsana({
+  //   projectId: process.env.ASANA_PROJECT_ID,
+  //   syncStatus: true,
+  // }),
+
+  // Everhour time tracking: auto-track time spent on tasks
+  // Uses metadata.everhourId or metadata.asanaGid (auto-prefixed with 'as:')
+  // withEverhour({
+  //   autoStartTimer: true,
+  //   autoStopTimer: true,
+  // }),
+
+  // Todoist integration: sync task status to Todoist
+  // Tasks should have metadata.todoistId set
+  // withTodoist({
+  //   projectId: process.env.TODOIST_PROJECT_ID,
+  //   syncStatus: true,
+  //   addComments: true,
+  // }),
+
+  // Discord notifications via webhook
+  // withDiscord({
+  //   webhookUrl: process.env.DISCORD_WEBHOOK_URL,
+  //   username: 'Loopwork',
+  //   notifyOnComplete: true,
+  //   notifyOnFail: true,
+  //   mentionOnFail: '<@&123456>',  // mention role on failures
+  // }),
+
+  // Cost tracking for token usage
+  withCostTracking({
+    enabled: true,
+    defaultModel: 'claude-3.5-sonnet',
+  }),
+
+  // Dashboard TUI: live progress display
+  // Requires: bun add ink react @types/react
+  // withPlugin(createDashboardPlugin({ totalTasks: 10 })),
+
+  // Custom plugin: Log to console
+  withPlugin({
+    name: 'console-logger',
+    onLoopStart: (namespace) => {
+      console.log(`\n🚀 Loop starting in namespace: ${namespace}\n`)
+    },
+    onTaskStart: (task) => {
+      console.log(`📋 Starting: ${task.id} - ${task.title}`)
+    },
+    onTaskComplete: (task, result) => {
+      console.log(`✅ Completed: ${task.id} in ${result.duration}s`)
+    },
+    onTaskFailed: (task, error) => {
+      console.log(`❌ Failed: ${task.id} - ${error}`)
+    },
+    onLoopEnd: (stats) => {
+      console.log(`\n📊 Loop finished: ${stats.completed} completed, ${stats.failed} failed\n`)
+    },
+  }),
+
+  // Custom plugin: Slack webhook (example)
+  // withPlugin({
+  //   name: 'slack-notify',
+  //   onTaskComplete: async (task) => {
+  //     await fetch(process.env.SLACK_WEBHOOK_URL, {
+  //       method: 'POST',
+  //       headers: { 'Content-Type': 'application/json' },
+  //       body: JSON.stringify({
+  //         text: `✅ Task completed: ${task.id} - ${task.title}`,
+  //       }),
+  //     })
+  //   },
+  // }),
+)(defineConfig({
+  // AI CLI tool: 'opencode', 'claude', or 'gemini'
+  cli: 'opencode',
+
+  // Loop settings
+  maxIterations: 50,
+  timeout: 600,          // seconds per task
+  namespace: 'default',  // for concurrent loops
+
+  // Behavior
+  autoConfirm: false,    // -y flag
+  dryRun: false,
+  debug: false,
+
+  // Retry settings
+  maxRetries: 3,
+  circuitBreakerThreshold: 5,
+  taskDelay: 2000,       // ms between tasks
+  retryDelay: 3000,      // ms before retry
+}))
+
+// =============================================================================
+// Alternative: Backend Plugins Pattern (recommended)
+// =============================================================================
+
+// export default compose(
+//   withJSONBackend({ tasksFile: 'tasks.json' }),
+//   withTelegram(),
+//   withAsana(),
+//   withEverhour(),
+// )(defineConfig({ cli: 'opencode' }))
+
+// =============================================================================
+// Alternative: GitHub Backend Plugin
+// =============================================================================
+
+// export default compose(
+//   withGitHubBackend({ repo: 'myorg/myrepo' }),
+//   withTelegram(),
+//   withDiscord({ webhookUrl: process.env.DISCORD_WEBHOOK_URL }),
+// )(defineConfig({
+//   cli: 'claude',
+//   feature: 'auth',  // filter by feature label
+// }))

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "loopwork",
+  "version": "0.3.0",
+  "description": "Loopwork - AI task runner with pluggable backends",
+  "main": "src/index.ts",
+  "bin": {
+    "loopwork": "bin/loopwork"
+  },
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "build": "bun build ./src/index.ts --compile --outfile bin/loopwork",
+    "test": "bun test",
+    "setup-labels": "bun run src/setup-labels.ts"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "ink": "^4.4.1",
+    "react": "^18.2.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0"
+  }
+}