@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/utils/debug-log.js

@@ -0,0 +1,57 @@
+/**
+ * Debug Logger
+ *
+ * Writes timestamped logs to a file for debugging timing issues.
+ * Usage: import { debugLog } from './utils/debug-log.js';
+ *        debugLog('event-name', 'description');
+ *
+ * For rendering debug: set DEBUG_RENDERING=1 environment variable
+ * Usage: DEBUG_RENDERING=1 compilr
+ *        Then: tail -f /tmp/compilr-debug.log
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const LOG_FILE = path.join(os.tmpdir(), 'compilr-debug.log');
+const startTime = Date.now();
+// Check if rendering debug is enabled via environment variable
+export const DEBUG_RENDERING = process.env['DEBUG_RENDERING'] === '1';
+/**
+ * Log a debug message with timestamp
+ */
+export function debugLog(event, details) {
+    const elapsed = Date.now() - startTime;
+    const timestamp = new Date().toISOString();
+    const line = `[${timestamp}] +${String(elapsed)}ms | ${event}${details ? ` | ${details}` : ''}\n`;
+    try {
+        fs.appendFileSync(LOG_FILE, line);
+    }
+    catch {
+        // Ignore errors
+    }
+}
+/**
+ * Clear the log file
+ */
+export function clearDebugLog() {
+    try {
+        fs.writeFileSync(LOG_FILE, `=== Debug Log Started ${new Date().toISOString()} ===\n`);
+    }
+    catch {
+        // Ignore errors
+    }
+}
+/**
+ * Get the log file path
+ */
+export function getDebugLogPath() {
+    return LOG_FILE;
+}
+/**
+ * Log rendering-specific debug info (only if DEBUG_RENDERING=1)
+ */
+export function debugRender(component, details) {
+    if (!DEBUG_RENDERING)
+        return;
+    debugLog(`[RENDER:${component}]`, details);
+}

package/dist/utils/model-tiers.js

@@ -81,7 +81,7 @@ export function getCommandMinTier(command) {
         '/build': 'medium',
         '/prd': 'medium',
         '/sketch': 'small', // Simplified version - works with any model
-        '/init': 'small',
+        '/new': 'small',
         '/backlog': 'small',
         '/note': 'small',
     };

package/dist/utils/path-safety.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Path Safety Utilities
+ *
+ * Safety validation for file operations, especially deletion.
+ * Prevents accidental deletion of system directories or unrelated folders.
+ */
+export interface DeleteValidation {
+    valid: boolean;
+    reason?: string;
+    warnings?: string[];
+}
+export interface CwdValidation {
+    matches: boolean;
+    projectPath: string;
+    cwd: string;
+}
+/**
+ * Validate a path is safe to delete
+ *
+ * @param projectPath - The path to validate for deletion
+ * @returns Validation result with valid flag, optional reason, and warnings
+ */
+export declare function validateDeletePath(projectPath: string): DeleteValidation;
+/**
+ * Validate active project matches current working directory
+ *
+ * @param project - Project with path property
+ * @returns Validation result with matches flag and paths
+ */
+export declare function validateProjectCwd(project: {
+    path: string;
+}): CwdValidation;
+/**
+ * Check if CWD validation warning should be shown
+ */
+export declare function shouldWarnCwdMismatch(project: {
+    path: string;
+}): boolean;
+/**
+ * Format a CWD mismatch warning message
+ */
+export declare function formatCwdMismatchWarning(project: {
+    path: string;
+}): string[];
+/**
+ * Format delete validation result for display
+ */
+export declare function formatDeleteValidation(validation: DeleteValidation, projectPath: string): string[];
+/**
+ * Check if a path is within the projects directory
+ */
+export declare function isWithinProjectsDir(targetPath: string): boolean;
+/**
+ * Get a safe display path (truncated if too long)
+ */
+export declare function getSafeDisplayPath(targetPath: string, maxLength?: number): string;

package/dist/utils/path-safety.js

