@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/tools/backlog-wrappers.js

@@ -0,0 +1,353 @@
+/**
+ * Backlog Tool Wrappers
+ *
+ * These wrappers provide `backlog_read` and `backlog_write` tools that skills expect,
+ * but internally delegate to the `workitem_*` database tools.
+ *
+ * This allows library skills (which reference backlog_*) to work seamlessly
+ * with the CLI's database-backed workitem system.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/sdk';
+import { workItemRepository } from '../db/repositories/index.js';
+import { getActiveProject } from './project-db.js';
+// =============================================================================
+// Type Mappings (Library ↔ CLI)
+// =============================================================================
+// Library status → CLI status
+const STATUS_TO_CLI = {
+    'backlog': 'backlog',
+    'in-progress': 'in_progress',
+    'done': 'completed',
+    'blocked': 'skipped', // closest match
+};
+// CLI status → Library status
+const STATUS_TO_LIBRARY = {
+    'backlog': 'backlog',
+    'in_progress': 'in-progress',
+    'completed': 'done',
+    'skipped': 'blocked',
+};
+// Library type → CLI type
+const TYPE_TO_CLI = {
+    'feature': 'feature',
+    'bug': 'bug',
+    'chore': 'chore',
+    'spike': 'tech-debt', // closest match
+};
+// CLI type → Library type
+const TYPE_TO_LIBRARY = {
+    'feature': 'feature',
+    'bug': 'bug',
+    'chore': 'chore',
+    'tech-debt': 'spike',
+};
+export const backlogReadTool = defineTool({
+    name: 'backlog_read',
+    description: 'Read backlog items from the project. ' +
+        'Use filters to narrow results. Use id parameter to get a specific item. ' +
+        'Returns items sorted by priority (critical first) then by creation date.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            id: {
+                type: 'string',
+                description: 'Get a specific item by ID (e.g., "FEAT-001")',
+            },
+            status: {
+                type: 'string',
+                enum: ['backlog', 'in-progress', 'done', 'blocked'],
+                description: 'Filter by status',
+            },
+            type: {
+                type: 'string',
+                enum: ['feature', 'bug', 'chore', 'spike'],
+                description: 'Filter by item type',
+            },
+            search: {
+                type: 'string',
+                description: 'Search in title and description',
+            },
+            priority: {
+                type: 'string',
+                enum: ['critical', 'high', 'medium', 'low'],
+                description: 'Filter by priority',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum items to return (default: 20)',
+            },
+        },
+    },
+    execute: async (input) => {
+        try {
+            // Note: workItemRepository methods are synchronous, but we keep async for interface consistency
+            await Promise.resolve();
+            const projectId = getActiveProject()?.id;
+            if (!projectId) {
+                return createSuccessResult({
+                    items: [],
+                    total: 0,
+                    filtered: 0,
+                    message: 'No active project. Use /projects to select a project first.',
+                });
+            }
+            // If specific ID requested, look it up directly
+            if (input.id) {
+                const item = workItemRepository.getByItemId(projectId, input.id);
+                if (!item) {
+                    return createErrorResult(`Item not found: ${input.id}`);
+                }
+                return createSuccessResult({
+                    items: [{
+                            id: item.itemId,
+                            type: TYPE_TO_LIBRARY[item.type],
+                            title: item.title,
+                            description: item.description || '',
+                            status: STATUS_TO_LIBRARY[item.status],
+                            priority: item.priority,
+                        }],
+                    total: 1,
+                    filtered: 1,
+                });
+            }
+            // Build query
+            const queryInput = {
+                project_id: projectId,
+                status: input.status ? STATUS_TO_CLI[input.status] : 'all',
+                type: input.type ? TYPE_TO_CLI[input.type] : 'all',
+                priority: input.priority || 'all',
+                search: input.search,
+                limit: input.limit || 20,
+                offset: 0,
+            };
+            const result = workItemRepository.query(queryInput);
+            // Map items to library format
+            const items = result.items.map((item) => ({
+                id: item.itemId,
+                type: TYPE_TO_LIBRARY[item.type],
+                title: item.title,
+                description: item.description || '',
+                status: STATUS_TO_LIBRARY[item.status],
+                priority: item.priority,
+                createdAt: item.createdAt.toISOString(),
+                updatedAt: item.createdAt.toISOString(), // DB doesn't track updatedAt separately
+            }));
+            return createSuccessResult({
+                items,
+                total: result.total,
+                filtered: items.length,
+            });
+        }
+        catch (error) {
+            return createErrorResult(error instanceof Error ? error.message : String(error));
+        }
+    },
+});
+export const backlogWriteTool = defineTool({
+    name: 'backlog_write',
+    description: 'Create, update, or delete backlog items. ' +
+        'Actions: add (new item), update (modify existing), delete (remove), replace (full list). ' +
+        'IDs are auto-generated for new items based on type (e.g., FEAT-001, BUG-002).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['add', 'update', 'delete', 'replace'],
+                description: 'Action to perform',
+            },
+            item: {
+                type: 'object',
+                description: 'Item to add or update (for add/update actions)',
+                properties: {
+                    id: { type: 'string', description: 'Item ID (required for update)' },
+                    type: {
+                        type: 'string',
+                        enum: ['feature', 'bug', 'chore', 'spike'],
+                        description: 'Item type (required for add)',
+                    },
+                    title: { type: 'string', description: 'Item title' },
+                    description: { type: 'string', description: 'Detailed description' },
+                    status: {
+                        type: 'string',
+                        enum: ['backlog', 'in-progress', 'done', 'blocked'],
+                        description: 'Item status',
+                    },
+                    priority: {
+                        type: 'string',
+                        enum: ['critical', 'high', 'medium', 'low'],
+                        description: 'Priority level',
+                    },
+                    owner: {
+                        type: 'string',
+                        description: 'Owner/assignee of the item',
+                    },
+                    commit_hash: {
+                        type: 'string',
+                        description: 'Git commit hash associated with the item (for update)',
+                    },
+                },
+            },
+            deleteId: {
+                type: 'string',
+                description: 'Item ID to delete (for delete action)',
+            },
+            items: {
+                type: 'array',
+                description: 'Full list of items (for replace action)',
+                items: {
+                    type: 'object',
+                },
+            },
+        },
+        required: ['action'],
+    },
+    execute: async (input) => {
+        try {
+            // Note: workItemRepository methods are synchronous, but we keep async for interface consistency
+            await Promise.resolve();
+            const projectId = getActiveProject()?.id;
+            if (!projectId) {
+                return createErrorResult('No active project. Use /projects to select a project first.');
+            }
+            switch (input.action) {
+                case 'add': {
+                    if (!input.item) {
+                        return createErrorResult('Item is required for add action');
+                    }
+                    if (!input.item.type) {
+                        return createErrorResult('Item type is required for add action');
+                    }
+                    if (!input.item.title) {
+                        return createErrorResult('Item title is required for add action');
+                    }
+                    const createInput = {
+                        project_id: projectId,
+                        type: TYPE_TO_CLI[input.item.type],
+                        title: input.item.title,
+                        description: input.item.description,
+                        priority: input.item.priority,
+                        owner: input.item.owner,
+                    };
+                    const item = workItemRepository.create(createInput);
+                    return createSuccessResult({
+                        success: true,
+                        action: 'add',
+                        itemId: item.itemId,
+                        message: `Created ${item.itemId}: "${item.title}"`,
+                    });
+                }
+                case 'update': {
+                    if (!input.item?.id) {
+                        return createErrorResult('Item ID is required for update action');
+                    }
+                    const existingItem = workItemRepository.getByItemId(projectId, input.item.id);
+                    if (!existingItem) {
+                        return createErrorResult(`Item not found: ${input.item.id}`);
+                    }
+                    const updateInput = {};
+                    if (input.item.status) {
+                        updateInput.status = STATUS_TO_CLI[input.item.status];
+                    }
+                    if (input.item.priority) {
+                        updateInput.priority = input.item.priority;
+                    }
+                    if (input.item.title) {
+                        updateInput.title = input.item.title;
+                    }
+                    if (input.item.description !== undefined) {
+                        updateInput.description = input.item.description;
+                    }
+                    if (input.item.owner !== undefined) {
+                        updateInput.owner = input.item.owner;
+                    }
+                    if (input.item.commit_hash) {
+                        updateInput.commit_hash = input.item.commit_hash;
+                    }
+                    const updated = workItemRepository.update(existingItem.id, updateInput);
+                    if (!updated) {
+                        return createErrorResult(`Failed to update item: ${input.item.id}`);
+                    }
+                    return createSuccessResult({
+                        success: true,
+                        action: 'update',
+                        itemId: input.item.id,
+                        message: `Updated ${input.item.id}`,
+                    });
+                }
+                case 'delete': {
+                    const deleteId = input.deleteId || input.item?.id;
+                    if (!deleteId) {
+                        return createErrorResult('deleteId or item.id is required for delete action');
+                    }
+                    const existingItem = workItemRepository.getByItemId(projectId, deleteId);
+                    if (!existingItem) {
+                        return createErrorResult(`Item not found: ${deleteId}`);
+                    }
+                    const deleted = workItemRepository.delete(existingItem.id);
+                    if (!deleted) {
+                        return createErrorResult(`Failed to delete item: ${deleteId}`);
+                    }
+                    return createSuccessResult({
+                        success: true,
+                        action: 'delete',
+                        itemId: deleteId,
+                        message: `Deleted ${deleteId}`,
+                    });
+                }
+                case 'replace': {
+                    if (!input.items) {
+                        return createErrorResult('Items array is required for replace action');
+                    }
+                    // Delete all existing items
+                    const existing = workItemRepository.query({
+                        project_id: projectId,
+                        limit: 1000,
+                        offset: 0,
+                    });
+                    for (const item of existing.items) {
+                        workItemRepository.delete(item.id);
+                    }
+                    // Add all new items
+                    const newIds = [];
+                    for (const newItem of input.items) {
+                        const createInput = {
+                            project_id: projectId,
+                            type: TYPE_TO_CLI[newItem.type],
+                            title: newItem.title,
+                            description: newItem.description,
+                            priority: newItem.priority,
+                        };
+                        const created = workItemRepository.create(createInput);
+                        newIds.push(created.itemId);
+                        // Update status if not backlog
+                        if (newItem.status && newItem.status !== 'backlog') {
+                            workItemRepository.update(created.id, {
+                                status: STATUS_TO_CLI[newItem.status],
+                            });
+                        }
+                    }
+                    return createSuccessResult({
+                        success: true,
+                        action: 'replace',
+                        itemCount: input.items.length,
+                        newIds,
+                        message: `Replaced backlog with ${String(input.items.length)} items`,
+                    });
+                }
+                default:
+                    return createErrorResult(`Unknown action: ${input.action}`);
+            }
+        }
+        catch (error) {
+            return createErrorResult(error instanceof Error ? error.message : String(error));
+        }
+    },
+});
+/**
+ * All backlog wrapper tools
+ */
+export const backlogWrapperTools = [
+    backlogReadTool,
+    backlogWriteTool,
+];

