@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/commands-v2/registry.js

@@ -0,0 +1,114 @@
+/**
+ * Command Registry for REPL V2
+ *
+ * Central registry for all V2 command handlers.
+ * Handles command resolution (including aliases) and execution.
+ */
+// =============================================================================
+// Registry State
+// =============================================================================
+const handlers = new Map();
+const aliasMap = new Map();
+// =============================================================================
+// Registry Functions
+// =============================================================================
+/**
+ * Register a command handler.
+ */
+export function registerCommand(handler) {
+    handlers.set(handler.name, handler);
+    // Register aliases
+    if (handler.aliases) {
+        for (const alias of handler.aliases) {
+            aliasMap.set(alias, handler.name);
+        }
+    }
+}
+/**
+ * Register multiple command handlers.
+ */
+export function registerCommands(handlerList) {
+    for (const handler of handlerList) {
+        registerCommand(handler);
+    }
+}
+/**
+ * Get a command handler by name or alias.
+ */
+export function getCommand(nameOrAlias) {
+    // Try direct lookup first
+    const handler = handlers.get(nameOrAlias);
+    if (handler)
+        return handler;
+    // Try alias lookup
+    const resolvedName = aliasMap.get(nameOrAlias);
+    if (resolvedName) {
+        return handlers.get(resolvedName);
+    }
+    return undefined;
+}
+/**
+ * Execute a command by name or alias.
+ *
+ * @returns true to continue, false to exit, null if command not found
+ */
+export async function executeCommand(nameOrAlias, args, ctx) {
+    const handler = getCommand(nameOrAlias);
+    if (!handler) {
+        return null; // Command not found
+    }
+    return handler.execute(args, ctx);
+}
+/**
+ * Get all registered command names (excluding aliases).
+ */
+export function getCommandNames() {
+    return Array.from(handlers.keys());
+}
+/**
+ * Check if a command exists (by name or alias).
+ */
+export function hasCommand(nameOrAlias) {
+    return handlers.has(nameOrAlias) || aliasMap.has(nameOrAlias);
+}
+/**
+ * Clear all registered commands (for testing).
+ */
+export function clearCommands() {
+    handlers.clear();
+    aliasMap.clear();
+}
+/**
+ * Get all commands formatted for autocomplete.
+ * Filters out internal/tool commands (those with underscores or camelCase).
+ */
+export function getAutocompleteCommands() {
+    const commands = [];
+    for (const [name, handler] of handlers) {
+        // Skip internal commands (tools, debug commands with underscores/camelCase)
+        if (name.includes('_') || /[A-Z]/.test(name))
+            continue;
+        commands.push({
+            command: `/${name}`,
+            description: handler.description,
+        });
+    }
+    return commands.sort((a, b) => a.command.localeCompare(b.command));
+}
+/**
+ * Get all commands formatted for help display.
+ */
+export function getHelpCommands() {
+    const commands = [];
+    for (const [name, handler] of handlers) {
+        // Skip internal commands
+        if (name.includes('_') || /[A-Z]/.test(name))
+            continue;
+        const aliases = handler.aliases?.length ? ` (also /${handler.aliases.join(', /')})` : '';
+        commands.push({
+            name: `/${name}`,
+            description: `${handler.description}${aliases}`,
+        });
+    }
+    return commands.sort((a, b) => a.name.localeCompare(b.name));
+}

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

