@compilr-dev/cli 0.5.0 → 0.5.1

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

@@ -4,8 +4,11 @@
  * Command system for the new TerminalUI-based REPL.
  * Uses TerminalUI instead of Footer, with real agent integration.
  */
-import type { Agent, ContextManager } from '@compilr-dev/agents';
+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.
@@ -15,12 +18,36 @@ export interface CommandContextV2 {
     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: () => void;
+    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) */
@@ -46,6 +73,51 @@ export interface CommandContextV2 {
     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.
@@ -55,8 +127,14 @@ export interface CommandHandlerV2 {
     name: string;
     /** Optional aliases that resolve to this command */
     aliases?: string[];
-    /** Short description for help text */
+    /** 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.
      *

package/dist/commands.js

@@ -219,6 +219,19 @@ export const COMMANDS = [
             '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: 'Select LLM model',

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';

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

@@ -0,0 +1,101 @@
+/**
+ * Plan Repository
+ *
+ * Handles all database operations for plans.
+ * Plans are stored in project_documents with doc_type='plan'.
+ */
+import type { PlanStatus } from '../schema.js';
+export interface CreatePlanInput {
+    project_id: number;
+    name: string;
+    content: string;
+    work_item_id?: number;
+}
+export interface UpdatePlanInput {
+    content?: string;
+    status?: PlanStatus;
+    work_item_id?: number | null;
+}
+export interface ListPlansOptions {
+    status?: PlanStatus | PlanStatus[];
+    work_item_id?: number;
+    limit?: number;
+    order_by?: 'updated_desc' | 'updated_asc' | 'created_desc' | 'name_asc';
+}
+export interface Plan {
+    id: number;
+    projectId: number;
+    name: string;
+    content: string;
+    status: PlanStatus;
+    workItemId: number | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface PlanSummary {
+    id: number;
+    name: string;
+    status: PlanStatus;
+    workItemId: number | null;
+    workItemTitle?: string;
+    workItemItemId?: string;
+    updatedAt: Date;
+}
+export interface PlanWithWorkItem extends Plan {
+    workItem?: {
+        id: number;
+        itemId: string;
+        title: string;
+        status: string;
+    };
+}
+export declare const planRepository: {
+    /**
+     * Create a new plan
+     */
+    create(input: CreatePlanInput): Plan;
+    /**
+     * Get plan by ID
+     */
+    getById(id: number): Plan | null;
+    /**
+     * Get plan by name for a project
+     */
+    getByName(projectId: number, name: string): Plan | null;
+    /**
+     * Get plan with linked work item details
+     */
+    getWithWorkItem(id: number): PlanWithWorkItem | null;
+    /**
+     * Update a plan
+     */
+    update(id: number, input: UpdatePlanInput): Plan | null;
+    /**
+     * Delete a plan
+     */
+    delete(id: number): boolean;
+    /**
+     * List plans for a project
+     */
+    list(projectId: number, options?: ListPlansOptions): PlanSummary[];
+    /**
+     * Count plans by status for a project
+     */
+    countByStatus(projectId: number): Record<PlanStatus, number>;
+    /**
+     * Get plans with status 'in_progress' for a project
+     */
+    getInProgress(projectId: number): PlanSummary[];
+    /**
+     * Check if there are any in_progress plans for a project
+     */
+    hasInProgress(projectId: number): boolean;
+    /**
+     * Link a plan to a work item
+     */
+    linkWorkItem(planId: number, workItemId: number): Plan | null;
+    /**
+     * Unlink a plan from its work item
+     */
+    unlinkWorkItem(planId: number): Plan | null;
+};

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

@@ -0,0 +1,275 @@
+/**
+ * Plan Repository
+ *
+ * Handles all database operations for plans.
+ * Plans are stored in project_documents with doc_type='plan'.
+ */
+import { getDb } from '../index.js';
+// =============================================================================
+// Status Transition Rules
+// =============================================================================
+const VALID_TRANSITIONS = {
+    draft: ['approved', 'abandoned'],
+    approved: ['in_progress', 'abandoned'],
+    in_progress: ['completed', 'abandoned'],
+    completed: [], // Terminal state
+    abandoned: ['draft'], // Can re-open
+};
+function isValidTransition(from, to) {
+    return VALID_TRANSITIONS[from].includes(to);
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function recordToPlan(record) {
+    return {
+        id: record.id,
+        projectId: record.project_id,
+        name: record.title,
+        content: record.content,
+        status: record.status ?? 'draft',
+        workItemId: record.work_item_id,
+        createdAt: new Date(record.created_at),
+        updatedAt: new Date(record.updated_at),
+    };
+}
+function recordToPlanSummary(record) {
+    return {
+        id: record.id,
+        name: record.title,
+        status: record.status ?? 'draft',
+        workItemId: record.work_item_id,
+        workItemTitle: record.work_item_title,
+        workItemItemId: record.work_item_item_id,
+        updatedAt: new Date(record.updated_at),
+    };
+}
+// =============================================================================
+// Repository
+// =============================================================================
+export const planRepository = {
+    /**
+     * Create a new plan
+     */
+    create(input) {
+        const db = getDb();
+        const now = new Date().toISOString();
+        const result = db
+            .prepare(`
+        INSERT INTO project_documents (
+          project_id, doc_type, title, content, status, work_item_id,
+          created_at, updated_at
+        ) VALUES (?, 'plan', ?, ?, 'draft', ?, ?, ?)
+      `)
+            .run(input.project_id, input.name, input.content, input.work_item_id ?? null, now, now);
+        const plan = this.getById(Number(result.lastInsertRowid));
+        if (!plan)
+            throw new Error('Failed to create plan');
+        return plan;
+    },
+    /**
+     * Get plan by ID
+     */
+    getById(id) {
+        const db = getDb();
+        const record = db
+            .prepare(`SELECT * FROM project_documents WHERE id = ? AND doc_type = 'plan'`)
+            .get(id);
+        return record ? recordToPlan(record) : null;
+    },
+    /**
+     * Get plan by name for a project
+     */
+    getByName(projectId, name) {
+        const db = getDb();
+        const record = db
+            .prepare(`SELECT * FROM project_documents
+         WHERE project_id = ? AND doc_type = 'plan' AND title = ?`)
+            .get(projectId, name);
+        return record ? recordToPlan(record) : null;
+    },
+    /**
+     * Get plan with linked work item details
+     */
+    getWithWorkItem(id) {
+        const db = getDb();
+        const record = db
+            .prepare(`
+        SELECT pd.*, wi.item_id as wi_item_id, wi.title as wi_title, wi.status as wi_status
+        FROM project_documents pd
+        LEFT JOIN work_items wi ON pd.work_item_id = wi.id
+        WHERE pd.id = ? AND pd.doc_type = 'plan'
+      `)
+            .get(id);
+        if (!record)
+            return null;
+        const plan = recordToPlan(record);
+        if (record.wi_item_id && record.work_item_id !== null) {
+            plan.workItem = {
+                id: record.work_item_id,
+                itemId: record.wi_item_id,
+                title: record.wi_title ?? '',
+                status: record.wi_status ?? '',
+            };
+        }
+        return plan;
+    },
+    /**
+     * Update a plan
+     */
+    update(id, input) {
+        const db = getDb();
+        // Get current plan for status validation
+        const current = this.getById(id);
+        if (!current)
+            return null;
+        // Validate status transition if changing status
+        if (input.status && input.status !== current.status) {
+            if (!isValidTransition(current.status, input.status)) {
+                throw new Error(`Invalid status transition: ${current.status} → ${input.status}`);
+            }
+        }
+        const updates = [];
+        const params = [];
+        if (input.content !== undefined) {
+            updates.push('content = ?');
+            params.push(input.content);
+        }
+        if (input.status !== undefined) {
+            updates.push('status = ?');
+            params.push(input.status);
+        }
+        if (input.work_item_id !== undefined) {
+            updates.push('work_item_id = ?');
+            params.push(input.work_item_id);
+        }
+        if (updates.length === 0) {
+            return current;
+        }
+        updates.push('updated_at = ?');
+        params.push(new Date().toISOString());
+        params.push(id);
+        const query = `UPDATE project_documents SET ${updates.join(', ')} WHERE id = ? AND doc_type = 'plan'`;
+        db.prepare(query).run(...params);
+        return this.getById(id);
+    },
+    /**
+     * Delete a plan
+     */
+    delete(id) {
+        const db = getDb();
+        const result = db
+            .prepare(`DELETE FROM project_documents WHERE id = ? AND doc_type = 'plan'`)
+            .run(id);
+        return result.changes > 0;
+    },
+    /**
+     * List plans for a project
+     */
+    list(projectId, options = {}) {
+        const db = getDb();
+        const conditions = ["pd.project_id = ?", "pd.doc_type = 'plan'"];
+        const params = [projectId];
+        // Filter by status
+        if (options.status) {
+            if (Array.isArray(options.status)) {
+                const placeholders = options.status.map(() => '?').join(', ');
+                conditions.push(`pd.status IN (${placeholders})`);
+                params.push(...options.status);
+            }
+            else {
+                conditions.push('pd.status = ?');
+                params.push(options.status);
+            }
+        }
+        // Filter by work item
+        if (options.work_item_id !== undefined) {
+            conditions.push('pd.work_item_id = ?');
+            params.push(options.work_item_id);
+        }
+        // Order by
+        let orderBy = 'pd.updated_at DESC';
+        switch (options.order_by) {
+            case 'updated_asc':
+                orderBy = 'pd.updated_at ASC';
+                break;
+            case 'created_desc':
+                orderBy = 'pd.created_at DESC';
+                break;
+            case 'name_asc':
+                orderBy = 'pd.title ASC';
+                break;
+        }
+        // Limit
+        const limit = options.limit ?? 20;
+        const query = `
+      SELECT pd.*, wi.title as work_item_title, wi.item_id as work_item_item_id
+      FROM project_documents pd
+      LEFT JOIN work_items wi ON pd.work_item_id = wi.id
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY ${orderBy}
+      LIMIT ?
+    `;
+        params.push(limit);
+        const records = db.prepare(query).all(...params);
+        return records.map(recordToPlanSummary);
+    },
+    /**
+     * Count plans by status for a project
+     */
+    countByStatus(projectId) {
+        const db = getDb();
+        const results = db
+            .prepare(`
+        SELECT status, COUNT(*) as count
+        FROM project_documents
+        WHERE project_id = ? AND doc_type = 'plan'
+        GROUP BY status
+      `)
+            .all(projectId);
+        const counts = {
+            draft: 0,
+            approved: 0,
+            in_progress: 0,
+            completed: 0,
+            abandoned: 0,
+        };
+        for (const row of results) {
+            if (row.status && row.status in counts) {
+                counts[row.status] = row.count;
+            }
+        }
+        return counts;
+    },
+    /**
+     * Get plans with status 'in_progress' for a project
+     */
+    getInProgress(projectId) {
+        return this.list(projectId, { status: 'in_progress' });
+    },
+    /**
+     * Check if there are any in_progress plans for a project
+     */
+    hasInProgress(projectId) {
+        const db = getDb();
+        const result = db
+            .prepare(`
+        SELECT COUNT(*) as count FROM project_documents
+        WHERE project_id = ? AND doc_type = 'plan' AND status = 'in_progress'
+      `)
+            .get(projectId);
+        return result.count > 0;
+    },
+    /**
+     * Link a plan to a work item
+     */
+    linkWorkItem(planId, workItemId) {
+        return this.update(planId, { work_item_id: workItemId });
+    },
+    /**
+     * Unlink a plan from its work item
+     */
+    unlinkWorkItem(planId) {
+        return this.update(planId, { work_item_id: null });
+    },
+};