@popoverai/dotrequirements 0.14.0 → 0.16.0

package/dist/mcp/convexClient.js

@@ -2,7 +2,7 @@ import { getProjectCredentials } from '../utils/project-settings.js';
 /**
  * Production Convex deployment URL
  */
-const CONVEX_URL = 'https://data.dotrequirements.io';
+export const CONVEX_URL = 'https://data.dotrequirements.io';
 /**
  * Load Convex configuration from project settings.
  * Returns null if credentials are not configured.
@@ -47,7 +47,11 @@ export async function getRequirementCoverage(requirementKey, projectId, projectS
     if (!response.ok) {
         throw new Error(`Failed to query coverage: ${response.statusText}`);
     }
-    return await response.json();
+    const json = await response.json();
+    if (json.status === 'error') {
+        throw new Error(`Convex query failed: ${json.errorMessage}`);
+    }
+    return json.value;
 }
 /**
  * Query Convex for project coverage summary
@@ -76,6 +80,50 @@ export async function getProjectCoverage(projectId, projectSecret, convexUrl, op
     if (!response.ok) {
         throw new Error(`Failed to query coverage: ${response.statusText}`);
     }
-    return await response.json();
+    const json = await response.json();
+    if (json.status === 'error') {
+        throw new Error(`Convex query failed: ${json.errorMessage}`);
+    }
+    return json.value;
+}
+/**
+ * PROJ-CONTEXT-7: Query Convex for project context (AI style guidelines)
+ */
+export async function getProjectContext(projectId, projectSecret, convexUrl) {
+    try {
+        const response = await fetch(`${convexUrl}/api/query`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                path: 'projects/queries:get',
+                args: {
+                    projectAuth: {
+                        projectSlug: projectId,
+                        projectSecret,
+                    },
+                    target: {
+                        type: 'project',
+                        slug: projectId,
+                    },
+                },
+                format: 'json',
+            }),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const json = await response.json();
+        if (json.status === 'error' || !json.value) {
+            return null;
+        }
+        return {
+            projectContext: json.value.projectContext ?? null,
+            requirementsStyleContext: json.value.requirementsStyleContext ?? null,
+        };
+    }
+    catch {
+        // Non-fatal: return null if query fails
+        return null;
+    }
 }
 //# sourceMappingURL=convexClient.js.map

package/dist/mcp/index.js

@@ -2,15 +2,18 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { loadAllRequirements, searchRequirements, getRequirementById, getRequirementTree, formatRequirementTree, } from './requirements.js';
+import { loadAllRequirements, searchRequirements, getRequirementById, getRequirementTree, formatRequirementTree, filterRequirementsByKeys, } from './requirements.js';
 import { findAllTestReferences, getReferencedRequirementIds, } from './grep.js';
 import { findTestCodeForRequirement, findFilesWithRequirement, } from './testCodeExtractor.js';
 import { glob } from 'glob';
-import { loadConvexConfig, getRequirementCoverage as queryRequirementCoverage, getProjectCoverage as queryProjectCoverage, } from './convexClient.js';
+import { CONVEX_URL, getRequirementCoverage as queryRequirementCoverage, getProjectCoverage as queryProjectCoverage, getProjectContext, } from './convexClient.js';
 import { discoverProjects, resolveProject, } from '../utils/project-discovery.js';
-import { readFileSync } from 'fs';
+import { getCredentialsFromEnv } from '../utils/project-settings.js';
+import { readFileSync, existsSync } from 'fs';
 import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { dirname, join, resolve, basename } from 'path';
