wiggum-cli 0.16.0 → 0.17.0

package/dist/agent/tools/backlog.js

@@ -0,0 +1,51 @@
+import { tool, zodSchema } from 'ai';
+import { z } from 'zod';
+import { listRepoIssues, fetchGitHubIssue } from '../../utils/github.js';
+const DEPENDENCY_PATTERN = /\b(?:depends on|blocked by|requires|after)\s+#(\d+)/gi;
+function extractDependencyHints(body) {
+    const matches = [...body.matchAll(DEPENDENCY_PATTERN)];
+    const numbers = matches.map(m => parseInt(m[1], 10));
+    return [...new Set(numbers)].sort((a, b) => a - b);
+}
+export function createBacklogTools(owner, repo, options = {}) {
+    const listIssues = tool({
+        description: 'List open GitHub issues from the backlog, optionally filtered by labels or milestone.',
+        inputSchema: zodSchema(z.object({
+            labels: z.array(z.string()).optional().describe('Filter by these labels (merged with configured defaults)'),
+            milestone: z.string().optional().describe('Filter by milestone name'),
+            limit: z.number().int().min(1).max(100).default(20).describe('Max issues to return'),
+        })),
+        execute: async ({ labels, milestone, limit }) => {
+            const parts = [];
+            // Merge default labels with any the agent provides
+            const allLabels = [...(options.defaultLabels ?? []), ...(labels ?? [])];
+            const uniqueLabels = [...new Set(allLabels)];
+            if (uniqueLabels.length)
+                parts.push(...uniqueLabels.map(l => `label:${l}`));
+            if (milestone)
+                parts.push(`milestone:${milestone}`);
+            const search = parts.length > 0 ? parts.join(' ') : undefined;
+            const result = await listRepoIssues(owner, repo, search, limit);
+            if (result.error)
+                return { issues: [], error: result.error };
+            // Sort by issue number ascending — lower numbers are typically more foundational
+            const sorted = [...result.issues].sort((a, b) => a.number - b.number);
+            return { issues: sorted };
+        },
+    });
+    const readIssue = tool({
+        description: 'Read full details of a GitHub issue including body and labels.',
+        inputSchema: zodSchema(z.object({
+            issueNumber: z.number().int().min(1).describe('The issue number to read'),
+        })),
+        execute: async ({ issueNumber }) => {
+            const detail = await fetchGitHubIssue(owner, repo, issueNumber);
+            if (!detail)
+                return { error: `Issue #${issueNumber} not found` };
+            // Extract dependency hints from body (e.g. "depends on #1", "blocked by #3")
+            const dependsOn = extractDependencyHints(detail.body);
+            return { ...detail, dependsOn };
+        },
+    });
+    return { listIssues, readIssue };
+}

package/dist/agent/tools/dry-run.d.ts

@@ -0,0 +1,106 @@
+export declare function createDryRunExecutionTools(): {
+    generateSpec: import("ai").Tool<{
+        featureName: string;
+        issueNumber: number;
+        goals?: string | undefined;
+        model?: string | undefined;
+        provider?: string | undefined;
+    }, {
+        success: boolean;
+        specPath: string;
+        dryRun: boolean;
+    }>;
+    runLoop: import("ai").Tool<{
+        featureName: string;
+        worktree: boolean;
+        resume: boolean;
+        reviewMode?: "manual" | "auto" | "merge" | undefined;
+    }, {
+        status: string;
+        iterations: number;
+        dryRun: boolean;
+    }>;
+    checkLoopStatus: import("ai").Tool<{
+        featureName: string;
+    }, {
+        status: string;
+        iteration: number;
+        maxIterations: number;
+        dryRun: boolean;
+    }>;
+};
+export declare function createDryRunReportingTools(): {
+    commentOnIssue: import("ai").Tool<{
+        issueNumber: number;
+        body: string;
+    }, {
+        success: boolean;
+        dryRun: boolean;
+        wouldComment: {
+            issueNumber: number;
+            bodyLength: number;
+        };
+    }>;
+    createIssue: import("ai").Tool<{
+        title: string;
+        body: string;
+        labels: string[];
+    }, {
+        success: boolean;
+        dryRun: boolean;
+        wouldCreate: {
+            title: string;
+        };
+    }>;
+    closeIssue: import("ai").Tool<{
+        issueNumber: number;
+        comment?: string | undefined;
+    }, {
+        success: boolean;
+        dryRun: boolean;
+        wouldClose: {
+            issueNumber: number;
+        };
+    }>;
+    checkAllBoxes: import("ai").Tool<{
+        issueNumber: number;
+    }, {
+        success: boolean;
+        dryRun: boolean;
+        wouldCheck: {
+            issueNumber: number;
+        };
+    }>;
+};
+export declare function createDryRunFeatureStateTools(): {
+    assessFeatureState: import("ai").Tool<{
+        featureName: string;
+        issueNumber?: number | undefined;
+    }, {
+        featureName: string;
+        branch: {
+            exists: boolean;
+            commitsAhead: number;
+        };
+        spec: {
+            exists: boolean;
+        };
+        plan: {
+            exists: boolean;
+            totalTasks: number;
+            completedTasks: number;
+            completionPercent: number;
+        };
+        pr: {
+            exists: boolean;
+        };
+        linkedPr: {
+            exists: boolean;
+        };
+        loopStatus: {
+            hasStatusFiles: boolean;
+        };
+        recommendation: "start_fresh";
+        dryRun: boolean;
+    }>;
+};

