@compilr-dev/cli 0.4.0 → 0.5.0

package/dist/anchors/project-anchors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Project Anchors - CLI wrapper for @compilr-dev/agents AnchorManager
+ *
+ * Manages per-project anchor isolation using the library's AnchorManager
+ * with project-scoped persistence based on CLI's dataPath configuration.
+ *
+ * Storage structure:
+ *   {dataPath}/anchors/
+ *     ├── global.json           # Non-project anchors
+ *     └── project-{id}.json     # Per-project anchors
+ */
+import { AnchorManager } from '@compilr-dev/agents';
+import type { Anchor, AnchorInput, AnchorQueryOptions } from '@compilr-dev/agents';
+export type { Anchor, AnchorInput, AnchorQueryOptions };
+/**
+ * Get anchor manager for a project (or global if projectId is null)
+ *
+ * Creates a new manager if one doesn't exist, using file-based persistence.
+ *
+ * @param projectId - Project ID, or null for global anchors
+ * @returns AnchorManager instance
+ */
+export declare function getAnchorManager(projectId: string | null): AnchorManager;
+/**
+ * Get the global anchor manager
+ */
+export declare function getGlobalAnchorManager(): AnchorManager;
+/**
+ * Clear all anchors for a project
+ *
+ * Should be called when a project is deleted.
+ *
+ * @param projectId - Project ID to clear
+ * @returns Number of anchors removed
+ */
+export declare function clearProjectAnchors(projectId: string): number;
+/**
+ * Get formatted anchor content for injection into system prompt
+ *
+ * Combines global anchors with project-specific anchors.
+ *
+ * @param projectId - Optional project ID to include project anchors
+ * @returns Formatted anchor string for system prompt
+ */
+export declare function getFormattedAnchors(projectId?: string): string;
+/**
+ * Add an anchor
+ *
+ * Convenience function that routes to the appropriate manager.
+ *
+ * @param input - Anchor input with optional projectId
+ * @returns Created anchor
+ */
+export declare function addAnchor(input: AnchorInput & {
+    projectId?: string;
+}): Anchor;
+/**
+ * Get all anchors across all managers
+ *
+ * @param options - Query options
+ * @returns Array of all anchors
+ */
+export declare function getAllAnchors(options?: AnchorQueryOptions): Anchor[];
+/**
+ * Get list of project IDs that have anchor files
+ */
+export declare function getProjectsWithAnchors(): string[];
+/**
+ * Get anchor statistics
+ */
+export declare function getAnchorStats(): {
+    globalCount: number;
+    projectCounts: Map<string, number>;
+    totalTokens: number;
+};
+/**
+ * Clear all cached managers (useful for testing or refresh)
+ */
+export declare function clearManagerCache(): void;

package/dist/anchors/project-anchors.js

