@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/repl-helpers.js

@@ -0,0 +1,318 @@
+/**
+ * REPL Helper Functions
+ *
+ * Standalone utility functions extracted from repl.ts to reduce file size
+ * and improve maintainability. These functions support the REPL but don't
+ * depend on REPL instance state.
+ */
+import { builtinSkills } from '@compilr-dev/agents';
+import { codingSkills } from '@compilr-dev/agents-coding';
+import * as fs from 'fs';
+import * as path from 'path';
+import { findBacklogPath, parseBacklogItems } from './tools/backlog.js';
+import { loadCompilrConfig } from './utils/project-status.js';
+// =============================================================================
+// Tool Intent Detection
+// =============================================================================
+/**
+ * Keyword patterns for tool selection based on user input.
+ * Maps tool names to keywords that suggest the tool should be used.
+ */
+export const TOOL_KEYWORDS = {
+    read_file: ['read', 'show', 'display', 'look at', 'view', 'what is in', 'content of'],
+    write_file: ['write', 'create', 'save', 'make a file'],
+    edit: ['edit', 'modify', 'change', 'update', 'fix', 'replace'],
+    bash: ['run', 'execute', 'command', 'shell', 'npm', 'git', 'pip', 'ls', 'pwd', 'mkdir', 'build', 'install'],
+    grep: ['search', 'find', 'grep', 'look for', 'where is', 'occurrences'],
+    glob: ['list files', 'find files', 'what files', 'show files', 'directory', 'pattern'],
+    todo_write: ['todo', 'task list', 'plan', 'steps'],
+    todo_read: ['todo', 'task list', 'plan', 'steps'],
+    // Database-backed workitem tools replace file-based backlog tools
+    workitem_query: ['backlog', 'requirements', 'features', 'bugs', 'items', 'work items'],
+    workitem_add: ['backlog', 'requirements', 'features', 'bugs', 'add item', 'add feature', 'add work item'],
+    workitem_update: ['update item', 'change status', 'complete item'],
+    git_status: ['git status', 'changes', 'modified', 'staged'],
+    git_diff: ['git diff', 'differences', 'what changed'],
+    git_log: ['git log', 'history', 'commits'],
+    git_commit: ['commit', 'save changes'],
+    git_branch: ['branch', 'branches'],
+    detect_project: ['project type', 'what kind of project', 'framework'],
+    find_project_root: ['project root', 'root directory'],
+    run_tests: ['test', 'tests', 'run tests', 'check tests'],
+    run_lint: ['lint', 'linting', 'check code', 'style'],
+    // Task tool for sub-agent delegation
+    task: [
+        'explore', 'investigate', 'analyze', 'review code', 'code review',
+        'security audit', 'refactor', 'help me find', 'search the codebase',
+        'look through', 'scan for', 'debug', 'figure out', 'understand',
+        'complex', 'multi-step', 'delegate', 'sub-agent', 'agent',
+    ],
+    // User interaction tools
+    ask_user: ['ask', 'question', 'choice', 'select', 'options'],
+    ask_user_simple: ['confirm', 'yes or no', 'simple question'],
+    suggest: ['suggest', 'recommendation', 'next step'],
+};
+/**
+ * Select relevant tool names based on user input intent.
+ * Returns all tools if input is short or a question.
+ */
+export function selectToolNamesByIntent(input, allToolNames) {
+    const lower = input.toLowerCase();
+    // If input is very short or a question, use all tools
+    if (input.length < 10 || input.includes('?')) {
+        return allToolNames;
+    }
+    const selected = new Set();
+    // Add tools based on keyword matches
+    for (const [tool, keywords] of Object.entries(TOOL_KEYWORDS)) {
+        if (keywords.some((kw) => lower.includes(kw)) && allToolNames.includes(tool)) {
+            selected.add(tool);
+        }
+    }
+    // If nothing matched from keywords, use all tools
+    // (Check BEFORE adding always-included tools)
+    if (selected.size === 0) {
+        return allToolNames;
+    }
+    // Always include todo tools (they're used implicitly for task tracking)
+    if (allToolNames.includes('todo_write'))
+        selected.add('todo_write');
+    if (allToolNames.includes('todo_read'))
+        selected.add('todo_read');
+    // Always include suggest tool (for next action suggestions)
+    if (allToolNames.includes('suggest'))
+        selected.add('suggest');
+    return Array.from(selected);
+}
+// =============================================================================
+// Build Command Types and Constants
+// =============================================================================
+/**
+ * Priority order for sorting backlog items (most important first).
+ */
+export const PRIORITY_ORDER = ['critical', 'high', 'medium', 'low'];
+/**
+ * Detect if we're in a compilr project (has .compilr folder or -docs sibling).
+ * Returns project path from config.json if available.
+ */
+export function detectCompilrProject() {
+    const cwd = process.cwd();
+    // First try to load config and get paths from there
+    const config = loadCompilrConfig(cwd);
+    if (config) {
+        return {
+            found: true,
+            backlogPath: findBacklogPath(cwd),
+            projectPath: config.paths.project || null,
+            docsPath: config.paths.docs,
+        };
+    }
+    // Check for .compilr folder in current directory
+    const compilrDir = path.join(cwd, '.compilr');
+    if (fs.existsSync(compilrDir)) {
+        const backlogPath = path.join(compilrDir, 'backlog.md');
+        return {
+            found: true,
+            backlogPath: fs.existsSync(backlogPath) ? backlogPath : null,
+            projectPath: cwd,
+            docsPath: null,
+        };
+    }
+    // Check for -docs sibling folder (two-repo pattern)
+    const parentDir = path.dirname(cwd);
+    const projectName = path.basename(cwd);
+    const docsDir = path.join(parentDir, `${projectName}-docs`);
+    const docsBacklogPath = path.join(docsDir, '01-planning', 'backlog.md');
+    if (fs.existsSync(docsBacklogPath)) {
+        return {
+            found: true,
+            backlogPath: docsBacklogPath,
+            projectPath: cwd,
+            docsPath: docsDir,
+        };
+    }
+    // Check if we're in the docs repo itself
+    const inDocsBacklog = path.join(cwd, '01-planning', 'backlog.md');
+    if (fs.existsSync(inDocsBacklog)) {
+        // We're in -docs folder, try to find sibling code folder
+        const baseName = projectName.replace(/-docs$/, '');
+        const codeDir = path.join(parentDir, baseName);
+        return {
+            found: true,
+            backlogPath: inDocsBacklog,
+            projectPath: fs.existsSync(codeDir) ? codeDir : null,
+            docsPath: cwd,
+        };
+    }
+    // Check for project subfolders (running from parent folder after /new)
+    try {
+        const entries = fs.readdirSync(cwd, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            // Check for .compilr in subfolder (single-repo pattern)
+            const subCompilrDir = path.join(cwd, entry.name, '.compilr');
+            if (fs.existsSync(subCompilrDir)) {
+                const backlogPath = path.join(subCompilrDir, 'backlog.md');
+                return {
+                    found: true,
+                    backlogPath: fs.existsSync(backlogPath) ? backlogPath : null,
+                    projectPath: path.join(cwd, entry.name),
+                    docsPath: null,
+                };
+            }
+            // Check for -docs subfolder (two-repo pattern)
+            if (entry.name.endsWith('-docs')) {
+                const docsBacklog = path.join(cwd, entry.name, '01-planning', 'backlog.md');
+                if (fs.existsSync(docsBacklog)) {
+                    const baseName = entry.name.replace(/-docs$/, '');
+                    const codeDir = path.join(cwd, baseName);
+                    return {
+                        found: true,
+                        backlogPath: docsBacklog,
+                        projectPath: fs.existsSync(codeDir) ? codeDir : null,
+                        docsPath: path.join(cwd, entry.name),
+                    };
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return { found: false, backlogPath: null, projectPath: null, docsPath: null };
+}
+/**
+ * Check if backlog has any items using the shared parser.
+ */
+export function hasBacklogItems(backlogPath) {
+    if (!backlogPath || !fs.existsSync(backlogPath)) {
+        return false;
+    }
+    try {
+        const content = fs.readFileSync(backlogPath, 'utf-8');
+        const items = parseBacklogItems(content);
+        return items.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get skill prompt by name from builtinSkills or codingSkills.
+ */
+export function getSkillPrompt(name) {
+    const skill = builtinSkills.find((s) => s.name === name)
+        ?? codingSkills.find((s) => s.name === name);
+    return skill?.prompt ?? null;
+}
+// =============================================================================
+// Build Command Helpers
+// =============================================================================
+/**
+ * Select the best backlog item to build.
+ * If requestedId is provided, finds that specific item.
+ * Otherwise, auto-picks the highest priority 📋 item.
+ */
+export function selectBuildItem(items, requestedId) {
+    // If specific ID requested, find it
+    if (requestedId && requestedId.toLowerCase() !== 'scaffold') {
+        const searchId = requestedId.toUpperCase();
+        const item = items.find(i => i.id === searchId);
+        if (!item)
+            return null;
+        if (item.status !== '📋') {
+            // Item exists but not in planned status
+            return null; // Handler will show appropriate message
+        }
+        return item;
+    }
+    // Filter to only 📋 (planned) items
+    const planned = items.filter(i => i.status === '📋');
+    if (planned.length === 0)
+        return null;
+    // Sort by priority, then by ID
+    planned.sort((a, b) => {
+        const prioA = PRIORITY_ORDER.indexOf(a.priority.toLowerCase());
+        const prioB = PRIORITY_ORDER.indexOf(b.priority.toLowerCase());
+        if (prioA !== prioB)
+            return prioA - prioB;
+        return a.id.localeCompare(b.id); // REQ-001 before REQ-002
+    });
+    return planned[0];
+}
+/**
+ * Find dependency IDs mentioned in item title/description.
+ * Looks for patterns like "depends on REQ-001", "blocked by BUG-002", etc.
+ */
+export function findDependencies(item) {
+    const text = `${item.title} ${item.description}`;
+    const patterns = [
+        /depends\s+on\s+([A-Z]+-\d+)/gi,
+        /blocked\s+by\s+([A-Z]+-\d+)/gi,
+        /requires\s+([A-Z]+-\d+)/gi,
+        /after\s+([A-Z]+-\d+)/gi,
+        /needs\s+([A-Z]+-\d+)/gi,
+    ];
+    const deps = [];
+    for (const pattern of patterns) {
+        const matches = text.matchAll(pattern);
+        for (const match of matches) {
+            deps.push(match[1].toUpperCase());
+        }
+    }
+    return [...new Set(deps)];
+}
+/**
+ * Get list of dependencies that are not yet completed.
+ */
+export function getUnmetDependencies(item, allItems) {
+    const depIds = findDependencies(item);
+    return allItems.filter(i => depIds.includes(i.id) && i.status !== '✅');
+}
+/**
+ * Check if the project has a code foundation (src/, package.json, etc.)
+ */
+export function hasProjectFoundation() {
+    const cwd = process.cwd();
+    const indicators = [
+        'src',
+        'lib',
+        'app',
+        'package.json',
+        'requirements.txt',
+        'Cargo.toml',
+        'go.mod',
+        'pom.xml',
+        'build.gradle',
+        'setup.py',
+        'pyproject.toml',
+    ];
+    for (const indicator of indicators) {
+        const fullPath = path.join(cwd, indicator);
+        if (fs.existsSync(fullPath)) {
+            return true;
+        }
+    }
+    // Also check in project subfolders (for two-repo pattern)
+    try {
+        const entries = fs.readdirSync(cwd, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            // Skip docs folder and hidden folders
+            if (entry.name.endsWith('-docs') || entry.name.startsWith('.'))
+                continue;
+            for (const indicator of indicators) {
+                const subPath = path.join(cwd, entry.name, indicator);
+                if (fs.existsSync(subPath)) {
+                    return true;
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return false;
+}

package/dist/repl-v2.d.ts

@@ -0,0 +1,155 @@
+/**
+ * REPL V2 - New Terminal UI based REPL
+ *
+ * Uses TerminalUI with:
+ * - Persistent footer (todo list + input prompt)
+ * - Overlay system for commands
+ * - Real agent integration (or simulation mode for testing)
+ *
+ * Can be run standalone: npx tsx src/repl-v2.ts
+ * Or imported and used with a real agent from index.ts
+ */
+import type { Agent } from '@compilr-dev/agents';
+import { type PermissionResult, type PermissionOverlayV2Options } from './ui/overlay/impl/permission-overlay-v2.js';
+import { type AskUserSimpleOptionsV2, type AskUserSimpleResultV2 } from './ui/overlay/impl/ask-user-simple-overlay-v2.js';
+import { type GuardrailConfirmOptionsV2, type GuardrailConfirmResultV2 } from './ui/overlay/impl/guardrail-overlay-v2.js';
+import { type AskUserOptionsV2, type AskUserResultV2 } from './ui/overlay/impl/ask-user-overlay-v2.js';
+import { type IterationLimitOptionsV2, type IterationLimitResultV2 } from './ui/overlay/impl/iteration-limit-overlay-v2.js';
+export interface ReplV2Options {
+    /** Agent instance (optional - uses simulation if not provided) */
+    agent?: Agent;
+    /** Current model ID */
+    model?: string;
+    /** Current provider */
+    provider?: string;
+    /** CLI version */
+    version?: string;
+    /** Initial project name */
+    projectName?: string;
+    /**
+     * Callback invoked when TerminalUI is ready.
+     * Allows index.ts to set up permission overlay callback.
+     */
+    onUIReady?: (showPermissionOverlay: (options: PermissionOverlayV2Options) => Promise<PermissionResult | null>) => void;
+    /**
+     * Callback invoked when text buffer flush function is ready.
+     * Allows index.ts to flush accumulated agent text before showing overlays.
+     */
+    onTextBufferReady?: (flushTextBuffer: () => void) => void;
+    /**
+     * Callback invoked when ask_user_simple overlay is ready.
+     * Allows index.ts to use V2 overlay for agent questions.
+     */
+    onAskUserSimpleReady?: (showOverlay: (options: AskUserSimpleOptionsV2) => Promise<AskUserSimpleResultV2>) => void;
+    /**
+     * Callback invoked when guardrail overlay is ready.
+     * Allows index.ts to use V2 overlay for guardrail confirmations.
+     */
+    onGuardrailReady?: (showOverlay: (options: GuardrailConfirmOptionsV2) => Promise<GuardrailConfirmResultV2>) => void;
+    /**
+     * Callback invoked when ask_user overlay is ready.
+     * Allows index.ts to use V2 overlay for multi-question forms.
+     */
+    onAskUserReady?: (showOverlay: (options: AskUserOptionsV2) => Promise<AskUserResultV2>) => void;
+    /**
+     * Callback invoked when iteration_limit overlay is ready.
+     * Allows index.ts to use V2 overlay for iteration limit prompts.
+     */
+    onIterationLimitReady?: (showOverlay: (options: IterationLimitOptionsV2) => Promise<IterationLimitResultV2>) => void;
+    /**
+     * Callback invoked when agent finishes processing.
+     * Allows index.ts to apply deferred actions like suggestions.
+     */
+    onAgentFinish?: () => void;
+    /**
+     * Callback invoked when suggestion setter is ready.
+     * Allows index.ts to set suggestions on the V2 UI.
+     */
+    onSuggestionReady?: (setSuggestion: (action: string | null) => void) => void;
+    /**
+     * Callback invoked when subagent tracking is ready.
+     * Allows index.ts to forward subagent events to LiveRegion for live rendering.
+     * Now uses toolUseId for direct correlation (no more FIFO queue matching).
+     */
+    onSubagentReady?: (callbacks: {
+        onStart: (toolUseId: string, agentType: string, description: string) => void;
+        onToolUse: (toolUseId: string, toolName: string, summary?: string) => void;
+        onEnd: (toolUseId: string, success: boolean, tokenCount: number, error?: string) => void;
+    }) => void;
+    /**
+     * Function to clear subagent tracking state in agent.ts between runs.
+     * Called at the start of each agent run to prevent stale data.
+     */
+    clearSubagentTracking?: () => void;
+}
+export declare class ReplV2 {
+    private readonly agent?;
+    private readonly model;
+    private readonly provider;
+    private readonly version;
+    private readonly projectName;
+    private currentSession;
+    private ui;
+    private readonly onUIReady?;
+    private readonly onTextBufferReady?;
+    private readonly onAskUserSimpleReady?;
+    private readonly onGuardrailReady?;
+    private readonly onAskUserReady?;
+    private readonly onIterationLimitReady?;
+    private readonly onAgentFinish?;
+    private readonly onSuggestionReady?;
+    private readonly onSubagentReady?;
+    private readonly clearSubagentTracking?;
+    private readonly startTime;
+    private sessionInputTokens;
+    private sessionOutputTokens;
+    private sessionRequests;
+    private textAccumulator;
+    constructor(options?: ReplV2Options);
+    /**
+     * Flush accumulated agent text to the UI.
+     * Called externally (e.g., before showing permission overlay) to ensure
+     * agent's "I'll do X" message appears before the overlay.
+     */
+    private flushTextBuffer;
+    /**
+     * Start the REPL.
+     */
+    start(): void;
+    /**
+     * Stop the REPL.
+     */
+    stop(): void;
+    /**
+     * Print just the logo to the scrolling area.
+     * Used for dashboard mode where hints are not needed.
+     */
+    private printLogo;
+    /**
+     * Print full welcome message for REPL mode.
+     */
+    private printWelcome;
+    private createCommandContext;
+    private handleCommand;
+    /**
+     * Process queued agent messages.
+     * Commands can queue messages to invoke the agent programmatically.
+     */
+    private processAgentMessageQueue;
+    private processInput;
+    /**
+     * Handle memory note input ("# note") - V2 compatible version
+     */
+    private handleMemoryInputV2;
+    private processQueue;
+    private runAgentReal;
+    private formatToolParams;
+    /**
+     * Extract content and summary from tool result.
+     * Delegates to tool-formatters module.
+     */
+    private extractToolResult;
+    private runAgentSimulation;
+    private sleep;
+    private cancelSession;
+}