@lbruton/specflow 3.0.0

package/dist/tools/log-implementation.js

@@ -0,0 +1,446 @@
+import { PathUtils } from '../core/path-utils.js';
+import { ImplementationLogManager } from '../dashboard/implementation-log-manager.js';
+import { parseTasksFromMarkdown } from '../core/task-parser.js';
+export const logImplementationTool = {
+    name: 'log-implementation',
+    description: `Record comprehensive implementation details for a completed task.
+
+⚠️ CRITICAL: Artifacts are REQUIRED. This creates a searchable knowledge base that future AI agents use to discover existing code and avoid duplication.
+
+# WHY DETAILED LOGGING MATTERS
+
+Future AI agents (and future you) will use grep/ripgrep to search implementation logs before implementing new tasks. Complete logs prevent:
+- ❌ Creating duplicate API endpoints
+- ❌ Reimplementing existing components
+- ❌ Duplicating utility functions and business logic
+- ❌ Breaking established integration patterns
+
+Incomplete logs = Duplicated code = Technical debt
+
+# REQUIRED FIELDS
+
+## artifacts (REQUIRED - Object)
+
+Contains structured data about what was implemented. Must include relevant artifact types:
+
+### apiEndpoints (array of API endpoint objects)
+When new API endpoints are created/modified, document:
+- method: HTTP method (GET, POST, PUT, DELETE, PATCH)
+- path: Route path (e.g., "/api/specs/:name/logs")
+- purpose: What this endpoint does
+- requestFormat: Request body/query params format (JSON schema or example)
+- responseFormat: Response structure (JSON schema or example)
+- location: File path and line number (e.g., "src/server.ts:245")
+
+Example:
+\`\`\`
+{
+  "method": "GET",
+  "path": "/api/specs/:name/implementation-log",
+  "purpose": "Retrieve implementation logs with optional filtering",
+  "requestFormat": "Query params: taskId (string, optional), search (string, optional)",
+  "responseFormat": "{ entries: ImplementationLogEntry[] }",
+  "location": "src/dashboard/server.ts:245"
+}
+\`\`\`
+
+### components (array of component objects)
+When reusable UI components are created, document:
+- name: Component name
+- type: Framework type (React, Vue, Svelte, etc.)
+- purpose: What the component does
+- location: File path
+- props: Props interface or type signature
+- exports: What it exports (array of export names)
+
+Example:
+\`\`\`
+{
+  "name": "LogsPage",
+  "type": "React",
+  "purpose": "Main dashboard page for viewing implementation logs with search and filtering",
+  "location": "src/modules/pages/LogsPage.tsx",
+  "props": "{ specs: any[], selectedSpec: string, onSelect: (value: string) => void }",
+  "exports": ["LogsPage (default)"]
+}
+\`\`\`
+
+### functions (array of function objects)
+When utility functions are created, document:
+- name: Function name
+- purpose: What it does
+- location: File path and line
+- signature: Function signature (params and return type)
+- isExported: Whether it can be imported
+
+Example:
+\`\`\`
+{
+  "name": "searchLogs",
+  "purpose": "Search implementation logs by keyword",
+  "location": "src/dashboard/implementation-log-manager.ts:156",
+  "signature": "(searchTerm: string) => Promise<ImplementationLogEntry[]>",
+  "isExported": true
+}
+\`\`\`
+
+### classes (array of class objects)
+When classes are created, document:
+- name: Class name
+- purpose: What the class does
+- location: File path
+- methods: List of public methods
+- isExported: Whether it can be imported
+
+Example:
+\`\`\`
+{
+  "name": "ImplementationLogManager",
+  "purpose": "Manages CRUD operations for implementation logs",
+  "location": "src/dashboard/implementation-log-manager.ts",
+  "methods": ["loadLog", "addLogEntry", "getAllLogs", "searchLogs", "getTaskStats"],
+  "isExported": true
+}
+\`\`\`
+
+### integrations (array of integration objects)
+Document how frontend connects to backend:
+- description: How components connect to APIs
+- frontendComponent: Which component initiates the connection
+- backendEndpoint: Which API endpoint is called
+- dataFlow: Describe the data flow (e.g., "User clicks → API call → State update → Re-render")
+
+Example:
+\`\`\`
+{
+  "description": "LogsPage fetches logs via REST API and subscribes to WebSocket for real-time updates",
+  "frontendComponent": "LogsPage",
+  "backendEndpoint": "GET /api/specs/:name/implementation-log",
+  "dataFlow": "Component mount → API fetch → Display logs → WebSocket subscription → Real-time updates on new entries"
+}
+\`\`\`
+
+### tests (array of test objects)
+When tests are written and run, document execution results. Tests MUST be run before logging — do not log tests you only wrote but never executed.
+- name: Test suite or file name (e.g., "E2E: User authentication flow")
+- type: Test type (unit, integration, e2e, smoke, acceptance)
+- framework: Test framework used (playwright, vitest, jest, cypress, manual)
+- location: File path (e.g., "tests/e2e/auth-flow.spec.ts")
+- status: Execution result (passed, failed, skipped) — must reflect actual test run
+- passed: Number of passing tests
+- failed: Number of failing tests
+- total: Total test count
+- duration: Execution time (optional, e.g., "4.2s")
+- coveragePercent: Code coverage percentage (optional)
+- userStories: Array of requirement IDs this test validates (e.g., ["1.1", "1.2", "2.1"])
+
+Example:
+\`\`\`
+{
+  "name": "E2E: Todo CRUD operations",
+  "type": "e2e",
+  "framework": "playwright",
+  "location": "tests/e2e/todo-crud.spec.ts",
+  "status": "passed",
+  "passed": 12,
+  "failed": 0,
+  "total": 12,
+  "duration": "8.3s",
+  "userStories": ["1.1", "1.2", "2.1"]
+}
+\`\`\`
+
+# GOOD EXAMPLE (Include ALL relevant artifacts)
+
+Task: "Implemented logs dashboard with real-time updates"
+
+\`\`\`json
+{
+  "taskId": "2.3",
+  "summary": "Implemented real-time implementation logs dashboard with filtering, search, and WebSocket updates",
+  "artifacts": {
+    "apiEndpoints": [
+      {
+        "method": "GET",
+        "path": "/api/specs/:name/implementation-log",
+        "purpose": "Retrieve implementation logs with optional filtering",
+        "requestFormat": "Query params: taskId (string, optional), search (string, optional)",
+        "responseFormat": "{ entries: ImplementationLogEntry[] }",
+        "location": "src/dashboard/server.ts:245"
+      }
+    ],
+    "components": [
+      {
+        "name": "LogsPage",
+        "type": "React",
+        "purpose": "Main dashboard page for viewing implementation logs with search and filtering",
+        "location": "src/modules/pages/LogsPage.tsx",
+        "props": "None (uses React Router params)",
+        "exports": ["LogsPage (default)"]
+      }
+    ],
+    "classes": [
+      {
+        "name": "ImplementationLogManager",
+        "purpose": "Manages CRUD operations for implementation logs",
+        "location": "src/dashboard/implementation-log-manager.ts",
+        "methods": ["loadLog", "addLogEntry", "getAllLogs", "searchLogs", "getTaskStats"],
+        "isExported": true
+      }
+    ],
+    "integrations": [
+      {
+        "description": "LogsPage fetches logs via REST API and subscribes to WebSocket for real-time updates",
+        "frontendComponent": "LogsPage",
+        "backendEndpoint": "GET /api/specs/:name/implementation-log",
+        "dataFlow": "Component mount → API fetch → Display logs → WebSocket subscription → Real-time updates on new entries"
+      }
+    ],
+    "tests": [
+      {
+        "name": "E2E: Implementation logs dashboard",
+        "type": "e2e",
+        "framework": "playwright",
+        "location": "tests/e2e/logs-dashboard.spec.ts",
+        "status": "passed",
+        "passed": 8,
+        "failed": 0,
+        "total": 8,
+        "duration": "12.4s",
+        "userStories": ["2.1", "2.3"]
+      }
+    ]
+  },
+  "filesModified": ["src/dashboard/server.ts"],
+  "filesCreated": ["src/modules/pages/LogsPage.tsx", "tests/e2e/logs-dashboard.spec.ts"],
+  "statistics": { "linesAdded": 750, "linesRemoved": 15, "filesChanged": 3 }
+}
+\`\`\`
+
+# BAD EXAMPLE (Don't do this)
+
+❌ Empty artifacts - Future agents learn nothing:
+\`\`\`json
+{
+  "taskId": "2.3",
+  "summary": "Added endpoint and page",
+  "artifacts": {},
+  "filesModified": ["server.ts"],
+  "filesCreated": ["LogsPage.tsx"]
+}
+\`\`\`
+
+❌ Vague summary with no structured data:
+\`\`\`json
+{
+  "taskId": "2.3",
+  "summary": "Implemented features",
+  "artifacts": {},
+  "filesModified": ["server.ts", "app.tsx"]
+}
+\`\`\`
+
+# Instructions
+
+1. After completing a task, review what you implemented
+2. Identify all artifacts (APIs, components, functions, classes, integrations, tests)
+3. Document each with full details and locations
+4. Include ALL the information - be thorough!
+5. Future agents depend on this data quality`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectPath: {
+                type: 'string',
+                description: 'Absolute path to the project root (optional - uses server context path if not provided)'
+            },
+            specName: {
+                type: 'string',
+                description: 'Name of the specification'
+            },
+            taskId: {
+                type: 'string',
+                description: 'Task ID (e.g., "1", "1.2", "3.1.4")'
+            },
+            summary: {
+                type: 'string',
+                description: 'Brief summary of what was implemented'
+            },
+            filesModified: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'List of files that were modified'
+            },
+            filesCreated: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'List of files that were created'
+            },
+            statistics: {
+                type: 'object',
+                properties: {
+                    linesAdded: {
+                        type: 'number',
+                        description: 'Number of lines added'
+                    },
+                    linesRemoved: {
+                        type: 'number',
+                        description: 'Number of lines removed'
+                    }
+                },
+                required: ['linesAdded', 'linesRemoved'],
+                description: 'Code statistics for the implementation'
+            },
+            artifacts: {
+                type: 'object',
+                description: 'REQUIRED: Structured data about implemented artifacts (APIs, components, functions, classes, integrations). See tool description for detailed format.',
+                properties: {
+                    apiEndpoints: {
+                        type: 'array',
+                        description: 'API endpoints created or modified',
+                        items: { type: 'object' }
+                    },
+                    components: {
+                        type: 'array',
+                        description: 'Reusable UI components created',
+                        items: { type: 'object' }
+                    },
+                    functions: {
+                        type: 'array',
+                        description: 'Utility functions or methods created',
+                        items: { type: 'object' }
+                    },
+                    classes: {
+                        type: 'array',
+                        description: 'Classes created',
+                        items: { type: 'object' }
+                    },
+                    integrations: {
+                        type: 'array',
+                        description: 'Frontend-backend integration patterns',
+                        items: { type: 'object' }
+                    },
+                    tests: {
+                        type: 'array',
+                        description: 'Tests written and run for this task (must include execution results)',
+                        items: { type: 'object' }
+                    }
+                }
+            }
+        },
+        required: ['specName', 'taskId', 'summary', 'filesModified', 'filesCreated', 'statistics', 'artifacts']
+    },
+    annotations: {
+        title: 'Log Implementation',
+        destructiveHint: true,
+    }
+};
+export async function logImplementationHandler(args, context) {
+    const { specName, taskId, summary, filesModified = [], filesCreated = [], statistics, artifacts } = args;
+    // Use context projectPath as default, allow override via args
+    const projectPath = args.projectPath || context.projectPath;
+    if (!projectPath) {
+        return {
+            success: false,
+            message: 'Project path is required but not provided in context or arguments'
+        };
+    }
+    try {
+        // Validate artifacts is provided
+        if (!artifacts) {
+            return {
+                success: false,
+                message: 'Artifacts field is REQUIRED. See tool description for detailed artifact format and examples.',
+                nextSteps: [
+                    'Review the log-implementation tool description for artifact structure',
+                    'Document all API endpoints, components, functions, classes, integrations, and tests',
+                    'Provide structured artifact data before calling this tool',
+                    'Ensure artifacts contains at least one of: apiEndpoints, components, functions, classes, integrations, or tests'
+                ]
+            };
+        }
+        // Validate task exists
+        const specTasksPath = PathUtils.getSpecPath(projectPath, specName);
+        const tasksFile = `${specTasksPath}/tasks.md`;
+        try {
+            const { promises: fs } = await import('fs');
+            const tasksContent = await fs.readFile(tasksFile, 'utf-8');
+            const parseResult = parseTasksFromMarkdown(tasksContent);
+            const taskExists = parseResult.tasks.some(t => t.id === taskId);
+            if (!taskExists) {
+                return {
+                    success: false,
+                    message: `Task '${taskId}' not found in specification '${specName}'`,
+                    nextSteps: [
+                        `Check the task ID in .spec-workflow/specs/${specName}/tasks.md`,
+                        'Verify the spec name is correct',
+                        'Use spec-status to see available tasks'
+                    ]
+                };
+            }
+        }
+        catch (parseError) {
+            return {
+                success: false,
+                message: `Failed to validate task: ${parseError instanceof Error ? parseError.message : String(parseError)}`,
+                nextSteps: [
+                    `Check that .spec-workflow/specs/${specName}/tasks.md exists`,
+                    'Verify the tasks file is valid markdown',
+                    'Use spec-status to diagnose issues'
+                ]
+            };
+        }
+        // Create log entry
+        const logManager = new ImplementationLogManager(specTasksPath);
+        const logEntry = {
+            taskId,
+            timestamp: new Date().toISOString(),
+            summary,
+            filesModified: filesModified || [],
+            filesCreated: filesCreated || [],
+            statistics: {
+                linesAdded: statistics.linesAdded || 0,
+                linesRemoved: statistics.linesRemoved || 0,
+                filesChanged: (filesModified?.length || 0) + (filesCreated?.length || 0)
+            },
+            artifacts
+        };
+        const createdEntry = await logManager.addLogEntry(logEntry);
+        // Get task stats
+        const taskStats = await logManager.getTaskStats(taskId);
+        return {
+            success: true,
+            message: `Implementation logged for task '${taskId}'`,
+            data: {
+                entryId: createdEntry.id,
+                entry: createdEntry,
+                taskStats,
+                dashboardUrl: `${context.dashboardUrl}/logs?spec=${encodeURIComponent(specName)}&task=${taskId}`
+            },
+            nextSteps: [
+                'Mark task as completed in tasks.md by changing [-] to [x]',
+                'View implementation log in dashboard under Logs tab',
+                'Continue with next pending task'
+            ],
+            projectContext: {
+                projectPath,
+                workflowRoot: PathUtils.getWorkflowRoot(projectPath),
+                specName,
+                dashboardUrl: context.dashboardUrl
+            }
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            message: `Failed to log implementation: ${errorMessage}`,
+            nextSteps: [
+                'Verify all required parameters are provided',
+                'Check that the spec and task exist',
+                'View dashboard logs to see previous entries'
+            ]
+        };
+    }
+}
+//# sourceMappingURL=log-implementation.js.map

