@compilr-dev/agents 0.2.0 → 0.3.0

package/dist/tools/builtin/backlog.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Backlog Tools - File-based project backlog management
+ *
+ * Provides backlog_read and backlog_write tools for managing project backlogs.
+ * Uses a JSON file stored in .compilr/backlog.json (or backlog.json in project root).
+ *
+ * Features:
+ * - Read with filters (status, type, search, limit)
+ * - Write/update individual items or full backlog
+ * - Support for common item types (feature, bug, chore, spike)
+ * - Priority levels (critical, high, medium, low)
+ */
+import type { Tool } from '../types.js';
+/**
+ * Status of a backlog item
+ */
+export type BacklogStatus = 'backlog' | 'in-progress' | 'done' | 'blocked';
+/**
+ * Type of backlog item
+ */
+export type BacklogItemType = 'feature' | 'bug' | 'chore' | 'spike';
+/**
+ * Priority level
+ */
+export type BacklogPriority = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * A backlog item
+ */
+export interface BacklogItem {
+    /** Unique identifier (e.g., "FEAT-001", "BUG-002") */
+    id: string;
+    /** Type of item */
+    type: BacklogItemType;
+    /** Short title */
+    title: string;
+    /** Detailed description (optional) */
+    description?: string;
+    /** Current status */
+    status: BacklogStatus;
+    /** Priority level (optional, defaults to medium) */
+    priority?: BacklogPriority;
+    /** Acceptance criteria (optional) */
+    acceptanceCriteria?: string[];
+    /** Dependencies on other items (optional) */
+    dependencies?: string[];
+    /** Labels/tags (optional) */
+    labels?: string[];
+    /** Created timestamp */
+    createdAt?: string;
+    /** Last updated timestamp */
+    updatedAt?: string;
+}
+/**
+ * Input parameters for backlog_read tool
+ */
+export interface BacklogReadInput {
+    /** Get a specific item by ID */
+    id?: string;
+    /** Filter by status */
+    status?: BacklogStatus;
+    /** Filter by type */
+    type?: BacklogItemType;
+    /** Search in title and description */
+    search?: string;
+    /** Filter by priority */
+    priority?: BacklogPriority;
+    /** Maximum items to return (default: 20) */
+    limit?: number;
+}
+/**
+ * Result from backlog_read
+ */
+export interface BacklogReadResult {
+    items: BacklogItem[];
+    total: number;
+    filtered: number;
+}
+/**
+ * Input parameters for backlog_write tool
+ */
+export interface BacklogWriteInput {
+    /** Action to perform */
+    action: 'add' | 'update' | 'delete' | 'replace';
+    /** Item to add or update (required for add/update) */
+    item?: Partial<BacklogItem>;
+    /** Item ID to delete (required for delete) */
+    deleteId?: string;
+    /** Full list of items (required for replace action) */
+    items?: BacklogItem[];
+}
+/**
+ * Result from backlog_write
+ */
+export interface BacklogWriteResult {
+    success: boolean;
+    action: string;
+    itemId?: string;
+    itemCount?: number;
+}
+/**
+ * Read backlog items with optional filters
+ */
+export declare const backlogReadTool: Tool<BacklogReadInput>;
+/**
+ * Write/update backlog items
+ */
+export declare const backlogWriteTool: Tool<BacklogWriteInput>;
+/**
+ * Options for creating custom backlog tools
+ */
+export interface BacklogToolOptions {
+    /** Custom base path for backlog file */
+    basePath?: string;
+}
+/**
+ * Create backlog tools with custom options
+ */
+export declare function createBacklogTools(_options?: BacklogToolOptions): {
+    backlogRead: Tool<BacklogReadInput>;
+    backlogWrite: Tool<BacklogWriteInput>;
+};

package/dist/tools/builtin/backlog.js