+import { parseFilesForPush, dryRunPush, executePush, } from '../push/index.js';
+import { findRequirementsFiles } from './requirements.js';
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -32,6 +35,9 @@ function getProjectPathsFromEnv() {
 // Get workspace root from environment or default to cwd
 const WORKSPACE_ROOT = process.env.REQUIREMENTS_DIR || process.cwd();
 const PROJECT_PATHS = getProjectPathsFromEnv();
+// Parse --auth-from-env flag for CI/CD environments
+// When set, credentials are read from DOTREQ_PROJECT_ID and DOTREQ_PROJECT_SECRET env vars
+const USE_ENV_AUTH = process.argv.includes('--auth-from-env');
 const STYLE_CHECK_GUIDANCE = `
 
 ---
@@ -57,6 +63,20 @@ async function getRequirements(projectId) {
 }
 async function getProjectFromDiscovery(projectId) {
     const { isConfiguredProject } = await import('../utils/project-discovery.js');
+    // If --auth-from-env flag is set, use credentials from environment variables
+    // This is the explicit opt-in for CI/CD environments
+    if (USE_ENV_AUTH) {
+        const envCredentials = getCredentialsFromEnv();
+        if (!envCredentials) {
+            throw new Error('--auth-from-env flag requires DOTREQ_PROJECT_ID and DOTREQ_PROJECT_SECRET environment variables to be set');
+        }
+        // Return a synthetic project using env credentials and workspace root
+        return {
+            path: WORKSPACE_ROOT,
+            projectId: envCredentials.projectId,
+            projectSecret: envCredentials.projectSecret,
+        };
+    }
     // If we have PROJ_* env vars, use those instead of filesystem discovery
     if (PROJECT_PATHS.size > 0) {
         const projects = [];
@@ -300,7 +320,7 @@ const tools = [
     },
     {
         name: 'style_check',
-        description: 'Check requirements files or test files for style issues and best practices. Uses AI to provide actionable feedback on writing style, clarity, and conventions. Supports requirements files (*.requirements.md) and test files (*.test.*, *.spec.*). Requires project to be linked to cloud (run `dotrequirements link`).',
+        description: 'Check requirements files or test files for style issues and best practices. Uses AI to provide actionable feedback on writing style, clarity, and conventions. Supports requirements files (*.requirements.md) and test files (*.test.*, *.spec.*). For requirements files, you can optionally specify requirement keys to check only those requirements instead of the entire file. Requires project to be linked to cloud (run `dotrequirements link`).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -308,6 +328,11 @@ const tools = [
                     type: 'string',
                     description: 'Path to the file to check (e.g., ".requirements/auth.requirements.md" or "src/auth.test.ts")',
                 },
+                requirementKeys: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional: Array of requirement keys to check (e.g., ["AUTH-1", "AUTH-2"]). Only valid for requirements files (*.requirements.md). When provided, only these requirements are checked instead of the entire file.',
+                },
                 model: {
                     type: 'string',
                     description: 'Optional: AI model to use for style checking (default: "anthropic/claude-haiku-4.5"). Supported models: "anthropic/claude-haiku-4.5", "google/gemini-3-flash"',
@@ -899,19 +924,7 @@ ${projectList || '(none found)'}`,
             case 'get_requirement_coverage': {
                 const { requirementKey, projectId } = args;
                 const project = await getProjectFromDiscovery(projectId);
-                const config = loadConvexConfig(project.path);
-                if (!config) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: 'Coverage queries require project credentials. Run `dotrequirements link` to connect to cloud.',
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                const coverage = await queryRequirementCoverage(requirementKey, config.projectId, config.projectSecret, config.convexUrl);
+                const coverage = await queryRequirementCoverage(requirementKey, project.projectId, project.projectSecret, CONVEX_URL);
                 if (!coverage.lastTestedAt) {
                     return {
                         content: [
@@ -946,19 +959,7 @@ ${projectList || '(none found)'}`,
             case 'get_project_coverage_summary': {
                 const { branch, sinceTimestamp, projectId } = args;
                 const project = await getProjectFromDiscovery(projectId);
-                const config = loadConvexConfig(project.path);
-                if (!config) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: 'Coverage queries require project credentials. Run `dotrequirements link` to connect to cloud.',
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                const coverage = await queryProjectCoverage(config.projectId, config.projectSecret, config.convexUrl, { branch, sinceTimestamp });
+                const coverage = await queryProjectCoverage(project.projectId, project.projectSecret, CONVEX_URL, { branch, sinceTimestamp });
                 const total = coverage.tested.length + coverage.untested.length;
                 const percentage = total > 0 ? ((coverage.tested.length / total) * 100).toFixed(1) : '0.0';
                 let filterInfo = '';
@@ -1055,6 +1056,24 @@ ${projectList || '(none found)'}`,
 
 **Use concise domain prefixes** like \`AUTH-1\`, \`LOGIN-1\`, etc. Start numbering at 1 and increment sequentially.`;
                 }
+                // PROJ-CONTEXT-7: Try to fetch user-provided style context from cloud
+                let userStyleGuidance = '';
+                try {
+                    const project = await getProjectFromDiscovery();
+                    const context = await getProjectContext(project.projectId, project.projectSecret, CONVEX_URL);
+                    if (context?.requirementsStyleContext?.trim()) {
+                        userStyleGuidance = `
+
+## User-Provided Style Guidelines
+
+The following style guidelines were provided by the project owner. When these conflict with the defaults above, prioritize the user's guidelines.
+
+${context.requirementsStyleContext.trim()}`;
+                    }
+                }
+                catch {
+                    // No credentials or cloud unavailable - continue without user context
+                }
                 const template = `---
 document:
   title: "Example Requirements"
@@ -1150,6 +1169,7 @@ ${labelGuidance}
 - Note: Even technical requirements can be user-centric: "95 percent of users experience under 1 second of delay"
 
 **11. Decompose Large Requirements**: If it can't be validated with a single test, break it down.
+${userStyleGuidance}
 
 ## Example Requirements
 
@@ -1282,33 +1302,13 @@ describe(requirement('AUTH-LOGIN-1'), () => {
             }
             case 'push_requirements': {
                 const { filePath, confirmed = false, projectId: projectIdParam } = args;
-                const fs = await import('fs');
-                const path = await import('path');
-                const { parseRequirementsFromFile, getAllRequirements } = await import('../schema/index.js');
-                const { ConvexHttpClient } = await import('convex/browser');
-                // Get project
+                // Get project (credentials come from project object, works with both file and env auth)
                 const project = await getProjectFromDiscovery(projectIdParam);
-                const config = loadConvexConfig(project.path);
-                if (!config) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: 'Push requires project credentials. Run `dotrequirements link` to connect to cloud.',
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                const convexUrl = config.convexUrl;
-                const projectId = config.projectId;
-                const projectSecret = config.projectSecret;
                 // Determine files to push
-                const requirementsDir = path.resolve(project.path, '.requirements');
                 let filesToPush;
                 if (filePath) {
-                    const fullPath = path.resolve(project.path, filePath);
-                    if (!fs.existsSync(fullPath)) {
+                    const fullPath = resolve(project.path, filePath);
+                    if (!existsSync(fullPath)) {
                         return {
                             content: [
                                 {
@@ -1322,78 +1322,121 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                     filesToPush = [fullPath];
                 }
                 else {
-                    if (!fs.existsSync(requirementsDir)) {
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: 'No .requirements/ directory found',
-                                },
-                            ],
-                            isError: true,
-                        };
-                    }
-                    const files = fs.readdirSync(requirementsDir);
-                    filesToPush = files
-                        .filter((f) => f.endsWith('.requirements.md'))
-                        .map((f) => path.join(requirementsDir, f));
+                    // Use same file discovery as CLI - searches entire workspace
+                    filesToPush = await findRequirementsFiles(project.path);
                     if (filesToPush.length === 0) {
                         return {
                             content: [
                                 {
                                     type: 'text',
-                                    text: 'No Markdown files (*.requirements.md) found in .requirements/',
+                                    text: 'No *.requirements.md files found. Nothing to push.',
                                 },
                             ],
-                            isError: true,
                         };
                     }
                 }
-                // Parse local requirements
-                const allLocalRequirements = [];
-                for (const file of filesToPush) {
-                    const parsed = parseRequirementsFromFile(file);
-                    const flatReqs = getAllRequirements(parsed.requirements);
-                    for (const req of flatReqs) {
-                        allLocalRequirements.push({
-                            key: req.id,
-                            label: req.label,
-                            content: req.content,
-                            rootId: req.metadata?.rootId,
-                            position: req.metadata?.position,
-                        });
-                    }
+                // 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,
+                    };
                 }
                 if (!confirmed) {
-                    // First call: show diff
-                    const client = new ConvexHttpClient(convexUrl);
-                    // Note: We need a public query to fetch requirements
-                    // For now, just show what would be pushed
+                    // First call: show preview with real dry run results
+                    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 {
                         content: [
                             {
                                 type: 'text',
-                                text: `# Push Preview\n\n**Files:** ${filesToPush.length}\n**Requirements:** ${allLocalRequirements.length}\n\n**Requirements to push:**\n${allLocalRequirements.map((r) => `- ${r.key}: ${r.label} → ${r.content}`).join('\n')}\n\n⚠️ This will **replace all** requirements in the project.\n\n**To proceed:** Call this tool again with \`confirmed: true\``,
+                                text: summary,
                             },
                         ],
                     };
                 }
                 // Second call: execute push
