@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/prompts/plan-mode-prompt.js

@@ -0,0 +1,95 @@
+/**
+ * Plan Mode System Prompt Addition
+ *
+ * Appended to the system prompt when Plan Mode is active.
+ * Instructs the agent to explore, create plans, and wait for approval.
+ */
+export const PLAN_MODE_PROMPT = `## PLAN MODE ACTIVE
+
+You are currently in **Plan Mode**. In this mode, you must:
+
+1. **Gather Context from Database FIRST**:
+   - Use \`project_document_get\` to read PRD and architecture docs
+   - Use \`workitem_query\` to read backlog items
+   - Use \`plan_list\` to see existing plans
+   - Only read actual source files when you need specific implementation details
+
+2. **Ask Questions**: Use \`ask_user\` to clarify requirements, constraints, and preferences. Don't assume.
+
+3. **Create a Plan**: Use \`plan_create\` to document your approach before implementing:
+   - Name: kebab-case, descriptive (e.g., "auth-jwt-migration")
+   - Content: Follow the standard plan format (Context, Goals, Steps, Verification)
+   - Link to work item if one was mentioned
+
+4. **Request Approval**: After creating the plan, summarize it and ask for approval:
+   - List 3-5 key points
+   - Mention files that will be modified
+   - End with: "Ready for your review. [PLAN_READY:plan_id:plan_name]"
+
+5. **Wait for Approval**: Do NOT implement until the user approves the plan.
+
+6. **Track Status**: After approval, update the plan status:
+   - Use \`plan_update\` with status: 'approved' when user approves
+   - Use \`plan_update\` with status: 'in_progress' when you start implementing
+   - Use \`plan_update\` with status: 'completed' when all steps are done
+
+### Plan Format
+
+Use this structure when creating plans:
+
+\`\`\`markdown
+# Plan: [Name]
+
+## Context
+[Why this plan exists, what problem it solves]
+[Link to work item if applicable]
+
+## Goals
+- [ ] Primary goal 1
+- [ ] Primary goal 2
+
+## Approach
+[High-level description of the implementation approach]
+
+## Steps
+1. **Step 1 Title**
+   - Details about step 1
+   - Files to modify: \`src/foo.ts\`
+
+2. **Step 2 Title**
+   - Details about step 2
+
+## Verification
+- [ ] How to verify completion
+- [ ] Tests pass
+\`\`\`
+
+### DO NOT in Plan Mode:
+- Skip planning for non-trivial tasks
+- Make code changes without an approved plan
+- Assume requirements without asking
+- Read files in .compilr/requirements/ (use project_document_get instead)
+- Scan the filesystem before checking database for project docs
+
+### Available Plan Tools:
+- \`plan_create\` - Create a new plan (starts as 'draft')
+- \`plan_update\` - Update plan content or status
+- \`plan_get\` - Get plan details by ID or name
+- \`plan_list\` - List plans for the project
+- \`plan_delete\` - Delete a plan
+`;
+/**
+ * Get the plan mode prompt for a specific active plan (if any)
+ */
+export function getPlanModePrompt(activePlanId, activePlanName) {
+    let prompt = PLAN_MODE_PROMPT;
+    if (activePlanId && activePlanName) {
+        prompt += `\n### Current Active Plan
+
+You are continuing work on plan **"${activePlanName}"** (ID: ${String(activePlanId)}).
+
+Use \`plan_get\` with plan_id: ${String(activePlanId)} to load the plan details and continue from where you left off.
+`;
+    }
+    return prompt;
+}

package/dist/repl-helpers.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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 type { BacklogItem } from './tools/backlog.js';
+/**
+ * Keyword patterns for tool selection based on user input.
+ * Maps tool names to keywords that suggest the tool should be used.
+ */
+export declare const TOOL_KEYWORDS: Record<string, string[]>;
+/**
+ * Select relevant tool names based on user input intent.
+ * Returns all tools if input is short or a question.
+ */
+export declare function selectToolNamesByIntent(input: string, allToolNames: string[]): string[];
+/**
+ * Priority order for sorting backlog items (most important first).
+ */
+export declare const PRIORITY_ORDER: string[];
+/**
+ * Result of detecting a compilr project structure.
+ */
+export interface CompilrProjectInfo {
+    found: boolean;
+    backlogPath: string | null;
+    projectPath: string | null;
+    docsPath: string | null;
+}
+/**
+ * Detect if we're in a compilr project (has .compilr folder or -docs sibling).
+ * Returns project path from config.json if available.
+ */
+export declare function detectCompilrProject(): CompilrProjectInfo;
+/**
+ * Check if backlog has any items using the shared parser.
+ */
+export declare function hasBacklogItems(backlogPath: string | null): boolean;
+/**
+ * Get skill prompt by name from builtinSkills or codingSkills.
+ */
+export declare function getSkillPrompt(name: string): string | null;
+/**
+ * Select the best backlog item to build.
+ * If requestedId is provided, finds that specific item.
+ * Otherwise, auto-picks the highest priority 📋 item.
+ */
+export declare function selectBuildItem(items: BacklogItem[], requestedId?: string): BacklogItem | null;
+/**
+ * Find dependency IDs mentioned in item title/description.
+ * Looks for patterns like "depends on REQ-001", "blocked by BUG-002", etc.
+ */
+export declare function findDependencies(item: BacklogItem): string[];
+/**
+ * Get list of dependencies that are not yet completed.
+ */
+export declare function getUnmetDependencies(item: BacklogItem, allItems: BacklogItem[]): BacklogItem[];
+/**
+ * Check if the project has a code foundation (src/, package.json, etc.)
+ */
+export declare function hasProjectFoundation(): boolean;

package/dist/repl-helpers.js

@@ -0,0 +1,319 @@
+/**
+ * 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, platformSkills } from '@compilr-dev/sdk';
+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 = platformSkills.find((s) => s.name === name)
+        ?? 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;
+}