wiggum-cli 0.15.0 → 0.16.0

package/README.md

@@ -25,7 +25,7 @@
 </p>
 
 <p align="center">
-  <img src=".github/screenshot.png" alt="Wiggum TUI — spec generation and autonomous coding loop" width="800">
+  <video src="https://github.com/user-attachments/assets/817edf0c-a7aa-418f-bf85-499be520fd94" width="800" controls></video>
 </p>
 
 ---
@@ -83,6 +83,12 @@ npx wiggum-cli init
 
 🔁 **Autonomous Coding Loops** — Hands specs to Claude Code (or any agent) and runs implement → test → fix cycles with git worktree isolation.
 
+✨ **Spec Autocomplete** — AI pre-fills spec names from your codebase context when running `/run`.
+
+📥 **Action Inbox** — Review AI decisions inline without breaking your flow. The loop pauses, you approve or redirect, it continues.
+
+📊 **Run Summaries** — See exactly what changed and why after each loop completes, with activity feed and diff stats.
+
 📋 **Tailored Prompts** — Generates prompts, guides, and scripts specific to your stack. Not generic templates — actual context about *your* project.
 
 🔌 **BYOK** — Bring your own API keys. Works with Anthropic, OpenAI, or OpenRouter. Keys stay local, never leave your machine.

package/dist/generator/templates.d.ts

