wiggum-cli 0.16.0 → 0.17.0

package/dist/agent/tools/feature-state.js

@@ -0,0 +1,184 @@
+import { tool, zodSchema } from 'ai';
+import { z } from 'zod';
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { FEATURE_NAME_SCHEMA } from './schemas.js';
+import { loadConfigWithDefaults } from '../../utils/config.js';
+import { findImplementationPlan, parseImplementationPlan } from '../../tui/utils/loop-status.js';
+const execFileAsync = promisify(execFile);
+function computeRecommendation(state) {
+    // PR state takes priority
+    if (state.pr.exists) {
+        if (state.pr.state === 'MERGED')
+            return 'pr_merged';
+        if (state.pr.state === 'CLOSED')
+            return 'pr_closed';
+        if (state.pr.state === 'OPEN')
+            return 'pr_exists_open';
+    }
+    // Linked PR (found via issue search, different branch name)
+    if (state.linkedPr.exists) {
+        if (state.linkedPr.state === 'MERGED')
+            return 'linked_pr_merged';
+        if (state.linkedPr.state === 'OPEN')
+            return 'linked_pr_open';
+    }
+    // Plan with all tasks done but no PR → resume to PR phase
+    if (state.plan.exists && state.plan.totalTasks > 0 && state.plan.completedTasks === state.plan.totalTasks) {
+        return 'resume_pr_phase';
+    }
+    // Plan with pending tasks → resume implementation
+    if (state.plan.exists && state.plan.totalTasks > 0 && state.plan.completedTasks < state.plan.totalTasks) {
+        return 'resume_implementation';
+    }
+    // Branch has commits but no plan found locally — the plan likely
+    // exists on the feature branch while we're checking from main.
+    // Recommend resume so the loop switches to the branch and picks up the work.
+    // This MUST come before the generate_plan check to prevent branch reset
+    // via `git checkout -B` which would destroy existing work.
+    if (state.branch.exists && state.branch.commitsAhead > 0) {
+        return 'resume_implementation';
+    }
+    // Spec exists but no plan → generate plan (fresh loop, no branch work to lose)
+    if (state.spec.exists) {
+        return 'generate_plan';
+    }
+    return 'start_fresh';
+}
+export async function assessFeatureStateImpl(projectRoot, featureName, issueNumber) {
+    const opts = { cwd: projectRoot };
+    const branchName = `feat/${featureName}`;
+    // 1. Check branch
+    let branchExists = false;
+    let commitsAhead = 0;
+    try {
+        await execFileAsync('git', ['rev-parse', '--verify', branchName], opts);
+        branchExists = true;
+        // Count commits ahead of default branch
+        let defaultBranch = 'main';
+        try {
+            const { stdout } = await execFileAsync('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], opts);
+            defaultBranch = stdout.trim().replace(/^origin\//, '');
+        }
+        catch {
+            // fall back to main
+        }
+        try {
+            const { stdout } = await execFileAsync('git', ['rev-list', '--count', `${defaultBranch}..${branchName}`], opts);
+            commitsAhead = parseInt(stdout.trim(), 10) || 0;
+        }
+        catch {
+            // count failure is non-fatal
+        }
+    }
+    catch {
+        // branch doesn't exist
+    }
+    // 2. Load config for correct paths
+    let specsDir = '.ralph/specs';
+    try {
+        const config = await loadConfigWithDefaults(projectRoot);
+        specsDir = config.paths.specs;
+    }
+    catch {
+        // Config load failure is non-fatal — use default paths
+    }
+    // 3. Check spec
+    const specPath = join(projectRoot, specsDir, `${featureName}.md`);
+    const specExists = existsSync(specPath);
+    // 4. Check implementation plan using shared utility (handles worktrees too)
+    const planPath = findImplementationPlan(projectRoot, specsDir, featureName);
+    const planExists = planPath !== null;
+    let totalTasks = 0;
+    let completedTasks = 0;
+    if (planExists) {
+        try {
+            const taskCounts = await parseImplementationPlan(projectRoot, featureName, specsDir);
+            completedTasks = taskCounts.tasksDone + taskCounts.e2eDone;
+            totalTasks = completedTasks + taskCounts.tasksPending + taskCounts.e2ePending;
+        }
+        catch {
+            // parse failure is non-fatal
+        }
+    }
+    // 5. Check PR via gh CLI
+    let prExists = false;
+    let prState;
+    let prNumber;
+    let prUrl;
+    try {
+        const { stdout } = await execFileAsync('gh', [
+            'pr', 'list',
+            '--head', branchName,
+            '--state', 'all',
+            '--json', 'number,state,url',
+            '--limit', '1',
+        ], { ...opts, timeout: 15000 });
+        const prs = JSON.parse(stdout.trim() || '[]');
+        if (prs.length > 0) {
+            prExists = true;
+            prState = prs[0].state;
+            prNumber = prs[0].number;
+            prUrl = prs[0].url;
+        }
+    }
+    catch {
+        // gh failure is non-fatal — tool works without GitHub CLI
+    }
+    // 6. Linked PR search (only when issueNumber provided and no branch-name PR found)
+    let linkedPrExists = false;
+    let linkedPrState;
+    let linkedPrNumber;
+    let linkedPrUrl;
+    let linkedPrHeadRefName;
+    if (issueNumber != null && !prExists) {
+        try {
+            const { stdout } = await execFileAsync('gh', [
+                'pr', 'list',
+                '--search', `in:body "closes #${issueNumber}" OR in:body "fixes #${issueNumber}" OR in:body "resolves #${issueNumber}"`,
+                '--state', 'all',
+                '--json', 'number,state,url,headRefName',
+                '--limit', '1',
+            ], { ...opts, timeout: 15000 });
+            const prs = JSON.parse(stdout.trim() || '[]');
+            if (prs.length > 0) {
+                linkedPrExists = true;
+                linkedPrState = prs[0].state;
+                linkedPrNumber = prs[0].number;
+                linkedPrUrl = prs[0].url;
+                linkedPrHeadRefName = prs[0].headRefName;
+            }
+        }
+        catch {
+            // gh failure is non-fatal
+        }
+    }
+    // 7. Check loop status files
+    const prefix = join('/tmp', `ralph-loop-${featureName}`);
+    const hasStatusFiles = existsSync(`${prefix}.final`) || existsSync(`${prefix}.phases`) || existsSync(`${prefix}.log`);
+    const partial = {
+        featureName,
+        branch: { exists: branchExists, commitsAhead },
+        spec: { exists: specExists, path: specExists ? specPath : undefined },
+        plan: { exists: planExists, path: planPath ?? undefined, totalTasks, completedTasks, completionPercent: totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0 },
+        pr: { exists: prExists, state: prState, number: prNumber, url: prUrl },
+        linkedPr: { exists: linkedPrExists, state: linkedPrState, number: linkedPrNumber, url: linkedPrUrl, headRefName: linkedPrHeadRefName },
+        loopStatus: { hasStatusFiles },
+    };
+    return { ...partial, recommendation: computeRecommendation(partial) };
+}
+export function createFeatureStateTools(projectRoot) {
+    const assessFeatureState = tool({
+        description: 'Assess the current state of a feature: branch, spec, plan, PR, loop status. Returns a recommendation for what action to take next. MUST be called before generateSpec or runLoop.',
+        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, issueNumber }) => {
+            return assessFeatureStateImpl(projectRoot, featureName, issueNumber);
+        },
+    });
+    return { assessFeatureState };
+}

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

