@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/tools/delegation-status.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Delegation Status Tool - Coordinator Mode
+ *
+ * Read-only tool for the coordinator to query delegation progress.
+ * Queries the DelegationTracker singleton and returns formatted status.
+ */
+interface DelegationStatusInput {
+    /** Specific delegation ID (e.g., "del_abc12345") */
+    delegation_id?: string;
+    /** Filter by target agent (e.g., "dev") */
+    agent_id?: string;
+    /** Filter by status: active (pending+running), completed, failed, all. Default: active */
+    status?: 'active' | 'completed' | 'failed' | 'all';
+}
+export declare const delegationStatusTool: import("@compilr-dev/sdk").Tool<DelegationStatusInput>;
+export {};

package/dist/tools/delegation-status.js

@@ -0,0 +1,128 @@
+/**
+ * Delegation Status Tool - Coordinator Mode
+ *
+ * Read-only tool for the coordinator to query delegation progress.
+ * Queries the DelegationTracker singleton and returns formatted status.
+ */
+import { defineTool } from '@compilr-dev/sdk';
+import { getDelegationTracker } from '../multi-agent/delegation-tracker.js';
+// =============================================================================
+// Helpers
+// =============================================================================
+function formatDuration(from, to) {
+    const endTime = to ?? new Date();
+    const ms = endTime.getTime() - from.getTime();
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0) {
+        return `${String(hours)}h ${String(minutes % 60)}m`;
+    }
+    else if (minutes > 0) {
+        return `${String(minutes)}m ${String(seconds % 60)}s`;
+    }
+    else {
+        return `${String(seconds)}s`;
+    }
+}
+function formatDelegation(d) {
+    const entry = {
+        id: d.id,
+        targetAgent: d.targetAgentId,
+        task: d.task.length > 100 ? d.task.slice(0, 100) + '...' : d.task,
+        status: d.status,
+        duration: formatDuration(d.createdAt, d.completedAt),
+    };
+    if (d.todoIndex !== undefined) {
+        entry.todoIndex = d.todoIndex;
+    }
+    if (d.result) {
+        entry.result = {
+            success: d.result.success,
+            summary: d.result.summary,
+            artifactIds: d.result.artifactIds,
+            ...(d.result.error ? { error: d.result.error } : {}),
+        };
+    }
+    return entry;
+}
+// =============================================================================
+// Tool Definition
+// =============================================================================
+export const delegationStatusTool = defineTool({
+    name: 'delegation_status',
+    description: 'Query the status of tasks delegated via delegate_background. ' +
+        'Returns active delegations by default (pending and running). ' +
+        'Use delegation_id for a specific delegation, agent_id to filter by agent, ' +
+        'or status to see completed/failed/all delegations. ' +
+        'Note: Only tracks delegate_background calls, not foreground delegate.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            delegation_id: {
+                type: 'string',
+                description: 'Specific delegation ID (e.g., "del_abc12345")',
+            },
+            agent_id: {
+                type: 'string',
+                description: 'Filter by target agent (e.g., "dev", "arch")',
+            },
+            status: {
+                type: 'string',
+                enum: ['active', 'completed', 'failed', 'all'],
+                description: 'Filter by status. Default: "active" (pending + running)',
+            },
+        },
+    },
+    execute: async (input) => {
+        const tracker = await Promise.resolve(getDelegationTracker());
+        // Single delegation lookup
+        if (input.delegation_id) {
+            const delegation = tracker.get(input.delegation_id);
+            if (!delegation) {
+                return {
+                    success: false,
+                    error: `Delegation ${input.delegation_id} not found`,
+                };
+            }
+            return {
+                success: true,
+                result: {
+                    delegations: [formatDelegation(delegation)],
+                    stats: tracker.getStats(),
+                },
+            };
+        }
+        // Get all delegations then filter
+        let delegations;
+        if (input.agent_id) {
+            delegations = tracker.getByAgent(input.agent_id);
+        }
+        else {
+            delegations = tracker.getAll();
+        }
+        // Apply status filter
+        const filter = input.status ?? 'active';
+        if (filter !== 'all') {
+            delegations = delegations.filter((d) => {
+                switch (filter) {
+                    case 'active':
+                        return d.status === 'pending' || d.status === 'running';
+                    case 'completed':
+                        return d.status === 'completed';
+                    case 'failed':
+                        return d.status === 'failed';
+                    default:
+                        return true;
+                }
+            });
+        }
+        return {
+            success: true,
+            result: {
+                delegations: delegations.map(formatDelegation),
+                stats: tracker.getStats(),
+            },
+        };
+    },
+});

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

