@compilr-dev/cli 0.5.1 → 0.5.2

package/dist/tools/workitem-db.js

@@ -1,730 +0,0 @@
-/**
- * Work Item Database Tools
- *
- * Tools for managing work items (backlog items, tasks, bugs) in the database.
- */
-import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/sdk';
-import { workItemRepository } from '../db/repositories/index.js';
-import { getActiveProject } from './project-db.js';
-import { getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, STEP_ORDER, } from '../workflow/index.js';
-import { awardWorkItemCompletion } from '../games/coins.js';
-import { getActiveSharedContext } from '../multi-agent/activity.js';
-/**
- * workitem_query - Query work items with filters
- */
-export const workitemQueryTool = defineTool({
-    name: 'workitem_query',
-    description: 'Query PERSISTENT work items from the project backlog (stored in database). ' +
-        'For session todos shown in footer, use todo_read. ' +
-        'Supports filtering by status, type, priority, owner, and search.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            project_id: {
-                type: 'number',
-                description: 'Project ID (uses active project if not provided)',
-            },
-            status: {
-                type: 'string',
-                enum: ['backlog', 'in_progress', 'completed', 'skipped', 'all'],
-                description: 'Filter by status (default: all)',
-            },
-            type: {
-                type: 'string',
-                enum: ['feature', 'bug', 'tech-debt', 'chore', 'all'],
-                description: 'Filter by type (default: all)',
-            },
-            priority: {
-                type: 'string',
-                enum: ['critical', 'high', 'medium', 'low', 'all'],
-                description: 'Filter by priority (default: all)',
-            },
-            owner: {
-                type: 'string',
-                description: 'Filter by owner: agent ID, "self" for your own items, "unassigned" for unowned, or "all" (default: all)',
-            },
-            search: {
-                type: 'string',
-                description: 'Search in title and description',
-            },
-            limit: {
-                type: 'number',
-                description: 'Maximum items to return (default: 50)',
-            },
-            offset: {
-                type: 'number',
-                description: 'Offset for pagination (default: 0)',
-            },
-        },
-        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.');
-            }
-            // Resolve "self" to the active agent ID
-            // TODO(Phase 3): This uses the FOREGROUND agent's ID from SharedContext.
-            // When background agents are implemented, each agent session needs its own
-            // identity. The tool execution context should include the caller's agent ID,
-            // so background agents can correctly resolve "self" to their own ID.
-            // See: background-agents-spec.md - Tool Execution Context section
-            let resolvedOwner = input.owner;
-            if (input.owner === 'self') {
-                const sharedContext = getActiveSharedContext();
-                const activeAgent = sharedContext?.getTeam().activeAgent;
-                if (activeAgent && activeAgent !== 'default') {
-                    resolvedOwner = activeAgent;
-                }
-                else {
-                    // No active team agent, treat as "all" or return empty
-                    resolvedOwner = undefined;
-                }
-            }
-            const queryInput = {
-                project_id: projectId,
-                status: input.status,
-                type: input.type,
-                priority: input.priority,
-                owner: resolvedOwner,
-                search: input.search,
-                limit: input.limit || 50,
-                offset: input.offset || 0,
-            };
-            const result = workItemRepository.query(queryInput);
-            const items = result.items.map((item) => ({
-                id: item.id,
-                itemId: item.itemId,
-                type: item.type,
-                status: item.status,
-                priority: item.priority,
-                owner: item.owner,
-                guidedStep: item.guidedStep,
-                title: item.title,
-                description: item.description,
-                estimatedEffort: item.estimatedEffort,
-                completedAt: item.completedAt?.toISOString(),
-                commitHash: item.commitHash,
-                createdAt: item.createdAt.toISOString(),
-            }));
-            return createSuccessResult({
-                success: true,
-                items,
-                total: result.total,
-                hasMore: result.hasMore,
-                projectId,
-            });
-        }
-        catch (error) {
-            return createErrorResult(`Failed to query work items: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    },
-});
-/**
- * workitem_add - Add a new work item
- */
-export const workitemAddTool = defineTool({
-    name: 'workitem_add',
-    description: 'Add a PERSISTENT work item to the project backlog (stored in database). ' +
-        'For session-level tasks shown in footer, use todo_write.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            project_id: {
-                type: 'number',
-                description: 'Project ID (uses active project if not provided)',
-            },
-            type: {
-                type: 'string',
-                enum: ['feature', 'bug', 'tech-debt', 'chore'],
-                description: 'Work item type',
-            },
-            title: {
-                type: 'string',
-                description: 'Title of the work item',
-            },
-            description: {
-                type: 'string',
-                description: 'Detailed description',
-            },
-            priority: {
-                type: 'string',
-                enum: ['critical', 'high', 'medium', 'low'],
-                description: 'Priority (default: medium)',
-            },
-            estimated_effort: {
-                type: 'string',
-                enum: ['low', 'medium', 'high'],
-                description: 'Estimated effort',
-            },
-            owner: {
-                type: 'string',
-                description: 'Owner agent ID (e.g., "dev", "pm", "arch"). Omit for unassigned.',
-            },
-        },
-        required: ['type', 'title'],
-    },
-    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,
-                type: input.type,
-                title: input.title,
-                description: input.description,
-                priority: input.priority,
-                estimated_effort: input.estimated_effort,
-                owner: input.owner,
-            };
-            const item = workItemRepository.create(createInput);
-            return createSuccessResult({
-                success: true,
-                message: `Work item ${item.itemId} created: "${item.title}"${item.owner ? ` (owner: ${item.owner})` : ''}`,
-                item: {
-                    id: item.id,
-                    itemId: item.itemId,
-                    type: item.type,
-                    status: item.status,
-                    priority: item.priority,
-                    owner: item.owner,
-                    title: item.title,
-                },
-            });
-        }
-        catch (error) {
-            return createErrorResult(`Failed to add work item: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    },
-});
-/**
- * workitem_update - Update a work item
- */
-export const workitemUpdateTool = defineTool({
-    name: 'workitem_update',
-    description: 'Update a PERSISTENT work item in the project backlog (stored in database). ' +
-        'Can update status, priority, owner, title, description, and more.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            item_id: {
-                type: 'string',
-                description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
-            },
-            project_id: {
-                type: 'number',
-                description: 'Project ID (uses active project if not provided)',
-            },
-            status: {
-                type: 'string',
-                enum: ['backlog', 'in_progress', 'completed', 'skipped'],
-                description: 'Work item status',
-            },
-            priority: {
-                type: 'string',
-                enum: ['critical', 'high', 'medium', 'low'],
-                description: 'Priority',
-            },
-            owner: {
-                type: 'string',
-                description: 'Owner agent ID. Set to empty string to unassign.',
-            },
-            guided_step: {
-                type: 'string',
-                enum: ['plan', 'implement', 'test', 'commit', 'review'],
-                description: 'Current step in guided mode workflow',
-            },
-            title: {
-                type: 'string',
-                description: 'Updated title',
-            },
-            description: {
-                type: 'string',
-                description: 'Updated description',
-            },
-            commit_hash: {
-                type: 'string',
-                description: 'Git commit hash when completing the item',
-            },
-        },
-        required: ['item_id'],
-    },
-    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 work item by item_id
-            const existingItem = workItemRepository.getByItemId(projectId, input.item_id);
-            if (!existingItem) {
-                return createErrorResult(`Work item "${input.item_id}" not found in current project`);
-            }
-            const updateInput = {};
-            if (input.status)
-                updateInput.status = input.status;
-            if (input.priority)
-                updateInput.priority = input.priority;
-            if (input.owner !== undefined) {
-                // Empty string means unassign
-                updateInput.owner = input.owner === '' ? null : input.owner;
-            }
-            if (input.guided_step !== undefined)
-                updateInput.guided_step = input.guided_step;
-            if (input.title)
-                updateInput.title = input.title;
-            if (input.description !== undefined)
-                updateInput.description = input.description;
-            if (input.commit_hash)
-                updateInput.commit_hash = input.commit_hash;
-            const item = workItemRepository.update(existingItem.id, updateInput);
-            if (!item) {
-                return createErrorResult(`Failed to update work item "${input.item_id}"`);
-            }
-            // Award coin if work item was just completed
-            if (input.status === 'completed' && existingItem.status !== 'completed') {
-                awardWorkItemCompletion();
-            }
-            return createSuccessResult({
-                success: true,
-                message: `Work item ${item.itemId} updated`,
-                item: {
-                    id: item.id,
-                    itemId: item.itemId,
-                    type: item.type,
-                    status: item.status,
-                    priority: item.priority,
-                    owner: item.owner,
-                    guidedStep: item.guidedStep,
-                    title: item.title,
-                    completedAt: item.completedAt?.toISOString(),
-                    commitHash: item.commitHash,
-                },
-            });
-        }
-        catch (error) {
-            return createErrorResult(`Failed to update work item: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    },
-});
-/**
- * workitem_next - Get the next work item to work on
- */
-export const workitemNextTool = defineTool({
-    name: 'workitem_next',
-    description: 'Get the next work item to work on (highest priority backlog item). Useful for guided mode to pick the next task.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            project_id: {
-                type: 'number',
-                description: 'Project ID (uses active project if not provided)',
-            },
-            type: {
-                type: 'string',
-                enum: ['feature', 'bug', 'tech-debt', 'chore'],
-                description: 'Filter by type (optional)',
-            },
-        },
-        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 item = workItemRepository.getNext(projectId, input.type);
-            if (!item) {
-                return createSuccessResult({
-                    success: true,
-                    item: null,
-                    message: 'No backlog items found. The backlog is empty or all items are completed.',
-                });
-            }
-            return createSuccessResult({
-                success: true,
-                item: {
-                    id: item.id,
-                    itemId: item.itemId,
-                    type: item.type,
-                    status: item.status,
-                    priority: item.priority,
-                    title: item.title,
-                    description: item.description,
-                    estimatedEffort: item.estimatedEffort,
-                },
-                message: `Next item: ${item.itemId} "${item.title}" (${item.priority} priority)`,
-            });
-        }
-        catch (error) {
-            return createErrorResult(`Failed to get next work item: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    },
-});
-/**
- * workitem_delete - Delete a work item
- */
-export const workitemDeleteTool = defineTool({
-    name: 'workitem_delete',
-    description: 'Delete a work item from the backlog.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            item_id: {
-                type: 'string',
-                description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
-            },
-            project_id: {
-                type: 'number',
-                description: 'Project ID (uses active project if not provided)',
-            },
-        },
-        required: ['item_id'],
-    },
-    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 work item by item_id
-            const existingItem = workItemRepository.getByItemId(projectId, input.item_id);
-            if (!existingItem) {
-                return createErrorResult(`Work item "${input.item_id}" not found in current project`);
-            }
-            const deleted = workItemRepository.delete(existingItem.id);
-            if (!deleted) {
-                return createErrorResult(`Failed to delete work item "${input.item_id}"`);
-            }
-            return createSuccessResult({
-                success: true,
-                message: `Work item ${input.item_id} deleted`,
-            });
-        }
-        catch (error) {
-            return createErrorResult(`Failed to delete work item: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    },
-});
-/**
- * workitem_status_counts - Get work item counts by status
- */
-export const workitemStatusCountsTool = defineTool({
-    name: 'workitem_status_counts',
-    description: 'Get counts of work items by status for the current project. Useful for showing progress.',
-    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 counts = workItemRepository.getStatusCounts(projectId);
-            const total = counts.backlog + counts.in_progress + counts.completed + counts.skipped;
-            const progress = total > 0 ? Math.round((counts.completed / total) * 100) : 0;
-            return createSuccessResult({
-                success: true,
-                counts,
-                total,
-                progress,
-                summary: `${String(counts.completed)}/${String(total)} completed (${String(progress)}%)`,
-            });
-        }
-        catch (error) {
-            return createErrorResult(`Failed to get status counts: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    },
-});
-/**
- * workitem_advance_step - Advance to the next guided workflow step
- */
-export const workitemAdvanceStepTool = defineTool({
-    name: 'workitem_advance_step',
-    description: `Advance a work item to the next guided workflow step.
-Steps progress in order: ${STEP_ORDER.join(' → ')} → complete.
-Use this tool when the criteria for the current step are met.
-The agent should explicitly call this to advance - it provides visibility and audit trail.`,
-    inputSchema: {
-        type: 'object',
-        properties: {
-            item_id: {
-                type: 'string',
-                description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
-            },
-            reason: {
-                type: 'string',
-                description: 'Why the step criteria was met (shown to user for visibility)',
-            },
-            force: {
-                type: 'boolean',
-                description: 'Skip validation and force advance (e.g., user override after test failures)',
-            },
-            project_id: {
-                type: 'number',
-                description: 'Project ID (uses active project if not provided)',
-            },
-        },
-        required: ['item_id', 'reason'],
-    },
-    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 work item
-            const item = workItemRepository.getByItemId(projectId, input.item_id);
-            if (!item) {
-                return createErrorResult(`Work item "${input.item_id}" not found in current project`);
-            }
-            // Check if item is in progress
-            if (item.status !== 'in_progress') {
-                return createErrorResult(`Work item "${input.item_id}" is not in progress (status: ${item.status}). ` +
-                    'Use workitem_update to set status to in_progress first.');
-            }
-            // Determine current and next step
-            const currentStep = item.guidedStep;
-            const nextStep = getNextStep(currentStep);
-            // Check for valid transition (unless forced)
-            if (!input.force && currentStep !== null) {
-                if (!isValidTransition(currentStep, nextStep)) {
-                    return createErrorResult(`Cannot advance from ${currentStep} to ${nextStep}. ` +
-                        `Valid next step: ${getNextStep(currentStep)}. ` +
-                        'Use force=true to override.');
-                }
-            }
-            // Handle completion
-            if (nextStep === 'complete') {
-                // Mark item as completed
-                const updatedItem = workItemRepository.update(item.id, {
-                    status: 'completed',
-                    guided_step: null,
-                });
-                if (!updatedItem) {
-                    return createErrorResult('Failed to update work item');
-                }
-                // Award coin for completing work item
-                awardWorkItemCompletion();
-                return createSuccessResult({
-                    success: true,
-                    item: {
-                        id: updatedItem.id,
-                        itemId: updatedItem.itemId,
-                        type: updatedItem.type,
-                        status: updatedItem.status,
-                        priority: updatedItem.priority,
-                        guidedStep: updatedItem.guidedStep,
-                        title: updatedItem.title,
-                        completedAt: updatedItem.completedAt?.toISOString(),
-                        commitHash: updatedItem.commitHash,
-                    },
-                    previous_step: currentStep,
-                    current_step: null,
-                    message: currentStep
-                        ? `✓ ${input.item_id}: ${formatStepDisplay(currentStep)} → COMPLETED`
-                        : `✓ ${input.item_id}: COMPLETED`,
-                    completed: true,
-                    reason: input.reason,
-                    next_action: 'Work item complete! Use workitem_next to pick the next item from backlog.',
-                });
-            }
-            // Advance to next step (we know nextStep is not 'complete' at this point
-            // because 'complete' case is handled above and returns early)
-            const nextGuidedStep = nextStep;
-            const updatedItem = workItemRepository.update(item.id, {
-                guided_step: nextGuidedStep,
-            });
-            if (!updatedItem) {
-                return createErrorResult('Failed to update work item');
-            }
-            // Get hints for next step
-            const nextCriteria = getStepCriteria(nextGuidedStep);
-            return createSuccessResult({
-                success: true,
-                item: {
-                    id: updatedItem.id,
-                    itemId: updatedItem.itemId,
-                    type: updatedItem.type,
-                    status: updatedItem.status,
-                    priority: updatedItem.priority,
-                    guidedStep: updatedItem.guidedStep,
-                    title: updatedItem.title,
-                },
-                previous_step: currentStep,
-                current_step: nextGuidedStep,
-                message: currentStep
-                    ? `✓ ${input.item_id}: ${formatStepDisplay(currentStep)} → ${formatStepDisplay(nextGuidedStep)}`
-                    : `✓ ${input.item_id}: Starting ${formatStepDisplay(nextGuidedStep)}`,
-                completed: false,
-                reason: input.reason,
-                next_action: nextCriteria.nextActionHint,
-                exit_criteria: nextCriteria.exitCriteria,
-            });
-        }
-        catch (error) {
-            return createErrorResult(`Failed to advance step: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    },
-});
-/**
- * workitem_claim - Claim an unassigned work item
- */
-export const workitemClaimTool = defineTool({
-    name: 'workitem_claim',
-    description: 'Claim an unassigned PERSISTENT work item from project backlog. ' +
-        'For session todos in footer, use todo_claim.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            item_id: {
-                type: 'string',
-                description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
-            },
-            agent_id: {
-                type: 'string',
-                description: 'The agent ID claiming the work item',
-            },
-            project_id: {
-                type: 'number',
-                description: 'Project ID (uses active project if not provided)',
-            },
-        },
-        required: ['item_id', 'agent_id'],
-    },
-    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.');
-            }
-            const existingItem = workItemRepository.getByItemId(projectId, input.item_id);
-            if (!existingItem) {
-                return createErrorResult(`Work item "${input.item_id}" not found in current project`);
-            }
-            if (existingItem.owner) {
-                return createErrorResult(`Work item "${input.item_id}" is already owned by "${existingItem.owner}". Use workitem_handoff to transfer ownership.`);
-            }
-            const item = workItemRepository.update(existingItem.id, { owner: input.agent_id });
-            if (!item) {
-                return createErrorResult(`Failed to claim work item "${input.item_id}"`);
-            }
-            return createSuccessResult({
-                success: true,
-                message: `Work item ${item.itemId} claimed by ${input.agent_id}`,
-                item: {
-                    id: item.id,
-                    itemId: item.itemId,
-                    type: item.type,
-                    status: item.status,
-                    priority: item.priority,
-                    owner: item.owner,
-                    title: item.title,
-                },
-            });
-        }
-        catch (error) {
-            return createErrorResult(`Failed to claim work item: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    },
-});
-/**
- * workitem_handoff - Hand off a work item to another agent
- */
-export const workitemHandoffTool = defineTool({
-    name: 'workitem_handoff',
-    description: 'Hand off a PERSISTENT work item (from project backlog) to another agent. ' +
-        'For session todos in footer, use todo_handoff.',
-    inputSchema: {
-        type: 'object',
-        properties: {
-            item_id: {
-                type: 'string',
-                description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
-            },
-            to_agent_id: {
-                type: 'string',
-                description: 'The agent ID to hand off to',
-            },
-            notes: {
-                type: 'string',
-                description: 'Optional notes about the handoff (context, status, blockers)',
-            },
-            project_id: {
-                type: 'number',
-                description: 'Project ID (uses active project if not provided)',
-            },
-        },
-        required: ['item_id', 'to_agent_id'],
-    },
-    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.');
-            }
-            const existingItem = workItemRepository.getByItemId(projectId, input.item_id);
-            if (!existingItem) {
-                return createErrorResult(`Work item "${input.item_id}" not found in current project`);
-            }
-            const previousOwner = existingItem.owner;
-            const item = workItemRepository.update(existingItem.id, { owner: input.to_agent_id });
-            if (!item) {
-                return createErrorResult(`Failed to hand off work item "${input.item_id}"`);
-            }
-            return createSuccessResult({
-                success: true,
-                message: `Work item ${item.itemId} handed off from "${previousOwner ?? 'unassigned'}" to "${input.to_agent_id}"`,
-                item: {
-                    id: item.id,
-                    itemId: item.itemId,
-                    type: item.type,
-                    status: item.status,
-                    priority: item.priority,
-                    owner: item.owner,
-                    title: item.title,
-                },
-                previousOwner,
-                notes: input.notes,
-            });
-        }
-        catch (error) {
-            return createErrorResult(`Failed to hand off work item: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    },
-});
-/**
- * All work item tools
- */
-export const workitemDbTools = [
-    workitemQueryTool,
-    workitemAddTool,
-    workitemUpdateTool,
-    workitemNextTool,
-    workitemDeleteTool,
-    workitemStatusCountsTool,
-    workitemAdvanceStepTool,
-    workitemClaimTool,
-    workitemHandoffTool,
-];