@popoverai/dotrequirements 0.15.0 → 0.17.0

package/dist/mcp/handlers/list.d.ts

@@ -0,0 +1,36 @@
+/**
+ * list_all_requirements and list_untested_requirements handlers
+ *
+ * Lists requirements in a project with optional filtering for untested requirements.
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for list_all_requirements tool
+ */
+export interface ListAllRequirementsArgs {
+    projectId?: string;
+}
+/**
+ * Handler for list_all_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-LIST-1.0: Response includes count of total requirements and total nodes
+ * - MCP-LIST-1.1: Each requirement displays its key, label, and child count
+ * - MCP-LIST-1.2: Requirements are listed from all files discovered in the project
+ */
+export declare function handleListAllRequirements(args: ListAllRequirementsArgs, context: HandlerContext): Promise<ToolResponse>;
+/**
+ * Arguments for list_untested_requirements tool
+ */
+export interface ListUntestedRequirementsArgs {
+    projectId?: string;
+}
+/**
+ * Handler for list_untested_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-LIST-2.0: Only requirements with no test references are included
+ * - MCP-LIST-2.1: Response indicates count of requirements lacking coverage
+ */
+export declare function handleListUntestedRequirements(args: ListUntestedRequirementsArgs, context: HandlerContext): Promise<ToolResponse>;
+//# sourceMappingURL=list.d.ts.map

package/dist/mcp/handlers/list.js

@@ -0,0 +1,65 @@
+/**
+ * list_all_requirements and list_untested_requirements handlers
+ *
+ * Lists requirements in a project with optional filtering for untested requirements.
+ */
+import { textResponse } from './types.js';
+import { getReferencedRequirementIds } from '../grep.js';
+/**
+ * Handler for list_all_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-LIST-1.0: Response includes count of total requirements and total nodes
+ * - MCP-LIST-1.1: Each requirement displays its key, label, and child count
+ * - MCP-LIST-1.2: Requirements are listed from all files discovered in the project
+ */
+export async function handleListAllRequirements(args, context) {
+    const { projectId } = args;
+    const project = await context.getProjectFromDiscovery(projectId);
+    const requirements = await context.getRequirements(projectId);
+    if (requirements.length === 0) {
+        return textResponse(`No requirements found in project: ${project.path}\n\nMake sure .requirements/ directory exists with Markdown files (*.requirements.md).`);
+    }
+    // MCP-LIST-1.2: Group requirements from all discovered files by root ID
+    const grouped = new Map();
+    for (const req of requirements) {
+        const existing = grouped.get(req.rootId) || [];
+        existing.push(req);
+        grouped.set(req.rootId, existing);
+    }
+    // MCP-LIST-1.1: Each requirement displays key, label (from content), and child count
+    const formatted = Array.from(grouped.entries())
+        .map(([rootId, reqs]) => {
+        const root = reqs.find((r) => r.path.length === 0);
+        const childCount = reqs.length - 1;
+        return `- **${rootId}**: ${root?.content || '(no content)'} (${childCount} children)`;
+    })
+        .join('\n');
+    // MCP-LIST-1.0: Response includes count of total requirements and total nodes
+    return textResponse(`Found ${grouped.size} requirement(s) with ${requirements.length} total nodes:\n\n${formatted}`);
+}
+/**
+ * Handler for list_untested_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-LIST-2.0: Only requirements with no test references are included
+ * - MCP-LIST-2.1: Response indicates count of requirements lacking coverage
+ */
+export async function handleListUntestedRequirements(args, context) {
+    const { projectId } = args;
+    const project = await context.getProjectFromDiscovery(projectId);
+    const requirements = await context.getRequirements(projectId);
+    const referencedIds = await getReferencedRequirementIds(project.path);
+    // MCP-LIST-2.0: Filter to root requirements without test references
+    const rootRequirements = requirements.filter((r) => r.path.length === 0);
+    const untested = rootRequirements.filter((r) => !referencedIds.has(r.id));
+    if (untested.length === 0) {
+        return textResponse(`All ${rootRequirements.length} requirements have test references!`);
+    }
+    const formatted = untested
+        .map((r) => `- **${r.id}**: ${r.content}`)
+        .join('\n');
+    // MCP-LIST-2.1: Response indicates count of requirements lacking coverage
+    return textResponse(`Found ${untested.length} untested requirement(s) out of ${rootRequirements.length} total:\n\n${formatted}`);
+}
+//# sourceMappingURL=list.js.map

