@compilr-dev/cli 0.5.0 → 0.5.1

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;

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

@@ -0,0 +1,54 @@
+/**
+ * Plan Database Tools
+ *
+ * Tools for managing plans in the database.
+ * Plans are used in Plan Mode for structured task planning before implementation.
+ */
+export declare const planCreateTool: import("@compilr-dev/sdk").Tool<{
+    name: string;
+    content: string;
+    work_item_id?: number;
+    project_id?: number;
+}>;
+export declare const planUpdateTool: import("@compilr-dev/sdk").Tool<{
+    plan_id: number;
+    content?: string;
+    status?: string;
+    work_item_id?: number | null;
+}>;
+export declare const planGetTool: import("@compilr-dev/sdk").Tool<{
+    plan_id?: number;
+    name?: string;
+    project_id?: number;
+}>;
+export declare const planListTool: import("@compilr-dev/sdk").Tool<{
+    project_id?: number;
+    status?: string;
+    work_item_id?: number;
+    limit?: number;
+    order_by?: string;
+}>;
+export declare const planDeleteTool: import("@compilr-dev/sdk").Tool<{
+    plan_id: number;
+}>;
+export declare const planDbTools: (import("@compilr-dev/sdk").Tool<{
+    name: string;
+    content: string;
+    work_item_id?: number;
+    project_id?: number;
+}> | import("@compilr-dev/sdk").Tool<{
+    plan_id: number;
+    content?: string;
+    status?: string;
+    work_item_id?: number | null;
+}> | import("@compilr-dev/sdk").Tool<{
+    plan_id?: number;
+    name?: string;
+    project_id?: number;
+}> | import("@compilr-dev/sdk").Tool<{
+    project_id?: number;
+    status?: string;
+    work_item_id?: number;
+    limit?: number;
+    order_by?: string;
+}>)[];

package/dist/tools/plan-tools.js