@@ -0,0 +1,202 @@
+/**
+ * Project Anchors - CLI wrapper for @compilr-dev/agents AnchorManager
+ *
+ * Manages per-project anchor isolation using the library's AnchorManager
+ * with project-scoped persistence based on CLI's dataPath configuration.
+ *
+ * Storage structure:
+ *   {dataPath}/anchors/
+ *     ├── global.json           # Non-project anchors
+ *     └── project-{id}.json     # Per-project anchors
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AnchorManager } from '@compilr-dev/agents';
+import { getDataPath } from '../settings/paths.js';
+// =============================================================================
+// State
+// =============================================================================
+/**
+ * Cache of anchor managers by project ID (null = global)
+ */
+const managers = new Map();
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Get the anchors directory path
+ */
+function getAnchorsDir() {
+    return path.join(getDataPath(), 'anchors');
+}
+/**
+ * Get the persist path for a project (or global)
+ */
+function getPersistPath(projectId) {
+    const anchorsDir = getAnchorsDir();
+    const filename = projectId ? `project-${projectId}.json` : 'global.json';
+    return path.join(anchorsDir, filename);
+}
+/**
+ * Ensure the anchors directory exists
+ */
+function ensureAnchorsDir() {
+    const anchorsDir = getAnchorsDir();
+    if (!fs.existsSync(anchorsDir)) {
+        fs.mkdirSync(anchorsDir, { recursive: true });
+    }
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Get anchor manager for a project (or global if projectId is null)
+ *
+ * Creates a new manager if one doesn't exist, using file-based persistence.
+ *
+ * @param projectId - Project ID, or null for global anchors
+ * @returns AnchorManager instance
+ */
+export function getAnchorManager(projectId) {
+    if (managers.has(projectId)) {
+        const existing = managers.get(projectId);
+        if (existing)
+            return existing;
+    }
+    ensureAnchorsDir();
+    const manager = new AnchorManager({
+        persistPath: getPersistPath(projectId),
+        // Only include default safety anchors for global manager
+        includeDefaults: projectId === null,
+        maxAnchors: 50,
+        maxTokens: 4000,
+    });
+    managers.set(projectId, manager);
+    return manager;
+}
+/**
+ * Get the global anchor manager
+ */
+export function getGlobalAnchorManager() {
+    return getAnchorManager(null);
+}
+/**
+ * Clear all anchors for a project
+ *
+ * Should be called when a project is deleted.
+ *
+ * @param projectId - Project ID to clear
+ * @returns Number of anchors removed
+ */
+export function clearProjectAnchors(projectId) {
+    const manager = managers.get(projectId);
+    let removed = 0;
+    if (manager) {
+        removed = manager.clear();
+        managers.delete(projectId);
+    }
+    // Also delete the persistence file
+    const filePath = getPersistPath(projectId);
+    if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+    }
+    return removed;
+}
+/**
+ * Get formatted anchor content for injection into system prompt
+ *
+ * Combines global anchors with project-specific anchors.
+ *
+ * @param projectId - Optional project ID to include project anchors
+ * @returns Formatted anchor string for system prompt
+ */
+export function getFormattedAnchors(projectId) {
+    const parts = [];
+    // Get global anchors
+    const globalManager = getGlobalAnchorManager();
+    const globalFormatted = globalManager.format();
+    if (globalFormatted) {
+        parts.push(globalFormatted);
+    }
+    // Get project-specific anchors if project ID provided
+    if (projectId) {
+        const projectManager = getAnchorManager(projectId);
+        const projectFormatted = projectManager.format();
+        if (projectFormatted) {
+            if (parts.length > 0) {
+                parts.push(''); // Empty line separator
+                parts.push(`### Project Anchors (${projectId})`);
+            }
+            parts.push(projectFormatted);
+        }
+    }
+    return parts.join('\n');
+}
+/**
+ * Add an anchor
+ *
+ * Convenience function that routes to the appropriate manager.
+ *
+ * @param input - Anchor input with optional projectId
+ * @returns Created anchor
+ */
+export function addAnchor(input) {
+    const manager = getAnchorManager(input.projectId ?? null);
+    return manager.add(input);
+}
+/**
+ * Get all anchors across all managers
+ *
+ * @param options - Query options
+ * @returns Array of all anchors
+ */
+export function getAllAnchors(options) {
+    const allAnchors = [];
+    for (const manager of managers.values()) {
+        allAnchors.push(...manager.getAll(options));
+    }
+    return allAnchors;
+}
+/**
+ * Get list of project IDs that have anchor files
+ */
+export function getProjectsWithAnchors() {
+    const anchorsDir = getAnchorsDir();
+    if (!fs.existsSync(anchorsDir)) {
+        return [];
+    }
+    const files = fs.readdirSync(anchorsDir);
+    const projectIds = [];
+    for (const file of files) {
+        const match = /^project-(.+)\.json$/.exec(file);
+        if (match && match[1]) {
+            projectIds.push(match[1]);
+        }
+    }
+    return projectIds;
+}
+/**
+ * Get anchor statistics
+ */
+export function getAnchorStats() {
+    const globalManager = getGlobalAnchorManager();
+    const projectCounts = new Map();
+    let totalTokens = globalManager.getTotalTokens();
+    // Load all project managers to get stats
+    for (const projectId of getProjectsWithAnchors()) {
+        const manager = getAnchorManager(projectId);
+        projectCounts.set(projectId, manager.size);
+        totalTokens += manager.getTotalTokens();
+    }
+    return {
+        globalCount: globalManager.size,
+        projectCounts,
+        totalTokens,
+    };
+}
+/**
+ * Clear all cached managers (useful for testing or refresh)
+ */
+export function clearManagerCache() {
+    managers.clear();
+}