package/dist/mcp/handlers/push.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Push handler for MCP tools
+ *
+ * Provides requirements push functionality:
+ * - push_requirements: Push local requirements to cloud
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for push_requirements tool
+ */
+export interface PushRequirementsArgs {
+    filePath?: string;
+    confirmed?: boolean;
+    projectId?: string;
+}
+/**
+ * Handler for push_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-PUSH-1.0: When a push is requested without confirmed flag, a diff preview is returned
+ * - MCP-PUSH-1.1: When confirmed is true, the push executes and returns success message
+ * - MCP-PUSH-1.2: When credentials are missing or invalid, an error explains how to authenticate
+ * - MCP-PUSH-1.3: When filePath is provided, only that file is pushed
+ */
+export declare function handlePushRequirements(args: PushRequirementsArgs, context: HandlerContext): Promise<ToolResponse>;
+//# sourceMappingURL=push.d.ts.map

package/dist/mcp/handlers/push.js

@@ -0,0 +1,143 @@
+/**
+ * Push handler for MCP tools
+ *
+ * Provides requirements push functionality:
+ * - push_requirements: Push local requirements to cloud
+ */
+import { textResponse, errorResponse } from './types.js';
+import { existsSync } from 'fs';
+import { resolve, basename } from 'path';
+import { CONVEX_URL } from '../convexClient.js';
+import { findRequirementsFiles } from '../requirements.js';
+import { parseFilesForPush, dryRunPush, executePush, } from '../../push/index.js';
+/**
+ * Handler for push_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-PUSH-1.0: When a push is requested without confirmed flag, a diff preview is returned
+ * - MCP-PUSH-1.1: When confirmed is true, the push executes and returns success message
+ * - MCP-PUSH-1.2: When credentials are missing or invalid, an error explains how to authenticate
+ * - MCP-PUSH-1.3: When filePath is provided, only that file is pushed
+ */
+export async function handlePushRequirements(args, context) {
+    const { filePath, confirmed = false, projectId } = args;
+    // MCP-PUSH-1.2: Get project credentials (throws if not configured)
+    let project;
+    try {
+        project = await context.getProjectFromDiscovery(projectId);
+    }
+    catch (error) {
+        return errorResponse(`Push requires project credentials. Run \`dotrequirements link\` to connect to cloud.\n\nError: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Determine files to push
+    let filesToPush;
+    // MCP-PUSH-1.3: When filePath is provided, only that file is pushed
+    if (filePath) {
+        const fullPath = resolve(project.path, filePath);
+        if (!existsSync(fullPath)) {
+            return errorResponse(`File not found: ${filePath}`);
+        }
+        filesToPush = [fullPath];
+    }
+    else {
+        // Use same file discovery as CLI - searches entire workspace
+        filesToPush = await findRequirementsFiles(project.path);
+        if (filesToPush.length === 0) {
+            return textResponse('No *.requirements.md files found. Nothing to push.');
+        }
+    }
+    // Parse files
+    const { parsedFiles, totalRequirements } = parseFilesForPush(filesToPush);
+    // Build credentials
+    const credentials = {
+        projectId: project.projectId,
+        projectSecret: project.projectSecret,
+        convexUrl: CONVEX_URL,
+    };
+    // Run dry run (always, even when confirmed - ensures fresh state)
+    const dryRunResult = await dryRunPush(parsedFiles, credentials);
+    // Check if there's anything to push
+    const pushableCount = dryRunResult.updates.length +
+        dryRunResult.creates.length +
+        dryRunResult.notFound.length;
+    if (pushableCount === 0 && dryRunResult.invalid.length > 0) {
+        // Only invalid files
+        const invalidList = dryRunResult.invalid
+            .map(({ file, result }) => `- ${basename(file.filePath)}: ${result.error}`)
+            .join('\n');
+        return {
+            content: [{ type: 'text', text: `✗ No valid documents to push.\n\n**Invalid files:**\n${invalidList}` }],
+            isError: true,
+        };
+    }
+    // MCP-PUSH-1.0: When not confirmed, show preview
+    if (!confirmed) {
+        let summary = `# Push Preview\n\n**Files:** ${parsedFiles.length}\n**Requirements:** ${totalRequirements}\n\n`;
+        if (dryRunResult.updates.length > 0) {
+            summary += `## Updates (${dryRunResult.updates.length})\n`;
+            for (const { file, result } of dryRunResult.updates) {
+                const fileName = basename(file.filePath);
+                const hasConflict = dryRunResult.conflicts.some((c) => c.item.file === file);
+                const conflictNote = hasConflict ? ' ⚠️ [cloud changed since pull]' : '';
+                const warningNote = result.warning ? ` (${result.warning})` : '';
+                summary += `- ~ ${fileName}${conflictNote}${warningNote}\n`;
+            }
+            summary += '\n';
+        }
+        if (dryRunResult.creates.length > 0) {
+            summary += `## New Documents (${dryRunResult.creates.length})\n`;
+            for (const { file, result } of dryRunResult.creates) {
+                const fileName = basename(file.filePath);
+                const warningNote = result.warning ? ` (${result.warning})` : '';
+                summary += `- + ${fileName}${warningNote}\n`;
+            }
+            summary += '\n';
+        }
+        if (dryRunResult.notFound.length > 0) {
+            summary += `## Not Found in Cloud (${dryRunResult.notFound.length}) - will create new\n`;
+            for (const { file, result } of dryRunResult.notFound) {
+                const fileName = basename(file.filePath);
+                summary += `- ! ${fileName} (ID: ${result.documentId})\n`;
+            }
+            summary += '\n';
+        }
+        if (dryRunResult.invalid.length > 0) {
+            summary += `## Skipped - Invalid (${dryRunResult.invalid.length})\n`;
+            for (const { file, result } of dryRunResult.invalid) {
+                const fileName = basename(file.filePath);
+                summary += `- ✗ ${fileName}: ${result.error}\n`;
+            }
+            summary += '\n';
+        }
+        if (dryRunResult.conflicts.length > 0) {
+            summary += `⚠️ **Warning:** ${dryRunResult.conflicts.length} file(s) have cloud changes since last pull. Pushing will overwrite those changes.\n\n`;
+        }
+        summary += `**To proceed:** Call this tool again with \`confirmed: true\``;
+        return textResponse(summary);
+    }
+    // MCP-PUSH-1.1: When confirmed, execute push
+    try {
+        const result = await executePush(dryRunResult, credentials);
+        let output = '✓ Push complete!\n\n';
+        if (result.created > 0) {
+            output += `**Created:** ${result.created} document(s)\n`;
+        }
+        if (result.updated > 0) {
+            output += `**Updated:** ${result.updated} document(s)\n`;
+        }
+        if (result.errors.length > 0) {
+            output += `\n**Errors:**\n`;
+            for (const { fileName, error } of result.errors) {
+                output += `- ${fileName}: ${error}\n`;
+            }
+        }
+        return textResponse(output);
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `✗ Push failed:\n\n${error instanceof Error ? error.message : String(error)}` }],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=push.js.map

package/dist/mcp/handlers/review.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Review handlers for MCP tools
+ *
+ * Provides AI-powered review functionality:
+ * - style_check: Check requirements or test files for style issues
+ * - review_test: Comprehensively review tests for semantic correctness
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for style_check tool
+ */
+export interface StyleCheckArgs {
+    filePath: string;
+    requirementKeys?: string[];
+    model?: string;
+}
+/**
+ * Arguments for review_test tool
+ */
+export interface ReviewTestArgs {
+    testFilePath: string;
+    projectId?: string;
+}
+/**
+ * Handler for style_check tool
+ *
+ * Requirements covered:
+ * - MCP-REVIEW-1.0: For requirements files, feedback identifies vague language, missing preconditions, and style violations
+ * - MCP-REVIEW-1.1: For test files, feedback identifies incorrect requirement() usage and missing test coverage
+ * - MCP-REVIEW-1.2: Feedback is categorized by severity: must fix, should fix, could improve
+ * - MCP-REVIEW-1.3: When cloud credentials are unavailable, an error explains how to authenticate
+ */
+export declare function handleStyleCheck(args: StyleCheckArgs, context: HandlerContext, options?: {
+    useEnvAuth?: boolean;
+    apiBaseUrl?: string;
+}): Promise<ToolResponse>;
+/**
+ * Handler for review_test tool
+ *
+ * Requirements covered:
+ * - MCP-REVIEW-2.0: The review validates that test setup matches requirement preconditions
+ * - MCP-REVIEW-2.1: The review validates that test actions match requirement triggers
+ * - MCP-REVIEW-2.2: The review validates that test assertions match requirement outcomes
+ * - MCP-REVIEW-2.3: Feedback identifies requirements without test coverage
+ * - MCP-REVIEW-2.4: Feedback identifies tests that reference non-existent requirements
+ * - MCP-REVIEW-2.5: When cloud credentials are unavailable, an error explains how to authenticate
+ */
+export declare function handleReviewTest(args: ReviewTestArgs, context: HandlerContext, options?: {
+    apiBaseUrl?: string;
+}): Promise<ToolResponse>;
+//# sourceMappingURL=review.d.ts.map

package/dist/mcp/handlers/review.js

@@ -0,0 +1,219 @@
+/**
+ * Review handlers for MCP tools
+ *
+ * Provides AI-powered review functionality:
+ * - style_check: Check requirements or test files for style issues
+ * - review_test: Comprehensively review tests for semantic correctness
+ */
+import { textResponse, errorResponse } from './types.js';
+import { existsSync, readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { filterRequirementsByKeys, getRequirementTree, formatRequirementTree, } from '../requirements.js';
+import { discoverProjects, } from '../../utils/project-discovery.js';
+const STYLE_CHECK_GUIDANCE = `
+
+---
+
+## How to use this feedback
+
+1. **This check is stateless.** It is a "new set of eyes" from any previous feedback rounds — it has no memory of prior suggestions or changes you've already made.
+
+2. **Act on feedback from the posture of "what will make the requirements better."** The severity categories (MUST FIX / SHOULD FIX / COULD IMPROVE) are prioritized for convenience, but unless the user has explicitly told you to ignore lower-priority feedback, go ahead and make any improvements — minor or otherwise. If you believe acting on a specific piece of feedback would make the requirements *worse*, surface that feedback to the user rather than silently ignoring it. Otherwise, just act.
+
+3. **Next steps:** Always run \`validate_requirements\` again after making updates. If you make significant changes based on this feedback, you can run \`style_check\` again — but be aware that will be a fresh set of eyes, not a continued conversation.`;
+/**
+ * Handler for style_check tool
+ *
+ * Requirements covered:
+ * - MCP-REVIEW-1.0: For requirements files, feedback identifies vague language, missing preconditions, and style violations
+ * - MCP-REVIEW-1.1: For test files, feedback identifies incorrect requirement() usage and missing test coverage
+ * - MCP-REVIEW-1.2: Feedback is categorized by severity: must fix, should fix, could improve
+ * - MCP-REVIEW-1.3: When cloud credentials are unavailable, an error explains how to authenticate
+ */
+export async function handleStyleCheck(args, context, options) {
+    const { filePath, requirementKeys, model } = args;
+    const { useEnvAuth = false, apiBaseUrl = 'https://app.dotrequirements.io' } = options ?? {};
+    const fullPath = resolve(context.workspaceRoot, filePath);
+    if (!existsSync(fullPath)) {
+        return errorResponse(`File not found: ${filePath}`);
+    }
+    // Read file contents
+    const fileContents = readFileSync(fullPath, 'utf-8');
+    // Detect file type
+    // MCP-REVIEW-1.0 & MCP-REVIEW-1.1: Different feedback for different file types
+    const isRequirementsFile = filePath.endsWith('.requirements.md');
+    const isTestFile = /\.(test|spec)\.(js|jsx|ts|tsx)$/.test(filePath);
+    if (!isRequirementsFile && !isTestFile) {
+        return errorResponse(`Unsupported file type. File must be:\n- Requirements file: *.requirements.md\n- Test file: *.test.{js,jsx,ts,tsx} or *.spec.{js,jsx,ts,tsx}`);
+    }
+    const fileType = isRequirementsFile ? 'requirements' : 'test';
+    // If requirementKeys provided, filter the file to only those requirements
+    let fileContentsToCheck = fileContents;
+    let scopeNote = '';
+    if (requirementKeys && requirementKeys.length > 0) {
+        if (!isRequirementsFile) {
+            return errorResponse(`requirementKeys can only be used with requirements files (*.requirements.md), not test files.`);
+        }
+        try {
+            const { filteredContent, foundKeys, missingKeys } = filterRequirementsByKeys(fileContents, requirementKeys);
+            if (foundKeys.length === 0) {
+                return errorResponse(`None of the specified requirement keys were found in ${filePath}: ${requirementKeys.join(', ')}`);
+            }
+            fileContentsToCheck = filteredContent;
+            if (missingKeys.length > 0) {
+                scopeNote = `\n\n> **Note:** Some specified keys were not found in the file: ${missingKeys.join(', ')}`;
+            }
+        }
+        catch (error) {
+            return errorResponse(`Failed to filter requirements: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // MCP-REVIEW-1.3: Get credentials - walk up from file's directory to find project
+    const fileDir = dirname(fullPath);
+    let project;
+    try {
+        if (useEnvAuth) {
+            // Using env auth - go straight to context
+            project = await context.getProjectFromDiscovery();
+        }
+        else {
+            // Try to find a project starting from the file's directory
+            const result = await discoverProjects(fileDir);
+            if (result.type === 'none') {
+                // If no project found from file dir, try from context
+                project = await context.getProjectFromDiscovery();
+            }
+            else if (result.type === 'single') {
+                project = result.project;
+            }
+            else {
+                // Multiple projects - can't auto-detect which one to use
+                throw new Error('Multiple projects found - cannot auto-detect for this file');
+            }
+        }
+    }
+    catch (error) {
+        return errorResponse(`Style check requires project credentials. Run \`dotrequirements link\` to connect to cloud.\n\nError: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Call API endpoint for style checking
+    try {
+        const response = await fetch(`${apiBaseUrl}/api/style-check`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                projectId: project.projectId,
+                projectSecret: project.projectSecret,
+                fileContents: fileContentsToCheck,
+                fileType,
+                model,
+            }),
+        });
+        if (!response.ok) {
+            const errorData = await response.json();
+            return errorResponse(`Style check failed: ${errorData.error || response.statusText}`);
+        }
+        const data = await response.json();
+        const scopeLabel = requirementKeys && requirementKeys.length > 0
+            ? ` (${requirementKeys.join(', ')})`
+            : '';
+        // MCP-REVIEW-1.2: Feedback includes severity categories (in the API response)
+        return textResponse(`# Style Check Results for \`${filePath}\`${scopeLabel}\n\n${data.feedback}${scopeNote}${STYLE_CHECK_GUIDANCE}`);
+    }
+    catch (error) {
+        return errorResponse(`Style check error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Handler for review_test tool
+ *
+ * Requirements covered:
+ * - MCP-REVIEW-2.0: The review validates that test setup matches requirement preconditions
+ * - MCP-REVIEW-2.1: The review validates that test actions match requirement triggers
+ * - MCP-REVIEW-2.2: The review validates that test assertions match requirement outcomes
+ * - MCP-REVIEW-2.3: Feedback identifies requirements without test coverage
+ * - MCP-REVIEW-2.4: Feedback identifies tests that reference non-existent requirements
+ * - MCP-REVIEW-2.5: When cloud credentials are unavailable, an error explains how to authenticate
+ */
+export async function handleReviewTest(args, context, options) {
+    const { testFilePath, projectId } = args;
+    const { apiBaseUrl = 'https://app.dotrequirements.io' } = options ?? {};
+    const fullPath = resolve(context.workspaceRoot, testFilePath);
+    if (!existsSync(fullPath)) {
+        return errorResponse(`File not found: ${testFilePath}`);
+    }
+    // Verify it's a test file
+    const isTestFile = /\.(test|spec)\.(js|jsx|ts|tsx)$/.test(testFilePath);
+    if (!isTestFile) {
+        return errorResponse(`File must be a test file: *.test.{js,jsx,ts,tsx} or *.spec.{js,jsx,ts,tsx}`);
+    }
+    // Read test file contents
+    const testFileContents = readFileSync(fullPath, 'utf-8');
+    // Extract requirement IDs from the test file using regex
+    const requirementIdMatches = testFileContents.matchAll(/requirement\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g);
+    const requirementIds = new Set();
+    for (const match of requirementIdMatches) {
+        requirementIds.add(match[1]);
+    }
+    // MCP-REVIEW-2.5: Get project credentials
+    let project;
+    try {
+        project = await context.getProjectFromDiscovery(projectId);
+    }
+    catch (error) {
+        return errorResponse(`Test review requires a configured dotrequirements project.\n\nError: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Load all requirements for this project
+    const allRequirements = await context.getRequirements(projectId);
+    // Group requirement IDs by their root to avoid sending duplicate trees
+    // e.g., NAV-3.0, NAV-3.1, NAV-3.2 all belong to root NAV-3
+    const rootToTestedIds = new Map();
+    for (const reqId of requirementIds) {
+        const req = allRequirements.find(r => r.id === reqId || r.rootId === reqId);
+        if (req) {
+            if (!rootToTestedIds.has(req.rootId)) {
+                rootToTestedIds.set(req.rootId, new Set());
+            }
+            rootToTestedIds.get(req.rootId).add(reqId);
+        }
+    }
+    // Build requirements array with one entry per unique root tree
+    // MCP-REVIEW-2.0, 2.1, 2.2: These validations happen in the API based on the tree structure
+    const requirements = [];
+    for (const [rootId, testedIds] of rootToTestedIds) {
+        const tree = getRequirementTree(allRequirements, rootId);
+        const formattedTree = formatRequirementTree(tree);
+        requirements.push({
+            id: rootId,
+            content: formattedTree,
+            testedIds: Array.from(testedIds).sort(),
+        });
+    }
+    // Call API endpoint for test review
+    // MCP-REVIEW-2.3 & 2.4: API identifies coverage gaps and non-existent references
+    try {
+        const response = await fetch(`${apiBaseUrl}/api/review-test`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                projectId: project.projectId,
+                projectSecret: project.projectSecret,
+                testFileContents,
+                requirements,
+            }),
+        });
+        if (!response.ok) {
+            const errorData = await response.json();
+            return errorResponse(`Test review failed: ${errorData.error || response.statusText}`);
+        }
+        const data = await response.json();
+        return textResponse(`# Test Review Results for \`${testFilePath}\`\n\n${data.feedback}`);
+    }
+    catch (error) {
+        return errorResponse(`Test review error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=review.js.map

package/dist/mcp/handlers/search.d.ts

@@ -0,0 +1,30 @@
+/**
+ * search_requirements handler
+ *
+ * Searches requirements by text or regex query across IDs, content, and labels.
+ * Returns matching requirements with their full tree context.
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for search_requirements tool
+ */
+export interface SearchRequirementsArgs {
+    query: string;
+    useRegex?: boolean;
+    projectId?: string;
+}
+/**
+ * Handler for search_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-SEARCH-1.0: Query matches requirement ID
+ * - MCP-SEARCH-1.1: Query matches requirement content
+ * - MCP-SEARCH-1.2: Query matches requirement label
+ * - MCP-SEARCH-1.3: useRegex interprets query as case-insensitive regex
+ * - MCP-SEARCH-1.4: Invalid regex returns error
+ * - MCP-SEARCH-1.5: No matches returns informative message
+ * - MCP-SEARCH-1.6: Nested match returns root requirement
+ * - MCP-SEARCH-1.7: Results include full tree as code block
+ */
+export declare function handleSearchRequirements(args: SearchRequirementsArgs, context: HandlerContext): Promise<ToolResponse>;
+//# sourceMappingURL=search.d.ts.map

package/dist/mcp/handlers/search.js

@@ -0,0 +1,60 @@
+/**
+ * search_requirements handler
+ *
+ * Searches requirements by text or regex query across IDs, content, and labels.
+ * Returns matching requirements with their full tree context.
+ */
+import { textResponse, errorResponse } from './types.js';
+import { searchRequirements, getRequirementTree, formatRequirementTree, } from '../requirements.js';
+/**
+ * Handler for search_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-SEARCH-1.0: Query matches requirement ID
+ * - MCP-SEARCH-1.1: Query matches requirement content
+ * - MCP-SEARCH-1.2: Query matches requirement label
+ * - MCP-SEARCH-1.3: useRegex interprets query as case-insensitive regex
+ * - MCP-SEARCH-1.4: Invalid regex returns error
+ * - MCP-SEARCH-1.5: No matches returns informative message
+ * - MCP-SEARCH-1.6: Nested match returns root requirement
+ * - MCP-SEARCH-1.7: Results include full tree as code block
+ */
+export async function handleSearchRequirements(args, context) {
+    const { query, useRegex = false, projectId } = args;
+    const requirements = await context.getRequirements(projectId);
+    let results;
+    if (useRegex) {
+        // MCP-SEARCH-1.3: Interpret query as case-insensitive regex
+        // MCP-SEARCH-1.4: Return error for invalid regex
+        try {
+            const regex = new RegExp(query, 'i');
+            results = requirements.filter((r) => regex.test(r.id) ||
+                regex.test(r.content) ||
+                regex.test(r.label));
+        }
+        catch (error) {
+            return errorResponse(`Invalid regular expression: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    else {
+        // MCP-SEARCH-1.0, MCP-SEARCH-1.1, MCP-SEARCH-1.2: Text search across ID, content, label
+        results = searchRequirements(requirements, query);
+    }
+    // MCP-SEARCH-1.6: Collect unique root IDs from all matches (nested matches bubble up to their root)
+    const matchedRootIds = new Set(results.map((r) => r.rootId));
+    const rootResults = requirements.filter((r) => r.path.length === 0 && matchedRootIds.has(r.rootId));
+    // MCP-SEARCH-1.5: No matches returns informative message
+    if (rootResults.length === 0) {
+        return textResponse(`No requirements found matching "${query}"${useRegex ? ' (regex)' : ''}`);
+    }
+    // MCP-SEARCH-1.7: Each result includes full tree as code block
+    const formatted = rootResults
+        .map((r) => {
+        const tree = getRequirementTree(requirements, r.id);
+        const treeFormatted = formatRequirementTree(tree);
+        return `**${r.id}** (${r.label})\n${r.content}\n_Source: ${r.documentTitle}_\n\n\`\`\`\n${treeFormatted}\n\`\`\``;
+    })
+        .join('\n\n---\n\n');
+    return textResponse(`Found ${rootResults.length} requirement(s) matching "${query}"${useRegex ? ' (regex)' : ''}:\n\n${formatted}`);
+}
+//# sourceMappingURL=search.js.map

package/dist/mcp/handlers/test-mapping.d.ts

@@ -0,0 +1,39 @@
+/**
+ * get_requirements_by_test and get_tests_by_requirement handlers
+ *
+ * Maps between test files and requirements in both directions.
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for get_requirements_by_test tool
+ */
+export interface GetRequirementsByTestArgs {
+    testFile: string;
+    projectId?: string;
+}
+/**
+ * Handler for get_requirements_by_test tool
+ *
+ * Requirements covered:
+ * - MCP-MAP-1.0: The response lists each requirement() call found in the test file
+ * - MCP-MAP-1.1: For each reference, the requirement content and line number are shown
+ * - MCP-MAP-1.2: When the test file does not exist, an error is returned
+ */
+export declare function handleGetRequirementsByTest(args: GetRequirementsByTestArgs, context: HandlerContext): Promise<ToolResponse>;
+/**
+ * Arguments for get_tests_by_requirement tool
+ */
+export interface GetTestsByRequirementArgs {
+    requirementsFile: string;
+    projectId?: string;
+}
+/**
+ * Handler for get_tests_by_requirement tool
+ *
+ * Requirements covered:
+ * - MCP-MAP-2.0: The response lists which requirements have test references
+ * - MCP-MAP-2.1: For each covered requirement, the test file and line number are shown
+ * - MCP-MAP-2.2: Requirements without test references are listed separately
+ */
+export declare function handleGetTestsByRequirement(args: GetTestsByRequirementArgs, context: HandlerContext): Promise<ToolResponse>;
+//# sourceMappingURL=test-mapping.d.ts.map