package/dist/agent/tools/dry-run.js

@@ -0,0 +1,119 @@
+import { tool, zodSchema } from 'ai';
+import { z } from 'zod';
+import { FEATURE_NAME_SCHEMA } from './schemas.js';
+export function createDryRunExecutionTools() {
+    const generateSpec = tool({
+        description: '[DRY RUN] Simulates spec generation — returns a mock spec path without spawning any process.',
+        inputSchema: zodSchema(z.object({
+            featureName: FEATURE_NAME_SCHEMA,
+            issueNumber: z.number().int().describe('GitHub issue number'),
+            goals: z.string().optional().describe('Feature goals'),
+            model: z.string().optional().describe('Model override'),
+            provider: z.string().optional().describe('Provider override'),
+        })),
+        execute: async ({ featureName }) => ({
+            success: true,
+            specPath: `.ralph/specs/${featureName}.md`,
+            dryRun: true,
+        }),
+    });
+    const runLoop = tool({
+        description: '[DRY RUN] Simulates running the dev loop — returns a mock result without spawning any process.',
+        inputSchema: zodSchema(z.object({
+            featureName: FEATURE_NAME_SCHEMA,
+            worktree: z.boolean().default(true).describe('Use git worktree isolation'),
+            reviewMode: z.enum(['manual', 'auto', 'merge']).optional().describe("Review mode: 'manual' (stop at PR), 'auto' (review, no merge), or 'merge' (review + merge)"),
+            resume: z.boolean().default(false).describe('Resume a previous loop session'),
+        })),
+        execute: async () => ({
+            status: 'done',
+            iterations: 3,
+            dryRun: true,
+        }),
+    });
+    const checkLoopStatus = tool({
+        description: '[DRY RUN] Simulates checking loop status.',
+        inputSchema: zodSchema(z.object({
+            featureName: FEATURE_NAME_SCHEMA,
+        })),
+        execute: async () => ({
+            status: 'done',
+            iteration: 3,
+            maxIterations: 10,
+            dryRun: true,
+        }),
+    });
+    return { generateSpec, runLoop, checkLoopStatus };
+}
+export function createDryRunReportingTools() {
+    const commentOnIssue = tool({
+        description: '[DRY RUN] Simulates posting a comment on a GitHub issue without actually posting.',
+        inputSchema: zodSchema(z.object({
+            issueNumber: z.number().int().describe('Issue number'),
+            body: z.string().describe('Comment body'),
+        })),
+        execute: async ({ issueNumber, body }) => ({
+            success: true,
+            dryRun: true,
+            wouldComment: { issueNumber, bodyLength: body.length },
+        }),
+    });
+    const createIssue = tool({
+        description: '[DRY RUN] Simulates creating a GitHub issue without actually creating it.',
+        inputSchema: zodSchema(z.object({
+            title: z.string().describe('Issue title'),
+            body: z.string().describe('Issue body'),
+            labels: z.array(z.string()).default([]).describe('Labels'),
+        })),
+        execute: async ({ title }) => ({
+            success: true,
+            dryRun: true,
+            wouldCreate: { title },
+        }),
+    });
+    const closeIssue = tool({
+        description: '[DRY RUN] Simulates closing a GitHub issue without actually closing it.',
+        inputSchema: zodSchema(z.object({
+            issueNumber: z.number().int().describe('Issue number'),
+            comment: z.string().optional().describe('Closing comment'),
+        })),
+        execute: async ({ issueNumber }) => ({
+            success: true,
+            dryRun: true,
+            wouldClose: { issueNumber },
+        }),
+    });
+    const checkAllBoxes = tool({
+        description: '[DRY RUN] Simulates checking all acceptance-criteria checkboxes.',
+        inputSchema: zodSchema(z.object({
+            issueNumber: z.number().int().describe('Issue number'),
+        })),
+        execute: async ({ issueNumber }) => ({
+            success: true,
+            dryRun: true,
+            wouldCheck: { issueNumber },
+        }),
+    });
+    return { commentOnIssue, createIssue, closeIssue, checkAllBoxes };
+}
+export function createDryRunFeatureStateTools() {
+    const assessFeatureState = tool({
+        description: '[DRY RUN] Simulates assessing feature state — returns a mock start_fresh recommendation.',
+        inputSchema: zodSchema(z.object({
+            featureName: FEATURE_NAME_SCHEMA,
+            issueNumber: z.number().int().optional().describe('GitHub issue number — enables linked PR detection when the feature was shipped under a different branch name'),
+        })),
+        execute: async ({ featureName }) => ({
+            featureName,
+            branch: { exists: false, commitsAhead: 0 },
+            spec: { exists: false },
+            plan: { exists: false, totalTasks: 0, completedTasks: 0, completionPercent: 0 },
+            pr: { exists: false },
+            linkedPr: { exists: false },
+            loopStatus: { hasStatusFiles: false },
+            recommendation: 'start_fresh',
+            dryRun: true,
+        }),
+    });
+    return { assessFeatureState };
+}