package/dist/commands/handler-types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Command Handler Types
+ *
+ * Defines the interfaces for the command handler system.
+ * Handlers are registered with the command registry and invoked
+ * by REPL.handleCommand() when a slash command is entered.
+ */
+import type { Agent } from '@compilr-dev/agents';
+import type { Footer } from '../ui/footer.js';
+import type { REPLState, AgentMode } from '../ui/types.js';
+/**
+ * Context passed to command handlers.
+ * Contains all dependencies needed to execute commands.
+ */
+export interface CommandContext {
+    agent: Agent;
+    model: string;
+    currentModel: string;
+    provider: string;
+    version: string;
+    footer: Footer;
+    state: REPLState;
+    startTime: Date;
+    sessionInputTokens: number;
+    sessionOutputTokens: number;
+    sessionRequests: number;
+    onModeChange?: (mode: AgentMode) => void;
+    setShouldReturnToMenu: (value: boolean) => void;
+    processMessage: (message: string, options?: {
+        displayMessage?: string;
+    }) => Promise<void>;
+    handleCommand: (command: string, args: string) => Promise<boolean>;
+    setModel: (model: string) => void;
+    showTools: () => Promise<void>;
+    showTokens: () => void;
+    showContext: () => void;
+    showStatus: () => void;
+    showTodos: () => void;
+    handleCompact: () => Promise<void>;
+    handleExport: (args: string) => Promise<void>;
+    reloadProjectAnchors: (oldProjectId: string | null, newProjectId: string) => void;
+}
+/**
+ * Interface for a command handler.
+ */
+export interface CommandHandler {
+    /** Primary command name (without leading slash) */
+    name: string;
+    /** Optional aliases that resolve to this command */
+    aliases?: string[];
+    /** Short description for help text */
+    description: string;
+    /**
+     * Execute the command.
+     *
+     * @param args - Arguments passed after the command (e.g., "/build REQ-001" -> "REQ-001")
+     * @param ctx - Command context with dependencies
+     * @returns true to continue REPL, false to exit
+     */
+    execute(args: string, ctx: CommandContext): Promise<boolean>;
+}
+/**
+ * Result of executing a command.
+ * - true: Command handled successfully, continue REPL
+ * - false: Exit REPL (e.g., /exit command)
+ * - null: Command not found in registry
+ */
+export type CommandResult = boolean | null;

package/dist/commands/handler-types.js

@@ -0,0 +1,8 @@
+/**
+ * Command Handler Types
+ *
+ * Defines the interfaces for the command handler system.
+ * Handlers are registered with the command registry and invoked
+ * by REPL.handleCommand() when a slash command is entered.
+ */
+export {};

package/dist/commands/handlers/agent-commands.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Agent Commands
+ *
+ * Commands that delegate work to the agent via processMessage:
+ * - build, note, prd, scaffold, workflow
+ */
+import type { CommandHandler } from '../handler-types.js';
+export declare const noteCommand: CommandHandler;
+export declare const prdCommand: CommandHandler;
+export declare const workflowCommand: CommandHandler;
+export declare const scaffoldCommand: CommandHandler;
+export declare const buildCommand: CommandHandler;
+export declare const agentCommands: CommandHandler[];

package/dist/commands/handlers/agent-commands.js