@@ -0,0 +1,368 @@
+/**
+ * Backlog Tools - File-based project backlog management
+ *
+ * Provides backlog_read and backlog_write tools for managing project backlogs.
+ * Uses a JSON file stored in .compilr/backlog.json (or backlog.json in project root).
+ *
+ * Features:
+ * - Read with filters (status, type, search, limit)
+ * - Write/update individual items or full backlog
+ * - Support for common item types (feature, bug, chore, spike)
+ * - Priority levels (critical, high, medium, low)
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { defineTool, createSuccessResult, createErrorResult } from '../define.js';
+// =============================================================================
+// File Operations
+// =============================================================================
+const BACKLOG_PATHS = ['.compilr/backlog.json', 'backlog.json', '.claude/backlog.json'];
+function findBacklogFile(cwd = process.cwd()) {
+    for (const relPath of BACKLOG_PATHS) {
+        const fullPath = path.join(cwd, relPath);
+        if (fs.existsSync(fullPath)) {
+            return fullPath;
+        }
+    }
+    return null;
+}
+function getDefaultBacklogPath(cwd = process.cwd()) {
+    // Prefer .compilr directory if it exists
+    const compilrDir = path.join(cwd, '.compilr');
+    if (fs.existsSync(compilrDir)) {
+        return path.join(compilrDir, 'backlog.json');
+    }
+    // Otherwise use project root
+    return path.join(cwd, 'backlog.json');
+}
+function loadBacklog(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(content);
+        return {
+            version: data.version || '1.0',
+            items: Array.isArray(data.items) ? data.items : [],
+        };
+    }
+    catch {
+        return { version: '1.0', items: [] };
+    }
+}
+function saveBacklog(filePath, backlog) {
+    // Ensure directory exists
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // Update timestamps
+    const now = new Date().toISOString();
+    backlog.items = backlog.items.map((item) => ({
+        ...item,
+        updatedAt: now,
+        createdAt: item.createdAt || now,
+    }));
+    fs.writeFileSync(filePath, JSON.stringify(backlog, null, 2), 'utf-8');
+}
+function generateItemId(type, items) {
+    const prefix = {
+        feature: 'FEAT',
+        bug: 'BUG',
+        chore: 'CHORE',
+        spike: 'SPIKE',
+    }[type];
+    // Find highest number for this type
+    const existingIds = items
+        .filter((i) => i.id.startsWith(prefix))
+        .map((i) => parseInt(i.id.split('-')[1], 10))
+        .filter((n) => !isNaN(n));
+    const nextNum = existingIds.length > 0 ? Math.max(...existingIds) + 1 : 1;
+    return `${prefix}-${String(nextNum).padStart(3, '0')}`;
+}
+// =============================================================================
+// Backlog Read Tool
+// =============================================================================
+/**
+ * Read backlog items with optional filters
+ */
+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)',
+            },
+        },
+    },
+    // eslint-disable-next-line @typescript-eslint/require-await
+    execute: async (input) => {
+        try {
+            const filePath = findBacklogFile();
+            if (!filePath) {
+                return createSuccessResult({
+                    items: [],
+                    total: 0,
+                    filtered: 0,
+                    message: 'No backlog file found. Use backlog_write to create one.',
+                });
+            }
+            const backlog = loadBacklog(filePath);
+            let items = [...backlog.items];
+            const total = items.length;
+            // Filter by ID (exact match)
+            if (input.id) {
+                items = items.filter((i) => i.id === input.id);
+            }
+            // Filter by status
+            if (input.status) {
+                items = items.filter((i) => i.status === input.status);
+            }
+            // Filter by type
+            if (input.type) {
+                items = items.filter((i) => i.type === input.type);
+            }
+            // Filter by priority
+            if (input.priority) {
+                items = items.filter((i) => i.priority === input.priority);
+            }
+            // Search in title and description
+            if (input.search) {
+                const query = input.search.toLowerCase();
+                items = items.filter((i) => i.title.toLowerCase().includes(query) || i.description?.toLowerCase().includes(query));
+            }
+            // Sort by priority then by creation date
+            const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+            items.sort((a, b) => {
+                const pa = priorityOrder[a.priority || 'medium'];
+                const pb = priorityOrder[b.priority || 'medium'];
+                if (pa !== pb)
+                    return pa - pb;
+                return (a.createdAt || '').localeCompare(b.createdAt || '');
+            });
+            // Apply limit
+            const limit = input.limit ?? 20;
+            const filtered = items.length;
+            items = items.slice(0, limit);
+            return createSuccessResult({
+                items,
+                total,
+                filtered,
+            });
+        }
+        catch (error) {
+            return createErrorResult(error instanceof Error ? error.message : String(error));
+        }
+    },
+});
+// =============================================================================
+// Backlog Write Tool
+// =============================================================================
+/**
+ * Write/update backlog items
+ */
+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',
+                    },
+                    acceptanceCriteria: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Acceptance criteria list',
+                    },
+                    dependencies: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'IDs of items this depends on',
+                    },
+                    labels: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Labels/tags',
+                    },
+                },
+            },
+            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'],
+    },
+    // eslint-disable-next-line @typescript-eslint/require-await
+    execute: async (input) => {
+        try {
+            const existingPath = findBacklogFile();
+            const filePath = existingPath || getDefaultBacklogPath();
+            const backlog = existingPath ? loadBacklog(existingPath) : { version: '1.0', items: [] };
+            switch (input.action) {
+                case 'add': {
+                    if (!input.item) {
+                        return createErrorResult('Item is required for add action');
+                    }
+                    const itemType = input.item.type;
+                    const itemTitle = input.item.title;
+                    if (!itemType) {
+                        return createErrorResult('Item type is required for add action');
+                    }
+                    if (!itemTitle) {
+                        return createErrorResult('Item title is required for add action');
+                    }
+                    const newItem = {
+                        id: generateItemId(itemType, backlog.items),
+                        type: itemType,
+                        title: itemTitle,
+                        description: input.item.description,
+                        status: input.item.status ?? 'backlog',
+                        priority: input.item.priority,
+                        acceptanceCriteria: input.item.acceptanceCriteria,
+                        dependencies: input.item.dependencies,
+                        labels: input.item.labels,
+                    };
+                    backlog.items.push(newItem);
+                    saveBacklog(filePath, backlog);
+                    return createSuccessResult({
+                        success: true,
+                        action: 'add',
+                        itemId: newItem.id,
+                        itemCount: backlog.items.length,
+                    });
+                }
+                case 'update': {
+                    const updateItem = input.item;
+                    const updateId = updateItem?.id;
+                    if (!updateItem || !updateId) {
+                        return createErrorResult('Item ID is required for update action');
+                    }
+                    const idx = backlog.items.findIndex((i) => i.id === updateId);
+                    if (idx === -1) {
+                        return createErrorResult(`Item not found: ${updateId}`);
+                    }
+                    // Merge updates
+                    backlog.items[idx] = {
+                        ...backlog.items[idx],
+                        ...updateItem,
+                        id: backlog.items[idx].id, // Preserve original ID
+                    };
+                    saveBacklog(filePath, backlog);
+                    return createSuccessResult({
+                        success: true,
+                        action: 'update',
+                        itemId: updateId,
+                        itemCount: backlog.items.length,
+                    });
+                }
+                case 'delete': {
+                    const deleteId = input.deleteId || input.item?.id;
+                    if (!deleteId) {
+                        return createErrorResult('deleteId or item.id is required for delete action');
+                    }
+                    const initialCount = backlog.items.length;
+                    backlog.items = backlog.items.filter((i) => i.id !== deleteId);
+                    if (backlog.items.length === initialCount) {
+                        return createErrorResult(`Item not found: ${deleteId}`);
+                    }
+                    saveBacklog(filePath, backlog);
+                    return createSuccessResult({
+                        success: true,
+                        action: 'delete',
+                        itemId: deleteId,
+                        itemCount: backlog.items.length,
+                    });
+                }
+                case 'replace': {
+                    if (!input.items) {
+                        return createErrorResult('Items array is required for replace action');
+                    }
+                    backlog.items = input.items;
+                    saveBacklog(filePath, backlog);
+                    return createSuccessResult({
+                        success: true,
+                        action: 'replace',
+                        itemCount: backlog.items.length,
+                    });
+                }
+                default:
+                    return createErrorResult(`Unknown action: ${input.action}`);
+            }
+        }
+        catch (error) {
+            return createErrorResult(error instanceof Error ? error.message : String(error));
+        }
+    },
+});
+/**
+ * Create backlog tools with custom options
+ */
+export function createBacklogTools(_options = {}) {
+    // For now, just return the default tools
+    // Future: could customize file paths, storage backend, etc.
+    return {
+        backlogRead: backlogReadTool,
+        backlogWrite: backlogWriteTool,
+    };
+}