@@ -0,0 +1,153 @@
+/**
+ * Command Handler Types for REPL V2
+ *
+ * Command system for the new TerminalUI-based REPL.
+ * Uses TerminalUI instead of Footer, with real agent integration.
+ */
+import type { Agent, ContextManager } from '@compilr-dev/sdk';
+import type { TerminalUI, AgentMessage } from '../ui/terminal-ui.js';
+import type { AgentTeam } from '../multi-agent/index.js';
+import type { BackgroundSessionInfo } from '../multi-agent/types.js';
+export type { BackgroundSessionInfo };
+/**
+ * Context passed to V2 command handlers.
+ * Provides access to agent, UI, and session information.
+ */
+export interface CommandContextV2 {
+    /** TerminalUI instance for output and overlays */
+    ui: TerminalUI;
+    /** CLI version string */
+    version: string;
+    /** Update available info (if any) */
+    updateAvailable?: {
+        current: string;
+        latest: string;
+    } | null;
+    /** Re-print the welcome screen (logo + hints for REPL mode) */
+    printWelcome: () => Promise<void>;
+    /** Print just the logo (for dashboard mode) */
+    printLogo: () => void;
+    /** Session restoration info from startup (one-shot, cleared after first read) */
+    consumeRestoredSessionInfo: () => string | null;
+    /** The main agent instance (may be undefined in simulation mode) */
+    agent?: Agent;
+    /** The multi-agent team (if multi-agent mode is enabled) */
+    team?: AgentTeam;
+    /**
+     * Replace the current team with a new one (after project switch).
+     * Returns the old team so it can be saved if needed.
+     */
+    setTeam?: (team: AgentTeam) => AgentTeam | undefined;
+    /**
+     * Agent factory function for creating new agents.
+     * Used when switching projects to create new team.
+     */
+    agentFactory?: (config: Record<string, unknown>, systemPromptAddition?: string, useMinimalSystemPrompt?: boolean, noTools?: boolean) => Promise<Agent>;
+    /**
+     * Replace the current agent with a restored one.
+     * Used by /resume command to restore from a saved session.
+     */
+    restoreAgent?: (agent: Agent) => void;
+    /** Current LLM model ID */
+    model?: string;
+    /** Current LLM provider (claude, openai, gemini, ollama) */
+    provider?: string;
+    /** Get the context manager from agent (for token/context stats) */
+    getContextManager?: () => ContextManager | null;
+    /** Get conversation history from agent */
+    getHistory?: () => Array<{
+        role: string;
+        content: unknown;
+    }>;
+    /**
+     * Queue a message to be sent to the agent after the command returns.
+     * The displayMessage (if provided) is shown to the user, while the
+     * full message is sent to the agent.
+     */
+    queueAgentMessage: (options: AgentMessage) => void;
+    /** Session start time */
+    startTime?: Date;
+    /** Total input tokens used in session */
+    sessionInputTokens?: number;
+    /** Total output tokens used in session */
+    sessionOutputTokens?: number;
+    /** Total requests in session */
+    sessionRequests?: number;
+    /**
+     * Get information about all running background sessions.
+     */
+    getBackgroundSessions?: () => BackgroundSessionInfo[];
+    /**
+     * Bring a background agent to the foreground.
+     * The current foreground agent (if any) will continue running but output will be minimized.
+     * @param agentId - The agent to bring to foreground
+     * @returns true if successful, false if agent not found
+     */
+    bringToForeground?: (agentId: string) => Promise<boolean>;
+    /**
+     * Switch the active agent (consolidated switching).
+     * Performs team switch, agent ref update, tool filter, footer, session tracking, telemetry.
+     * Callers handle their own messaging.
+     * @param agentId - The agent to switch to
+     */
+    switchAgent?: (agentId: string) => Promise<void>;
+    /**
+     * Kill/cancel a background agent.
+     * @param agentId - The agent to kill
+     * @returns true if successful, false if agent not found
+     */
+    killBackgroundAgent?: (agentId: string) => boolean;
+    /**
+     * Send the current foreground agent to background without aborting it.
+     * The agent continues running; the user regains the input prompt.
+     * @returns The agent ID that was sent to background, or null if no foreground session
+     */
+    sendForegroundToBackground?: () => string | null;
+    /**
+     * Clear all message queues for all agents.
+     * Used by /reset to clear queued messages along with conversation history.
+     * @returns Total number of messages cleared
+     */
+    clearAllQueues?: () => number;
+}
+/**
+ * Example usage for a command.
+ */
+export interface CommandExample {
+    /** The command to run (e.g., '/backlog') */
+    code: string;
+    /** What this example demonstrates */
+    description?: string;
+}
+/**
+ * Interface for a V2 command handler.
+ */
+export interface CommandHandlerV2 {
+    /** Primary command name (without leading slash) */
+    name: string;
+    /** Optional aliases that resolve to this command */
+    aliases?: string[];
+    /** Short description for help text and autocomplete */
+    description: string;
+    /** Detailed explanation of what the command does (for help detail view) */
+    details?: string;
+    /** Usage examples with optional descriptions */
+    examples?: CommandExample[];
+    /** UI interaction hints (keyboard shortcuts, navigation) */
+    interactions?: string[];
+    /**
+     * Execute the command.
+     *
+     * @param args - Arguments passed after the command
+     * @param ctx - Command context with dependencies
+     * @returns true to continue REPL, false to exit
+     */
+    execute(args: string, ctx: CommandContextV2): 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 CommandResultV2 = boolean | null;

package/dist/commands-v2/types.js

@@ -0,0 +1,7 @@
+/**
+ * Command Handler Types for REPL V2
+ *
+ * Command system for the new TerminalUI-based REPL.
+ * Uses TerminalUI instead of Footer, with real agent integration.
+ */
+export {};

package/dist/commands.js

@@ -21,6 +21,20 @@ export const COMMANDS = [
             'Esc to close',
         ],
     },