@@ -0,0 +1,239 @@
+/**
+ * Path Safety Utilities
+ *
+ * Safety validation for file operations, especially deletion.
+ * Prevents accidental deletion of system directories or unrelated folders.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { getAllowedDeletePaths, isDeleteProtectionEnabled, isProjectMatchRequired } from '../settings/paths.js';
+// =============================================================================
+// Dangerous Paths
+// =============================================================================
+/**
+ * Get list of dangerous system paths that should never be deleted
+ */
+function getDangerousPaths() {
+    const home = os.homedir();
+    return [
+        home, // Home directory itself
+        '/', // Root
+        '/usr',
+        '/bin',
+        '/sbin',
+        '/lib',
+        '/lib64',
+        '/opt',
+        '/etc',
+        '/var',
+        '/tmp',
+        '/dev',
+        '/proc',
+        '/sys',
+        '/boot',
+        '/root',
+        '/home', // Parent of all home directories
+        // macOS specific
+        '/System',
+        '/Library',
+        '/Applications',
+        '/Users',
+        '/Volumes',
+        '/private',
+        '/cores',
+        // Windows specific (when running under WSL or similar)
+        '/mnt/c',
+        '/mnt/c/Windows',
+        '/mnt/c/Program Files',
+        '/mnt/c/Program Files (x86)',
+        '/mnt/c/Users',
+        // Common temp directories
+        os.tmpdir(),
+        path.join(home, 'Desktop'),
+        path.join(home, 'Documents'),
+        path.join(home, 'Downloads'),
+        path.join(home, 'Pictures'),
+        path.join(home, 'Videos'),
+        path.join(home, 'Music'),
+        // CLI data directory should not be deleted via project delete
+        path.join(home, '.compilr-dev'),
+    ];
+}
+// =============================================================================
+// Validation Functions
+// =============================================================================
+/**
+ * Validate a path is safe to delete
+ *
+ * @param projectPath - The path to validate for deletion
+ * @returns Validation result with valid flag, optional reason, and warnings
+ */
+export function validateDeletePath(projectPath) {
+    const resolved = path.resolve(projectPath);
+    const warnings = [];
+    // 1. Path must be absolute (after resolve, it always is)
+    if (!path.isAbsolute(resolved)) {
+        return { valid: false, reason: 'Project path must be absolute' };
+    }
+    // 2. Check if path exists (OK to proceed if it doesn't - just skip file deletion)
+    if (!fs.existsSync(resolved)) {
+        return { valid: true, warnings: ['Path does not exist, skipping file deletion'] };
+    }
+    // 3. Prevent dangerous system paths
+    const dangerousPaths = getDangerousPaths();
+    for (const dangerous of dangerousPaths) {
+        const resolvedDangerous = path.resolve(dangerous);
+        if (resolved === resolvedDangerous) {
+            return {
+                valid: false,
+                reason: `Cannot delete system directory: ${resolved}`,
+            };
+        }
+    }
+    // 4. Check path is within allowed directories (if protection enabled)
+    if (isDeleteProtectionEnabled()) {
+        const allowedRoots = getAllowedDeletePaths();
+        const isWithinAllowed = allowedRoots.some((root) => {
+            const resolvedRoot = path.resolve(root);
+            return resolved.startsWith(resolvedRoot + path.sep) || resolved === resolvedRoot;
+        });
+        if (!isWithinAllowed) {
+            return {
+                valid: false,
+                reason: `Path is outside allowed directories. Configure allowedPaths in /config if needed.`,
+            };
+        }
+    }
+    // 5. Check for project markers (.compilr, .git, package.json)
+    const hasCompilrMarker = fs.existsSync(path.join(resolved, '.compilr'));
+    const hasGit = fs.existsSync(path.join(resolved, '.git'));
+    const hasPackageJson = fs.existsSync(path.join(resolved, 'package.json'));
+    const hasPyprojectToml = fs.existsSync(path.join(resolved, 'pyproject.toml'));
+    const hasCargoToml = fs.existsSync(path.join(resolved, 'Cargo.toml'));
+    const hasGoMod = fs.existsSync(path.join(resolved, 'go.mod'));
+    const hasProjectMarker = hasCompilrMarker || hasGit || hasPackageJson || hasPyprojectToml || hasCargoToml || hasGoMod;
+    if (!hasProjectMarker) {
+        warnings.push('Directory has no project markers (.compilr, .git, package.json, etc.)');
+    }
+    // 6. Warn if path seems too short (e.g., /home/user/a)
+    const pathParts = resolved.split(path.sep).filter(Boolean);
+    if (pathParts.length < 3) {
+        warnings.push('Path seems unusually short - double check this is correct');
+    }
+    // 7. Warn if path is very deep (might indicate system path)
+    if (pathParts.length > 15) {
+        warnings.push('Path is very deep - verify this is the correct project');
+    }
+    // 8. Check if path is a parent of current working directory
+    const cwd = process.cwd();
+    if (cwd.startsWith(resolved + path.sep) || cwd === resolved) {
+        warnings.push('This path contains or is your current working directory');
+    }
+    return { valid: true, warnings };
+}
+/**
+ * Validate active project matches current working directory
+ *
+ * @param project - Project with path property
+ * @returns Validation result with matches flag and paths
+ */
+export function validateProjectCwd(project) {
+    const cwd = process.cwd();
+    const projectPath = path.resolve(project.path);
+    // CWD should be within or equal to project path
+    const matches = cwd === projectPath || cwd.startsWith(projectPath + path.sep);
+    return { matches, projectPath, cwd };
+}
+/**
+ * Check if CWD validation warning should be shown
+ */
+export function shouldWarnCwdMismatch(project) {
+    if (!isProjectMatchRequired()) {
+        return false;
+    }
+    const { matches } = validateProjectCwd(project);
+    return !matches;
+}
+/**
+ * Format a CWD mismatch warning message
+ */
+export function formatCwdMismatchWarning(project) {
+    const { projectPath, cwd } = validateProjectCwd(project);
+    return [
+        "Current directory doesn't match active project",
+        `  Active project: ${projectPath}`,
+        `  Current dir:    ${cwd}`,
+        `  Consider: cd ${projectPath}`,
+    ];
+}
+/**
+ * Format delete validation result for display
+ */
+export function formatDeleteValidation(validation, projectPath) {
+    const lines = [];
+    if (validation.valid) {
+        lines.push('Path is within allowed directory');
+        // Check for project markers
+        if (fs.existsSync(path.join(projectPath, '.compilr'))) {
+            lines.push('Project has .compilr marker');
+        }
+        else if (fs.existsSync(path.join(projectPath, '.git'))) {
+            lines.push('Project has .git repository');
+        }
+        else if (fs.existsSync(path.join(projectPath, 'package.json'))) {
+            lines.push('Project has package.json');
+        }
+        if (validation.warnings && validation.warnings.length > 0) {
+            lines.push('');
+            lines.push('Warnings:');
+            for (const warning of validation.warnings) {
+                lines.push(`  - ${warning}`);
+            }
+        }
+    }
+    else {
+        lines.push(`Error: ${validation.reason || 'Unknown error'}`);
+        lines.push('');
+        lines.push('Allowed directories:');
+        for (const allowed of getAllowedDeletePaths()) {
+            lines.push(`  - ${allowed}`);
+        }
+        lines.push('');
+        lines.push('Options:');
+        lines.push('  1. Move the project to an allowed directory');
+        lines.push('  2. Add path to allowedPaths in /config');
+        lines.push('  3. Delete files manually and remove from database only');
+    }
+    return lines;
+}
+/**
+ * Check if a path is within the projects directory
+ */
+export function isWithinProjectsDir(targetPath) {
+    const allowedPaths = getAllowedDeletePaths();
+    const resolved = path.resolve(targetPath);
+    return allowedPaths.some((allowed) => {
+        const resolvedAllowed = path.resolve(allowed);
+        return resolved.startsWith(resolvedAllowed + path.sep) || resolved === resolvedAllowed;
+    });
+}
+/**
+ * Get a safe display path (truncated if too long)
+ */
+export function getSafeDisplayPath(targetPath, maxLength = 50) {
+    if (targetPath.length <= maxLength) {
+        return targetPath;
+    }
+    const parts = targetPath.split(path.sep);
+    if (parts.length <= 2) {
+        return targetPath.slice(0, maxLength - 3) + '...';
+    }
+    // Show first and last parts with ellipsis
+    const first = parts.slice(0, 2).join(path.sep);
+    const last = parts.slice(-2).join(path.sep);
+    if (first.length + last.length + 4 <= maxLength) {
+        return first + '/.../' + last;
+    }
+    return targetPath.slice(0, maxLength - 3) + '...';
+}