@@ -0,0 +1,43 @@
+/**
+ * Document Database Tools
+ *
+ * Tools for managing project documents (PRD, architecture, design notes) in the database.
+ */
+/**
+ * project_document_add - Add or update a project document
+ */
+export declare const projectDocumentAddTool: import("@compilr-dev/sdk").Tool<{
+    project_id?: number;
+    doc_type: string;
+    title: string;
+    content: string;
+}>;
+/**
+ * project_document_get - Get a project document
+ */
+export declare const projectDocumentGetTool: import("@compilr-dev/sdk").Tool<{
+    project_id?: number;
+    doc_type: string;
+}>;
+/**
+ * project_document_list - List all documents for a project
+ */
+export declare const projectDocumentListTool: import("@compilr-dev/sdk").Tool<{
+    project_id?: number;
+}>;
+/**
+ * project_document_delete - Delete a project document
+ */
+export declare const projectDocumentDeleteTool: import("@compilr-dev/sdk").Tool<{
+    project_id?: number;
+    doc_type: string;
+}>;
+/**
+ * All document tools
+ */
+export declare const documentDbTools: import("@compilr-dev/sdk").Tool<{
+    project_id?: number;
+    doc_type: string;
+    title: string;
+    content: string;
+}>[];

package/dist/tools/document-db.js