package/dist/tools/log-implementation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-implementation.js","sourceRoot":"","sources":["../../src/tools/log-implementation.ts"],"names":[],"mappings":"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"}

package/dist/tools/spec-list.d.ts

@@ -0,0 +1,5 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ToolContext, ToolResponse } from '../types.js';
+export declare const specListTool: Tool;
+export declare function specListHandler(args: any, context: ToolContext): Promise<ToolResponse>;
+//# sourceMappingURL=spec-list.d.ts.map

package/dist/tools/spec-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-list.d.ts","sourceRoot":"","sources":["../../src/tools/spec-list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKxD,eAAO,MAAM,YAAY,EAAE,IA4B1B,CAAC;AAkCF,wBAAsB,eAAe,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CA6F5F"}

package/dist/tools/spec-list.js

@@ -0,0 +1,144 @@
+import { PathUtils } from '../core/path-utils.js';
+import { SpecParser } from '../core/parser.js';
+import { readdir, stat } from 'fs/promises';
+export const specListTool = {
+    name: 'spec-list',
+    description: `Search and list specifications by issue ID or title keywords.
+
+# Instructions
+Call to find existing specs before creating new ones. Searches both active and optionally archived specs. Matches against the full directory name (both issue ID prefix and title portion).`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            projectPath: {
+                type: 'string',
+                description: 'Absolute path to the project root (optional - uses server context path if not provided)'
+            },
+            query: {
+                type: 'string',
+                description: 'Search query — matches against spec directory name (e.g., "STAK-123" or "authentication"). Case-insensitive.'
+            },
+            includeArchived: {
+                type: 'boolean',
+                description: 'Include archived specs in results (default: false)'
+            }
+        },
+        required: []
+    },
+    annotations: {
+        title: 'Spec List',
+        readOnlyHint: true,
+    }
+};
+function determinePhaseAndStatus(spec) {
+    if (!spec.phases.requirements.exists) {
+        return { currentPhase: 'requirements', overallStatus: 'requirements-needed' };
+    }
+    if (!spec.phases.design.exists) {
+        return { currentPhase: 'design', overallStatus: 'design-needed' };
+    }
+    if (!spec.phases.tasks.exists) {
+        return { currentPhase: 'tasks', overallStatus: 'tasks-needed' };
+    }
+    if (spec.phases.readinessReport && !spec.phases.readinessReport.exists) {
+        return { currentPhase: 'readiness-gate', overallStatus: 'readiness-gate-needed' };
+    }
+    if (spec.taskProgress && spec.taskProgress.completed === spec.taskProgress.total && spec.taskProgress.total > 0) {
+        return { currentPhase: 'completed', overallStatus: 'completed' };
+    }
+    if (spec.taskProgress && spec.taskProgress.pending > 0) {
+        return { currentPhase: 'implementation', overallStatus: 'implementing' };
+    }
+    return { currentPhase: 'implementation', overallStatus: 'ready-for-implementation' };
+}
+export async function specListHandler(args, context) {
+    const projectPath = args.projectPath || context.projectPath;
+    const query = args.query?.trim().toLowerCase() || '';
+    const includeArchived = args.includeArchived || false;
+    if (!projectPath) {
+        return {
+            success: false,
+            message: 'Project path is required but not provided in context or arguments'
+        };
+    }
+    try {
+        const translatedPath = PathUtils.translatePath(projectPath);
+        const parser = new SpecParser(translatedPath);
+        const results = [];
+        // Get active specs
+        const activeSpecs = await parser.getAllSpecs();
+        for (const spec of activeSpecs) {
+            if (!query || spec.name.toLowerCase().includes(query)) {
+                const { currentPhase, overallStatus } = determinePhaseAndStatus(spec);
+                results.push({
+                    name: spec.name,
+                    currentPhase,
+                    overallStatus,
+                    taskProgress: spec.taskProgress || { total: 0, completed: 0, pending: 0 },
+                    createdAt: spec.createdAt,
+                    lastModified: spec.lastModified,
+                    archived: false
+                });
+            }
+        }
+        // Get archived specs if requested
+        if (includeArchived) {
+            const archivePath = PathUtils.getArchiveSpecsPath(translatedPath);
+            try {
+                const entries = await readdir(archivePath, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory()) {
+                        if (!query || entry.name.toLowerCase().includes(query)) {
+                            const specPath = PathUtils.getArchiveSpecPath(translatedPath, entry.name);
+                            try {
+                                const stats = await stat(specPath);
+                                results.push({
+                                    name: entry.name,
+                                    currentPhase: 'archived',
+                                    overallStatus: 'archived',
+                                    taskProgress: { total: 0, completed: 0, pending: 0 },
+                                    createdAt: stats.birthtime.toISOString(),
+                                    lastModified: stats.mtime.toISOString(),
+                                    archived: true
+                                });
+                            }
+                            catch {
+                                // Skip unreadable archive entries
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // Archive directory doesn't exist — that's fine
+            }
+        }
+        const matchLabel = query ? ` matching "${args.query}"` : '';
+        const archivedCount = results.filter(r => r.archived).length;
+        const activeCount = results.length - archivedCount;
+        return {
+            success: true,
+            message: `Found ${results.length} spec(s)${matchLabel} (${activeCount} active${includeArchived ? `, ${archivedCount} archived` : ''})`,
+            data: {
+                specs: results,
+                query: args.query || null,
+                includeArchived
+            },
+            nextSteps: results.length === 0
+                ? ['No specs found. Use create-spec-doc to create a new specification.']
+                : ['Use spec-status with a spec name for detailed phase information.']
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            message: `Failed to list specifications: ${errorMessage}`,
+            nextSteps: [
+                'Verify the project path is correct',
+                'Check if .spec-workflow/specs/ directory exists'
+            ]
+        };
+    }
+}
+//# sourceMappingURL=spec-list.js.map

package/dist/tools/spec-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-list.js","sourceRoot":"","sources":["../../src/tools/spec-list.ts"],"names":[],"mappings":"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"}

package/dist/tools/spec-status.d.ts

@@ -0,0 +1,5 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ToolContext, ToolResponse } from '../types.js';
+export declare const specStatusTool: Tool;
+export declare function specStatusHandler(args: any, context: ToolContext): Promise<ToolResponse>;
+//# sourceMappingURL=spec-status.d.ts.map

package/dist/tools/spec-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-status.d.ts","sourceRoot":"","sources":["../../src/tools/spec-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMxD,eAAO,MAAM,cAAc,EAAE,IAwB5B,CAAC;AAEF,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAsN9F"}