@compilr-dev/cli 0.4.0

package/dist/tools/backlog.js

@@ -0,0 +1,709 @@
+/**
+ * Backlog Tools - Read and write project backlog items
+ *
+ * These tools allow the agent to programmatically manage the project backlog,
+ * supporting the /design and /refine workflow.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { defineTool } from '@compilr-dev/agents';
+// =============================================================================
+// Backlog File Detection
+// =============================================================================
+/**
+ * Find the backlog file path for the current project.
+ * Checks both single-repo and two-repo patterns.
+ */
+export function findBacklogPath(basePath = process.cwd()) {
+    // Single repo pattern: .compilr/backlog.md
+    const singleRepoPath = path.join(basePath, '.compilr', 'backlog.md');
+    if (fs.existsSync(singleRepoPath)) {
+        return singleRepoPath;
+    }
+    // Two repo pattern: look for -docs sibling folder
+    const parentDir = path.dirname(basePath);
+    const projectName = path.basename(basePath);
+    const docsRepoPath = path.join(parentDir, `${projectName}-docs`, '01-planning', 'backlog.md');
+    if (fs.existsSync(docsRepoPath)) {
+        return docsRepoPath;
+    }
+    // Also check if we're already in the docs repo
+    const inDocsPath = path.join(basePath, '01-planning', 'backlog.md');
+    if (fs.existsSync(inDocsPath)) {
+        return inDocsPath;
+    }
+    // Check for project subfolders with -docs pattern
+    // This handles when running from a parent folder (e.g., /workspace/test-folder/)
+    // where projects are in subfolders (e.g., test-project-03, test-project-03-docs)
+    try {
+        const entries = fs.readdirSync(basePath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.endsWith('-docs')) {
+                const docsBacklog = path.join(basePath, entry.name, '01-planning', 'backlog.md');
+                if (fs.existsSync(docsBacklog)) {
+                    return docsBacklog;
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return null;
+}
+/**
+ * Get or create the backlog path.
+ * If no backlog exists, determines the best location based on project structure.
+ */
+function getOrCreateBacklogPath(basePath = process.cwd()) {
+    const existingPath = findBacklogPath(basePath);
+    if (existingPath) {
+        return existingPath;
+    }
+    // Check for -docs subfolder pattern (two-repo setup in parent folder)
+    try {
+        const entries = fs.readdirSync(basePath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && entry.name.endsWith('-docs')) {
+                const docsDir = path.join(basePath, entry.name, '01-planning');
+                // If the 01-planning directory exists, use it
+                if (fs.existsSync(docsDir)) {
+                    return path.join(docsDir, 'backlog.md');
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    // Check for sibling -docs folder (two-repo setup in project folder)
+    const parentDir = path.dirname(basePath);
+    const projectName = path.basename(basePath);
+    const siblingDocsDir = path.join(parentDir, `${projectName}-docs`, '01-planning');
+    if (fs.existsSync(siblingDocsDir)) {
+        return path.join(siblingDocsDir, 'backlog.md');
+    }
+    // Default to single repo pattern
+    const defaultPath = path.join(basePath, '.compilr', 'backlog.md');
+    return defaultPath;
+}
+// =============================================================================
+// Markdown Table Parsing & Generation
+// =============================================================================
+const TABLE_HEADER = '| ID | Type | Status | Priority | Title | Description | Commit |';
+const TABLE_SEPARATOR = '|----|------|--------|----------|-------|-------------|--------|';
+/**
+ * Parse a markdown table row into a BacklogItem.
+ */
+function parseTableRow(row) {
+    // Remove leading/trailing pipes and split by |
+    const cells = row.split('|').map(c => c.trim()).filter(c => c !== '');
+    if (cells.length < 6) {
+        return null;
+    }
+    const [id, type, status, priority, title, description, commit] = cells;
+    // Validate ID format (e.g., REQ-001, BUG-001)
+    if (!id || !/^[A-Z]+-\d{3}$/.test(id)) {
+        return null;
+    }
+    return {
+        id,
+        type: type,
+        status: status,
+        priority: priority,
+        title,
+        description,
+        commit: commit || undefined,
+    };
+}
+/**
+ * Generate a markdown table row from a BacklogItem.
+ */
+function generateTableRow(item) {
+    return `| ${item.id} | ${item.type} | ${item.status} | ${item.priority} | ${item.title} | ${item.description} | ${item.commit || ''} |`;
+}
+/**
+ * Parse backlog items from markdown content.
+ */
+export function parseBacklogItems(content) {
+    const items = [];
+    const lines = content.split('\n');
+    let inTable = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Detect table header
+        if (trimmed.startsWith('| ID |')) {
+            inTable = true;
+            continue;
+        }
+        // Skip separator row
+        if (trimmed.startsWith('|---')) {
+            continue;
+        }
+        // Parse table rows
+        if (inTable && trimmed.startsWith('|')) {
+            const item = parseTableRow(trimmed);
+            if (item) {
+                items.push(item);
+            }
+            else {
+                // End of table if row doesn't parse
+                inTable = false;
+            }
+        }
+        else if (inTable && !trimmed.startsWith('|')) {
+            // End of table
+            inTable = false;
+        }
+    }
+    return items;
+}
+/**
+ * Generate markdown content for backlog items.
+ */
+function generateBacklogMarkdown(items, existingContent) {
+    // If there's existing content with our table format, replace just the table
+    if (existingContent && existingContent.includes(TABLE_HEADER)) {
+        const lines = existingContent.split('\n');
+        const result = [];
+        let inTable = false;
+        let tableReplaced = false;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.startsWith('| ID |')) {
+                // Start of our table - replace it
+                inTable = true;
+                if (!tableReplaced) {
+                    result.push(TABLE_HEADER);
+                    result.push(TABLE_SEPARATOR);
+                    for (const item of items) {
+                        result.push(generateTableRow(item));
+                    }
+                    tableReplaced = true;
+                }
+                continue;
+            }
+            if (inTable) {
+                if (trimmed.startsWith('|---') || (trimmed.startsWith('|') && trimmed.includes('|'))) {
+                    // Skip existing table rows
+                    continue;
+                }
+                // End of table - include this line and stop skipping
+                inTable = false;
+            }
+            // Include non-table lines
+            result.push(line);
+        }
+        return result.join('\n');
+    }
+    // Generate new content
+    const date = new Date().toISOString().split('T')[0];
+    let content = `# Backlog
+
+${TABLE_HEADER}
+${TABLE_SEPARATOR}
+`;
+    for (const item of items) {
+        content += generateTableRow(item) + '\n';
+    }
+    content += `
+---
+
+*Last updated: ${date} by agent*
+`;
+    return content;
+}
+// =============================================================================
+// Input Sanitization
+// =============================================================================
+/**
+ * Sanitize a string for use in a markdown table cell.
+ * - Removes newlines (replace with space)
+ * - Removes pipe characters (breaks table)
+ * - Trims whitespace
+ * - Limits length
+ */
+function sanitizeTableCell(value, maxLength = 500) {
+    if (!value || typeof value !== 'string') {
+        return '';
+    }
+    return value
+        // Replace newlines with spaces
+        .replace(/[\r\n]+/g, ' ')
+        // Remove pipe characters (break markdown tables)
+        .replace(/\|/g, '-')
+        // Collapse multiple spaces
+        .replace(/\s+/g, ' ')
+        // Trim whitespace
+        .trim()
+        // Limit length
+        .slice(0, maxLength);
+}
+/**
+ * Sanitize a backlog item's text fields.
+ */
+function sanitizeBacklogItem(item) {
+    const warnings = [];
+    // Sanitize title (max 100 chars)
+    const originalTitle = item.title || '';
+    const sanitizedTitle = sanitizeTableCell(originalTitle, 100);
+    if (sanitizedTitle !== originalTitle.trim()) {
+        warnings.push(`Title was sanitized (removed newlines/pipes or truncated)`);
+    }
+    // Sanitize description (max 500 chars)
+    const originalDesc = item.description || '';
+    const sanitizedDesc = sanitizeTableCell(originalDesc, 500);
+    if (sanitizedDesc !== originalDesc.trim()) {
+        warnings.push(`Description was sanitized (removed newlines/pipes or truncated)`);
+    }
+    // Validate type
+    const validTypes = ['feature', 'bug', 'tech-debt', 'chore'];
+    const type = validTypes.includes(item.type) ? item.type : 'feature';
+    if (type !== item.type) {
+        warnings.push(`Invalid type "${item.type}" defaulted to "feature"`);
+    }
+    // Validate status
+    const validStatuses = ['📋', '🚧', '✅'];
+    const status = validStatuses.includes(item.status) ? item.status : '📋';
+    if (item.status && status !== item.status) {
+        warnings.push(`Invalid status "${item.status}" defaulted to "📋"`);
+    }
+    // Validate priority
+    const validPriorities = ['critical', 'high', 'medium', 'low'];
+    const priority = validPriorities.includes(item.priority) ? item.priority : 'medium';
+    if (priority !== item.priority) {
+        warnings.push(`Invalid priority "${item.priority}" defaulted to "medium"`);
+    }
+    return {
+        title: sanitizedTitle || 'Untitled',
+        description: sanitizedDesc || 'No description',
+        type,
+        status,
+        priority,
+        warnings,
+    };
+}
+// =============================================================================
+// ID Generation
+// =============================================================================
+const TYPE_PREFIX_MAP = {
+    'feature': 'REQ',
+    'bug': 'BUG',
+    'tech-debt': 'TECH',
+    'chore': 'CHORE',
+};
+/**
+ * Generate a new ID for a backlog item based on its type and existing items.
+ */
+function generateId(type, existingItems) {
+    const prefix = TYPE_PREFIX_MAP[type];
+    // Find highest number for this prefix
+    let maxNum = 0;
+    for (const item of existingItems) {
+        if (item.id.startsWith(prefix + '-')) {
+            const num = parseInt(item.id.split('-')[1], 10);
+            if (!isNaN(num) && num > maxNum) {
+                maxNum = num;
+            }
+        }
+    }
+    return `${prefix}-${String(maxNum + 1).padStart(3, '0')}`;
+}
+export const backlogReadTool = defineTool({
+    name: 'backlog_read',
+    description: 'Read backlog items from the project. ' +
+        'Use "id" to get a specific item, or use filters to query multiple items. ' +
+        'Default limit is 10 items - use offset for pagination. ' +
+        'Use "search" to find items by title/description text.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            id: {
+                type: 'string',
+                description: 'Get a specific item by ID (e.g., "REQ-001", "BUG-002")',
+            },
+            search: {
+                type: 'string',
+                description: 'Search text in title and description (case-insensitive)',
+            },
+            status: {
+                type: 'string',
+                enum: ['📋', '🚧', '✅', 'all'],
+                description: 'Filter by status (📋=backlog, 🚧=in-progress, ✅=done, all=no filter)',
+            },
+            type: {
+                type: 'string',
+                enum: ['feature', 'bug', 'tech-debt', 'chore', 'all'],
+                description: 'Filter by item type',
+            },
+            priority: {
+                type: 'string',
+                enum: ['critical', 'high', 'medium', 'low', 'all'],
+                description: 'Filter by priority',
+            },
+            limit: {
+                type: 'number',
+                description: 'Maximum items to return (default: 10, max: 50)',
+            },
+            offset: {
+                type: 'number',
+                description: 'Skip first N items for pagination (default: 0)',
+            },
+        },
+        required: [],
+    },
+    execute: (input) => {
+        const backlogPath = findBacklogPath();
+        if (!backlogPath) {
+            return Promise.resolve({
+                success: false,
+                error: 'No backlog file found. Run /init to create a project first, or /design to create the backlog.',
+            });
+        }
+        try {
+            const content = fs.readFileSync(backlogPath, 'utf-8');
+            let items = parseBacklogItems(content);
+            // If ID specified, return just that item
+            if (input.id) {
+                const searchId = input.id.toLowerCase();
+                const item = items.find(i => i.id.toLowerCase() === searchId);
+                if (!item) {
+                    return Promise.resolve({
+                        success: false,
+                        error: `Item "${input.id}" not found in backlog.`,
+                    });
+                }
+                return Promise.resolve({
+                    success: true,
+                    result: {
+                        items: [item],
+                        total: 1,
+                        returned: 1,
+                        hasMore: false,
+                        path: backlogPath,
+                    },
+                });
+            }
+            // Apply search filter
+            if (input.search) {
+                const searchLower = input.search.toLowerCase();
+                items = items.filter(i => i.title.toLowerCase().includes(searchLower) ||
+                    i.description.toLowerCase().includes(searchLower));
+            }
+            // Apply status filter
+            if (input.status && input.status !== 'all') {
+                items = items.filter(i => i.status === input.status);
+            }
+            // Apply type filter
+            if (input.type && input.type !== 'all') {
+                items = items.filter(i => i.type === input.type);
+            }
+            // Apply priority filter
+            if (input.priority && input.priority !== 'all') {
+                items = items.filter(i => i.priority === input.priority);
+            }
+            const total = items.length;
+            // Apply pagination
+            const offset = Math.max(0, input.offset || 0);
+            const limit = Math.min(50, Math.max(1, input.limit || 10)); // Default 10, max 50
+            items = items.slice(offset, offset + limit);
+            const readResult = {
+                items,
+                total,
+                returned: items.length,
+                hasMore: offset + items.length < total,
+                path: backlogPath,
+            };
+            return Promise.resolve({
+                success: true,
+                result: readResult,
+            });
+        }
+        catch (err) {
+            return Promise.resolve({
+                success: false,
+                error: `Failed to read backlog: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    },
+});
+export const backlogWriteTool = defineTool({
+    name: 'backlog_write',
+    description: 'Modify the project backlog. ' +
+        'Actions: add (create new items), update (modify existing item), ' +
+        'remove (delete items), reorder (change order). ' +
+        'IDs are auto-generated based on type (REQ-001, BUG-001, TECH-001, CHORE-001).',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ['add', 'update', 'remove', 'reorder'],
+                description: 'The action to perform',
+            },
+            items: {
+                type: 'array',
+                description: 'For "add" action: array of new items to add (ID auto-generated)',
+                items: {
+                    type: 'object',
+                    properties: {
+                        type: {
+                            type: 'string',
+                            enum: ['feature', 'bug', 'tech-debt', 'chore'],
+                            description: 'Item type',
+                        },
+                        status: {
+                            type: 'string',
+                            enum: ['📋', '🚧', '✅'],
+                            description: 'Status (default: 📋)',
+                        },
+                        priority: {
+                            type: 'string',
+                            enum: ['critical', 'high', 'medium', 'low'],
+                            description: 'Priority level',
+                        },
+                        title: {
+                            type: 'string',
+                            description: 'Short title',
+                        },
+                        description: {
+                            type: 'string',
+                            description: 'Detailed description',
+                        },
+                    },
+                    required: ['type', 'priority', 'title', 'description'],
+                },
+            },
+            id: {
+                type: 'string',
+                description: 'For "update" action: ID of item to update',
+            },
+            updates: {
+                type: 'object',
+                description: 'For "update" action: fields to update',
+                properties: {
+                    type: { type: 'string', enum: ['feature', 'bug', 'tech-debt', 'chore'] },
+                    status: { type: 'string', enum: ['📋', '🚧', '✅'] },
+                    priority: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
+                    title: { type: 'string' },
+                    description: { type: 'string' },
+                    commit: { type: 'string' },
+                },
+            },
+            ids: {
+                type: 'array',
+                description: 'For "remove" action: IDs of items to remove',
+                items: { type: 'string' },
+            },
+            order: {
+                type: 'array',
+                description: 'For "reorder" action: IDs in desired order',
+                items: { type: 'string' },
+            },
+        },
+        required: ['action'],
+    },
+    execute: (input) => {
+        const backlogPath = getOrCreateBacklogPath();
+        try {
+            // Read existing content if it exists
+            let existingContent = '';
+            let existingItems = [];
+            if (fs.existsSync(backlogPath)) {
+                existingContent = fs.readFileSync(backlogPath, 'utf-8');
+                existingItems = parseBacklogItems(existingContent);
+            }
+            else {
+                // Ensure directory exists
+                const dir = path.dirname(backlogPath);
+                if (!fs.existsSync(dir)) {
+                    fs.mkdirSync(dir, { recursive: true });
+                }
+            }
+            let itemsAffected = 0;
+            const newIds = [];
+            let updatedItems = [...existingItems];
+            const allWarnings = [];
+            switch (input.action) {
+                case 'add': {
+                    if (!input.items || input.items.length === 0) {
+                        return Promise.resolve({
+                            success: false,
+                            error: 'No items provided for "add" action',
+                        });
+                    }
+                    for (const newItem of input.items) {
+                        // Sanitize input to prevent markdown table corruption
+                        const sanitized = sanitizeBacklogItem({
+                            title: newItem.title,
+                            description: newItem.description,
+                            type: newItem.type,
+                            status: newItem.status,
+                            priority: newItem.priority,
+                        });
+                        if (sanitized.warnings.length > 0) {
+                            allWarnings.push(...sanitized.warnings.map(w => `Item "${sanitized.title.slice(0, 30)}...": ${w}`));
+                        }
+                        const id = generateId(sanitized.type, updatedItems);
+                        const item = {
+                            id,
+                            type: sanitized.type,
+                            status: sanitized.status,
+                            priority: sanitized.priority,
+                            title: sanitized.title,
+                            description: sanitized.description,
+                        };
+                        updatedItems.push(item);
+                        newIds.push(id);
+                        itemsAffected++;
+                    }
+                    break;
+                }
+                case 'update': {
+                    if (!input.id || !input.updates) {
+                        return Promise.resolve({
+                            success: false,
+                            error: 'Both "id" and "updates" are required for "update" action',
+                        });
+                    }
+                    const index = updatedItems.findIndex(i => i.id === input.id);
+                    if (index === -1) {
+                        return Promise.resolve({
+                            success: false,
+                            error: `Item not found: ${input.id}`,
+                        });
+                    }
+                    // Build sanitized updates
+                    const currentItem = updatedItems[index];
+                    const sanitizedUpdates = {};
+                    const updateWarnings = [];
+                    // Sanitize title if provided
+                    if (input.updates.title !== undefined) {
+                        const sanitizedTitle = sanitizeTableCell(input.updates.title, 100);
+                        if (sanitizedTitle !== input.updates.title.trim()) {
+                            updateWarnings.push('Title was sanitized');
+                        }
+                        sanitizedUpdates.title = sanitizedTitle || currentItem.title;
+                    }
+                    // Sanitize description if provided
+                    if (input.updates.description !== undefined) {
+                        const sanitizedDesc = sanitizeTableCell(input.updates.description, 500);
+                        if (sanitizedDesc !== input.updates.description.trim()) {
+                            updateWarnings.push('Description was sanitized');
+                        }
+                        sanitizedUpdates.description = sanitizedDesc || currentItem.description;
+                    }
+                    // Validate type if provided
+                    if (input.updates.type !== undefined) {
+                        const validTypes = ['feature', 'bug', 'tech-debt', 'chore'];
+                        if (validTypes.includes(input.updates.type)) {
+                            sanitizedUpdates.type = input.updates.type;
+                        }
+                        else {
+                            updateWarnings.push(`Invalid type "${input.updates.type}" ignored`);
+                        }
+                    }
+                    // Validate status if provided
+                    if (input.updates.status !== undefined) {
+                        const validStatuses = ['📋', '🚧', '✅'];
+                        if (validStatuses.includes(input.updates.status)) {
+                            sanitizedUpdates.status = input.updates.status;
+                        }
+                        else {
+                            updateWarnings.push(`Invalid status "${input.updates.status}" ignored`);
+                        }
+                    }
+                    // Validate priority if provided
+                    if (input.updates.priority !== undefined) {
+                        const validPriorities = ['critical', 'high', 'medium', 'low'];
+                        if (validPriorities.includes(input.updates.priority)) {
+                            sanitizedUpdates.priority = input.updates.priority;
+                        }
+                        else {
+                            updateWarnings.push(`Invalid priority "${input.updates.priority}" ignored`);
+                        }
+                    }
+                    // Sanitize commit if provided (no newlines, limited length)
+                    if (input.updates.commit !== undefined) {
+                        sanitizedUpdates.commit = sanitizeTableCell(input.updates.commit, 50);
+                    }
+                    if (updateWarnings.length > 0) {
+                        const itemId = input.id ?? 'unknown';
+                        allWarnings.push(...updateWarnings.map(w => `${itemId}: ${w}`));
+                    }
+                    updatedItems[index] = {
+                        ...currentItem,
+                        ...sanitizedUpdates,
+                    };
+                    itemsAffected = 1;
+                    break;
+                }
+                case 'remove': {
+                    if (!input.ids || input.ids.length === 0) {
+                        return Promise.resolve({
+                            success: false,
+                            error: 'No IDs provided for "remove" action',
+                        });
+                    }
+                    const idsToRemove = new Set(input.ids);
+                    const originalLength = updatedItems.length;
+                    updatedItems = updatedItems.filter(i => !idsToRemove.has(i.id));
+                    itemsAffected = originalLength - updatedItems.length;
+                    break;
+                }
+                case 'reorder': {
+                    if (!input.order || input.order.length === 0) {
+                        return Promise.resolve({
+                            success: false,
+                            error: 'No order provided for "reorder" action',
+                        });
+                    }
+                    const itemMap = new Map(updatedItems.map(i => [i.id, i]));
+                    const reordered = [];
+                    for (const id of input.order) {
+                        const item = itemMap.get(id);
+                        if (item) {
+                            reordered.push(item);
+                            itemMap.delete(id);
+                        }
+                    }
+                    // Append any items not in the order list
+                    for (const item of itemMap.values()) {
+                        reordered.push(item);
+                    }
+                    updatedItems = reordered;
+                    itemsAffected = input.order.length;
+                    break;
+                }
+                default: {
+                    const _exhaustiveCheck = input.action;
+                    return Promise.resolve({
+                        success: false,
+                        error: `Unknown action: ${String(_exhaustiveCheck)}`,
+                    });
+                }
+            }
+            // Generate new markdown content
+            const newContent = generateBacklogMarkdown(updatedItems, existingContent);
+            // Write to file
+            fs.writeFileSync(backlogPath, newContent, 'utf-8');
+            const writeResult = {
+                success: true,
+                itemsAffected,
+                newIds: newIds.length > 0 ? newIds : undefined,
+                warnings: allWarnings.length > 0 ? allWarnings : undefined,
+                path: backlogPath,
+            };
+            return Promise.resolve({
+                success: true,
+                result: writeResult,
+            });
+        }
+        catch (err) {
+            return Promise.resolve({
+                success: false,
+                error: `Failed to write backlog: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    },
+});