package/dist/workflow/guided-mode-injector.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Guided Mode System Prompt Injector
+ *
+ * Injects guided workflow context into the agent's system prompt.
+ * Two types of injection:
+ * - Static: General rules about guided mode behavior (added to base system prompt)
+ * - Dynamic: Current project/item/step state (injected per-session)
+ */
+import type { Project } from '../db/repositories/project-repository.js';
+import type { WorkItem } from '../db/repositories/work-item-repository.js';
+/**
+ * Static system prompt addition for guided mode.
+ * Added to base system prompt when a project uses guided mode.
+ */
+export declare const GUIDED_MODE_SYSTEM_PROMPT: string;
+/**
+ * Options for generating dynamic context
+ */
+export interface DynamicContextOptions {
+    project: Project;
+    currentItem: WorkItem | null;
+    backlogCount: number;
+    inProgressCount: number;
+    completedCount: number;
+}
+/**
+ * Generate dynamic context injection for current workflow state.
+ * Injected on startup and when project/step changes.
+ */
+export declare function generateDynamicContext(options: DynamicContextOptions): string;
+/**
+ * Generate a compact status line for footer display
+ */
+export declare function generateStatusLine(options: DynamicContextOptions): string;
+/**
+ * Check if we should inject guided mode context
+ */
+export declare function shouldInjectGuidedContext(project: Project | null): boolean;
+/**
+ * Combine static and dynamic prompts for full guided mode injection
+ */
+export declare function getFullGuidedPrompt(options: DynamicContextOptions): string;