-                const client = new ConvexHttpClient(convexUrl);
                 try {
-                    const result = await client.mutation('requirements/mutations:bulkReplace', {
-                        projectAuth: {
-                            projectSlug: projectId,
-                            projectSecret,
-                        },
-                        target: { type: 'project', slug: projectId },
-                        requirements: allLocalRequirements,
-                    });
+                    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 {
                         content: [
                             {
                                 type: 'text',
-                                text: `✓ Push complete!\n\n**Inserted:** ${result.inserted}\n**Deleted:** ${result.deleted}`,
+                                text: output,
                             },
                         ],
                     };
@@ -1411,7 +1454,7 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                 }
             }
             case 'style_check': {
-                const { filePath, model } = args;
+                const { filePath, model, requirementKeys } = args;
                 const fs = await import('fs');
                 const path = await import('path');
                 const fullPath = path.resolve(WORKSPACE_ROOT, filePath);
@@ -1443,22 +1486,73 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                     };
                 }
                 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 {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `requirementKeys can only be used with requirements files (*.requirements.md), not test files.`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    try {
+                        const { filteredContent, foundKeys, missingKeys } = filterRequirementsByKeys(fileContents, requirementKeys);
+                        if (foundKeys.length === 0) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: `None of the specified requirement keys were found in ${filePath}: ${requirementKeys.join(', ')}`,
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        fileContentsToCheck = filteredContent;
+                        if (missingKeys.length > 0) {
+                            scopeNote = `\n\n> **Note:** Some specified keys were not found in the file: ${missingKeys.join(', ')}`;
+                        }
+                    }
+                    catch (error) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Failed to filter requirements: ${error instanceof Error ? error.message : String(error)}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
                 // Get Convex config for credentials - walk up from file's directory to find project
                 const fileDir = path.dirname(fullPath);
                 let project;
                 try {
-                    // 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 WORKSPACE_ROOT
+                    // If using env auth, go straight to getProjectFromDiscovery (handles env credentials)
+                    if (USE_ENV_AUTH) {
                         project = await 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');
+                        // 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 WORKSPACE_ROOT
+                            project = await 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) {
@@ -1472,18 +1566,8 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                         isError: true,
                     };
                 }
-                const config = loadConvexConfig(project.path);
-                if (!config) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: 'Style check requires project credentials. Run `dotrequirements link` to connect to cloud.',
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
+                // Use credentials from project (works with both file-based and env-based auth)
+                const { projectId: projId, projectSecret: projSecret } = project;
                 // Call Vercel API endpoint for style checking
                 // Default to production, allow override via env var for local dev
                 const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL || 'https://app.dotrequirements.io';
@@ -1494,9 +1578,9 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                             'Content-Type': 'application/json',
                         },
                         body: JSON.stringify({
-                            projectId: config.projectId,
-                            projectSecret: config.projectSecret,
-                            fileContents,
+                            projectId: projId,
+                            projectSecret: projSecret,
+                            fileContents: fileContentsToCheck,
                             fileType,
                             model,
                         }),