package/dist/tools/backlog.d.ts

@@ -34,7 +34,7 @@ interface BacklogReadInput {
     search?: string;
     id?: string;
 }
-export declare const backlogReadTool: import("@compilr-dev/agents").Tool<BacklogReadInput>;
+export declare const backlogReadTool: import("@compilr-dev/sdk").Tool<BacklogReadInput>;
 interface BacklogWriteInput {
     action: 'add' | 'update' | 'remove' | 'reorder';
     items?: Array<{
@@ -49,5 +49,5 @@ interface BacklogWriteInput {
     ids?: string[];
     order?: string[];
 }
-export declare const backlogWriteTool: import("@compilr-dev/agents").Tool<BacklogWriteInput>;
+export declare const backlogWriteTool: import("@compilr-dev/sdk").Tool<BacklogWriteInput>;
 export {};

package/dist/tools/backlog.js

@@ -6,7 +6,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { defineTool } from '@compilr-dev/agents';
+import { defineTool } from '@compilr-dev/sdk';
 // =============================================================================
 // Backlog File Detection
 // =============================================================================
@@ -357,7 +357,7 @@ export const backlogReadTool = defineTool({
         if (!backlogPath) {
             return Promise.resolve({
                 success: false,
-                error: 'No backlog file found. Run /init to create a project first, or /design to create the backlog.',
+                error: 'No backlog file found. Run /new to create a project first, or /design to create the backlog.',
             });
         }
         try {

package/dist/tools/db-tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Database Tools Index
+ *
+ * All 24 platform tools (project, workitem, document, plan, backlog) are now
+ * provided by the SDK via platform-adapter.ts. This file re-exports them
+ * along with state management functions still needed by ~15+ CLI files.
+ */
+export { getActiveProject, setActiveProject } from './project-db.js';
+/**
+ * All database tools combined (24 tools from SDK)
+ */
+export declare const allDbTools: import("@compilr-dev/agents").Tool<never>[];

package/dist/tools/db-tools.js

@@ -0,0 +1,14 @@
+/**
+ * Database Tools Index
+ *
+ * All 24 platform tools (project, workitem, document, plan, backlog) are now
+ * provided by the SDK via platform-adapter.ts. This file re-exports them
+ * along with state management functions still needed by ~15+ CLI files.
+ */
+import { allPlatformTools } from './platform-adapter.js';
+// Re-export state management functions (still needed by many CLI files)
+export { getActiveProject, setActiveProject } from './project-db.js';
+/**
+ * All database tools combined (24 tools from SDK)
+ */
+export const allDbTools = allPlatformTools;

package/dist/tools/delegate-background.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Delegate Background Tool - Coordinator Mode
+ *
+ * Allows the coordinator to delegate tasks to specialists running in background.
+ * Unlike the foreground `delegate` tool (which switches the active agent),
+ * this tool keeps the coordinator in the foreground while the specialist
+ * works independently in the background.
+ *
+ * Flow:
+ * 1. Coordinator calls delegate_background(agentId, task)
+ * 2. DelegationTracker registers the delegation
+ * 3. Specialist starts as background agent (or queued if busy)
+ * 4. Coordinator continues working
+ * 5. On completion, coordinator is notified via completion events (Phase 2)
+ */
+interface DelegateBackgroundInput {
+    /** Target specialist agent ID (e.g., 'arch', 'dev', 'qa') */
+    agentId: string;
+    /** Detailed task description for the specialist */
+    task: string;
+    /** Optional todo index to associate with this delegation */
+    todoIndex?: number;
+    /** What the specialist should produce (e.g., "architecture document") */
+    expectedOutput?: string;
+}
+export declare const delegateBackgroundTool: import("@compilr-dev/sdk").Tool<DelegateBackgroundInput>;
+export {};

package/dist/tools/delegate-background.js

@@ -0,0 +1,115 @@
+/**
+ * Delegate Background Tool - Coordinator Mode
+ *
+ * Allows the coordinator to delegate tasks to specialists running in background.
+ * Unlike the foreground `delegate` tool (which switches the active agent),
+ * this tool keeps the coordinator in the foreground while the specialist
+ * works independently in the background.
+ *
+ * Flow:
+ * 1. Coordinator calls delegate_background(agentId, task)
+ * 2. DelegationTracker registers the delegation
+ * 3. Specialist starts as background agent (or queued if busy)
+ * 4. Coordinator continues working
+ * 5. On completion, coordinator is notified via completion events (Phase 2)
+ */
+import { defineTool } from '@compilr-dev/sdk';
+import { getDelegateBackgroundHandler } from '../shared-handlers.js';
+// =============================================================================
+// Tool Definition
+// =============================================================================
+export const delegateBackgroundTool = defineTool({
+    name: 'delegate_background',
+    description: 'Delegate a task to a specialist running in background. ' +
+        'The specialist executes independently while you continue working. ' +
+        'You will be notified when the specialist completes. ' +
+        'Use delegation_status to check progress. ' +
+        'Prefer this over delegate — it keeps you in control and tracks status. ' +
+        'Only available to the coordinator.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agentId: {
+                type: 'string',
+                description: 'Target specialist agent ID (e.g., "arch", "dev", "qa")',
+            },
+            task: {
+                type: 'string',
+                description: 'Detailed task description for the specialist',
+            },
+            todoIndex: {
+                type: 'number',
+                description: 'Optional todo index to associate with this delegation',
+            },
+            expectedOutput: {
+                type: 'string',
+                description: 'What the specialist should produce (e.g., "architecture document", "implementation")',
+            },
+        },
+        required: ['agentId', 'task'],
+    },
+    execute: async (input) => {
+        try {
+            // Validate input
+            if (!input.agentId || input.agentId.trim().length === 0) {
+                return {
+                    success: false,
+                    error: 'Agent ID is required',
+                };
+            }
+            if (!input.task || input.task.trim().length === 0) {
+                return {
+                    success: false,
+                    error: 'Task description is required',
+                };
+            }
+            // Prevent self-delegation
+            if (input.agentId.trim() === 'default') {
+                return {
+                    success: false,
+                    error: 'Cannot delegate to yourself (the coordinator). Delegate to a specialist agent.',
+                };
+            }
+            // Get the delegate background handler from shared-handlers
+            const handler = getDelegateBackgroundHandler();
+            if (!handler) {
+                return {
+                    success: false,
+                    error: 'Delegate background handler not initialized. ' +
+                        'This tool requires multi-agent mode with coordinator role.',
+                };
+            }
+            // Execute background delegation
+            const result = await handler({
+                agentId: input.agentId.trim(),
+                task: input.task.trim(),
+                todoIndex: input.todoIndex,
+                expectedOutput: input.expectedOutput?.trim(),
+            });
+            if (result.error) {
+                return {
+                    success: false,
+                    error: result.error,
+                };
+            }
+            const output = {
+                delegated: true,
+                delegationId: result.delegationId,
+                status: result.status,
+                message: result.status === 'queued'
+                    ? `Task queued for $${input.agentId} (currently busy). It will start when they're free.`
+                    : `Task delegated to $${input.agentId} running in background. You'll be notified on completion.`,
+            };
+            return {
+                success: true,
+                result: output,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Background delegation failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    },
+});

package/dist/tools/delegate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Delegate Tool - Multi-Agent Task Delegation
+ *
+ * Allows the coordinator to delegate tasks to specialist agents.
+ * Only available to the coordinator (default agent).
+ *
+ * Flow:
+ * 1. Coordinator calls delegate(agentId, task, reason?)
+ * 2. CLI shows approval prompt
+ * 3. If approved: auto-switch to specialist, inject task
+ * 4. If denied: return "User declined" to coordinator
+ */
+interface DelegateInput {
+    /** Target agent ID (e.g., 'arch', 'dev', 'qa') */
+    agentId: string;
+    /** Task description for the specialist */
+    task: string;
+    /** Optional reason for delegation (shown to user for context) */
+    reason?: string;
+}
+export declare const delegateTool: import("@compilr-dev/sdk").Tool<DelegateInput>;
+export {};

package/dist/tools/delegate.js

@@ -0,0 +1,97 @@
+/**
+ * Delegate Tool - Multi-Agent Task Delegation
+ *
+ * Allows the coordinator to delegate tasks to specialist agents.
+ * Only available to the coordinator (default agent).
+ *
+ * Flow:
+ * 1. Coordinator calls delegate(agentId, task, reason?)
+ * 2. CLI shows approval prompt
+ * 3. If approved: auto-switch to specialist, inject task
+ * 4. If denied: return "User declined" to coordinator
+ */
+import { defineTool } from '@compilr-dev/sdk';
+import { getDelegateHandler } from '../shared-handlers.js';
+// =============================================================================
+// Tool Definition
+// =============================================================================
+export const delegateTool = defineTool({
+    name: 'delegate',
+    description: 'Hand off the conversation to a specialist (foreground switch). ' +
+        'You stop working and the specialist takes over. No status tracking. ' +
+        'Use delegate_background instead if you want to continue working while ' +
+        'the specialist runs in the background (with delegation tracking). ' +
+        'Only available to the coordinator.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agentId: {
+                type: 'string',
+                description: 'Target agent ID (e.g., "arch", "dev", "qa")',
+            },
+            task: {
+                type: 'string',
+                description: 'Task description for the specialist - be specific and clear',
+            },
+            reason: {
+                type: 'string',
+                description: 'Why this specialist is suited for the task (shown to user)',
+            },
+        },
+        required: ['agentId', 'task'],
+    },
+    execute: async (input) => {
+        try {
+            // Validate input
+            if (!input.agentId || input.agentId.trim().length === 0) {
+                return {
+                    success: false,
+                    error: 'Agent ID is required',
+                };
+            }
+            if (!input.task || input.task.trim().length === 0) {
+                return {
+                    success: false,
+                    error: 'Task description is required',
+                };
+            }
+            // Get the delegate handler from shared-handlers
+            const delegateHandler = getDelegateHandler();
+            if (!delegateHandler) {
+                return {
+                    success: false,
+                    error: 'Delegate handler not initialized. ' +
+                        'This tool requires multi-agent mode with coordinator role.',
+                };
+            }
+            // Execute delegation (shows approval prompt, switches if approved)
+            const result = await delegateHandler({
+                agentId: input.agentId.trim(),
+                task: input.task.trim(),
+                reason: input.reason?.trim(),
+            });
+            if (result.error) {
+                return {
+                    success: false,
+                    error: result.error,
+                };
+            }
+            const output = {
+                delegated: result.success,
+                message: result.declined
+                    ? 'User declined the delegation. Continue handling the task yourself.'
+                    : `Task delegated to $${input.agentId}. They will handle it from here.`,
+            };
+            return {
+                success: true,
+                result: output,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Delegation failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    },
+});