package/dist/workflow/guided-mode-injector.js

@@ -0,0 +1,191 @@
+/**
+ * Guided Mode System Prompt Injector
+ *
+ * Injects guided workflow context into the agent's system prompt.
+ * Two types of injection:
+ * - Static: General rules about guided mode behavior (added to base system prompt)
+ * - Dynamic: Current project/item/step state (injected per-session)
+ */
+import { STEP_ORDER, getStepCriteria, formatStepDisplay, getStepDescription } from './step-criteria.js';
+/**
+ * Static system prompt addition for guided mode.
+ * Added to base system prompt when a project uses guided mode.
+ */
+export const GUIDED_MODE_SYSTEM_PROMPT = `
+## Guided Workflow Mode
+
+When a project uses **guided mode**, follow these rules:
+
+1. **Work Item Focus**: Always work on the current work item unless the user explicitly requests otherwise
+2. **Step Cycle**: Progress through steps in order: ${STEP_ORDER.join(' → ')}
+3. **Step Transitions**: Use \`workitem_advance_step\` tool when the criteria for the current step are met
+4. **Visibility**: Announce step transitions clearly in conversation so the user sees progress
+5. **Flexibility**: The user can always interrupt - acknowledge and respect their requests
+6. **Test Failures**: After 2 failed test attempts, ask the user how to proceed (skip, retry, switch item)
+
+### Step Criteria
+
+- **PLAN**: Requirements understood, approach designed, target files identified
+- **IMPLEMENT**: Code written, no placeholder TODOs left, lint passes
+- **TEST**: All tests pass (or user overrides after 2 failures)
+- **COMMIT**: Changes committed with proper message, commit hash captured
+- **REVIEW**: User confirms ready for next item
+
+### Detour Handling
+
+If the user wants to work on something else mid-cycle:
+1. Acknowledge their request
+2. Optionally suggest finishing the current item (gentle challenge)
+3. If they insist, accommodate gracefully
+4. Options: pause current item, switch to different item, or switch to flexible mode
+`.trim();
+/**
+ * Generate dynamic context injection for current workflow state.
+ * Injected on startup and when project/step changes.
+ */
+export function generateDynamicContext(options) {
+    const { project, currentItem, backlogCount, inProgressCount, completedCount } = options;
+    // Base project context
+    let context = `
+## Current Workflow State
+
+**Project:** ${project.displayName} (Mode: ${project.workflowMode})
+**Lifecycle:** ${project.lifecycleState}
+**Progress:** ${String(completedCount)} completed, ${String(inProgressCount)} in progress, ${String(backlogCount)} in backlog
+`.trim();
+    // Add current item context if in guided mode with active item
+    if (project.workflowMode === 'guided' && currentItem) {
+        context += `
+
+### Current Work Item
+
+**Item:** ${currentItem.itemId} "${currentItem.title}"
+**Type:** ${currentItem.type}
+**Priority:** ${currentItem.priority}
+**Status:** ${currentItem.status}
+**Step:** ${currentItem.guidedStep ? formatStepDisplay(currentItem.guidedStep) : 'Not started'}
+${currentItem.description ? `\n**Description:**\n${currentItem.description}` : ''}
+
+### Instructions
+
+${getStepInstructions(currentItem.guidedStep)}`;
+    }
+    else if (project.workflowMode === 'guided') {
+        context += `
+
+### No Active Work Item
+
+Use \`workitem_next\` to get the highest priority item from the backlog, or ask the user which item to work on.
+Once an item is selected, set its status to 'in_progress' and begin the guided cycle.`;
+    }
+    else {
+        // Flexible mode
+        context += `
+
+### Flexible Mode
+
+Work on tasks as requested by the user. Work items are tracked but the step cycle is not enforced.
+You can still use \`workitem_advance_step\` if you want to track progress through steps.`;
+    }
+    return context;
+}
+/**
+ * Get step-specific instructions for the agent
+ */
+function getStepInstructions(step) {
+    if (!step) {
+        return `No step active. Use \`workitem_advance_step\` to start at PLAN step.`;
+    }
+    const criteria = getStepCriteria(step);
+    const stepDesc = getStepDescription(step);
+    let instructions = `You are in **${step.toUpperCase()}** step: ${stepDesc}
+
+**Exit Criteria:**
+${criteria.exitCriteria.map((c) => `- ${c}`).join('\n')}
+
+**When complete:** Use \`workitem_advance_step\` with a reason explaining why criteria are met.`;
+    // Add step-specific hints
+    switch (step) {
+        case 'plan':
+            instructions += `
+
+**Actions:**
+1. Read and understand the requirements
+2. Design the approach (what files to create/modify)
+3. Consider edge cases and potential issues
+4. Document the plan in conversation`;
+            break;
+        case 'implement':
+            instructions += `
+
+**Actions:**
+1. Create/modify files according to the plan
+2. Ensure code is complete (no TODOs unless intentional)
+3. Run lint if available and fix any issues
+4. Review your changes before advancing`;
+            break;
+        case 'test':
+            instructions += `
+
+**Actions:**
+1. Run the test suite
+2. If tests fail, analyze and fix the issues
+3. Re-run tests after fixes
+4. After 2 failed attempts, ask user how to proceed
+
+**Note:** Track failed attempts. After 2 failures, offer options:
+- Try again (you'll fix the issue)
+- Skip tests and continue to commit
+- Switch to flexible mode for this item
+- Work on a different item`;
+            break;
+        case 'commit':
+            instructions += `
+
+**Actions:**
+1. Stage the relevant changes
+2. Create a descriptive commit message
+3. Run git commit
+4. Capture the commit hash
+5. Use \`workitem_update\` to store the commit_hash on the item`;
+            break;
+        case 'review':
+            instructions += `
+
+**Actions:**
+1. Summarize what was accomplished
+2. Ask user if they're ready for the next item
+3. Wait for user confirmation before proceeding
+
+**On user confirmation:**
+- Use \`workitem_advance_step\` to complete this item
+- Then use \`workitem_next\` to get the next item`;
+            break;
+    }
+    return instructions;
+}
+/**
+ * Generate a compact status line for footer display
+ */
+export function generateStatusLine(options) {
+    const { project, currentItem } = options;
+    if (!currentItem) {
+        return `${project.displayName} | ${project.workflowMode} mode | No active item`;
+    }
+    const stepDisplay = currentItem.guidedStep
+        ? currentItem.guidedStep.toUpperCase()
+        : 'READY';
+    return `${project.displayName} | ${currentItem.itemId} | ${stepDisplay}`;
+}
+/**
+ * Check if we should inject guided mode context
+ */
+export function shouldInjectGuidedContext(project) {
+    return project !== null && project.workflowMode === 'guided';
+}
+/**
+ * Combine static and dynamic prompts for full guided mode injection
+ */
+export function getFullGuidedPrompt(options) {
+    return `${GUIDED_MODE_SYSTEM_PROMPT}\n\n${generateDynamicContext(options)}`;
+}

