chatroom-cli 1.31.1 → 1.33.0

package/dist/commands/backlog/index.js

@@ -0,0 +1,694 @@
+/**
+ * Backlog commands for managing task queue and backlog
+ */
+import { api } from '../../api.js';
+import { getSessionId, getOtherSessionUrls } from '../../infrastructure/auth/storage.js';
+import { getConvexClient, getConvexUrl } from '../../infrastructure/convex/client.js';
+import { getErrorMessage } from '../../utils/convex-error.js';
+import { createHash } from 'node:crypto';
+import * as nodePath from 'node:path';
+/** Export file name constant */
+const BACKLOG_EXPORT_FILENAME = 'backlog-export.json';
+/** Staleness threshold: 7 days in milliseconds */
+const STALENESS_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
+/** Default export/import directory relative to cwd */
+const DEFAULT_EXPORT_DIR = '.chatroom/exports';
+// ─── Default Deps Factory ──────────────────────────────────────────────────
+async function createDefaultDeps() {
+    const client = await getConvexClient();
+    const fs = await import('node:fs/promises');
+    return {
+        backend: {
+            mutation: (endpoint, args) => client.mutation(endpoint, args),
+            query: (endpoint, args) => client.query(endpoint, args),
+        },
+        session: {
+            getSessionId,
+            getConvexUrl,
+            getOtherSessionUrls,
+        },
+        fs: {
+            writeFile: (path, data) => fs.writeFile(path, data, 'utf-8'),
+            readFile: (path, encoding) => fs.readFile(path, { encoding }),
+            mkdir: (path, options) => fs.mkdir(path, options),
+        },
+    };
+}
+// ─── Auth Helper ───────────────────────────────────────────────────────────
+function requireAuth(d) {
+    const sessionId = d.session.getSessionId();
+    if (!sessionId) {
+        console.error(`❌ Not authenticated. Please run: chatroom auth login`);
+        process.exit(1);
+    }
+    return sessionId;
+}
+function validateChatroomId(chatroomId) {
+    if (!chatroomId ||
+        typeof chatroomId !== 'string' ||
+        chatroomId.length < 20 ||
+        chatroomId.length > 40) {
+        console.error(`❌ Invalid chatroom ID format: ID must be 20-40 characters (got ${chatroomId?.length || 0})`);
+        process.exit(1);
+    }
+}
+// ─── Commands ──────────────────────────────────────────────────────────────
+/**
+ * List backlog items (excludes pending_user_review)
+ */
+export async function listBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    const limit = options.limit ?? 100;
+    try {
+        // Get backlog items from the dedicated chatroom_backlog table
+        const backlogItems = await d.backend.query(api.backlog.listBacklogItems, {
+            sessionId,
+            chatroomId: chatroomId,
+            statusFilter: 'backlog',
+            sort: options.sort,
+            filter: options.filter,
+            limit,
+        });
+        // Display header
+        console.log('');
+        console.log('══════════════════════════════════════════════════');
+        console.log('📋 BACKLOG');
+        console.log('══════════════════════════════════════════════════');
+        console.log(`Chatroom: ${chatroomId}`);
+        console.log('');
+        if (backlogItems.length === 0) {
+            console.log('No backlog items.');
+        }
+        else {
+            console.log('──────────────────────────────────────────────────');
+            for (let i = 0; i < backlogItems.length; i++) {
+                const item = backlogItems[i];
+                const statusEmoji = getStatusEmoji(item.status);
+                const date = new Date(item.createdAt).toLocaleString('en-US', {
+                    month: 'short',
+                    day: 'numeric',
+                    hour: '2-digit',
+                    minute: '2-digit',
+                    hour12: false,
+                });
+                console.log(`#${i + 1} [${statusEmoji} ${item.status.toUpperCase()}] ${item.content}`);
+                console.log(`   ID: ${item._id}`);
+                console.log(`   Created: ${date}${item.assignedTo ? ` | Assigned: ${item.assignedTo}` : ''}`);
+                // Show scoring info if available
+                if (item.complexity !== undefined ||
+                    item.value !== undefined ||
+                    item.priority !== undefined) {
+                    const parts = [];
+                    if (item.complexity)
+                        parts.push(`complexity=${item.complexity}`);
+                    if (item.value)
+                        parts.push(`value=${item.value}`);
+                    if (item.priority !== undefined)
+                        parts.push(`priority=${item.priority}`);
+                    console.log(`   Score: ${parts.join(' | ')}`);
+                }
+                console.log('');
+            }
+        }
+        console.log('──────────────────────────────────────────────────');
+        console.log(`Showing ${backlogItems.length} backlog item(s)`);
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to list backlog items: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+/**
+ * Add a backlog item
+ */
+export async function addBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    // Validate content
+    if (!options.content || options.content.trim().length === 0) {
+        console.error(`❌ Backlog item content cannot be empty`);
+        process.exit(1);
+        return;
+    }
+    try {
+        const itemId = await d.backend.mutation(api.backlog.createBacklogItem, {
+            sessionId,
+            chatroomId: chatroomId,
+            content: options.content.trim(),
+            createdBy: options.role,
+        });
+        console.log('');
+        console.log('✅ Backlog item added');
+        console.log(`   ID: ${itemId}`);
+        console.log(`   Status: backlog`);
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to add backlog item: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+/**
+ * Complete a backlog item by ID.
+ * Use --force to complete stuck in_progress or pending tasks.
+ */
+export async function completeBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    // Validate backlog item ID
+    if (!options.backlogItemId || options.backlogItemId.trim().length === 0) {
+        console.error(`❌ Backlog item ID is required`);
+        process.exit(1);
+        return;
+    }
+    try {
+        const result = await d.backend.mutation(api.backlog.completeBacklogItem, {
+            sessionId,
+            itemId: options.backlogItemId,
+        });
+        console.log('');
+        console.log('✅ Backlog item completed');
+        console.log(`   ID: ${options.backlogItemId}`);
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to complete backlog item: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+/**
+ * Reopen a closed backlog item, returning it to backlog status.
+ */
+export async function reopenBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    // Validate backlog item ID
+    if (!options.backlogItemId || options.backlogItemId.trim().length === 0) {
+        console.error(`❌ Backlog item ID is required`);
+        process.exit(1);
+        return;
+    }
+    try {
+        await d.backend.mutation(api.backlog.reopenBacklogItem, {
+            sessionId,
+            itemId: options.backlogItemId,
+        });
+        console.log('');
+        console.log('✅ Backlog item reopened');
+        console.log(`   ID: ${options.backlogItemId}`);
+        console.log(`   Status: backlog`);
+        console.log('');
+        console.log('💡 The backlog item is now ready for user review again.');
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to reopen backlog item: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+/**
+ * Patch a backlog item's scoring fields (complexity, value, priority).
+ * Idempotent - can be called multiple times with same or different values.
+ */
+export async function patchBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    // Validate backlog item ID
+    if (!options.backlogItemId || options.backlogItemId.trim().length === 0) {
+        console.error(`❌ Backlog item ID is required`);
+        process.exit(1);
+        return;
+    }
+    // Validate at least one field is provided
+    if (options.complexity === undefined &&
+        options.value === undefined &&
+        options.priority === undefined) {
+        console.error(`❌ At least one of --complexity, --value, or --priority is required`);
+        process.exit(1);
+        return;
+    }
+    // Validate complexity if provided
+    const validComplexity = ['low', 'medium', 'high'];
+    if (options.complexity !== undefined && !validComplexity.includes(options.complexity)) {
+        console.error(`❌ Invalid complexity: ${options.complexity}. Must be one of: ${validComplexity.join(', ')}`);
+        process.exit(1);
+        return;
+    }
+    // Validate value if provided
+    const validValue = ['low', 'medium', 'high'];
+    if (options.value !== undefined && !validValue.includes(options.value)) {
+        console.error(`❌ Invalid value: ${options.value}. Must be one of: ${validValue.join(', ')}`);
+        process.exit(1);
+        return;
+    }
+    // Parse and validate priority if provided
+    let priorityNum;
+    if (options.priority !== undefined) {
+        priorityNum = parseInt(options.priority, 10);
+        if (isNaN(priorityNum)) {
+            console.error(`❌ Invalid priority: ${options.priority}. Must be a number.`);
+            process.exit(1);
+            return;
+        }
+    }
+    try {
+        await d.backend.mutation(api.backlog.patchBacklogItem, {
+            sessionId,
+            itemId: options.backlogItemId,
+            complexity: options.complexity,
+            value: options.value,
+            priority: priorityNum,
+        });
+        console.log('');
+        console.log('✅ Backlog item updated');
+        console.log(`   ID: ${options.backlogItemId}`);
+        if (options.complexity !== undefined) {
+            console.log(`   Complexity: ${options.complexity}`);
+        }
+        if (options.value !== undefined) {
+            console.log(`   Value: ${options.value}`);
+        }
+        if (priorityNum !== undefined) {
+            console.log(`   Priority: ${priorityNum}`);
+        }
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to patch backlog item: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+/**
+ * Score a backlog item by complexity, value, and priority.
+ */
+export async function scoreBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    // Validate backlog item ID
+    if (!options.backlogItemId || options.backlogItemId.trim().length === 0) {
+        console.error(`❌ Backlog item ID is required`);
+        process.exit(1);
+        return;
+    }
+    // Validate at least one scoring field is provided
+    if (options.complexity === undefined &&
+        options.value === undefined &&
+        options.priority === undefined) {
+        console.error(`❌ At least one of --complexity, --value, or --priority is required`);
+        console.error(`   Example: chatroom backlog score --backlog-item-id=... --complexity=medium --value=high`);
+        process.exit(1);
+        return;
+    }
+    // Validate complexity if provided
+    const validComplexity = ['low', 'medium', 'high'];
+    if (options.complexity !== undefined && !validComplexity.includes(options.complexity)) {
+        console.error(`❌ Invalid complexity: ${options.complexity}. Must be one of: ${validComplexity.join(', ')}`);
+        process.exit(1);
+        return;
+    }
+    // Validate value if provided
+    const validValue = ['low', 'medium', 'high'];
+    if (options.value !== undefined && !validValue.includes(options.value)) {
+        console.error(`❌ Invalid value: ${options.value}. Must be one of: ${validValue.join(', ')}`);
+        process.exit(1);
+        return;
+    }
+    // Parse and validate priority if provided
+    let priorityNum;
+    if (options.priority !== undefined) {
+        priorityNum = parseInt(options.priority, 10);
+        if (isNaN(priorityNum)) {
+            console.error(`❌ Invalid priority: ${options.priority}. Must be a number.`);
+            process.exit(1);
+            return;
+        }
+    }
+    try {
+        await d.backend.mutation(api.backlog.patchBacklogItem, {
+            sessionId,
+            itemId: options.backlogItemId,
+            complexity: options.complexity,
+            value: options.value,
+            priority: priorityNum,
+        });
+        console.log('');
+        console.log('✅ Backlog item scored');
+        console.log(`   ID: ${options.backlogItemId}`);
+        if (options.complexity !== undefined) {
+            console.log(`   Complexity: ${options.complexity}`);
+        }
+        if (options.value !== undefined) {
+            console.log(`   Value: ${options.value}`);
+        }
+        if (priorityNum !== undefined) {
+            console.log(`   Priority: ${priorityNum}`);
+        }
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to score backlog item: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+/**
+ * Mark a backlog item as ready for user review.
+ */
+export async function markForReviewBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    // Validate backlog item ID
+    if (!options.backlogItemId || options.backlogItemId.trim().length === 0) {
+        console.error(`❌ Backlog item ID is required`);
+        process.exit(1);
+        return;
+    }
+    try {
+        await d.backend.mutation(api.backlog.markBacklogItemForReview, {
+            sessionId,
+            itemId: options.backlogItemId,
+        });
+        console.log('');
+        console.log('✅ Backlog item marked for review');
+        console.log(`   ID: ${options.backlogItemId}`);
+        console.log(`   Status: pending_user_review`);
+        console.log('');
+        console.log('💡 The backlog item is now visible in the "Pending Review" section for user confirmation.');
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to mark backlog item for review: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+/**
+ * View completed and closed backlog items by date range.
+ */
+export async function historyBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    // Parse date range
+    const now = Date.now();
+    const defaultFrom = now - 30 * 24 * 60 * 60 * 1000; // 30 days ago
+    let fromMs;
+    let toMs;
+    if (options.from) {
+        const parsed = Date.parse(options.from);
+        if (isNaN(parsed)) {
+            console.error(`❌ Invalid --from date: "${options.from}". Use YYYY-MM-DD format.`);
+            process.exit(1);
+            return;
+        }
+        fromMs = parsed;
+    }
+    if (options.to) {
+        const parsed = Date.parse(options.to);
+        if (isNaN(parsed)) {
+            console.error(`❌ Invalid --to date: "${options.to}". Use YYYY-MM-DD format.`);
+            process.exit(1);
+            return;
+        }
+        // Include the full end day (end of day = +86399999ms)
+        toMs = parsed + 86399999;
+    }
+    try {
+        const tasks = await d.backend.query(api.tasks.listHistoricalTasks, {
+            sessionId,
+            chatroomId: chatroomId,
+            from: fromMs,
+            to: toMs,
+            limit: options.limit,
+        });
+        // Compute display range strings
+        const fromDate = new Date(fromMs ?? defaultFrom).toLocaleDateString('en-US', {
+            month: 'short',
+            day: 'numeric',
+            year: 'numeric',
+        });
+        const toDate = new Date(toMs ?? now).toLocaleDateString('en-US', {
+            month: 'short',
+            day: 'numeric',
+            year: 'numeric',
+        });
+        console.log('');
+        console.log('══════════════════════════════════════════════════');
+        console.log('📜 TASK HISTORY');
+        console.log('══════════════════════════════════════════════════');
+        console.log(`Chatroom: ${chatroomId}`);
+        console.log(`Date range: ${fromDate} → ${toDate}`);
+        console.log(`Filter: completed + closed`);
+        console.log('');
+        if (tasks.length === 0) {
+            console.log('No history found for date range.');
+        }
+        else {
+            console.log('──────────────────────────────────────────────────');
+            console.log('📝 COMPLETED / CLOSED TASKS');
+            console.log('──────────────────────────────────────────────────');
+            for (let i = 0; i < tasks.length; i++) {
+                const task = tasks[i];
+                const statusEmoji = getStatusEmoji(task.status);
+                const completedTs = task.completedAt ?? task.updatedAt;
+                const date = new Date(completedTs).toLocaleString('en-US', {
+                    month: 'short',
+                    day: 'numeric',
+                    year: 'numeric',
+                    hour: '2-digit',
+                    minute: '2-digit',
+                    hour12: false,
+                });
+                console.log(`#${i + 1} [${statusEmoji} ${task.status.toUpperCase()}] ${task.content}`);
+                console.log(`   ID: ${task._id}`);
+                console.log(`   Completed: ${date}${task.assignedTo ? ` | Assigned: ${task.assignedTo}` : ''}`);
+                if (task.complexity !== undefined ||
+                    task.value !== undefined ||
+                    task.priority !== undefined) {
+                    const parts = [];
+                    if (task.complexity)
+                        parts.push(`complexity=${task.complexity}`);
+                    if (task.value)
+                        parts.push(`value=${task.value}`);
+                    if (task.priority !== undefined)
+                        parts.push(`priority=${task.priority}`);
+                    console.log(`   Score: ${parts.join(' | ')}`);
+                }
+                console.log('');
+            }
+        }
+        console.log('──────────────────────────────────────────────────');
+        console.log(`Showing ${tasks.length} task(s)`);
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to load history: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+/**
+ * Close a backlog item (mark as closed/stale).
+ */
+export async function closeBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    if (!options.backlogItemId || options.backlogItemId.trim().length === 0) {
+        console.error(`❌ Backlog item ID is required`);
+        process.exit(1);
+        return;
+    }
+    if (!options.reason || options.reason.trim().length === 0) {
+        console.error(`❌ Reason is required when closing a backlog item`);
+        process.exit(1);
+        return;
+    }
+    try {
+        await d.backend.mutation(api.backlog.closeBacklogItem, {
+            sessionId,
+            itemId: options.backlogItemId,
+            reason: options.reason,
+        });
+        console.log('');
+        console.log('✅ Backlog item closed');
+        console.log(`   ID: ${options.backlogItemId}`);
+        console.log(`   Status: closed`);
+        console.log(`   Reason: ${options.reason}`);
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to close backlog item: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+function getStatusEmoji(status) {
+    switch (status) {
+        case 'pending':
+            return '🟢';
+        case 'acknowledged':
+            return '📬';
+        case 'in_progress':
+            return '🔵';
+        case 'backlog':
+            return '⚪';
+        case 'completed':
+            return '✅';
+        case 'pending_user_review':
+            return '👀';
+        case 'closed':
+            return '🔒';
+        default:
+            return '⚫';
+    }
+}
+// ─── Content Hash Helper ───────────────────────────────────────────────────
+/**
+ * Compute a SHA-256 content hash for idempotent import.
+ */
+export function computeContentHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+// ─── Export / Import Commands ──────────────────────────────────────────────
+/**
+ * Export all backlog items to a JSON file.
+ */
+export async function exportBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    if (!d.fs) {
+        console.error('❌ File system operations not available');
+        process.exit(1);
+        return;
+    }
+    try {
+        // Fetch all backlog items
+        const backlogItems = await d.backend.query(api.backlog.listBacklogItems, {
+            sessionId,
+            chatroomId: chatroomId,
+            statusFilter: 'backlog',
+        });
+        // Build export structure
+        const exportData = {
+            exportedAt: Date.now(),
+            chatroomId,
+            items: backlogItems.map((item) => {
+                const exportItem = {
+                    contentHash: computeContentHash(item.content),
+                    content: item.content,
+                    status: item.status,
+                    createdBy: item.createdBy ?? 'unknown',
+                    createdAt: item.createdAt,
+                };
+                if (item.complexity)
+                    exportItem.complexity = item.complexity;
+                if (item.value)
+                    exportItem.value = item.value;
+                if (item.priority !== undefined)
+                    exportItem.priority = item.priority;
+                return exportItem;
+            }),
+        };
+        // Ensure output directory exists
+        const exportDir = options.path ?? nodePath.join(process.cwd(), DEFAULT_EXPORT_DIR);
+        await d.fs.mkdir(exportDir, { recursive: true });
+        // Write JSON file
+        const filePath = nodePath.join(exportDir, BACKLOG_EXPORT_FILENAME);
+        await d.fs.writeFile(filePath, JSON.stringify(exportData, null, 2));
+        console.log('');
+        console.log(`✅ Exported ${exportData.items.length} backlog item(s)`);
+        console.log(`   File: ${filePath}`);
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to export backlog items: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+/**
+ * Import backlog items from a JSON export file.
+ * Idempotent — skips items whose content hash matches an existing item.
+ */
+export async function importBacklog(chatroomId, options, deps) {
+    const d = deps ?? (await createDefaultDeps());
+    const sessionId = requireAuth(d);
+    validateChatroomId(chatroomId);
+    if (!d.fs) {
+        console.error('❌ File system operations not available');
+        process.exit(1);
+        return;
+    }
+    try {
+        // Read the export file
+        const importDir = options.path ?? nodePath.join(process.cwd(), DEFAULT_EXPORT_DIR);
+        const filePath = nodePath.join(importDir, BACKLOG_EXPORT_FILENAME);
+        const raw = await d.fs.readFile(filePath, 'utf-8');
+        const exportData = JSON.parse(raw);
+        // Staleness warning
+        const ageMs = Date.now() - exportData.exportedAt;
+        if (ageMs > STALENESS_THRESHOLD_MS) {
+            const ageDays = Math.floor(ageMs / (24 * 60 * 60 * 1000));
+            console.log(`⚠️  This export is ${ageDays} days old and may be stale.`);
+        }
+        // Fetch existing backlog items to check for duplicates
+        const existingItems = await d.backend.query(api.backlog.listBacklogItems, {
+            sessionId,
+            chatroomId: chatroomId,
+            statusFilter: 'backlog',
+        });
+        // Build set of existing content hashes
+        const existingHashes = new Set(existingItems.map((item) => computeContentHash(item.content)));
+        let imported = 0;
+        let skipped = 0;
+        for (const item of exportData.items) {
+            // Recompute hash from content for verification
+            const hash = computeContentHash(item.content);
+            if (existingHashes.has(hash)) {
+                skipped++;
+                continue;
+            }
+            // Create the backlog item
+            await d.backend.mutation(api.backlog.createBacklogItem, {
+                sessionId,
+                chatroomId: chatroomId,
+                content: item.content,
+                createdBy: item.createdBy,
+                priority: item.priority,
+                complexity: item.complexity,
+                value: item.value,
+            });
+            // Add hash to set so subsequent duplicates in same file are also skipped
+            existingHashes.add(hash);
+            imported++;
+        }
+        console.log('');
+        console.log(`✅ Import complete`);
+        console.log(`   Total items in file: ${exportData.items.length}`);
+        console.log(`   Imported: ${imported}`);
+        console.log(`   Skipped (duplicate): ${skipped}`);
+        console.log('');
+    }
+    catch (error) {
+        console.error(`❌ Failed to import backlog items: ${getErrorMessage(error)}`);
+        process.exit(1);
+        return;
+    }
+}
+//# sourceMappingURL=index.js.map