@@ -0,0 +1,220 @@
+/**
+ * Document Database Tools
+ *
+ * Tools for managing project documents (PRD, architecture, design notes) in the database.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/sdk';
+import { documentRepository } from '../db/repositories/index.js';
+import { getActiveProject } from './project-db.js';
+/**
+ * project_document_add - Add or update a project document
+ */
+export const projectDocumentAddTool = defineTool({
+    name: 'project_document_add',
+    description: 'Add or update a project document (PRD, architecture, design, notes). If a document of the same type exists, it will be updated.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            project_id: {
+                type: 'number',
+                description: 'Project ID (uses active project if not provided)',
+            },
+            doc_type: {
+                type: 'string',
+                enum: ['prd', 'architecture', 'design', 'notes'],
+                description: 'Document type',
+            },
+            title: {
+                type: 'string',
+                description: 'Document title',
+            },
+            content: {
+                type: 'string',
+                description: 'Document content (markdown)',
+            },
+        },
+        required: ['doc_type', 'title', 'content'],
+    },
+    execute: async (input) => {
+        await Promise.resolve(); // Required for async type signature
+        try {
+            const projectId = input.project_id || getActiveProject()?.id;
+            if (!projectId) {
+                return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+            }
+            const createInput = {
+                project_id: projectId,
+                doc_type: input.doc_type,
+                title: input.title,
+                content: input.content,
+            };
+            const doc = documentRepository.upsert(createInput);
+            return createSuccessResult({
+                success: true,
+                message: `Document "${doc.title}" saved`,
+                document: {
+                    id: doc.id,
+                    docType: doc.docType,
+                    title: doc.title,
+                    contentLength: doc.content.length,
+                    updatedAt: doc.updatedAt.toISOString(),
+                },
+            });
+        }
+        catch (error) {
+            return createErrorResult(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});
+/**
+ * project_document_get - Get a project document
+ */
+export const projectDocumentGetTool = defineTool({
+    name: 'project_document_get',
+    description: 'Get a project document by type. Returns the document content.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            project_id: {
+                type: 'number',
+                description: 'Project ID (uses active project if not provided)',
+            },
+            doc_type: {
+                type: 'string',
+                enum: ['prd', 'architecture', 'design', 'notes'],
+                description: 'Document type to retrieve',
+            },
+        },
+        required: ['doc_type'],
+    },
+    execute: async (input) => {
+        await Promise.resolve(); // Required for async type signature
+        try {
+            const projectId = input.project_id || getActiveProject()?.id;
+            if (!projectId) {
+                return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+            }
+            const doc = documentRepository.getByType(projectId, input.doc_type);
+            if (!doc) {
+                return createSuccessResult({
+                    success: true,
+                    document: null,
+                    message: `No ${input.doc_type} document found for this project`,
+                });
+            }
+            return createSuccessResult({
+                success: true,
+                document: {
+                    id: doc.id,
+                    docType: doc.docType,
+                    title: doc.title,
+                    content: doc.content,
+                    createdAt: doc.createdAt.toISOString(),
+                    updatedAt: doc.updatedAt.toISOString(),
+                },
+            });
+        }
+        catch (error) {
+            return createErrorResult(`Failed to get document: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});
+/**
+ * project_document_list - List all documents for a project
+ */
+export const projectDocumentListTool = defineTool({
+    name: 'project_document_list',
+    description: 'List all documents for a project. Returns document metadata without full content.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            project_id: {
+                type: 'number',
+                description: 'Project ID (uses active project if not provided)',
+            },
+        },
+        required: [],
+    },
+    execute: async (input) => {
+        await Promise.resolve(); // Required for async type signature
+        try {
+            const projectId = input.project_id || getActiveProject()?.id;
+            if (!projectId) {
+                return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+            }
+            const docs = documentRepository.listByProject(projectId);
+            const documents = docs.map((doc) => ({
+                id: doc.id,
+                docType: doc.docType,
+                title: doc.title,
+                contentLength: doc.content.length,
+                createdAt: doc.createdAt.toISOString(),
+                updatedAt: doc.updatedAt.toISOString(),
+            }));
+            return createSuccessResult({
+                success: true,
+                documents,
+                count: documents.length,
+            });
+        }
+        catch (error) {
+            return createErrorResult(`Failed to list documents: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});
+/**
+ * project_document_delete - Delete a project document
+ */
+export const projectDocumentDeleteTool = defineTool({
+    name: 'project_document_delete',
+    description: 'Delete a project document by type.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            project_id: {
+                type: 'number',
+                description: 'Project ID (uses active project if not provided)',
+            },
+            doc_type: {
+                type: 'string',
+                enum: ['prd', 'architecture', 'design', 'notes'],
+                description: 'Document type to delete',
+            },
+        },
+        required: ['doc_type'],
+    },
+    execute: async (input) => {
+        await Promise.resolve(); // Required for async type signature
+        try {
+            const projectId = input.project_id || getActiveProject()?.id;
+            if (!projectId) {
+                return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+            }
+            // Find the document first
+            const doc = documentRepository.getByType(projectId, input.doc_type);
+            if (!doc) {
+                return createErrorResult(`No ${input.doc_type} document found for this project`);
+            }
+            const deleted = documentRepository.delete(doc.id);
+            if (!deleted) {
+                return createErrorResult(`Failed to delete ${input.doc_type} document`);
+            }
+            return createSuccessResult({
+                success: true,
+                message: `Document "${doc.title}" deleted`,
+            });
+        }
+        catch (error) {
+            return createErrorResult(`Failed to delete document: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});
+/**
+ * All document tools
+ */
+export const documentDbTools = [
+    projectDocumentAddTool,
+    projectDocumentGetTool,
+    projectDocumentListTool,
+    projectDocumentDeleteTool,
+];

package/dist/tools/guide-tool.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compilr Guide Tool
+ *
+ * Provides documentation about the CLI for the AI agent.
+ * The agent can call this tool to answer user questions about how to use the CLI.
+ */
+interface GuideInput {
+    query?: string;
+    list_topics?: boolean;
+}
+export declare const guideTool: import("@compilr-dev/sdk").Tool<GuideInput>;
+export {};

package/dist/tools/guide-tool.js

@@ -0,0 +1,59 @@
+/**
+ * Compilr Guide Tool
+ *
+ * Provides documentation about the CLI for the AI agent.
+ * The agent can call this tool to answer user questions about how to use the CLI.
+ */
+import { defineTool } from '@compilr-dev/sdk';
+import { searchGuide, getGuideTopics } from '../guide/index.js';
+export const guideTool = defineTool({
+    name: 'compilr_guide',
+    description: 'Get documentation about Compilr Dev CLI features and commands. ' +
+        'Use this to answer user questions about how to use the CLI. ' +
+        'Query by topic (e.g., "creating-project", "team-agents") or command (e.g., "/design", "/backlog").',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Topic or command to look up. Examples: "creating-project", "/design", "team-agents", "workflow"',
+            },
+            list_topics: {
+                type: 'boolean',
+                description: 'Set to true to list all available topics',
+            },
+        },
+    },
+    execute: (input) => {
+        if (input.list_topics) {
+            const topics = getGuideTopics();
+            return Promise.resolve({
+                success: true,
+                result: { output: `Available guide topics:\n\n${topics.map(t => `- ${t}`).join('\n')}` },
+            });
+        }
+        if (!input.query) {
+            return Promise.resolve({
+                success: true,
+                result: { output: 'Please provide a query (topic or command) or set list_topics=true to see all topics.' },
+            });
+        }
+        const results = searchGuide(input.query);
+        if (results.length === 0) {
+            const topics = getGuideTopics();
+            return Promise.resolve({
+                success: true,
+                result: { output: `No guide found for "${input.query}".\n\nAvailable topics:\n${topics.map(t => `- ${t}`).join('\n')}` },
+            });
+        }
+        // Format results
+        const formatted = results
+            .map((entry) => `## ${entry.title}\n\n${entry.content}\n`)
+            .join('\n---\n\n');
+        return Promise.resolve({
+            success: true,
+            result: { output: formatted },
+        });
+    },
+    silent: true,
+});