package/dist/workflow/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Guided Workflow Module
+ *
+ * Provides step-by-step workflow tracking for guided mode.
+ */
+export { type StepCriteria, STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, getPreviousStep, getStepNumber, isValidTransition, getStepCriteria, getStepDescription, formatStepDisplay, } from './step-criteria.js';
+export { type StepAttempt, GuidedStepTracker, stepTracker, } from './step-tracker.js';
+export { type DynamicContextOptions, GUIDED_MODE_SYSTEM_PROMPT, generateDynamicContext, generateStatusLine, shouldInjectGuidedContext, getFullGuidedPrompt, } from './guided-mode-injector.js';

package/dist/workflow/index.js

@@ -0,0 +1,8 @@
+/**
+ * Guided Workflow Module
+ *
+ * Provides step-by-step workflow tracking for guided mode.
+ */
+export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, getPreviousStep, getStepNumber, isValidTransition, getStepCriteria, getStepDescription, formatStepDisplay, } from './step-criteria.js';
+export { GuidedStepTracker, stepTracker, } from './step-tracker.js';
+export { GUIDED_MODE_SYSTEM_PROMPT, generateDynamicContext, generateStatusLine, shouldInjectGuidedContext, getFullGuidedPrompt, } from './guided-mode-injector.js';