@@ -1514,11 +1598,14 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                         };
                     }
                     const data = await response.json();
+                    const scopeLabel = requirementKeys && requirementKeys.length > 0
+                        ? ` (${requirementKeys.join(', ')})`
+                        : '';
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: `# Style Check Results for \`${filePath}\`\n\n${data.feedback}${STYLE_CHECK_GUIDANCE}`,
+                                text: `# Style Check Results for \`${filePath}\`${scopeLabel}\n\n${data.feedback}${scopeNote}${STYLE_CHECK_GUIDANCE}`,
                             },
                         ],
                     };
@@ -1614,18 +1701,8 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                     });
                 }
                 // Get Convex config
-                const config = loadConvexConfig(project.path);
-                if (!config) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: 'Test review requires project credentials. Run `dotrequirements link` to connect to cloud.',
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
+                // Use credentials from project (works with both file-based and env-based auth)
+                const { projectId: projId, projectSecret: projSecret } = project;
                 // Call Vercel API endpoint for test review
                 // Default to production, allow override via env var for local dev
                 const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL || 'https://app.dotrequirements.io';
@@ -1636,8 +1713,8 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                             'Content-Type': 'application/json',
                         },
                         body: JSON.stringify({
-                            projectId: config.projectId,
-                            projectSecret: config.projectSecret,
+                            projectId: projId,
+                            projectSecret: projSecret,
                             testFileContents,
                             requirements,
                         }),