+    {
+        name: 'anchors',
+        description: 'View and manage anchors (persistent context)',
+        details: 'Anchors are critical pieces of information that survive context compaction. They are always included at the top of the context window. Manage both global anchors and project-specific anchors.',
+        examples: [{ code: '/anchors' }],
+        interactions: [
+            '↑/↓ to navigate anchors',
+            '[a] Add new anchor',
+            '[e] or Enter to edit',
+            '[d] to delete',
+            '[r] to refresh',
+            'Esc to close',
+        ],
+    },
     {
         name: 'arch',
         description: 'Create architecture documentation (ADRs, diagrams, etc.)',
@@ -103,9 +117,23 @@ export const COMMANDS = [
     {
         name: 'design',
         description: 'Design your project and populate the backlog',
-        details: 'Comprehensive requirements gathering workflow. The agent guides you through vision, features, and technical context phases, then creates a PRD and populates the backlog with 5-15 items. Best used after /init.',
+        details: 'Comprehensive requirements gathering workflow. The agent guides you through vision, features, and technical context phases, then creates a PRD and populates the backlog with 5-15 items. Best used after /new.',
         examples: [{ code: '/design' }],
     },
+    {
+        name: 'docs',
+        description: 'View project documents (PRD, architecture, etc.)',
+        details: 'Opens an overlay to browse and read documents stored in the database for the active project. Documents are created by /design, /arch, and other workflow commands.',
+        examples: [
+            { code: '/docs', description: 'List all documents' },
+        ],
+        interactions: [
+            '↑/↓ or j/k to navigate',
+            'Enter to view document',
+            '↑/↓ to scroll content',
+            'Esc to go back or close',
+        ],
+    },
     {
         name: 'exit',
         description: 'Exit the REPL',
@@ -152,21 +180,70 @@ export const COMMANDS = [
         ],
     },
     {
-        name: 'init',
-        description: 'Initialize a new project with structured workflow',
+        name: 'menu',
+        description: 'Return to Project Dashboard',
+        details: 'Opens the Project Dashboard where you can see current project info, switch projects, or start new work. From the dashboard you can create new projects, open existing ones, or start Quick Chat mode.',
+        examples: [{ code: '/menu' }],
+        interactions: [
+            '↑/↓ or j/k to navigate',
+            '←/→ or h/l to switch tabs (Dashboard ↔ More)',
+            'Enter to select, q/Esc to exit',
+            'n for /new, p for projects, c for chat, w for workflow',
+        ],
+    },
+    {
+        name: 'new',
+        description: 'Create a new project with structured workflow',
         details: 'Interactive wizard to scaffold a new project. Asks about project name, type, tech stack, and documentation preferences. Creates project structure with COMPILR.md, backlog, and optional separate docs repo.',
-        examples: [{ code: '/init' }],
+        examples: [{ code: '/new' }],
         interactions: [
             '8-step wizard (0-7)',
             '↑/↓ for selection steps, type for input steps',
             'Enter to confirm, Esc to go back',
         ],
     },
+    {
+        name: 'init',
+        description: 'View CLI setup status (placeholder)',
+        details: 'Shows current CLI configuration status including API keys, provider settings, and startup preferences. Directs users to /config, /keys, and other commands for configuration. Full setup wizard coming in a future release.',
+        examples: [{ code: '/init' }],
+    },
+    {
+        name: 'mascot',
+        description: 'Select mascot expression',
+        details: 'Opens the mascot selector overlay. Choose the mascot expression shown in the CLI. Options include various expressions, random (changes each startup), or none.',
+        examples: [{ code: '/mascot' }],
+        interactions: [
+            '↑/↓ or j/k to navigate options',
+            'Enter/Space to select mascot',
+            'q/Esc to close without changing',
+        ],
+    },
+    {
+        name: 'mcp',
+        description: 'View MCP servers and tools',
+        details: 'Opens the MCP (Model Context Protocol) servers overlay. View connected external tool servers, their discovered tools, and manage connections (restart/disconnect). Configure servers in ~/.compilr-dev/mcp.json.',
+        examples: [{ code: '/mcp' }],
+        interactions: [
+            'Enter to view server details and tools',
+            'r to restart a server',
+            'd to disconnect a server',
+            '/ to search',
+            'Esc to close',
+        ],
+    },
     {
         name: 'model',
-        description: 'Show the current model',
-        details: 'Displays the currently active LLM model (e.g., claude-3-5-sonnet, gpt-4o).',
+        description: 'Select LLM model',
+        details: 'Opens the model selector overlay. Choose from Claude, OpenAI, Gemini, or Ollama models. Changes within the same provider apply immediately; switching providers requires restart.',
         examples: [{ code: '/model' }],
+        interactions: [
+            'Tab/Shift+Tab to switch providers',
+            '1-4 for quick provider selection',
+            '↑/↓ or j/k to navigate models',
+            'Enter to select model',
+            'Esc to close',
+        ],
     },
     {
         name: 'note',
@@ -193,6 +270,21 @@ export const COMMANDS = [
             { code: '/prd scope', description: 'Update scope section' },
         ],
     },
+    {
+        name: 'projects',
+        description: 'View and manage projects',
+        details: 'Opens an interactive overlay to browse, filter, and manage projects tracked in the database. You can view details, open projects, archive, restore, or delete them.',
+        examples: [{ code: '/projects' }],
+        interactions: [
+            'Tab cycles: All → Active → Paused → Completed → Archived',
+            '↑/↓ or j/k to navigate',
+            'Enter to view details and actions',
+            'x to archive/restore project',
+            'd to delete project',
+            'a to show/hide archived',
+            'Esc to close',
+        ],
+    },
     {
         name: 'refine',
         description: 'Refine and expand existing requirements',
@@ -220,6 +312,19 @@ export const COMMANDS = [
         details: 'Displays current session status including CLI version, active model, mode, and context usage.',
         examples: [{ code: '/status' }],
     },
+    {
+        name: 'theme',
+        description: 'Select UI theme',
+        details: 'Opens the theme selector overlay. Browse themes with tabs for Curated, All, Dark, and Light. Themes are terminal color schemes that change the UI appearance.',
+        examples: [{ code: '/theme' }],
+        interactions: [
+            'Tab cycles: Curated → All → Dark → Light',
+            '↑/↓ or j/k to navigate, ←/→ for pages',
+            '/ to search themes by name',
+            '1-9,0 for quick selection (Curated tab)',
+            'Enter/Space to select, q/Esc to close',
+        ],
+    },
     {
         name: 'todos',
         description: 'List current todo items',
@@ -238,10 +343,21 @@ export const COMMANDS = [
         details: 'Shows all tools available to the agent including file operations, bash, git, and custom tools.',
         examples: [{ code: '/tools' }],
     },
+    {
+        name: 'workflow',
+        description: 'Show workflow status and next steps',
+        details: 'Displays the current project workflow status, progress through phases (init → design → backlog → scaffold → build), and recommended next actions. Helps you understand where you are in the development process.',
+        examples: [{ code: '/workflow' }],
+        interactions: [
+            '↑/↓ to navigate actions',
+            'Enter to run selected action',
+            'Esc to close',
+        ],
+    },
     {
         name: 'tutorial',
         description: 'Interactive tutorial for the workflow',
-        details: 'Opens an interactive tutorial that guides you through the compilr.dev workflow. Choose a guided tour to learn everything step-by-step, or jump directly to specific topics like /init, /design, or /build.',
+        details: 'Opens an interactive tutorial that guides you through the compilr.dev workflow. Choose a guided tour to learn everything step-by-step, or jump directly to specific topics like /new, /design, or /build.',
         examples: [{ code: '/tutorial' }],
         interactions: [
             '↑/↓ to navigate options and topics',

package/dist/db/index.js

@@ -49,6 +49,8 @@ export function getDb() {
     dbInstance.pragma('foreign_keys = ON');
     // Enable WAL mode for better concurrency
     dbInstance.pragma('journal_mode = WAL');
+    // Prevent SQLITE_BUSY under concurrent access (multi-terminal)
+    dbInstance.pragma('busy_timeout = 5000');
     // Initialize schema if needed
     initializeSchema(dbInstance);
     return dbInstance;
@@ -81,10 +83,102 @@ function initializeSchema(db) {
  * Run database migrations from one version to another
  */
 function runMigrations(db, fromVersion, toVersion) {
-    // Future migrations go here
-    // For now, just update the version
-    if (fromVersion < toVersion) {
-        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(toVersion);
+    // Migration from v1 to v2: Add plan columns to project_documents
+    if (fromVersion < 2 && toVersion >= 2) {
+        // Add status column (for plans)
+        db.exec(`
+      ALTER TABLE project_documents ADD COLUMN status TEXT;
+    `);
+        // Add work_item_id column (for linking plans to work items)
+        db.exec(`
+      ALTER TABLE project_documents ADD COLUMN work_item_id INTEGER
+      REFERENCES work_items(id) ON DELETE SET NULL;
+    `);
+        // Add indexes for the new columns
+        db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_project_documents_status ON project_documents(status);
+      CREATE INDEX IF NOT EXISTS idx_project_documents_work_item ON project_documents(work_item_id);
+    `);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(2);
+    }
+    // Migration from v2 to v3: Add owner column to work_items
+    if (fromVersion < 3 && toVersion >= 3) {
+        // Add owner column for multi-agent task assignment
+        db.exec(`
+      ALTER TABLE work_items ADD COLUMN owner TEXT;
+    `);
+        // Add index for owner queries
+        db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_work_items_owner ON work_items(owner);
+    `);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(3);
+    }
+    // Migration from v3 to v4: Add terminal_sessions table (multi-terminal awareness)
+    if (fromVersion < 4 && toVersion >= 4) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS terminal_sessions (
+        id TEXT PRIMARY KEY,
+        project_id INTEGER,
+        pid INTEGER NOT NULL,
+        tty_path TEXT,
+        label TEXT,
+        started_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        last_heartbeat DATETIME DEFAULT CURRENT_TIMESTAMP,
+        active_agent TEXT DEFAULT 'default',
+        agents_json TEXT DEFAULT '[]',
+        status TEXT DEFAULT 'active',
+        FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE SET NULL
+      );
+    `);
+        db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_terminal_sessions_project ON terminal_sessions(project_id);
+      CREATE INDEX IF NOT EXISTS idx_terminal_sessions_status ON terminal_sessions(status);
+    `);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(4);
+    }
+    // Migration from v4 to v5: Add file_locks table (multi-terminal file lock awareness)
+    if (fromVersion < 5 && toVersion >= 5) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS file_locks (
+        path TEXT NOT NULL,
+        project_id INTEGER NOT NULL,
+        session_id TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
+        locked_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        PRIMARY KEY (path, project_id),
+        FOREIGN KEY (session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE,
+        FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
+      );
+    `);
+        db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_file_locks_session ON file_locks(session_id);
+    `);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(5);
+    }
+    // Migration from v5 to v6: Add session_notifications table (cross-session notifications)
+    if (fromVersion < 6 && toVersion >= 6) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS session_notifications (
+        id TEXT PRIMARY KEY,
+        project_id INTEGER NOT NULL,
+        from_session_id TEXT NOT NULL,
+        to_session_id TEXT,
+        type TEXT NOT NULL,
+        title TEXT NOT NULL,
+        message TEXT,
+        payload_json TEXT,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        read_at DATETIME,
+        FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE,
+        FOREIGN KEY (from_session_id) REFERENCES terminal_sessions(id) ON DELETE CASCADE
+      );
+    `);
+        db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_session_notifications_project ON session_notifications(project_id);
+      CREATE INDEX IF NOT EXISTS idx_session_notifications_to_session ON session_notifications(to_session_id);
+      CREATE INDEX IF NOT EXISTS idx_session_notifications_unread ON session_notifications(read_at);
+    `);
+        db.prepare('INSERT INTO schema_version (version) VALUES (?)').run(6);
     }
 }
 /**

package/dist/db/repositories/document-repository.d.ts

@@ -22,6 +22,8 @@ export interface ProjectDocument {
     content: string;
     createdAt: Date;
     updatedAt: Date;
+    status: string | null;
+    workItemId: number | null;
 }
 export declare const documentRepository: {
     /**

package/dist/db/repositories/document-repository.js

@@ -16,6 +16,8 @@ function recordToDocument(record) {
         content: record.content,
         createdAt: new Date(record.created_at),
         updatedAt: new Date(record.updated_at),
+        status: record.status,
+        workItemId: record.work_item_id,
     };
 }
 export const documentRepository = {
@@ -105,7 +107,8 @@ export const documentRepository = {
           WHEN 'architecture' THEN 2
           WHEN 'design' THEN 3
           WHEN 'notes' THEN 4
-          ELSE 5
+          WHEN 'plan' THEN 5
+          ELSE 6
         END,
         created_at ASC
     `)
@@ -175,6 +178,7 @@ export const documentRepository = {
             architecture: 0,
             design: 0,
             notes: 0,
+            plan: 0,
         };
         for (const row of results) {
             counts[row.doc_type] = row.count;

package/dist/db/repositories/index.d.ts

@@ -7,3 +7,5 @@ export { workItemRepository } from './work-item-repository.js';
 export type { CreateWorkItemInput, UpdateWorkItemInput, QueryWorkItemsInput, WorkItem, } from './work-item-repository.js';
 export { documentRepository } from './document-repository.js';
 export type { CreateDocumentInput, UpdateDocumentInput, ProjectDocument, } from './document-repository.js';
+export { planRepository } from './plan-repository.js';
+export type { CreatePlanInput, UpdatePlanInput, ListPlansOptions, Plan, PlanSummary, PlanWithWorkItem, } from './plan-repository.js';

package/dist/db/repositories/index.js

@@ -4,3 +4,4 @@
 export { projectRepository } from './project-repository.js';
 export { workItemRepository } from './work-item-repository.js';
 export { documentRepository } from './document-repository.js';
+export { planRepository } from './plan-repository.js';