@@ -28,6 +28,7 @@ export interface TemplateVariables {
     typecheckCommand: string;
     formatCommand: string;
     appDir: string;
+    isTui: string;
     aiEntryPoints: string;
     aiKeyDirectories: string;
     aiNamingConventions: string;

package/dist/generator/templates.js

@@ -3,7 +3,7 @@
  * Reads template files with {{variable}} placeholders and substitutes values
  */
 import { readFile, readdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const __filename = fileURLToPath(import.meta.url);
@@ -150,6 +150,18 @@ export function extractVariables(scanResult, customVars = {}) {
         existsSync(join(projectRoot, 'src', 'main.ts'))) {
         appDir = 'src';
     }
+    // Detect TUI (Ink) projects
+    let isTui = '';
+    try {
+        const pkgPath = join(projectRoot, 'package.json');
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (allDeps['ink'])
+                isTui = 'true';
+        }
+    }
+    catch { /* ignore */ }
     return {
         projectName,
         projectRoot,
@@ -166,6 +178,7 @@ export function extractVariables(scanResult, customVars = {}) {
         stylingVersion,
         stylingVariant,
         appDir,
+        isTui,
         ...commands,
         ...aiData,
         ...customVars,

package/dist/index.d.ts

@@ -1,6 +1,19 @@
+/**
+ * Parsed CLI arguments
+ */
+export interface ParsedArgs {
+    command: string | undefined;
+    positionalArgs: string[];
+    flags: Record<string, string | boolean>;
+}
+/**
+ * Parse CLI arguments into command, positional args, and flags.
+ * Supports: --flag value, --flag=value, boolean flags, short flags (-i, -y, -e, -f, -h, -v).
+ */
+export declare function parseCliArgs(argv: string[]): ParsedArgs;
 /**
  * Main entry point for the Wiggum CLI
- * TUI-first: routes args to appropriate TUI screens
+ * TUI-first: routes args to appropriate TUI screens or CLI commands
  */
 export declare function main(): Promise<void>;
 export { displayHeader } from './utils/header.js';

package/dist/index.js

@@ -9,6 +9,87 @@ import { loadApiKeysFromEnvLocal } from './utils/env.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
+import { runCommand } from './commands/run.js';
+import { monitorCommand } from './commands/monitor.js';
+import { handleConfigCommand } from './commands/config.js';
+import { isCI } from './utils/ci.js';
+/**
+ * Normalize a flag name: strip '--' prefix and convert kebab-case to camelCase
+ */
+function normalizeFlagName(flag) {
+    return flag.replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+/**
+ * Parse CLI arguments into command, positional args, and flags.
+ * Supports: --flag value, --flag=value, boolean flags, short flags (-i, -y, -e, -f, -h, -v).
+ */
+export function parseCliArgs(argv) {
+    const positionalArgs = [];
+    const flags = {};
+    let command;
+    const shortFlags = {
+        '-i': 'interactive',
+        '-y': 'yes',
+        '-e': 'edit',
+        '-f': 'force',
+        '-h': 'help',
+        '-v': 'version',
+    };
+    // Flags that consume the next argument as their value
+    const valueFlagSet = new Set([
+        '--model',
+        '--max-iterations',
+        '--max-e2e-attempts',
+        '--interval',
+        '--provider',
+        '--review-mode',
+    ]);
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (arg in shortFlags) {
+            flags[shortFlags[arg]] = true;
+            i++;
+            continue;
+        }
+        if (arg.startsWith('--') && arg.includes('=')) {
+            const eqIdx = arg.indexOf('=');
+            const key = normalizeFlagName(arg.slice(0, eqIdx));
+            const value = arg.slice(eqIdx + 1);
+            flags[key] = value;
+            i++;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            const normalized = normalizeFlagName(arg);
+            if (valueFlagSet.has(arg) && i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+                flags[normalized] = argv[i + 1];
+                i += 2;
+            }
+            else {
+                flags[normalized] = true;
+                i++;
+            }
+            continue;
+        }
+        if (command === undefined) {
+            command = arg;
+        }
+        else {
+            positionalArgs.push(arg);
+        }
+        i++;
+    }
+    return { command, positionalArgs, flags };
+}
+function parseIntFlag(value, flagName) {
+    const n = parseInt(value, 10);
+    if (Number.isNaN(n)) {
+        console.error(`Error: ${flagName} must be a number, got "${value}"`);
+        process.exit(1);
+    }
+    return n;
+}
 /**
  * Get version from package.json
  */
@@ -29,7 +110,8 @@ function getVersion() {
  * Start Ink TUI mode
  * Called when wiggum is invoked with no arguments or with screen-routing args
  */
-async function startInkTui(initialScreen = 'shell', interviewFeature) {
+async function startInkTui(initialScreen = 'shell', options) {
+    const interviewFeature = options?.interviewFeature;
     const projectRoot = process.cwd();
     const version = getVersion();
     /**
@@ -75,11 +157,16 @@ async function startInkTui(initialScreen = 'shell', interviewFeature) {
             scanResult: initialState.scanResult,
         }
         : undefined;
+    // Build run props if starting on run/monitor screen
+    const runProps = options?.runFeature
+        ? { featureName: options.runFeature, monitorOnly: options.monitorOnly }
+        : undefined;
     const instance = renderApp({
         screen: initialScreen,
         initialSessionState: initialState,
         version,
         interviewProps,
+        runProps,
         onComplete: (specPath) => {
             // Spec was saved to disk by app.tsx (avoid stdout noise during TUI)
             logger.debug(`Created spec: ${specPath}`);
@@ -93,62 +180,157 @@ async function startInkTui(initialScreen = 'shell', interviewFeature) {
 }
 /**
  * Main entry point for the Wiggum CLI
- * TUI-first: routes args to appropriate TUI screens
+ * TUI-first: routes args to appropriate TUI screens or CLI commands
  */
 export async function main() {
     // Load API keys from .ralph/.env.local before any provider detection
     loadApiKeysFromEnvLocal();
-    const args = process.argv.slice(2);
+    const parsed = parseCliArgs(process.argv.slice(2));
     // Check for updates (non-blocking, fails silently)
     await notifyIfUpdateAvailable();
-    // No args = start with shell
-    if (args.length === 0) {
+    // Handle --help / -h
+    if (parsed.flags.help) {
+        console.log(`
+Wiggum CLI - AI-powered feature development assistant
+
+Usage:
+  wiggum                    Start interactive TUI
+  wiggum init               Initialize project (TUI)
+  wiggum new <name>         Create new feature spec (TUI)
+  wiggum run <feature>      Run feature development loop
+  wiggum monitor <feature>  Monitor a running feature loop
+  wiggum config [args...]   Manage API keys and settings
+
+Options for run:
+  --worktree                Use git worktree isolation
+  --resume                  Resume from last checkpoint
+  --model <model>           AI model to use
+  --max-iterations <n>      Maximum loop iterations
+  --max-e2e-attempts <n>    Maximum E2E test attempts
+  --review-mode <mode>      Review mode: manual, auto, merge
+
+Options for monitor:
+  --interval <seconds>      Refresh interval (default: 5)
+  --bash                    Use bash monitor script
+  --stream                  Force headless streaming output (skip TUI)
+
+Options for init:
+  --provider <name>         AI provider (anthropic, openai, openrouter)
+  -i, --interactive         Interactive mode
+  -y, --yes                 Accept all defaults
+
+Options for new:
+  --provider <name>         AI provider
+  --model <model>           AI model
+  -e, --edit                Open in editor after creation
+  -f, --force               Overwrite existing spec
+
+In the TUI:
+  /init                     Initialize or reconfigure project
+  /new <name>               Create a new feature specification
+  /run <name>               Run the feature development loop
+  /monitor <name>           Monitor a running feature loop
+  /sync                     Sync context from git history
+  /config [set <svc> <key>] Manage API keys and settings
+  /help                     Show available commands
+  /exit                     Exit the application
+
+Press Esc to cancel any operation.
+`);
+        return;
+    }
+    // Handle --version / -v
+    if (parsed.flags.version) {
+        console.log(getVersion());
+        return;
+    }
+    // No command = start with shell
+    if (!parsed.command) {
         await startInkTui('shell');
         return;
     }
-    // Route commands to TUI screens
-    const command = args[0];
-    switch (command) {
-        case 'init':
-            // Start TUI at init screen
+    switch (parsed.command) {
+        case 'init': {
+            // TODO: pass parsed flags to startInkTui once TUI supports init flags
             await startInkTui('init');
             break;
-        case 'new':
-            // Start TUI at interview screen with feature name
-            const featureName = args[1];
+        }
+        case 'new': {
+            const featureName = parsed.positionalArgs[0];
             if (!featureName) {
-                logger.error('Feature name required. Usage: wiggum new <feature-name>');
+                console.error('Error: <name> is required for "new"');
+                console.error('Usage: wiggum new <name> [--provider <name>] [--model <model>] [-e] [-f]');
                 process.exit(1);
             }
-            await startInkTui('interview', featureName);
+            // TODO: pass parsed flags to startInkTui once TUI supports new flags
+            await startInkTui('interview', { interviewFeature: featureName });
             break;
-        case '--help':
-        case '-h':
-            // Show help
-            console.log(`
-Wiggum CLI - AI-powered feature development assistant
-
-Usage:
-  wiggum              Start interactive TUI
-  wiggum init         Initialize project (TUI)
-  wiggum new <name>   Create new feature spec (TUI)
-
-In the TUI:
-  /init               Initialize or reconfigure project
-  /new <name>         Create a new feature specification
-  /help               Show available commands
-  /exit               Exit the application
-
-Press Esc to cancel any operation.
-`);
-            return;
-        case '--version':
-        case '-v':
-            console.log(getVersion());
-            return;
+        }
+        case 'run': {
+            const feature = parsed.positionalArgs[0];
+            if (!feature) {
+                console.error('Error: <feature> is required for "run"');
+                console.error('Usage: wiggum run <feature> [--worktree] [--resume] [--model <model>] [--max-iterations <n>] [--max-e2e-attempts <n>]');
+                process.exit(1);
+            }
+            const runOptions = {
+                worktree: parsed.flags.worktree === true,
+                resume: parsed.flags.resume === true,
+                model: typeof parsed.flags.model === 'string' ? parsed.flags.model : undefined,
+                maxIterations: typeof parsed.flags.maxIterations === 'string' ? parseIntFlag(parsed.flags.maxIterations, '--max-iterations') : undefined,
+                maxE2eAttempts: typeof parsed.flags.maxE2eAttempts === 'string' ? parseIntFlag(parsed.flags.maxE2eAttempts, '--max-e2e-attempts') : undefined,
+                reviewMode: typeof parsed.flags.reviewMode === 'string' ? parsed.flags.reviewMode : undefined,
+            };
+            await runCommand(feature, runOptions);
+            break;
+        }
+        case 'monitor': {
+            const feature = parsed.positionalArgs[0];
+            if (!feature) {
+                console.error('Error: <feature> is required for "monitor"');
+                console.error('Usage: wiggum monitor <feature> [--interval <seconds>] [--bash] [--stream]');
+                process.exit(1);
+            }
+            const interval = typeof parsed.flags.interval === 'string'
+                ? parseIntFlag(parsed.flags.interval, '--interval')
+                : undefined;
+            // Routing order per spec:
+            // 1. --bash → always use bash script path
+            // 2. --stream → force headless streaming
+            // 3. TTY and not CI → start Ink TUI in monitor-only mode
+            // 4. default → headless streaming monitor
+            if (parsed.flags.bash === true) {
+                await monitorCommand(feature, { bash: true, interval });
+            }
+            else if (parsed.flags.stream === true) {
+                await monitorCommand(feature, { interval });
+            }
+            else if (process.stdout.isTTY && !isCI()) {
+                try {
+                    await startInkTui('run', { runFeature: feature, monitorOnly: true });
+                }
+                catch (err) {
+                    logger.error(`TUI failed to start: ${err instanceof Error ? err.message : String(err)}. Falling back to headless monitor.`);
+                    await monitorCommand(feature, { interval });
+                }
+            }
+            else {
+                await monitorCommand(feature, { interval });
+            }
+            break;
+        }
+        case 'config': {
+            const provider = getAvailableProvider();
+            const model = provider
+                ? (AVAILABLE_MODELS[provider].find((m) => m.hint?.includes('recommended'))?.value ?? AVAILABLE_MODELS[provider][0].value)
+                : 'sonnet';
+            const state = createSessionState(process.cwd(), provider, model);
+            await handleConfigCommand(parsed.positionalArgs, state);
+            break;
+        }
         default:
             // Unknown command - start TUI at shell
-            logger.warn(`Unknown command: ${command}. Starting TUI...`);
+            logger.warn(`Unknown command: ${parsed.command}. Starting TUI...`);
             await startInkTui('shell');
     }
 }

package/dist/templates/prompts/PROMPT_e2e.md.tmpl

@@ -12,10 +12,160 @@ Pay special attention to "E2E Pitfalls" section to avoid known issues.
 Before E2E testing, verify:
 1. Build passes: `cd {{appDir}} && {{buildCommand}}`
 2. All unit tests pass: `cd {{appDir}} && {{testCommand}}`
+{{#unless isTui}}
 3. Clear cache if issues: `rm -rf {{appDir}}/.next`
+{{/unless}}
 
 If either fails, fix issues before proceeding with E2E tests.
 
+{{#if isTui}}
+## Task
+Execute automated E2E tests for the completed TUI feature using the xterm.js bridge and agent-browser.
+
+### Step 1: Start Bridge
+Check the bridge is running:
+```bash
+curl -s http://localhost:3999/health || (cd {{projectRoot}} && npm run e2e:bridge &)
+sleep 3
+```
+
+### Step 2: Parse E2E Test Scenarios
+Read E2E test scenarios from @.ralph/specs/$FEATURE-implementation-plan.md.
+Each scenario is marked with `- [ ] E2E:` prefix and follows this format:
+
+```
+- [ ] E2E: [Scenario name]
+  - **Command:** [wiggum command, e.g., init, new auth-flow]
+  - **CWD:** [working directory, e.g., e2e/fixtures/bare-project]
+  - **Steps:**
+    1. [Action] -> [expected terminal output]
+  - **Verify:** [text that should appear in terminal]
+```
+
+### Step 3: Execute Each Scenario
+
+For each scenario:
+
+1. **Open the TUI in the bridge:**
+```bash
+agent-browser open "http://localhost:3999?cmd=<command>&cwd=<path>"
+```
+
+2. **Wait for terminal ready:**
+```bash
+agent-browser wait --text "Ready" --source title --timeout 10000
+```
+
+3. **Read terminal content:**
+```bash
+agent-browser eval "document.getElementById('terminal-mirror').textContent"
+```
+
+4. **Interact with TUI:**
+```bash
+# Click to focus terminal
+agent-browser snapshot -i
+agent-browser click @<terminal-ref>
+
+# Type text (Enter = press Enter after)
+agent-browser type @<terminal-ref> "/help"
+agent-browser key Enter
+
+# Arrow navigation
+agent-browser key ArrowDown
+agent-browser key ArrowDown
+agent-browser key Enter
+
+# Escape
+agent-browser key Escape
+```
+
+5. **Assert expected output:**
+```bash
+# Read terminal and check for expected text
+CONTENT=$(agent-browser eval "document.getElementById('terminal-mirror').textContent")
+# Verify CONTENT contains expected strings
+```
+
+6. **Reset between scenarios:**
+```bash
+agent-browser close
+```
+
+### TUI Interaction Cheatsheet
+
+| Action | Command |
+|--------|---------|
+| Open TUI | `agent-browser open "http://localhost:3999?cmd=init&cwd=/path"` |
+| Read screen | `agent-browser eval "document.getElementById('terminal-mirror').textContent"` |
+| Take snapshot | `agent-browser snapshot -i` |
+| Click element | `agent-browser click @ref` |
+| Type text | `agent-browser type @ref "text"` |
+| Press Enter | `agent-browser key Enter` |
+| Arrow down | `agent-browser key ArrowDown` |
+| Escape | `agent-browser key Escape` |
+| Screenshot | `agent-browser screenshot e2e-failure.png` |
+| Wait for text | `agent-browser wait --text "expected" --timeout 10000` |
+| Close session | `agent-browser close` |
+
+### Key Rules
+- Always wait for expected text before asserting (TUI renders async via React)
+- Use `agent-browser eval` with `terminal-mirror` for reliable text reading
+- Take screenshots on failures for debugging
+- Each scenario navigates to a fresh URL (clean state)
+- Wait 500ms after key presses before reading (Ink re-render delay)
+
+### Step 4: Report Results
+Update @.ralph/specs/$FEATURE-implementation-plan.md for each scenario:
+
+**Passed:**
+```markdown
+- [x] E2E: scenario name - PASSED
+```
+
+**Failed:**
+```markdown
+- [ ] E2E: scenario name - FAILED: [brief reason]
+  - Error: [what went wrong]
+  - Screenshot: [if captured]
+  - Fix needed: [suggested action]
+```
+
+## Error Recovery
+
+If a scenario fails:
+1. Document the failure with specific error details
+2. Take a screenshot: `agent-browser screenshot e2e-failure-<scenario>.png`
+3. Note what fix is likely needed (code bug vs test spec issue)
+4. Continue with remaining scenarios
+5. At end, summary shows total passed/failed
+
+Failures will trigger a fix iteration in the loop.
+
+## Completion
+
+When all scenarios are executed:
+1. Update implementation plan with results for each scenario
+2. Update the Implementation Summary status to `[PASSED]` if all passed
+3. **Commit the updated implementation plan:**
+   ```bash
+   git add -A && git commit -m "test($FEATURE): E2E tests passed via agent-browser"
+   ```
+4. **Push to remote:**
+   ```bash
+   git push origin feat/$FEATURE
+   ```
+5. If all passed: signal ready for PR phase
+6. If any failed: failures documented, loop will retry after fix iteration
+
+## Learning Capture
+If E2E testing revealed issues worth remembering, append to @.ralph/LEARNINGS.md:
+- Flaky test patterns -> Add under "## Anti-Patterns" > "E2E Pitfalls"
+- TUI timing issues -> Add under "## Anti-Patterns"
+- Useful agent-browser techniques -> Add under "## Tool Usage"
+
+Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`
+{{else}}
 ## Task
 Execute automated E2E tests for the completed feature using Playwright MCP tools.
 
@@ -232,3 +382,4 @@ If E2E testing revealed issues worth remembering, append to @.ralph/LEARNINGS.md
 - Timing issues or race conditions -> Add under "## Anti-Patterns"
 
 Format: `- [YYYY-MM-DD] [$FEATURE] Brief description`
+{{/if}}

package/dist/templates/prompts/PROMPT_feature.md.tmpl

@@ -44,6 +44,28 @@ Study @.ralph/specs/$FEATURE.md for feature specification.
 - [ ] Task N (additional polish)
 
 ### Phase 5: E2E Testing
+{{#if isTui}}
+TUI E2E tests executed via xterm.js bridge + agent-browser.
+Fixture projects in `e2e/fixtures/`. Bridge at `http://localhost:3999`.
+
+- [ ] E2E: [Scenario name] - [brief description]
+  - **Command:** [wiggum command, e.g., init, new auth-flow]
+  - **CWD:** [working directory, e.g., e2e/fixtures/bare-project]
+  - **Steps:**
+    1. [Action] -> [expected terminal output]
+    2. [Action] -> [expected terminal output]
+  - **Verify:** [text that should appear in terminal]
+
+Example TUI E2E scenario:
+- [ ] E2E: Init in bare project - happy path
+  - **Command:** init
+  - **CWD:** e2e/fixtures/bare-project
+  - **Steps:**
+    1. Open bridge with init command -> Welcome screen renders
+    2. Arrow down to select option -> Option highlighted
+    3. Press Enter -> Next screen appears
+  - **Verify:** "initialized" text visible in terminal
+{{else}}
 Browser-based tests executed via Playwright MCP tools.
 
 - [ ] E2E: [Scenario name] - [brief description]
@@ -67,6 +89,7 @@ Example E2E scenario:
     5. Wait for "Thank You!" -> Success card displays
   - **Verify:** "successfully submitted" text visible
   - **Database check:** SELECT * FROM survey_responses WHERE survey_id = '{surveyId}'
+{{/if}}
 
 ## Done
 - [x] Completed task - [commit hash]

package/dist/templates/prompts/PROMPT_review_auto.md.tmpl

@@ -90,12 +90,17 @@ Run: git diff main
 
 Respond with:
 - APPROVED if everything looks good
-- Or list specific issues with file:line references that need to be fixed"
+- Or list specific issues with file:line references that need to be fixed
+
+IMPORTANT: After posting any PR review comment, you MUST print your final verdict as the LAST line of your output. Print exactly one of:
+  VERDICT: APPROVED
+  VERDICT: NOT APPROVED
+This line is parsed by the automation — do not omit it."
 fi
 ```
 
 **Handle review feedback:**
-- If Claude outputs "APPROVED" -> Done. The PR is ready for manual merge by the user.
+- If Claude outputs "VERDICT: APPROVED" -> Done. The PR is ready for manual merge by the user.
 - If Claude lists issues:
   1. Address each issue with code fixes
   2. Commit: `git -C {{appDir}} add -A && git -C {{appDir}} commit -m "fix($FEATURE): address review feedback"`

package/dist/templates/prompts/PROMPT_review_merge.md.tmpl

@@ -90,12 +90,17 @@ Run: git diff main
 
 Respond with:
 - APPROVED if everything looks good
-- Or list specific issues with file:line references that need to be fixed"
+- Or list specific issues with file:line references that need to be fixed
+
+IMPORTANT: After posting any PR review comment, you MUST print your final verdict as the LAST line of your output. Print exactly one of:
+  VERDICT: APPROVED
+  VERDICT: NOT APPROVED
+This line is parsed by the automation — do not omit it."
 fi
 ```
 
 **Handle review feedback:**
-- If Claude outputs "APPROVED" -> Proceed to Step 5 (rebase and merge)
+- If Claude outputs "VERDICT: APPROVED" -> Proceed to Step 5 (rebase and merge)
 - If Claude lists issues:
   1. Address each issue with code fixes
   2. Commit: `git -C {{appDir}} add -A && git -C {{appDir}} commit -m "fix($FEATURE): address review feedback"`