package/dist/agent/tools/execution.d.ts

@@ -0,0 +1,51 @@
+export interface ExecutionToolsOptions {
+    onProgress?: (toolName: string, line: string) => void;
+}
+export declare function createExecutionTools(projectRoot: string, options?: ExecutionToolsOptions): {
+    generateSpec: import("ai").Tool<{
+        featureName: string;
+        issueNumber: number;
+        goals?: string | undefined;
+        model?: string | undefined;
+        provider?: string | undefined;
+    }, {
+        success: boolean;
+        specPath?: string;
+        error?: string;
+    }>;
+    runLoop: import("ai").Tool<{
+        featureName: string;
+        worktree: boolean;
+        resume: boolean;
+        reviewMode?: "manual" | "auto" | "merge" | undefined;
+    }, {
+        status: string;
+        iterations?: number;
+        error?: string;
+        logPath: string;
+    }>;
+    checkLoopStatus: import("ai").Tool<{
+        featureName: string;
+    }, {
+        status: string;
+        iteration: number | undefined;
+        maxIterations: number | undefined;
+        timestamp: string;
+        logPath: string;
+        lastPhase?: undefined;
+    } | {
+        status: string;
+        lastPhase: string;
+        logPath: string;
+        iteration?: undefined;
+        maxIterations?: undefined;
+        timestamp?: undefined;
+    } | {
+        status: string;
+        logPath: string;
+        iteration?: undefined;
+        maxIterations?: undefined;
+        timestamp?: undefined;
+        lastPhase?: undefined;
+    }>;
+};

package/dist/agent/tools/execution.js