package/dist/tools/handoff.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Handoff Tool - Multi-Agent Task Handoff
+ *
+ * Allows any agent to hand off the current task to another agent.
+ * Available to all agents (specialists and coordinator).
+ *
+ * Flow:
+ * 1. Agent calls handoff(agentId, task, reason?)
+ * 2. CLI shows approval prompt (unless auto-approve is enabled)
+ * 3. If approved: auto-switch to target agent, inject task
+ * 4. If denied: return "User declined" to current agent
+ *
+ * One-hop rule: If this agent was itself handed a task, it cannot
+ * re-hand it off (except back to the coordinator/default).
+ */
+interface HandoffInput {
+    /** Target agent ID (e.g., 'arch', 'dev', 'qa', 'default') */
+    agentId: string;
+    /** Task description for the target agent */
+    task: string;
+    /** Optional reason for handoff (shown to user for context) */
+    reason?: string;
+}
+export declare const handoffTool: import("@compilr-dev/sdk").Tool<HandoffInput>;
+export {};

package/dist/tools/handoff.js

@@ -0,0 +1,99 @@
+/**
+ * Handoff Tool - Multi-Agent Task Handoff
+ *
+ * Allows any agent to hand off the current task to another agent.
+ * Available to all agents (specialists and coordinator).
+ *
+ * Flow:
+ * 1. Agent calls handoff(agentId, task, reason?)
+ * 2. CLI shows approval prompt (unless auto-approve is enabled)
+ * 3. If approved: auto-switch to target agent, inject task
+ * 4. If denied: return "User declined" to current agent
+ *
+ * One-hop rule: If this agent was itself handed a task, it cannot
+ * re-hand it off (except back to the coordinator/default).
+ */
+import { defineTool } from '@compilr-dev/sdk';
+import { getHandoffHandler } from '../shared-handlers.js';
+// =============================================================================
+// Tool Definition
+// =============================================================================
+export const handoffTool = defineTool({
+    name: 'handoff',
+    description: 'Hand off the current task to another team agent. ' +
+        'Use this when a task is outside your expertise or would benefit from another specialist. ' +
+        'The user will be asked to approve the handoff before switching. ' +
+        'Example: hand off architecture questions to $arch, implementation to $dev, testing to $qa.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agentId: {
+                type: 'string',
+                description: 'Target agent ID (e.g., "arch", "dev", "qa", "default")',
+            },
+            task: {
+                type: 'string',
+                description: 'Task description for the target agent - be specific and clear',
+            },
+            reason: {
+                type: 'string',
+                description: 'Why this agent is better 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 handoff handler from shared-handlers
+            const handoffHandler = getHandoffHandler();
+            if (!handoffHandler) {
+                return {
+                    success: false,
+                    error: 'Handoff handler not initialized. ' +
+                        'This tool requires multi-agent mode with a team.',
+                };
+            }
+            // Execute handoff (shows approval prompt, switches if approved)
+            const result = await handoffHandler({
+                agentId: input.agentId.trim(),
+                task: input.task.trim(),
+                reason: input.reason?.trim(),
+            });
+            if (result.error) {
+                return {
+                    success: false,
+                    error: result.error,
+                };
+            }
+            const output = {
+                handedOff: result.success,
+                message: result.declined
+                    ? 'User declined the handoff. Continue handling the task yourself.'
+                    : `Task handed off to $${input.agentId}. They will handle it from here.`,
+            };
+            return {
+                success: true,
+                result: output,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Handoff failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    },
+});

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