@@ -0,0 +1,338 @@
+/**
+ * Plan Database Tools
+ *
+ * Tools for managing plans in the database.
+ * Plans are used in Plan Mode for structured task planning before implementation.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/sdk';
+import { planRepository, } from '../db/repositories/index.js';
+import { getActiveProject } from './project-db.js';
+// =============================================================================
+// plan_create - Create a new plan
+// =============================================================================
+export const planCreateTool = defineTool({
+    name: 'plan_create',
+    description: 'Create a new plan for the current project. Plans are used to document implementation approaches before coding. The plan is created with "draft" status.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            name: {
+                type: 'string',
+                description: 'Plan name (kebab-case, 3-5 words). Example: "auth-jwt-migration", "add-dark-mode-toggle"',
+            },
+            content: {
+                type: 'string',
+                description: 'Plan content in markdown format. Should include: Context, Goals, Steps, Verification sections.',
+            },
+            work_item_id: {
+                type: 'number',
+                description: 'Optional: ID of the work item this plan is for. Links the plan to a backlog item.',
+            },
+            project_id: {
+                type: 'number',
+                description: 'Project ID (uses active project if not provided)',
+            },
+        },
+        required: ['name', 'content'],
+    },
+    execute: async (input) => {
+        await Promise.resolve();
+        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.');
+            }
+            // Validate name format (kebab-case)
+            if (!/^[a-z][a-z0-9-]*[a-z0-9]$/.test(input.name) && input.name.length > 2) {
+                // Allow simple 2-char names, but enforce kebab-case for longer names
+                if (input.name.length > 2 && !/^[a-z0-9-]+$/.test(input.name)) {
+                    return createErrorResult('Plan name should be kebab-case (lowercase letters, numbers, hyphens). Example: "auth-jwt-migration"');
+                }
+            }
+            const createInput = {
+                project_id: projectId,
+                name: input.name,
+                content: input.content,
+                work_item_id: input.work_item_id,
+            };
+            const plan = planRepository.create(createInput);
+            return createSuccessResult({
+                success: true,
+                message: `Plan "${plan.name}" created`,
+                plan: {
+                    id: plan.id,
+                    name: plan.name,
+                    status: plan.status,
+                    workItemId: plan.workItemId,
+                    createdAt: plan.createdAt.toISOString(),
+                },
+            });
+        }
+        catch (error) {
+            return createErrorResult(`Failed to create plan: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});
+// =============================================================================
+// plan_update - Update an existing plan
+// =============================================================================
+export const planUpdateTool = defineTool({
+    name: 'plan_update',
+    description: 'Update an existing plan. Can update content, status, or work item link. Status transitions: draft→approved→in_progress→completed. Any status can transition to "abandoned".',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            plan_id: {
+                type: 'number',
+                description: 'ID of the plan to update',
+            },
+            content: {
+                type: 'string',
+                description: 'New plan content (optional)',
+            },
+            status: {
+                type: 'string',
+                enum: ['draft', 'approved', 'in_progress', 'completed', 'abandoned'],
+                description: 'New status (optional). Valid transitions: draft→approved, approved→in_progress, in_progress→completed. Any→abandoned. abandoned→draft.',
+            },
+            work_item_id: {
+                type: ['number', 'null'],
+                description: 'Work item ID to link (optional). Use null to unlink.',
+            },
+        },
+        required: ['plan_id'],
+    },
+    execute: async (input) => {
+        await Promise.resolve();
+        try {
+            const updateInput = {};
+            if (input.content !== undefined) {
+                updateInput.content = input.content;
+            }
+            if (input.status !== undefined) {
+                updateInput.status = input.status;
+            }
+            if (input.work_item_id !== undefined) {
+                updateInput.work_item_id = input.work_item_id;
+            }
+            const plan = planRepository.update(input.plan_id, updateInput);
+            if (!plan) {
+                return createErrorResult(`Plan with ID ${String(input.plan_id)} not found`);
+            }
+            return createSuccessResult({
+                success: true,
+                message: `Plan "${plan.name}" updated`,
+                plan: {
+                    id: plan.id,
+                    name: plan.name,
+                    status: plan.status,
+                    workItemId: plan.workItemId,
+                    updatedAt: plan.updatedAt.toISOString(),
+                },
+            });
+        }
+        catch (error) {
+            return createErrorResult(`Failed to update plan: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});
+// =============================================================================
+// plan_get - Get a plan by ID or name
+// =============================================================================
+export const planGetTool = defineTool({
+    name: 'plan_get',
+    description: 'Get a plan by ID or name. Returns the full plan content and linked work item details.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            plan_id: {
+                type: 'number',
+                description: 'Plan ID (preferred)',
+            },
+            name: {
+                type: 'string',
+                description: 'Plan name (alternative to ID)',
+            },
+            project_id: {
+                type: 'number',
+                description: 'Project ID (required if using name, uses active project if not provided)',
+            },
+        },
+        required: [],
+    },
+    execute: async (input) => {
+        await Promise.resolve();
+        try {
+            let plan;
+            if (input.plan_id) {
+                plan = planRepository.getWithWorkItem(input.plan_id);
+            }
+            else if (input.name) {
+                const projectId = input.project_id ?? getActiveProject()?.id;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Provide plan_id or project_id.');
+                }
+                const basePlan = planRepository.getByName(projectId, input.name);
+                if (basePlan) {
+                    plan = planRepository.getWithWorkItem(basePlan.id);
+                }
+            }
+            else {
+                return createErrorResult('Either plan_id or name is required');
+            }
+            if (!plan) {
+                return createSuccessResult({
+                    success: true,
+                    plan: null,
+                    message: 'Plan not found',
+                });
+            }
+            return createSuccessResult({
+                success: true,
+                plan: {
+                    id: plan.id,
+                    name: plan.name,
+                    content: plan.content,
+                    status: plan.status,
+                    workItemId: plan.workItemId,
+                    workItem: plan.workItem
+                        ? {
+                            id: plan.workItem.id,
+                            itemId: plan.workItem.itemId,
+                            title: plan.workItem.title,
+                            status: plan.workItem.status,
+                        }
+                        : null,
+                    createdAt: plan.createdAt.toISOString(),
+                    updatedAt: plan.updatedAt.toISOString(),
+                },
+            });
+        }
+        catch (error) {
+            return createErrorResult(`Failed to get plan: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});
+// =============================================================================
+// plan_list - List plans for a project
+// =============================================================================
+export const planListTool = defineTool({
+    name: 'plan_list',
+    description: 'List plans for a project. Supports filtering by status and work item. Returns plan summaries without full content.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            project_id: {
+                type: 'number',
+                description: 'Project ID (uses active project if not provided)',
+            },
+            status: {
+                type: 'string',
+                enum: ['draft', 'approved', 'in_progress', 'completed', 'abandoned', 'all'],
+                description: 'Filter by status (default: all)',
+            },
+            work_item_id: {
+                type: 'number',
+                description: 'Filter by linked work item',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum plans to return (default: 20)',
+            },
+            order_by: {
+                type: 'string',
+                enum: ['updated_desc', 'updated_asc', 'created_desc', 'name_asc'],
+                description: 'Sort order (default: updated_desc)',
+            },
+        },
+        required: [],
+    },
+    execute: async (input) => {
+        await Promise.resolve();
+        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 options = {
+                limit: input.limit ?? 20,
+                order_by: input.order_by ?? 'updated_desc',
+            };
+            if (input.status && input.status !== 'all') {
+                options.status = input.status;
+            }
+            if (input.work_item_id !== undefined) {
+                options.work_item_id = input.work_item_id;
+            }
+            const plans = planRepository.list(projectId, options);
+            const counts = planRepository.countByStatus(projectId);
+            const planSummaries = plans.map((plan) => ({
+                id: plan.id,
+                name: plan.name,
+                status: plan.status,
+                workItemId: plan.workItemId,
+                workItemTitle: plan.workItemTitle,
+                workItemItemId: plan.workItemItemId,
+                updatedAt: plan.updatedAt.toISOString(),
+            }));
+            return createSuccessResult({
+                success: true,
+                plans: planSummaries,
+                count: planSummaries.length,
+                statusCounts: counts,
+                projectId,
+            });
+        }
+        catch (error) {
+            return createErrorResult(`Failed to list plans: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});
+// =============================================================================
+// plan_delete - Delete a plan
+// =============================================================================
+export const planDeleteTool = defineTool({
+    name: 'plan_delete',
+    description: 'Delete a plan by ID. This action cannot be undone.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            plan_id: {
+                type: 'number',
+                description: 'ID of the plan to delete',
+            },
+        },
+        required: ['plan_id'],
+    },
+    execute: async (input) => {
+        await Promise.resolve();
+        try {
+            // Get plan first to show name in message
+            const plan = planRepository.getById(input.plan_id);
+            if (!plan) {
+                return createErrorResult(`Plan with ID ${String(input.plan_id)} not found`);
+            }
+            const deleted = planRepository.delete(input.plan_id);
+            if (!deleted) {
+                return createErrorResult(`Failed to delete plan "${plan.name}"`);
+            }
+            return createSuccessResult({
+                success: true,
+                message: `Plan "${plan.name}" deleted`,
+            });
+        }
+        catch (error) {
+            return createErrorResult(`Failed to delete plan: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    },
+});
+// =============================================================================
+// All plan tools
+// =============================================================================
+export const planDbTools = [
+    planCreateTool,
+    planUpdateTool,
+    planGetTool,
+    planListTool,
+    planDeleteTool,
+];