@bamptee/aia-code 2.0.11 → 2.0.13

package/README.md

@@ -4,6 +4,19 @@ CLI tool that orchestrates AI-assisted development workflows using a `.aia` fold
 
 AIA structures your feature development into steps (brief, spec, tech-spec, dev-plan, implement, etc.), builds rich prompts from project context and knowledge files, and delegates execution to AI CLI tools (Claude Code, Codex CLI, Gemini CLI) with weighted random model selection.
 
+## Table of contents
+
+- [Quick start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Commands](#commands)
+- [Integrate into an existing project](#integrate-into-an-existing-project)
+- [Web UI](#web-ui)
+- [Feature workflow](#feature-workflow)
+- [Prompt assembly](#prompt-assembly)
+- [Project structure](#project-structure)
+- [Dependencies](#dependencies)
+- [Worktrunk Integration](#worktrunk-integration)
+
 ## Quick start
 
 ```bash
@@ -400,6 +413,37 @@ aia repo scan
 
 Generates `.aia/repo-map.json` -- a categorized index of your source files (services, models, routes, controllers, middleware, utils, config). Useful as additional context for prompts.
 
+## Web UI
+
+Launch the local web interface to manage features visually:
+
+```bash
+aia ui
+# Opens http://localhost:3000
+```
+
+### Dashboard
+
+- View all features with their current step and progress
+- Create new features
+- Delete features
+- Quick access to run next step
+
+### Feature detail
+
+- Execute steps with real-time log streaming (SSE)
+- View step outputs (specs, plans, code)
+- Reset steps to re-run them
+- Edit `init.md` directly in the UI
+
+### Integrated terminal
+
+The UI includes a full terminal emulator (xterm.js + node-pty). Open a shell directly in your project directory without leaving the browser.
+
+### Config editor
+
+Edit your `.aia/config.yaml` directly in the UI with syntax highlighting and validation.
+
 ## Feature workflow
 
 Each feature follows a fixed pipeline of 8 steps:
@@ -470,48 +514,378 @@ The full prompt is piped to the CLI tool via stdin, so there are no argument len
 
 ```
 bin/
-  aia.js                  # CLI entrypoint
+  aia.js                    # CLI entrypoint
 src/
-  cli.js                  # Commander program, registers commands
-  constants.js            # Shared constants (dirs, steps, scan config)
-  models.js               # Config loader + validation, weighted model selection
-  logger.js               # Execution log writer
-  knowledge-loader.js     # Recursive markdown loader by category
-  prompt-builder.js       # Assembles full prompt from all sources
-  utils.js                # Shared filesystem helpers
+  cli.js                    # Commander program, registers commands
+  constants.js              # Shared constants (dirs, steps, icons)
+  models.js                 # Config loader + validation, weighted model selection
+  logger.js                 # Execution log writer
+  knowledge-loader.js       # Recursive markdown loader by category
+  prompt-builder.js         # Assembles full prompt from all sources
+  utils.js                  # Shared filesystem helpers
   commands/
-    init.js               # aia init
-    feature.js            # aia feature <name>
-    run.js                # aia run <step> <feature>
-    next.js               # aia next <feature>
-    iterate.js            # aia iterate <step> <feature> <instructions>
-    quick.js              # aia quick <name> [description]
-    status.js             # aia status <feature>
-    reset.js              # aia reset <step> <feature>
-    repo.js               # aia repo scan
+    init.js                 # aia init
+    feature.js              # aia feature <name>
+    run.js                  # aia run <step> <feature>
+    next.js                 # aia next <feature>
+    iterate.js              # aia iterate <step> <feature> <instructions>
+    quick.js                # aia quick <name> [description]
+    status.js               # aia status <feature>
+    reset.js                # aia reset <step> <feature>
+    repo.js                 # aia repo scan
+    ui.js                   # aia ui
   providers/
-    registry.js           # Model name + aliases -> provider routing
-    cli-runner.js         # Shared CLI spawn (streaming, idle timeout, verbose)
-    openai.js             # codex exec
-    anthropic.js          # claude -p
-    gemini.js             # gemini
+    registry.js             # Model name + aliases -> provider routing
+    cli-runner.js           # Shared CLI spawn (streaming, idle timeout, verbose)
+    openai.js               # codex exec
+    anthropic.js            # claude -p
+    gemini.js               # gemini
   services/
-    scaffold.js           # .aia/ folder creation
-    config.js             # Default config generation
-    feature.js            # Feature workspace creation + validation
-    status.js             # status.yaml read/write/reset
-    runner.js             # Step execution orchestrator
-    model-call.js         # Provider dispatch
-    repo-scan.js          # Codebase scanner + categorizer
+    scaffold.js             # .aia/ folder creation
+    config.js               # Default config generation
+    feature.js              # Feature workspace creation + validation
+    status.js               # status.yaml read/write/reset
+    runner.js               # Step execution orchestrator
+    model-call.js           # Provider dispatch
+    repo-scan.js            # Codebase scanner + categorizer
+    agent-sessions.js       # Real-time agent session tracking (SSE)
+    apps.js                 # Monorepo app/submodule detection
+    worktrunk.js            # Worktrunk git worktree integration
+  types/
+    test-quick.js           # Type definitions and validators
+  ui/
+    server.js               # Express server for web UI
+    router.js               # API route registration
+    api/
+      features.js           # Feature CRUD + step execution
+      config.js             # Config read/write endpoints
+      worktrunk.js          # Worktree management endpoints
+      logs.js               # Log streaming
+    public/
+      index.html            # SPA entry point
+      main.js               # App initialization
+      components/
+        dashboard.js        # Feature list + status overview
+        feature-detail.js   # Step execution + outputs
+        config-view.js      # Config editor
+        terminal.js         # Integrated xterm terminal
+        worktrunk-panel.js  # Worktree management UI
 ```
 
 ## Dependencies
 
-Only four runtime dependencies:
+Runtime dependencies:
 
-- `commander` -- CLI framework
-- `yaml` -- YAML parse/stringify
-- `fs-extra` -- filesystem utilities
-- `chalk` -- terminal colors
+| Package | Purpose |
+|---------|---------|
+| `commander` | CLI framework |
+| `yaml` | YAML parse/stringify |
+| `fs-extra` | Filesystem utilities |
+| `chalk` | Terminal colors |
+| `@iarna/toml` | TOML parsing (for `wt.toml`) |
+| `ws` | WebSocket server (UI real-time updates) |
+| `node-pty` | Pseudo-terminal (UI integrated terminal) |
+| `xterm` + `xterm-addon-fit` | Terminal emulator (UI) |
+| `busboy` | Multipart form parsing |
 
 AI calls use `child_process.spawn` to delegate to installed CLI tools. No API keys needed -- each CLI manages its own authentication.
+
+## Worktrunk Integration
+
+AIA integrates with [Worktrunk](https://github.com/bamptee/worktrunk) (`wt`) to create isolated development environments for each feature using git worktrees.
+
+### Why Worktrunk?
+
+- **Isolation**: Each feature gets its own directory and branch, no stashing needed
+- **Services**: Run separate Docker containers per feature (database, cache, etc.)
+- **Parallel work**: Work on multiple features simultaneously without conflicts
+- **Clean state**: Delete the worktree when done, main branch stays untouched
+
+### Installation
+
+```bash
+# Install Worktrunk CLI
+cargo install worktrunk
+
+# Verify installation
+wt --version
+```
+
+### Quick Start
+
+```bash
+# In the AIA UI, click "Create Worktree" on any feature
+# Or via CLI:
+wt switch -c feature/my-feature
+```
+
+### Configuration
+
+Create `wt.toml` at the root of your project:
+
+```toml
+# wt.toml - Worktrunk configuration
+
+[worktree]
+# Directory where worktrees are created (relative to repo root)
+# Default: "../<repo-name>-wt"
+base_path = "../my-project-wt"
+
+# Branch prefix for feature worktrees
+# AIA uses "feature/" by default
+branch_prefix = "feature/"
+
+[hooks]
+# Hooks run automatically when creating/removing worktrees
+# Available hooks: post_create, pre_remove, post_remove
+
+# Run after worktree is created
+post_create = [
+    "cp .env.example .env",
+    "docker-compose -f docker-compose.wt.yml up -d",
+    "npm install",
+]
+
+# Run before worktree is removed
+pre_remove = [
+    "docker-compose -f docker-compose.wt.yml down -v",
+]
+```
+
+### Docker Services per Feature
+
+Create `docker-compose.wt.yml` for services that should run in each worktree:
+
+```yaml
+# docker-compose.wt.yml - Services for isolated development
+
+version: '3.8'
+
+# Use environment variable for unique container names
+# WT_BRANCH is set by worktrunk (e.g., "feature-my-feature")
+x-branch: &branch ${WT_BRANCH:-dev}
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: ${WT_BRANCH:-dev}-postgres
+    environment:
+      POSTGRES_DB: myapp_dev
+      POSTGRES_USER: dev
+      POSTGRES_PASSWORD: dev
+    ports:
+      - "${DB_PORT:-5432}:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    container_name: ${WT_BRANCH:-dev}-redis
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+
+  mailhog:
+    image: mailhog/mailhog
+    container_name: ${WT_BRANCH:-dev}-mailhog
+    ports:
+      - "${MAIL_UI_PORT:-8025}:8025"
+      - "${MAIL_SMTP_PORT:-1025}:1025"
+
+volumes:
+  postgres_data:
+    name: ${WT_BRANCH:-dev}-postgres-data
+```
+
+### Port Management
+
+To avoid port conflicts between worktrees, use a `.env` file with dynamic ports:
+
+```bash
+# .env.example - Copy to .env in each worktree
+
+# Each worktree should use different ports
+# Tip: Use feature hash or manual assignment
+DB_PORT=5432
+REDIS_PORT=6379
+MAIL_UI_PORT=8025
+MAIL_SMTP_PORT=1025
+```
+
+Or use a hook to auto-assign ports:
+
+```toml
+# wt.toml
+[hooks]
+post_create = [
+    # Generate random ports based on branch name hash
+    '''
+    HASH=$(echo "$WT_BRANCH" | md5sum | cut -c1-4)
+    PORT_OFFSET=$((16#$HASH % 1000))
+    cat > .env << EOF
+    DB_PORT=$((5432 + PORT_OFFSET))
+    REDIS_PORT=$((6379 + PORT_OFFSET))
+    MAIL_UI_PORT=$((8025 + PORT_OFFSET))
+    EOF
+    ''',
+    "docker-compose -f docker-compose.wt.yml up -d",
+]
+```
+
+### Full Example Setup
+
+Here's a complete setup for a Node.js project with PostgreSQL, Redis, and S3 (MinIO):
+
+```
+my-project/
+├── wt.toml                    # Worktrunk config
+├── docker-compose.wt.yml      # Services template
+├── .env.example               # Environment template
+├── scripts/
+│   └── setup-worktree.sh      # Custom setup script
+└── .aia/
+    └── features/
+        └── my-feature/
+```
+
+**wt.toml**:
+```toml
+[worktree]
+base_path = "../my-project-wt"
+
+[hooks]
+post_create = [
+    "bash scripts/setup-worktree.sh",
+]
+
+pre_remove = [
+    "docker-compose -f docker-compose.wt.yml down -v --remove-orphans",
+]
+```
+
+**scripts/setup-worktree.sh**:
+```bash
+#!/bin/bash
+set -e
+
+echo "🔧 Setting up worktree: $WT_BRANCH"
+
+# Copy environment template
+cp .env.example .env
+
+# Generate unique ports based on branch
+HASH=$(echo "$WT_BRANCH" | md5sum | cut -c1-4)
+OFFSET=$((16#$HASH % 900 + 100))
+
+sed -i "s/DB_PORT=.*/DB_PORT=$((5000 + OFFSET))/" .env
+sed -i "s/REDIS_PORT=.*/REDIS_PORT=$((6000 + OFFSET))/" .env
+sed -i "s/MINIO_PORT=.*/MINIO_PORT=$((9000 + OFFSET))/" .env
+sed -i "s/APP_PORT=.*/APP_PORT=$((3000 + OFFSET))/" .env
+
+echo "📦 Starting Docker services..."
+docker-compose -f docker-compose.wt.yml up -d
+
+echo "📚 Installing dependencies..."
+npm install
+
+echo "🗃️ Running migrations..."
+npm run db:migrate
+
+echo "✅ Worktree ready!"
+echo "   App:      http://localhost:$((3000 + OFFSET))"
+echo "   Database: localhost:$((5000 + OFFSET))"
+```
+
+**docker-compose.wt.yml**:
+```yaml
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    container_name: ${WT_BRANCH:-dev}-postgres
+    environment:
+      POSTGRES_DB: app_dev
+      POSTGRES_USER: dev
+      POSTGRES_PASSWORD: dev
+    ports:
+      - "${DB_PORT:-5432}:5432"
+    volumes:
+      - pg_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U dev"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    container_name: ${WT_BRANCH:-dev}-redis
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  minio:
+    image: minio/minio
+    container_name: ${WT_BRANCH:-dev}-minio
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    ports:
+      - "${MINIO_PORT:-9000}:9000"
+      - "${MINIO_CONSOLE_PORT:-9001}:9001"
+    volumes:
+      - minio_data:/data
+
+volumes:
+  pg_data:
+    name: ${WT_BRANCH:-dev}-pg-data
+  minio_data:
+    name: ${WT_BRANCH:-dev}-minio-data
+```
+
+### Using Worktrunk in AIA UI
+
+1. **Create a feature**: `aia feature my-feature` or via UI
+2. **Open the feature** in the UI
+3. **Click "Create Worktree"** in the Worktrunk panel
+   - Runs `wt switch -c feature/my-feature`
+   - Executes `post_create` hooks (Docker services, npm install, etc.)
+4. **Open Terminal** to work in the worktree directory
+5. **View Docker Containers** directly in the UI
+   - Start/Stop individual containers
+   - Open a shell inside any running container
+6. **When done**: Click "Remove" to clean up
+   - Runs `pre_remove` hooks (docker-compose down)
+   - Removes the worktree directory
+
+### Troubleshooting
+
+**"Worktrunk not installed"**
+```bash
+cargo install worktrunk
+# Make sure ~/.cargo/bin is in your PATH
+```
+
+**Containers not showing in UI**
+- Containers must have names matching pattern: `feature-<name>-*`
+- Check Docker is running: `docker ps`
+- Click "Refresh Containers" in the UI
+
+**Port conflicts**
+- Each worktree needs unique ports
+- Use the port auto-assignment hook above
+- Or manually set ports in `.env` per worktree
+
+**Worktree creation fails**
+```bash
+# Check git status - uncommitted changes can block
+git status
+
+# Manual worktree creation
+wt switch -c feature/my-feature --force
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bamptee/aia-code",
-  "version": "2.0.11",
+  "version": "2.0.13",
   "description": "AI Architecture Assistant - orchestrate AI-assisted development workflows via CLI tools (Claude, Codex, Gemini)",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,16 @@
     "url": "git+https://github.com/bamptee/aia-code.git"
   },
   "scripts": {
-    "start": "node bin/aia.js"
+    "start": "node bin/aia.js",
+    "test": "node --test tests/*.test.js",
+    "test:service": "node --test tests/test-quick.service.test.js",
+    "test:api": "node --test tests/test-quick.api.test.js",
+    "test:delete": "node --test tests/feature-delete.*.test.js",
+    "test:delete:service": "node --test tests/feature-delete.service.test.js",
+    "test:delete:api": "node --test tests/feature-delete.api.test.js",
+    "test:ux": "node --test tests/feature-list-ux.*.test.js",
+    "test:ux:unit": "node --test tests/feature-list-ux.unit.test.js",
+    "test:ux:api": "node --test tests/feature-list-ux.api.test.js"
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",

package/src/constants.js

@@ -48,3 +48,27 @@ export const STEP_STATUS = {
   DONE: 'done',
   ERROR: 'error',
 };
+
+export const FEATURE_TYPES = Object.freeze(['feature', 'bug']);
+export const DEFAULT_FEATURE_TYPE = 'feature';
+
+/**
+ * Feature deletion status filter options
+ */
+export const DELETION_FILTER = Object.freeze({
+  ACTIVE: 'active',
+  DELETED: 'deleted',
+  ALL: 'all',
+});
+
+export const APP_ICONS = {
+  react: '\u269B',
+  vue: '\uD83D\uDC9A',
+  angular: '\uD83C\uDD70',
+  node: '\uD83D\uDCE6',
+  go: '\uD83D\uDD27',
+  java: '\u2615',
+  python: '\uD83D\uDC0D',
+  rust: '\uD83E\uDD80',
+  generic: '\uD83D\uDCC1',
+};

package/src/providers/anthropic.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import chalk from 'chalk';
 import { runCli } from './cli-runner.js';
 
-export async function generate(prompt, model, { verbose = false, apply = false, onData } = {}) {
+export async function generate(prompt, model, { verbose = false, apply = false, onData, cwd } = {}) {
   const args = ['-p'];
   if (model) {
     args.push('--model', model);
@@ -17,24 +17,5 @@ export async function generate(prompt, model, { verbose = false, apply = false,
     args.push('--verbose');
   }
 
-  // In agent mode, large prompts via stdin can hang Claude CLI.
-  // Write context to a temp file and give a short prompt to read it.
-  if (apply) {
-    const tmpFile = path.join(tmpdir(), `aia-prompt-${randomBytes(6).toString('hex')}.md`);
-    writeFileSync(tmpFile, prompt, 'utf-8');
-    console.error(chalk.gray(`[AI] Prompt written to temp file (${(prompt.length / 1024).toFixed(1)}KB): ${tmpFile}`));
-    const shortPrompt = `Read the file at ${tmpFile} — it contains your full instructions and context. Follow them exactly.`;
-    args.push('-');
-    console.error(chalk.gray(`[AI] Spawning: claude ${args.join(' ')}`));
-    console.error(chalk.gray(`[AI] Waiting for Claude agent response...`));
-    try {
-      return await runCli('claude', args, { stdin: shortPrompt, verbose: verbose || apply, apply, onData });
-    } finally {
-      try { unlinkSync(tmpFile); } catch {}
-    }
-  }
-
-  args.push('-');
-  console.error(chalk.gray(`[AI] Spawning: claude ${args.join(' ')} (${(prompt.length / 1024).toFixed(1)}KB prompt)`));
-  return runCli('claude', args, { stdin: prompt, verbose: verbose || apply, apply, onData });
+  return runCli('claude', args, { stdin: prompt, verbose: verbose || apply, apply, onData, cwd });
 }

package/src/providers/cli-runner.js

@@ -1,10 +1,11 @@
 import { spawn } from 'node:child_process';
+import { Readable } from 'node:stream';
 import chalk from 'chalk';
 
 const DEFAULT_IDLE_TIMEOUT_MS = 180_000;
 const AGENT_IDLE_TIMEOUT_MS = 600_000;
 
-export function runCli(command, args, { stdin: stdinData, verbose = false, apply = false, idleTimeoutMs, onData } = {}) {
+export function runCli(command, args, { stdin: stdinData, verbose = false, apply = false, idleTimeoutMs, onData, cwd } = {}) {
   if (!idleTimeoutMs) {
     idleTimeoutMs = apply ? AGENT_IDLE_TIMEOUT_MS : DEFAULT_IDLE_TIMEOUT_MS;
   }
@@ -12,7 +13,8 @@ export function runCli(command, args, { stdin: stdinData, verbose = false, apply
     const { CLAUDECODE, ...cleanEnv } = process.env;
     const child = spawn(command, args, {
       stdio: ['pipe', 'pipe', 'pipe'],
-      env: { ...cleanEnv, FORCE_COLOR: '0' },
+      env: { ...process.env, FORCE_COLOR: '0' },
+      cwd,
     });
 
     const chunks = [];
@@ -45,7 +47,7 @@ export function runCli(command, args, { stdin: stdinData, verbose = false, apply
         console.error(chalk.gray('[AI] First stdout received — agent is running'));
       }
       const text = data.toString();
-      process.stdout.write(text);
+      if (verbose) process.stdout.write(text);
       chunks.push(text);
       if (onData) onData({ type: 'stdout', text });
       resetTimer();

package/src/services/agent-sessions.js

@@ -0,0 +1,110 @@
+// Agent session tracking - in-memory Map with log buffer
+// Map<featureName, { step, startedAt, logs: Array<{text, type, ts}>, sseClients: Set<Response> }>
+const sessions = new Map();
+const MAX_LOGS = 500;
+
+/**
+ * Start a new agent session for a feature
+ * @param {string} feature - Feature name
+ * @param {string} step - Step name
+ */
+export function startSession(feature, step) {
+  sessions.set(feature, {
+    step,
+    startedAt: Date.now(),
+    logs: [],
+    sseClients: new Set(),
+  });
+}
+
+/**
+ * End an agent session and notify all SSE clients
+ * @param {string} feature - Feature name
+ */
+export function endSession(feature) {
+  const session = sessions.get(feature);
+  if (session) {
+    // Notify all SSE clients that session ended
+    for (const client of session.sseClients) {
+      try {
+        client.write(`event: done\ndata: {}\n\n`);
+      } catch {
+        // Client may have disconnected
+      }
+    }
+    sessions.delete(feature);
+  }
+}
+
+/**
+ * Get an active session for a feature
+ * @param {string} feature - Feature name
+ * @returns {Object|null} Session object or null
+ */
+export function getSession(feature) {
+  return sessions.get(feature) || null;
+}
+
+/**
+ * Append a log entry to a session's buffer
+ * @param {string} feature - Feature name
+ * @param {string} text - Log text
+ * @param {string} type - Log type ('stdout' or 'stderr')
+ */
+export function appendLog(feature, text, type = 'stdout') {
+  const session = sessions.get(feature);
+  if (!session) return;
+
+  session.logs.push({ text, type, ts: Date.now() });
+  if (session.logs.length > MAX_LOGS) session.logs.shift();
+
+  // Broadcast to all SSE clients
+  for (const client of session.sseClients) {
+    try {
+      client.write(`event: log\ndata: ${JSON.stringify({ text, type })}\n\n`);
+    } catch {
+      // Client may have disconnected
+    }
+  }
+}
+
+/**
+ * Register an SSE client for a session
+ * @param {string} feature - Feature name
+ * @param {Response} res - HTTP response object
+ */
+export function addSseClient(feature, res) {
+  const session = sessions.get(feature);
+  if (session) session.sseClients.add(res);
+}
+
+/**
+ * Unregister an SSE client from a session
+ * @param {string} feature - Feature name
+ * @param {Response} res - HTTP response object
+ */
+export function removeSseClient(feature, res) {
+  const session = sessions.get(feature);
+  if (session) session.sseClients.delete(res);
+}
+
+/**
+ * Check if a feature has an active session
+ * @param {string} feature - Feature name
+ * @returns {boolean}
+ */
+export function isRunning(feature) {
+  return sessions.has(feature);
+}
+
+/**
+ * Get all running sessions (for dashboard)
+ * @returns {Object} Map of feature name to session summary
+ */
+export function getAllRunningSessions() {
+  const result = {};
+  for (const [feature, session] of sessions) {
+    result[feature] = { step: session.step, startedAt: session.startedAt };
+  }
+  return result;
+}