@@ -0,0 +1,26 @@
+/**
+ * Meta-Tools for Dynamic Tool Loading
+ *
+ * Thin singleton wrapper over @compilr-dev/sdk's MetaToolsRegistry.
+ * Provides the same module-level API used by the CLI while delegating
+ * all logic to the SDK's class-based implementation.
+ *
+ * Instead of declaring all 49 tools (~15K tokens), we declare:
+ * 1. A small set of "direct" tools (always available)
+ * 2. A get_tool_info meta-tool (always available)
+ * 3. A tool index in the system prompt
+ * 4. A transparent fallback handler that routes calls to the registry
+ */
+import { type Tool, type ToolExecutionResult } from '@compilr-dev/sdk';
+export declare function setMetaToolFilter(filter: string[] | null | undefined): void;
+export declare function getMetaToolFilter(): Set<string> | null;
+export declare function initializeMetaToolRegistry(tools: Tool[]): void;
+export declare function getRegisteredMetaTools(): Tool[];
+export declare function getMetaToolCount(): number;
+export declare function generateToolIndex(): string;
+export declare const listToolsTool: Tool<object>;
+export declare const getToolInfoTool: Tool<object>;
+export declare const useToolTool: Tool<object>;
+export declare const metaTools: Tool<object>[];
+export declare function createMetaToolFallback(): (name: string, input: Record<string, unknown>) => Promise<ToolExecutionResult | null>;
+export declare const META_TOOLS_SYSTEM_PROMPT_PREFIX = "\n## Tool Index (Specialized Tools)\n\nThese tools are called **exactly like direct tools** \u2014 just use the tool name with parameters. No special syntax or wrapper needed. The system routes them automatically.\n\n**IMPORTANT \u2014 These are CLI system tools, NOT your project's backend. Never use localhost/curl to access them.**\n\n**Parameter Rules:**\n- For **zero-parameter calls**: call the tool directly (e.g., `workitem_query()`, `git_status()`).\n- For **calls WITH parameters**: you MUST call `get_tool_info(\"tool_name\")` first to get the exact JSON schema. The signatures below are summaries only \u2014 do NOT guess parameter structure from them.\n- After a failed tool call, always call `get_tool_info()` before retrying.\n\n";

package/dist/tools/meta-tools.js

@@ -0,0 +1,47 @@
+/**
+ * Meta-Tools for Dynamic Tool Loading
+ *
+ * Thin singleton wrapper over @compilr-dev/sdk's MetaToolsRegistry.
+ * Provides the same module-level API used by the CLI while delegating
+ * all logic to the SDK's class-based implementation.
+ *
+ * Instead of declaring all 49 tools (~15K tokens), we declare:
+ * 1. A small set of "direct" tools (always available)
+ * 2. A get_tool_info meta-tool (always available)
+ * 3. A tool index in the system prompt
+ * 4. A transparent fallback handler that routes calls to the registry
+ */
+import { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX as SDK_META_TOOLS_SYSTEM_PROMPT_PREFIX, } from '@compilr-dev/sdk';
+// Singleton registry for the CLI process
+const registry = new MetaToolsRegistry();
+const metaToolSet = createMetaTools(registry);
+// =============================================================================
+// Module-level API (same signatures as before)
+// =============================================================================
+export function setMetaToolFilter(filter) {
+    registry.setFilter(filter);
+}
+export function getMetaToolFilter() {
+    return registry.getFilter();
+}
+export function initializeMetaToolRegistry(tools) {
+    registry.initialize(tools);
+}
+export function getRegisteredMetaTools() {
+    return registry.getRegisteredTools();
+}
+export function getMetaToolCount() {
+    return registry.getToolCount();
+}
+export function generateToolIndex() {
+    return registry.generateToolIndex();
+}
+// Re-export tool instances
+export const listToolsTool = metaToolSet.listToolsTool;
+export const getToolInfoTool = metaToolSet.getToolInfoTool;
+export const useToolTool = metaToolSet.useToolTool;
+export const metaTools = [listToolsTool, getToolInfoTool, useToolTool];
+export function createMetaToolFallback() {
+    return metaToolSet.createFallback();
+}
+export const META_TOOLS_SYSTEM_PROMPT_PREFIX = SDK_META_TOOLS_SYSTEM_PROMPT_PREFIX;