package/dist/mcp/requirements.d.ts

@@ -40,6 +40,16 @@ export declare function getRequirementTree(requirements: FlattenedRequirement[],
  * Format a requirement for display
  */
 export declare function formatRequirement(req: FlattenedRequirement): string;
+/**
+ * Filter a requirements file's content to only include specified requirement keys.
+ * Parses the file content, filters top-level requirements by key, and rebuilds as
+ * markdown requirement blocks (without frontmatter).
+ */
+export declare function filterRequirementsByKeys(fileContents: string, keys: string[]): {
+    filteredContent: string;
+    foundKeys: string[];
+    missingKeys: string[];
+};
 /**
  * Format a requirement tree for display
  */

package/dist/mcp/requirements.js

@@ -1,6 +1,6 @@
 import * as path from 'path';
 import { glob } from 'glob';
-import { parseRequirementsFromFile, getAllRequirements, } from '../schema/index.js';
+import { parseRequirementsFromFile, parseRequirementsFile, buildRequirementMarkdown, getAllRequirements, } from '../schema/index.js';
 /**
  * Find all *.requirements.md files in the workspace.
  * Supports both .requirements/ directories and colocated files.
@@ -114,6 +114,20 @@ export function formatRequirement(req) {
     const label = req.label ? ` (${req.label})` : '';
     return `${indent}${req.id}${label}: ${req.content}`;
 }
+/**
+ * Filter a requirements file's content to only include specified requirement keys.
+ * Parses the file content, filters top-level requirements by key, and rebuilds as
+ * markdown requirement blocks (without frontmatter).
+ */
+export function filterRequirementsByKeys(fileContents, keys) {
+    const { requirements } = parseRequirementsFile(fileContents);
+    const upperKeys = keys.map(k => k.toUpperCase());
+    const filtered = requirements.filter(r => upperKeys.includes(r.id.toUpperCase()));
+    const foundKeys = filtered.map(r => r.id);
+    const missingKeys = upperKeys.filter(k => !foundKeys.map(f => f.toUpperCase()).includes(k));
+    const filteredContent = filtered.map(buildRequirementMarkdown).join('\n');
+    return { filteredContent, foundKeys, missingKeys };
+}
 /**
  * Format a requirement tree for display
  */