@@ -0,0 +1,256 @@
+import { tool, zodSchema } from 'ai';
+import { z } from 'zod';
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, openSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { FEATURE_NAME_SCHEMA } from './schemas.js';
+import { runPreflightChecks } from './preflight.js';
+import { loadConfigWithDefaults } from '../../utils/config.js';
+const SPEC_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+const LOOP_TIMEOUT_MS = 60 * 60 * 1000; // 60 minutes
+const MAX_STDERR_BYTES = 256 * 1024; // 256 KB — only tail matters for error reporting
+const MAX_STDOUT_BYTES = 64 * 1024; // 64 KB — only last line used (spec path)
+function killWithTimeout(proc, timeoutMs) {
+    let fired = false;
+    const timer = setTimeout(() => {
+        fired = true;
+        proc.kill('SIGTERM');
+        const escalation = setTimeout(() => {
+            if (!proc.killed)
+                proc.kill('SIGKILL');
+        }, 5000);
+        escalation.unref();
+    }, timeoutMs);
+    return { timer, didTimeout: () => fired };
+}
+export function createExecutionTools(projectRoot, options) {
+    const emitProgress = options?.onProgress;
+    const generateSpec = tool({
+        description: 'Generate a feature spec from a GitHub issue using the interview agent in headless mode. Returns the spec file path on success.',
+        inputSchema: zodSchema(z.object({
+            featureName: FEATURE_NAME_SCHEMA,
+            issueNumber: z.number().int().describe('GitHub issue number to use as context'),
+            goals: z.string().optional().describe('Feature goals description'),
+            model: z.string().optional().describe('Model override (e.g. gpt-5.3-codex)'),
+            provider: z.string().optional().describe('Provider override (anthropic, openai, openrouter)'),
+        })),
+        execute: async ({ featureName, issueNumber, goals, model, provider }, { abortSignal }) => {
+            if (abortSignal?.aborted)
+                return { success: false, error: 'Aborted' };
+            return new Promise((resolve) => {
+                const args = ['new', featureName, '--auto', '--issue', String(issueNumber)];
+                if (goals)
+                    args.push('--goals', goals);
+                if (model)
+                    args.push('--model', model);
+                if (provider)
+                    args.push('--provider', provider);
+                const proc = spawn('wiggum', args, { cwd: projectRoot, stdio: 'pipe', env: { ...process.env, RALPH_AUTOMATED: '1' } });
+                const { timer, didTimeout } = killWithTimeout(proc, SPEC_TIMEOUT_MS);
+                let stdout = '';
+                let stderr = '';
+                let aborted = false;
+                let resolved = false;
+                const onAbort = () => {
+                    aborted = true;
+                    proc.kill('SIGTERM');
+                };
+                abortSignal?.addEventListener('abort', onAbort, { once: true });
+                proc.stdout?.on('data', (d) => {
+                    stdout += d.toString();
+                    if (stdout.length > MAX_STDOUT_BYTES)
+                        stdout = stdout.slice(-MAX_STDOUT_BYTES);
+                });
+                proc.stderr?.on('data', (d) => {
+                    const chunk = d.toString();
+                    stderr += chunk;
+                    if (stderr.length > MAX_STDERR_BYTES)
+                        stderr = stderr.slice(-MAX_STDERR_BYTES);
+                    if (emitProgress) {
+                        for (const line of chunk.split('\n')) {
+                            const trimmed = line.trim();
+                            if (trimmed)
+                                emitProgress('generateSpec', trimmed);
+                        }
+                    }
+                });
+                proc.on('close', (code) => {
+                    if (resolved)
+                        return;
+                    resolved = true;
+                    clearTimeout(timer);
+                    abortSignal?.removeEventListener('abort', onAbort);
+                    if (aborted) {
+                        resolve({ success: false, error: 'Aborted' });
+                    }
+                    else if (didTimeout()) {
+                        resolve({ success: false, error: `Timed out after ${SPEC_TIMEOUT_MS / 60000}m` });
+                    }
+                    else if (code === 0) {
+                        const specPath = stdout.trim().split('\n').pop() ?? '';
+                        resolve({ success: true, specPath });
+                    }
+                    else {
+                        resolve({ success: false, error: stderr.trim() || `Exit code ${code}` });
+                    }
+                });
+                proc.on('error', (err) => {
+                    if (resolved)
+                        return;
+                    resolved = true;
+                    clearTimeout(timer);
+                    abortSignal?.removeEventListener('abort', onAbort);
+                    resolve({ success: false, error: err.message });
+                });
+            });
+        },
+    });
+    const runLoop = tool({
+        description: 'Run the development loop for a feature. Spawns a background process and returns when complete. The loop uses Claude Code internally with its own model config — do NOT forward the agent model here.',
+        inputSchema: zodSchema(z.object({
+            featureName: FEATURE_NAME_SCHEMA,
+            worktree: z.boolean().default(true).describe('Use git worktree isolation'),
+            reviewMode: z.enum(['manual', 'auto', 'merge']).optional().describe("Review mode: 'manual' (stop at PR), 'auto' (review, no merge), or 'merge' (review + merge)"),
+            resume: z.boolean().default(false).describe('Resume a previous loop session instead of starting fresh'),
+        })),
+        execute: async ({ featureName, worktree, reviewMode, resume }, { abortSignal }) => {
+            const logPath = join('/tmp', `ralph-loop-${featureName}.log`);
+            if (abortSignal?.aborted)
+                return { status: 'aborted', error: 'Aborted', logPath };
+            // Spec existence check — catch "forgot to call generateSpec" before spawning.
+            // Skip when resuming: the spec lives on the feature branch and the shell
+            // script validates it after checkout. Checking here would fail because
+            // the agent runs on main where the spec doesn't exist yet.
+            if (!resume) {
+                let specsDir = '.ralph/specs';
+                try {
+                    const config = await loadConfigWithDefaults(projectRoot);
+                    specsDir = config.paths.specs;
+                }
+                catch { /* non-fatal, use default */ }
+                const specPath = join(projectRoot, specsDir, `${featureName}.md`);
+                if (!existsSync(specPath)) {
+                    return {
+                        status: 'spec_missing',
+                        error: `Spec file not found: ${specPath}. Call generateSpec first.`,
+                        logPath,
+                    };
+                }
+            }
+            // Pre-flight checks
+            const preflight = await runPreflightChecks(projectRoot, featureName, emitProgress);
+            if (!preflight.ok) {
+                return { status: 'preflight_failed', error: preflight.error, logPath };
+            }
+            // Signal loop start immediately — the subprocess writes to stdout (log file),
+            // not stderr, so the piped stderr stream won't carry progress events.
+            // This triggers TUI polling for temp file updates.
+            emitProgress?.('runLoop', `Ralph Loop: ${featureName}`);
+            return new Promise((resolve) => {
+                const args = ['run', featureName];
+                if (worktree)
+                    args.push('--worktree');
+                if (reviewMode)
+                    args.push('--review-mode', reviewMode);
+                if (resume)
+                    args.push('--resume');
+                // Route stdout to log file so echo statements from the shell script populate the activity feed.
+                // stderr is piped for progress reporting; stdin is ignored.
+                const logFd = openSync(logPath, 'a');
+                const proc = spawn('wiggum', args, { cwd: projectRoot, stdio: ['ignore', logFd, 'pipe'], env: { ...process.env, RALPH_AUTOMATED: '1' } });
+                closeSync(logFd); // close parent's copy; child inherits its own fd
+                const { timer, didTimeout } = killWithTimeout(proc, LOOP_TIMEOUT_MS);
+                let stderr = '';
+                let aborted = false;
+                let resolved = false;
+                const onAbort = () => {
+                    aborted = true;
+                    proc.kill('SIGTERM');
+                };
+                abortSignal?.addEventListener('abort', onAbort, { once: true });
+                proc.stderr?.on('data', (d) => {
+                    const chunk = d.toString();
+                    stderr += chunk;
+                    if (stderr.length > MAX_STDERR_BYTES)
+                        stderr = stderr.slice(-MAX_STDERR_BYTES);
+                    if (emitProgress) {
+                        for (const line of chunk.split('\n')) {
+                            const trimmed = line.trim();
+                            if (trimmed)
+                                emitProgress('runLoop', trimmed);
+                        }
+                    }
+                });
+                proc.on('close', (code) => {
+                    if (resolved)
+                        return;
+                    resolved = true;
+                    clearTimeout(timer);
+                    abortSignal?.removeEventListener('abort', onAbort);
+                    const finalPath = join('/tmp', `ralph-loop-${featureName}.final`);
+                    if (aborted) {
+                        resolve({ status: 'aborted', error: 'Aborted', logPath });
+                    }
+                    else if (didTimeout()) {
+                        resolve({ status: 'timeout', error: `Timed out after ${LOOP_TIMEOUT_MS / 60000}m`, logPath });
+                    }
+                    else if (existsSync(finalPath)) {
+                        const parts = readFileSync(finalPath, 'utf-8').trim().split('|');
+                        resolve({
+                            status: parts[3] ?? (code === 0 ? 'done' : 'failed'),
+                            iterations: parseInt(parts[0], 10) || undefined,
+                            logPath,
+                        });
+                    }
+                    else {
+                        resolve({
+                            status: code === 0 ? 'done' : 'failed',
+                            error: stderr.trim() || undefined,
+                            logPath,
+                        });
+                    }
+                });
+                proc.on('error', (err) => {
+                    if (resolved)
+                        return;
+                    resolved = true;
+                    clearTimeout(timer);
+                    abortSignal?.removeEventListener('abort', onAbort);
+                    resolve({ status: 'error', error: err.message, logPath });
+                });
+            });
+        },
+    });
+    const checkLoopStatus = tool({
+        description: 'Check the current status of a running or completed development loop.',
+        inputSchema: zodSchema(z.object({
+            featureName: FEATURE_NAME_SCHEMA,
+        })),
+        execute: async ({ featureName }) => {
+            const prefix = join('/tmp', `ralph-loop-${featureName}`);
+            const logPath = `${prefix}.log`;
+            const finalPath = `${prefix}.final`;
+            if (existsSync(finalPath)) {
+                const parts = readFileSync(finalPath, 'utf-8').trim().split('|');
+                return {
+                    status: parts[3] ?? 'unknown',
+                    iteration: parseInt(parts[0], 10) || undefined,
+                    maxIterations: parseInt(parts[1], 10) || undefined,
+                    timestamp: parts[2] ?? undefined,
+                    logPath,
+                };
+            }
+            const phasesPath = `${prefix}.phases`;
+            if (existsSync(phasesPath)) {
+                const lines = readFileSync(phasesPath, 'utf-8').trim().split('\n');
+                const lastLine = lines[lines.length - 1];
+                return { status: 'running', lastPhase: lastLine, logPath };
+            }
+            if (existsSync(logPath)) {
+                return { status: 'possibly_running', logPath };
+            }
+            return { status: 'not_found', logPath };
+        },
+    });
+    return { generateSpec, runLoop, checkLoopStatus };
+}