@@ -0,0 +1,23 @@
+export declare function createIntrospectionTools(projectRoot: string): {
+    readLoopLog: import("ai").Tool<{
+        featureName: string;
+        tailLines: number;
+    }, {
+        error: string;
+        lines?: undefined;
+        totalLines?: undefined;
+    } | {
+        lines: string[];
+        totalLines: number;
+        error?: undefined;
+    }>;
+    syncContext: import("ai").Tool<Record<string, never>, {
+        success: boolean;
+        contextPath: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        contextPath?: undefined;
+    }>;
+};

package/dist/agent/tools/introspection.js

@@ -0,0 +1,40 @@
+import { tool, zodSchema } from 'ai';
+import { z } from 'zod';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FEATURE_NAME_SCHEMA } from './schemas.js';
+export function createIntrospectionTools(projectRoot) {
+    const readLoopLog = tool({
+        description: 'Read the stdout/stderr log of a development loop (running or completed).',
+        inputSchema: zodSchema(z.object({
+            featureName: FEATURE_NAME_SCHEMA,
+            tailLines: z.number().int().min(1).max(500).default(100).describe('Number of lines from the end'),
+        })),
+        execute: async ({ featureName, tailLines }) => {
+            const logPath = join('/tmp', `ralph-loop-${featureName}.log`);
+            if (!existsSync(logPath)) {
+                return { error: `No log found at ${logPath} — verify featureName matches exactly what runLoop used` };
+            }
+            const content = await readFile(logPath, 'utf-8');
+            const allLines = content.split('\n');
+            const lines = allLines.slice(-tailLines);
+            return { lines, totalLines: allLines.length };
+        },
+    });
+    const syncContext = tool({
+        description: 'Refresh project context by scanning the codebase and running AI analysis. Call before planning if context is stale.',
+        inputSchema: zodSchema(z.object({})),
+        execute: async () => {
+            const { syncProjectContext } = await import('../../commands/sync.js');
+            try {
+                const contextPath = await syncProjectContext(projectRoot);
+                return { success: true, contextPath };
+            }
+            catch (err) {
+                return { success: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    });
+    return { readLoopLog, syncContext };
+}

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

@@ -0,0 +1,44 @@
+import type { MemoryStore } from '../memory/store.js';
+export declare const REFLECT_TOOL_NAME = "reflectOnWork";
+export declare function createMemoryTools(store: MemoryStore, projectRoot?: string): {
+    readMemory: import("ai").Tool<{
+        limit: number;
+        type?: "work_log" | "project_knowledge" | "decision" | "strategic_context" | undefined;
+        search?: string | undefined;
+    }, {
+        entries: import("../memory/types.js").MemoryEntry[];
+    }>;
+    writeMemory: import("ai").Tool<{
+        type: "work_log" | "project_knowledge" | "decision";
+        content: string;
+        tags?: string[] | undefined;
+        relatedIssue?: number | undefined;
+    }, {
+        id: string;
+        timestamp: string;
+    }>;
+    reflectOnWork: import("ai").Tool<{
+        issueNumber: number;
+        outcome: "success" | "skipped" | "partial" | "failure";
+        whatWorked: string;
+        whatFailed: string;
+        patternDiscovered?: string | undefined;
+        specQualityNote?: string | undefined;
+    }, {
+        memoriesWritten: number;
+    }>;
+    listStrategicDocs: import("ai").Tool<Record<string, never>, {
+        files: string[];
+    }>;
+    readStrategicDoc: import("ai").Tool<{
+        filename: string;
+    }, {
+        error: string;
+        filename?: undefined;
+        content?: undefined;
+    } | {
+        filename: string;
+        content: string;
+        error?: undefined;
+    }>;
+};

package/dist/agent/tools/memory.js

@@ -0,0 +1,99 @@
+import { tool, zodSchema } from 'ai';
+import { z } from 'zod';
+import { createMemoryEntry } from '../memory/types.js';
+import { listStrategicDocs, readStrategicDoc, } from '../memory/ingest.js';
+export const REFLECT_TOOL_NAME = 'reflectOnWork';
+export function createMemoryTools(store, projectRoot) {
+    const readMemory = tool({
+        description: 'Read recent memory entries. Use before planning to recall past outcomes and decisions.',
+        inputSchema: zodSchema(z.object({
+            type: z.enum(['work_log', 'project_knowledge', 'decision', 'strategic_context']).optional()
+                .describe('Filter by memory type'),
+            limit: z.number().int().min(1).max(50).default(10).describe('Max entries to return'),
+            search: z.string().optional().describe('Search term to filter by content'),
+        })),
+        execute: async ({ type, limit, search }) => {
+            const entries = await store.read({ type, limit, search });
+            return { entries };
+        },
+    });
+    const writeMemory = tool({
+        description: 'Write a memory entry. Use after completing work or learning something important.',
+        inputSchema: zodSchema(z.object({
+            type: z.enum(['work_log', 'project_knowledge', 'decision']).describe('Type of memory'),
+            content: z.string().describe('The memory content — be specific and narrative'),
+            tags: z.array(z.string()).optional().describe('Tags for filtering (e.g., auth, api)'),
+            relatedIssue: z.number().int().optional().describe('Related GitHub issue number'),
+        })),
+        execute: async ({ type, content, tags, relatedIssue }) => {
+            const entry = createMemoryEntry({ type, content, tags, relatedIssue });
+            await store.append(entry);
+            return { id: entry.id, timestamp: entry.timestamp };
+        },
+    });
+    const reflectOnWork = tool({
+        description: 'Reflect on completed work to extract learnings and patterns. Call after each issue.',
+        inputSchema: zodSchema(z.object({
+            issueNumber: z.number().int().describe('The issue that was worked on'),
+            outcome: z.enum(['success', 'partial', 'failure', 'skipped']).describe('How did it go? Use "skipped" when the issue was already complete or requires no work.'),
+            whatWorked: z.string().describe('What went well'),
+            whatFailed: z.string().describe('What went wrong or was difficult'),
+            patternDiscovered: z.string().optional().describe('Any reusable pattern discovered'),
+            specQualityNote: z.string().optional().describe('How could the spec have been better?'),
+        })),
+        execute: async ({ issueNumber, outcome, whatWorked, whatFailed, patternDiscovered, specQualityNote }) => {
+            const entries = [];
+            entries.push(createMemoryEntry({
+                type: 'work_log',
+                content: `Issue #${issueNumber} (${outcome}). Worked: ${whatWorked}. Failed: ${whatFailed}`,
+                relatedIssue: issueNumber,
+                tags: [outcome],
+            }));
+            if (patternDiscovered) {
+                entries.push(createMemoryEntry({
+                    type: 'project_knowledge',
+                    content: patternDiscovered,
+                    relatedIssue: issueNumber,
+                    tags: ['pattern'],
+                }));
+            }
+            if (specQualityNote) {
+                entries.push(createMemoryEntry({
+                    type: 'project_knowledge',
+                    content: `Spec quality (#${issueNumber}): ${specQualityNote}`,
+                    relatedIssue: issueNumber,
+                    tags: ['spec-quality'],
+                }));
+            }
+            for (const entry of entries) {
+                await store.append(entry);
+            }
+            return { memoriesWritten: entries.length };
+        },
+    });
+    const listStrategicDocsT = tool({
+        description: 'List available strategic documents in .ralph/strategic/. Returns filenames. Use readStrategicDoc to read full content.',
+        inputSchema: zodSchema(z.object({})),
+        execute: async () => {
+            if (!projectRoot)
+                return { files: [] };
+            const files = await listStrategicDocs(projectRoot);
+            return { files };
+        },
+    });
+    const readStrategicDocT = tool({
+        description: 'Read the full content of a strategic document. Use to get detailed architecture, design, or implementation plans relevant to the current task.',
+        inputSchema: zodSchema(z.object({
+            filename: z.string().describe('Filename to read (e.g. "design.md")'),
+        })),
+        execute: async ({ filename }) => {
+            if (!projectRoot)
+                return { error: 'No project root configured' };
+            const content = await readStrategicDoc(projectRoot, filename);
+            if (content === null)
+                return { error: `File not found: ${filename}` };
+            return { filename, content };
+        },
+    });
+    return { readMemory, writeMemory, reflectOnWork, listStrategicDocs: listStrategicDocsT, readStrategicDoc: readStrategicDocT };
+}

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

@@ -0,0 +1,7 @@
+export interface PreflightResult {
+    ok: boolean;
+    defaultBranch?: string;
+    stashed?: boolean;
+    error?: string;
+}
+export declare function runPreflightChecks(projectRoot: string, featureName: string, emitProgress?: (toolName: string, line: string) => void): Promise<PreflightResult>;

package/dist/agent/tools/preflight.js

@@ -0,0 +1,137 @@
+import { execFile } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export async function runPreflightChecks(projectRoot, featureName, emitProgress) {
+    const opts = { cwd: projectRoot };
+    // 1. Detect default branch
+    let defaultBranch;
+    try {
+        const { stdout } = await execFileAsync('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], opts);
+        defaultBranch = stdout.trim().replace(/^origin\//, '');
+    }
+    catch {
+        // symbolic-ref not set, try fallbacks
+    }
+    if (!defaultBranch) {
+        try {
+            await execFileAsync('git', ['rev-parse', '--verify', 'main'], opts);
+            defaultBranch = 'main';
+        }
+        catch {
+            try {
+                await execFileAsync('git', ['rev-parse', '--verify', 'master'], opts);
+                defaultBranch = 'master';
+            }
+            catch {
+                // neither exists
+            }
+        }
+    }
+    if (!defaultBranch) {
+        return { ok: false, error: 'Cannot determine default branch: no origin/HEAD, main, or master found' };
+    }
+    emitProgress?.('preflight', `Default branch: ${defaultBranch}`);
+    // 2. Clean stale worktrees
+    try {
+        await execFileAsync('git', ['worktree', 'prune'], opts);
+    }
+    catch {
+        // prune failure is non-fatal
+    }
+    const branchName = `feat/${featureName}`;
+    try {
+        const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain'], opts);
+        const worktrees = parseWorktreeList(stdout);
+        // Resolve projectRoot to compare with worktree paths
+        let resolvedRoot;
+        try {
+            resolvedRoot = realpathSync(projectRoot);
+        }
+        catch {
+            resolvedRoot = projectRoot;
+        }
+        for (const wt of worktrees) {
+            if (wt.branch === branchName || wt.branch === `refs/heads/${branchName}`) {
+                // Branch is checked out in the main worktree (projectRoot itself) —
+                // the loop script handles this case (it detects CURRENT_BRANCH == BRANCH).
+                let resolvedWtPath;
+                try {
+                    resolvedWtPath = realpathSync(wt.path);
+                }
+                catch {
+                    resolvedWtPath = wt.path;
+                }
+                if (resolvedWtPath === resolvedRoot) {
+                    emitProgress?.('preflight', `Branch ${branchName} already checked out in project root`);
+                    continue;
+                }
+                // Branch is checked out in a different worktree
+                const isEphemeral = wt.path.includes('/.claude/worktrees/');
+                if (!existsSync(wt.path) || !existsSync(`${wt.path}/.git`) || isEphemeral) {
+                    // Stale or ephemeral worktree — auto-fix
+                    emitProgress?.('preflight', `Removing ${isEphemeral ? 'ephemeral' : 'stale'} worktree at ${wt.path}`);
+                    try {
+                        await execFileAsync('git', ['worktree', 'remove', '--force', wt.path], opts);
+                    }
+                    catch {
+                        // If remove fails, try prune again
+                        await execFileAsync('git', ['worktree', 'prune'], opts).catch(() => { });
+                    }
+                }
+                else {
+                    return { ok: false, error: `Branch locked by active worktree at ${wt.path}` };
+                }
+            }
+        }
+    }
+    catch {
+        // worktree list failure is non-fatal (may not be in a git repo with worktree support)
+    }
+    // 3. Stash dirty working tree so branch switching succeeds
+    let stashed = false;
+    let dirty = false;
+    try {
+        const { stdout } = await execFileAsync('git', ['status', '--porcelain'], opts);
+        dirty = stdout.trim().length > 0;
+    }
+    catch {
+        // status check failure — proceed optimistically
+    }
+    if (dirty) {
+        emitProgress?.('preflight', 'Stashing uncommitted changes');
+        try {
+            await execFileAsync('git', ['stash', 'push', '-m', `wiggum-preflight: auto-stash before ${branchName}`], opts);
+            stashed = true;
+        }
+        catch {
+            return { ok: false, error: 'Working tree has uncommitted changes and git stash failed' };
+        }
+    }
+    return { ok: true, defaultBranch, stashed };
+}
+function parseWorktreeList(output) {
+    const entries = [];
+    let currentPath = '';
+    let currentBranch = '';
+    for (const line of output.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            currentPath = line.slice('worktree '.length);
+        }
+        else if (line.startsWith('branch ')) {
+            currentBranch = line.slice('branch '.length);
+        }
+        else if (line === '') {
+            if (currentPath && currentBranch) {
+                entries.push({ path: currentPath, branch: currentBranch });
+            }
+            currentPath = '';
+            currentBranch = '';
+        }
+    }
+    // Handle last entry without trailing newline
+    if (currentPath && currentBranch) {
+        entries.push({ path: currentPath, branch: currentBranch });
+    }
+    return entries;
+}

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

@@ -0,0 +1,58 @@
+export declare function createReportingTools(owner: string, repo: string): {
+    commentOnIssue: import("ai").Tool<{
+        issueNumber: number;
+        body: string;
+    }, {
+        success: boolean;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+    }>;
+    createIssue: import("ai").Tool<{
+        title: string;
+        body: string;
+        labels: string[];
+    }, {
+        success: boolean;
+        issueNumber: number | undefined;
+        url: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        issueNumber?: undefined;
+        url?: undefined;
+    }>;
+    closeIssue: import("ai").Tool<{
+        issueNumber: number;
+        comment?: string | undefined;
+    }, {
+        success: boolean;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+    }>;
+    checkAllBoxes: import("ai").Tool<{
+        issueNumber: number;
+    }, {
+        success: boolean;
+        changed: boolean;
+        message: string;
+        totalChecked?: undefined;
+        error?: undefined;
+    } | {
+        success: boolean;
+        changed: boolean;
+        totalChecked: number;
+        message?: undefined;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        changed?: undefined;
+        message?: undefined;
+        totalChecked?: undefined;
+    }>;
+};