package/dist/workflow/step-criteria.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Step Criteria - Defines exit criteria for each guided workflow step
+ *
+ * Each step has:
+ * - Human-readable exit criteria (for system prompt)
+ * - Success indicators (what agent looks for)
+ * - Configuration (max attempts, auto-advance)
+ */
+import type { GuidedStep } from '../db/schema.js';
+/**
+ * Step criteria definition
+ */
+export interface StepCriteria {
+    /** The guided step */
+    step: GuidedStep;
+    /** Human-readable exit criteria for system prompt */
+    exitCriteria: string[];
+    /** What agent looks for to determine success */
+    successIndicators: string[];
+    /** Maximum attempts for retryable steps (like test) */
+    maxAttempts?: number;
+    /** Can agent advance automatically when criteria met? */
+    autoAdvance: boolean;
+    /** Hint for next action after advancing */
+    nextActionHint: string;
+}
+/**
+ * Step order - defines valid step progression
+ */
+export declare const STEP_ORDER: readonly GuidedStep[];
+/**
+ * Get the next step in the workflow
+ */
+export declare function getNextStep(current: GuidedStep | null): GuidedStep | 'complete';
+/**
+ * Get the previous step in the workflow
+ */
+export declare function getPreviousStep(current: GuidedStep): GuidedStep | null;
+/**
+ * Get step number (1-indexed for display)
+ */
+export declare function getStepNumber(step: GuidedStep): number;
+/**
+ * Check if step transition is valid (can only advance to next step)
+ */
+export declare function isValidTransition(from: GuidedStep | null, to: GuidedStep | 'complete'): boolean;
+/**
+ * Guided step criteria definitions
+ */
+export declare const GUIDED_STEP_CRITERIA: readonly StepCriteria[];
+/**
+ * Get criteria for a specific step
+ */
+export declare function getStepCriteria(step: GuidedStep): StepCriteria;
+/**
+ * Get human-readable step description for messages
+ */
+export declare function getStepDescription(step: GuidedStep): string;
+/**
+ * Format step for display (e.g., "IMPLEMENT (2 of 5)")
+ */
+export declare function formatStepDisplay(step: GuidedStep): string;