package/dist/agent/tools/feature-state.d.ts

@@ -0,0 +1,43 @@
+export type Recommendation = 'start_fresh' | 'generate_plan' | 'resume_implementation' | 'resume_pr_phase' | 'pr_exists_open' | 'pr_merged' | 'pr_closed' | 'linked_pr_merged' | 'linked_pr_open';
+export interface FeatureState {
+    featureName: string;
+    branch: {
+        exists: boolean;
+        commitsAhead: number;
+    };
+    spec: {
+        exists: boolean;
+        path?: string;
+    };
+    plan: {
+        exists: boolean;
+        path?: string;
+        totalTasks: number;
+        completedTasks: number;
+        completionPercent: number;
+    };
+    pr: {
+        exists: boolean;
+        state?: 'OPEN' | 'MERGED' | 'CLOSED';
+        number?: number;
+        url?: string;
+    };
+    linkedPr: {
+        exists: boolean;
+        state?: 'OPEN' | 'MERGED' | 'CLOSED';
+        number?: number;
+        url?: string;
+        headRefName?: string;
+    };
+    loopStatus: {
+        hasStatusFiles: boolean;
+    };
+    recommendation: Recommendation;
+}
+export declare function assessFeatureStateImpl(projectRoot: string, featureName: string, issueNumber?: number): Promise<FeatureState>;
+export declare function createFeatureStateTools(projectRoot: string): {
+    assessFeatureState: import("ai").Tool<{
+        featureName: string;
+        issueNumber?: number | undefined;
+    }, FeatureState>;
+};