@@ -0,0 +1,305 @@
+/**
+ * Agent Commands
+ *
+ * Commands that delegate work to the agent via processMessage:
+ * - build, note, prd, scaffold, workflow
+ */
+import fs from 'node:fs';
+import * as conversation from '../../ui/conversation.js';
+import { showWorkflowOverlay } from '../../ui/workflow-overlay.js';
+import { findBacklogPath, parseBacklogItems } from '../../tools/backlog.js';
+import { detectCompilrProject, getSkillPrompt, hasProjectFoundation, selectBuildItem, getUnmetDependencies, } from '../../repl-helpers.js';
+// =============================================================================
+// Note Command
+// =============================================================================
+export const noteCommand = {
+    name: 'note',
+    description: 'Create a session note',
+    async execute(args, ctx) {
+        // Check if project is initialized
+        const noteProject = detectCompilrProject();
+        if (!noteProject.found) {
+            conversation.printError('No .compilr project found. Run /new first.');
+            return true;
+        }
+        // Get session-notes skill prompt
+        const notePrompt = getSkillPrompt('session-notes');
+        if (!notePrompt) {
+            conversation.printError('Session-notes skill not found.');
+            return true;
+        }
+        // Check for optional title argument
+        const noteTitle = args.trim();
+        conversation.printInfo('📝 Creating session note...');
+        conversation.printInfo('');
+        // Resume footer animation before processing message
+        ctx.footer.resumeAnimation();
+        // Build message based on whether title was provided
+        const titleInstruction = noteTitle
+            ? `The session title is: "${noteTitle}"`
+            : 'Please ask me for a title using ask_user_simple, or generate one from the session summary.';
+        await ctx.processMessage(`I want to create a session note capturing what we've done.
+
+${notePrompt}
+
+${titleInstruction}
+
+Review the conversation context to understand what was accomplished, then create the session note file.`, {
+            displayMessage: noteTitle
+                ? `Create session note: "${noteTitle}"`
+                : 'Create a session note for this session.',
+        });
+        return true;
+    },
+};
+// =============================================================================
+// PRD Command
+// =============================================================================
+export const prdCommand = {
+    name: 'prd',
+    description: 'Update the Product Requirements Document',
+    async execute(args, ctx) {
+        // Check if project is initialized
+        const prdProject = detectCompilrProject();
+        if (!prdProject.found) {
+            conversation.printError('No .compilr project found. Run /new first.');
+            return true;
+        }
+        // Get prd skill prompt
+        const prdPrompt = getSkillPrompt('prd');
+        if (!prdPrompt) {
+            conversation.printError('PRD skill not found.');
+            return true;
+        }
+        // Check for optional section argument
+        const prdSection = args.trim().toLowerCase();
+        const validSections = ['vision', 'scope', 'technical', 'success'];
+        const sectionInstruction = validSections.includes(prdSection)
+            ? `The user wants to update the "${prdSection}" section specifically.`
+            : 'Ask the user which section they want to update using ask_user_simple.';
+        conversation.printInfo('📄 Opening PRD for updates...');
+        conversation.printInfo('');
+        // Resume footer animation before processing message
+        ctx.footer.resumeAnimation();
+        await ctx.processMessage(`I want to update the Product Requirements Document.
+
+${prdPrompt}
+
+${sectionInstruction}
+
+Start by reading the existing PRD.md file to understand current state.`, {
+            displayMessage: prdSection
+                ? `Update PRD: ${prdSection} section`
+                : 'Update the Product Requirements Document',
+        });
+        return true;
+    },
+};
+// =============================================================================
+// Workflow Command
+// =============================================================================
+export const workflowCommand = {
+    name: 'workflow',
+    description: 'Show the workflow overlay',
+    async execute(_args, ctx) {
+        // Loop: workflow → command → back to workflow → etc.
+        // User presses Esc in workflow to exit back to REPL
+        let stayInWorkflow = true;
+        while (stayInWorkflow) {
+            // Result may be undefined if user cancelled with Esc (base overlay casts undefined to TResult)
+            const result = await showWorkflowOverlay();
+            if (result?.command) {
+                // User selected a command from workflow, run it
+                await ctx.handleCommand(result.command.slice(1), ''); // Remove leading /, no args
+                // After command completes, loop back to workflow
+            }
+            else {
+                // User cancelled workflow (Esc), exit to REPL
+                stayInWorkflow = false;
+            }
+        }
+        return true;
+    },
+};
+// =============================================================================
+// Scaffold Command
+// =============================================================================
+export const scaffoldCommand = {
+    name: 'scaffold',
+    description: 'Create project scaffold/foundation',
+    async execute(_args, ctx) {
+        // Check if project is initialized
+        const scaffoldProject = detectCompilrProject();
+        if (!scaffoldProject.found) {
+            conversation.printError('No .compilr project found. Run /new first.');
+            return true;
+        }
+        // Get project path for context
+        const projectPathForScaffold = scaffoldProject.projectPath || process.cwd();
+        const scaffoldPathContext = `**IMPORTANT: Project Directory**
+All code files MUST be created in: ${projectPathForScaffold}
+Do NOT create files in the current working directory if it differs from the project path.
+`;
+        // Check if foundation already exists
+        const foundationExists = hasProjectFoundation();
+        if (foundationExists) {
+            // Let agent confirm with user
+            conversation.printInfo('🔍 Project files detected...');
+            conversation.printInfo('');
+            ctx.footer.resumeAnimation();
+            await ctx.processMessage(`User wants to create a project scaffold, but a foundation may already exist.
+
+${scaffoldPathContext}
+
+Use detect_project to analyze the current state. Then use ask_user_simple:
+"Project files already exist. What would you like to do?"
+- "Continue anyway (may overwrite)"
+- "Cancel"
+
+If continuing, read COMPILR.md and PRD.md for tech stack info, then create the scaffold:
+
+${getSkillPrompt('scaffold') ?? ''}`, { displayMessage: 'Create project scaffold (foundation exists).' });
+            return true;
+        }
+        // Get scaffold skill prompt
+        const scaffoldPrompt = getSkillPrompt('scaffold');
+        if (!scaffoldPrompt) {
+            conversation.printError('Scaffold skill not found.');
+            return true;
+        }
+        conversation.printInfo('🏗️ Creating project scaffold...');
+        conversation.printInfo('');
+        ctx.footer.resumeAnimation();
+        await ctx.processMessage(`I want to create the project scaffold (foundation).
+
+${scaffoldPathContext}
+
+${scaffoldPrompt}
+
+Read COMPILR.md and PRD.md first to understand the tech stack, then create the appropriate scaffold.`, { displayMessage: 'Create project scaffold.' });
+        return true;
+    },
+};
+// =============================================================================
+// Build Command
+// =============================================================================
+export const buildCommand = {
+    name: 'build',
+    description: 'Build a backlog item',
+    async execute(args, ctx) {
+        const itemId = args.trim() || undefined;
+        // Handle /build scaffold - redirect to scaffold handler
+        if (itemId?.toLowerCase() === 'scaffold') {
+            return ctx.handleCommand('scaffold', '');
+        }
+        // Check if project is initialized
+        const buildProject = detectCompilrProject();
+        if (!buildProject.found) {
+            conversation.printError('No .compilr project found. Run /new first.');
+            return true;
+        }
+        // Read backlog using the shared path detection
+        const buildBacklogPath = findBacklogPath();
+        if (!buildBacklogPath) {
+            conversation.printError('No backlog found. Run /design or /sketch first.');
+            return true;
+        }
+        // Parse backlog items
+        let buildItems = [];
+        try {
+            const backlogContent = fs.readFileSync(buildBacklogPath, 'utf-8');
+            buildItems = parseBacklogItems(backlogContent);
+        }
+        catch {
+            conversation.printError('Failed to read backlog file.');
+            return true;
+        }
+        if (buildItems.length === 0) {
+            conversation.printError('No backlog items found. Run /design or /sketch first.');
+            return true;
+        }
+        // Get project path for context
+        const projectPathForBuild = buildProject.projectPath || process.cwd();
+        const projectPathContext = `**IMPORTANT: Project Directory**
+All code files MUST be created in: ${projectPathForBuild}
+Do NOT create files in the current working directory if it differs from the project path.
+`;
+        // Check foundation
+        const foundationExists = hasProjectFoundation();
+        if (!foundationExists) {
+            // Let agent handle foundation check via skill
+            conversation.printInfo('🔍 Checking project foundation...');
+            conversation.printInfo('');
+            ctx.footer.resumeAnimation();
+            await ctx.processMessage(`I want to build a feature from the backlog, but first check if the project has a foundation.
+
+${projectPathContext}
+
+Use detect_project to check the current state. If there's no code foundation (no src/, no package.json or equivalent), use ask_user_simple to ask:
+"No project foundation detected. Would you like to:"
+- "Create scaffold first (recommended)"
+- "Proceed with feature anyway"
+- "Cancel"
+
+If user chooses scaffold, read COMPILR.md and PRD.md for tech stack info, then create the project scaffold following these guidelines:
+
+${getSkillPrompt('scaffold') ?? ''}
+
+After scaffold is done (or if user chose to proceed anyway), continue with building the feature.`, { displayMessage: 'Check project foundation before building.' });
+            return true;
+        }
+        // Select item
+        const item = selectBuildItem(buildItems, itemId);
+        if (!item) {
+            if (itemId) {
+                const existingItem = buildItems.find(i => i.id.toUpperCase() === itemId.toUpperCase());
+                if (existingItem) {
+                    conversation.printError(`Item ${itemId} is already ${existingItem.status === '✅' ? 'completed' : 'in progress'}.`);
+                }
+                else {
+                    conversation.printError(`Item ${itemId} not found in backlog.`);
+                }
+            }
+            else {
+                conversation.printInfo('No pending items in backlog. All done! 🎉');
+            }
+            return true;
+        }
+        // Check dependencies
+        const unmetDeps = getUnmetDependencies(item, buildItems);
+        const depsWarning = unmetDeps.length > 0
+            ? `\n\n**⚠️ UNMET DEPENDENCIES:**\n${unmetDeps.map(d => `- ${d.id}: ${d.title} (${d.status})`).join('\n')}\n\nThese items are not yet completed. Ask user to confirm before proceeding.`
+            : '';
+        // Get build skill prompt and replace placeholders
+        const buildPromptTemplate = getSkillPrompt('build');
+        if (!buildPromptTemplate) {
+            conversation.printError('Build skill not found.');
+            return true;
+        }
+        const buildPrompt = buildPromptTemplate
+            .replace(/\{\{item_id\}\}/g, item.id)
+            .replace(/\{\{item_title\}\}/g, item.title)
+            .replace(/\{\{item_description\}\}/g, item.description)
+            .replace(/\{\{item_type\}\}/g, item.type)
+            .replace(/\{\{item_priority\}\}/g, item.priority);
+        conversation.printInfo(`🔨 Building ${item.id}: ${item.title}`);
+        conversation.printInfo('');
+        ctx.footer.resumeAnimation();
+        await ctx.processMessage(`I want to implement backlog item ${item.id}.
+
+${projectPathContext}
+
+${buildPrompt}${depsWarning}`, { displayMessage: `Build ${item.id}: ${item.title}` });
+        return true;
+    },
+};
+// =============================================================================
+// Export All Agent Commands
+// =============================================================================
+export const agentCommands = [
+    buildCommand,
+    noteCommand,
+    prdCommand,
+    scaffoldCommand,
+    workflowCommand,
+];

package/dist/commands/handlers/design-commands.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Design Commands
+ *
+ * Commands for project design and requirements:
+ * - design: Full project design workflow
+ * - sketch: Quick project outline
+ * - refine: Refine existing requirements
+ * - arch: Create architecture documentation
+ */
+import type { CommandHandler } from '../handler-types.js';
+export declare const designCommand: CommandHandler;
+export declare const sketchCommand: CommandHandler;
+export declare const refineCommand: CommandHandler;
+export declare const archCommand: CommandHandler;
+export declare const designCommands: CommandHandler[];