@popoverai/dotrequirements 0.16.0 → 0.17.0

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

@@ -0,0 +1,41 @@
+/**
+ * Authoring handlers for MCP tools
+ *
+ * Provides document creation and validation:
+ * - create_requirement_document: Generate requirements template with format guidance
+ * - validate_requirements: Validate requirements file syntax offline
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for create_requirement_document tool
+ */
+export interface CreateRequirementDocumentArgs {
+    filePath?: string;
+}
+/**
+ * Arguments for validate_requirements tool
+ */
+export interface ValidateRequirementsArgs {
+    filePath: string;
+}
+/**
+ * Handler for create_requirement_document tool
+ *
+ * Requirements covered:
+ * - MCP-AUTHOR-1.0: The template includes format guidance with code block examples
+ * - MCP-AUTHOR-1.1: The template includes guidance on concrete examples, concise prose, and testable conditions
+ * - MCP-AUTHOR-1.2: When the project has requirementsStyleContext configured, it is included in the template
+ * - MCP-AUTHOR-1.3: When cloud credentials are unavailable, the template works without the custom context
+ */
+export declare function handleCreateRequirementDocument(args: CreateRequirementDocumentArgs, context: HandlerContext): Promise<ToolResponse>;
+/**
+ * Handler for validate_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-AUTHOR-2.0: When the file has valid syntax, the response confirms validation passed
+ * - MCP-AUTHOR-2.1: When the file has syntax errors, the response lists each error with location
+ * - MCP-AUTHOR-2.2: Validation does not require network access or cloud credentials
+ * - MCP-AUTHOR-2.3: When the file does not exist, an error is returned
+ */
+export declare function handleValidateRequirements(args: ValidateRequirementsArgs, context: HandlerContext): Promise<ToolResponse>;
+//# sourceMappingURL=authoring.d.ts.map

package/dist/mcp/handlers/authoring.js

@@ -0,0 +1,308 @@
+/**
+ * Authoring handlers for MCP tools
+ *
+ * Provides document creation and validation:
+ * - create_requirement_document: Generate requirements template with format guidance
+ * - validate_requirements: Validate requirements file syntax offline
+ */
+import { textResponse, errorResponse } from './types.js';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { parseRequirementsFromFile, validateForPush } from '../../schema/index.js';
+import { CONVEX_URL, getProjectContext, } from '../convexClient.js';
+/**
+ * Handler for create_requirement_document tool
+ *
+ * Requirements covered:
+ * - MCP-AUTHOR-1.0: The template includes format guidance with code block examples
+ * - MCP-AUTHOR-1.1: The template includes guidance on concrete examples, concise prose, and testable conditions
+ * - MCP-AUTHOR-1.2: When the project has requirementsStyleContext configured, it is included in the template
+ * - MCP-AUTHOR-1.3: When cloud credentials are unavailable, the template works without the custom context
+ */
+export async function handleCreateRequirementDocument(args, context) {
+    const { filePath = '.requirements/example.requirements.md' } = args;
+    // Discover existing label and key patterns in the codebase
+    // Try to get requirements, but don't fail if no project is configured
+    let requirements = [];
+    try {
+        requirements = await context.getRequirements();
+    }
+    catch {
+        // MCP-AUTHOR-1.3: No project configured - that's okay, we'll just not have discovered patterns
+    }
+    const labels = new Set();
+    const keyPrefixes = new Set();
+    for (const req of requirements) {
+        // Collect labels (empty string means unlabeled, so skip those)
+        if (req.label && req.label.trim()) {
+            labels.add(req.label);
+        }
+        // Collect requirement key prefixes (root IDs only)
+        // Extract prefix from keys like "AUTH-1" -> "AUTH", "LOGIN-FLOW-2" -> "LOGIN-FLOW"
+        if (req.path.length === 0 && req.id) {
+            const lastDashIndex = req.id.lastIndexOf('-');
+            if (lastDashIndex > 0) {
+                const prefix = req.id.substring(0, lastDashIndex);
+                keyPrefixes.add(prefix);
+            }
+        }
+    }
+    const discoveredLabels = Array.from(labels).sort();
+    const discoveredPrefixes = Array.from(keyPrefixes).sort();
+    let labelGuidance = '';
+    let keyGuidance = '';
+    // Generate label guidance
+    if (discoveredLabels.length > 0) {
+        const labelList = discoveredLabels.slice(0, 10).map(l => `"${l}"`).join(', ');
+        const more = discoveredLabels.length > 10 ? ` (and ${discoveredLabels.length - 10} more)` : '';
+        labelGuidance = `**Existing labels in this codebase:** ${labelList}${more}
+
+**Use these existing labels** to maintain consistency. If you're unsure which labels to use for a new requirement, ask the user.`;
+    }
+    else {
+        labelGuidance = `**No existing requirements found in this codebase.**
+
+**Default to unlabeled requirements** (\`0. → content\`). If the user wants labels, ask them which format they prefer. Do not choose an opinionated framework like Given/When/Then without explicit user consent.`;
+    }
+    // Generate key guidance
+    if (discoveredPrefixes.length > 0) {
+        const prefixList = discoveredPrefixes.map(p => `"${p}"`).join(', ');
+        keyGuidance = `**Existing requirement key prefixes in this codebase:** ${prefixList}
+
+**Match the existing pattern** when creating new requirement keys. Use the same domain prefixes and sequential numbering style.`;
+    }
+    else {
+        keyGuidance = `**No existing requirements found in this codebase.**
+
+**Use concise domain prefixes** like \`AUTH-1\`, \`LOGIN-1\`, etc. Start numbering at 1 and increment sequentially.`;
+    }
+    // MCP-AUTHOR-1.2: Try to fetch user-provided style context from cloud
+    let userStyleGuidance = '';
+    try {
+        const project = await context.getProjectFromDiscovery();
+        const contextData = await getProjectContext(project.projectId, project.projectSecret, CONVEX_URL);
+        if (contextData?.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.
+
+${contextData.requirementsStyleContext.trim()}`;
+        }
+    }
+    catch {
+        // MCP-AUTHOR-1.3: No credentials or cloud unavailable - continue without user context
+    }
+    // MCP-AUTHOR-1.0: Template with format guidance and code block examples
+    // MCP-AUTHOR-1.1: Template includes style principles (concrete examples, concise prose, testable conditions)
+    const template = `---
+document:
+  title: "Example Requirements"
+---
+
+# Example Requirements
+
+This template demonstrates the dotrequirements Markdown format and style guidelines.
+
+## Syntax Overview
+
+**File naming:** Use \`*.requirements.md\` pattern (colocated: \`auth.requirements.md\` or centralized: \`.requirements/auth.requirements.md\`)
+
+**Block format:**
+\`\`\`dotrequirements
+KEY: Root requirement content
+  0. → First criterion (unlabeled)
+  1. Label → Second criterion (with label)
+    1.0. → Nested criterion (unlabeled)
+\`\`\`
+
+- First line: \`KEY: content\` (requirement key and description)
+- Criteria: \`position. Label → content\` or \`position. → content\` (unlabeled)
+- Position: \`0\`, \`1\`, \`2\` (top-level) or \`0.0\`, \`1.0\` (nested) - defines hierarchy
+- Delimiter: \`→\` or \`->\` separates optional label from content
+
+## Requirement Keys: Concise and Sequential
+
+${keyGuidance}
+
+**Key format:** \`DOMAIN-FEATURE-N\` where N is sequential (1, 2, 3...)
+
+**Best practices:**
+1. **Concise domains** - Use short, clear prefixes
+   - ✅ \`AUTHZ-1\` (authorization)
+   - ✅ \`AUTH-1\` (authentication)
+   - ❌ \`AUTHORIZATION-1\` (too verbose)
+   - ❌ \`REQ-IDENTITY-ACCESS-AUTHZ-1\` (too nested)
+
+2. **Sequential, 1-indexed numbering** - Start at 1, no padding
+   - ✅ \`LOGIN-1\`, \`LOGIN-2\`, \`LOGIN-3\`
+   - ❌ \`LOGIN-0\` (don't use 0-indexing for requirement IDs)
+   - ❌ \`LOGIN-001\` (no zero-padding)
+
+3. **Unique across project** - Each key must be unique in the entire project
+
+4. **Match existing patterns** - Check existing requirements first and follow their convention
+
+## Labels: Match Your Codebase or Ask the User
+
+${labelGuidance}
+
+## Style Principles for Requirements
+
+**1. Use Concrete Examples**: Replace vague language with specific, testable conditions.
+- ❌ "users can log in" or "works properly"
+- ✅ "When a registered user provides valid credentials, they are authenticated"
+
+**2. Write Natural, Concise Prose**: Avoid terseness and verbosity. Use declarative style (not "should").
+- ❌ "registered user with valid credentials is authenticated" (too terse)
+- ❌ "A registered user, whose account was created on Tuesday and whose life story is as follows..." (too verbose)
+- ✅ "When a registered user provides valid credentials, they are authenticated"
+
+**3. Keep Arrange/Act/Assert in Mind**: Well-written requirements describe preconditions, trigger, and result.
+- ✅ "When [preconditions:] a registered user [trigger:] provides valid credentials, [result:] they are authenticated"
+
+**4. Be Framework Neutral**: Don't prescribe Given/When/Then vs AC vs other formats - focus on content quality.
+
+**5. Use Named Personas**: Establish personas in parent requirements, reuse in children.
+- ✅ Parent: "A registered user, Jamie, can log in normally" → Child: "When Jamie provides valid credentials, they are authenticated"
+
+**6. Use User-Centric Language**: Describe user experience, not technical internals.
+- ❌ "they are redirected to app.dotrequirements.io/redirect/dashboard"
+- ✅ "they are automatically brought to the dashboard"
+
+**7. Single Action Per Requirement**: Don't chain multiple actions with "and then".
+- ❌ "When Robin provides credentials, requests an OTP, then provides the OTP..."
+- ✅ Break into separate requirements for each action
+
+**8. Each Requirement Should Be Independent**: Requirements within a block should be independently testable. If they share preconditions or form a sequence, either nest them or restate context.
+- ❌ "0. → When Jordan submits signup, an account is created" / "1. → Welcome email is sent" / "2. → Dashboard appears"
+- ✅ Option A: Restate context - "1. → When Jordan submits signup, a welcome email is sent"
+- ✅ Option B: Use nesting - "0. When → Jordan submits signup" / "  0.0. Then → an account is created"
+- Test: Can you understand what's being tested by reading just one requirement, or do you need to read its siblings?
+
+**9. Focus on Behavior, Not Design**: Describe what happens, not UI specifics.
+- ❌ "enters valid credentials into two single-line input fields and presses a green button"
+- ✅ "provides valid credentials"
+
+**10. Focus on Outcomes, Not Implementation**: User perspective, even for technical requirements.
+- ❌ "When the app requests that Twilio send Casey an OTP from /email/POST endpoint..."
+- ✅ "When Casey requests an email OTP..."
+- 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
+
+**Unlabeled (recommended default):**
+\`\`\`dotrequirements
+AUTH-LOGIN-1: A registered user, Jamie, can log in to their account
+  0. → When Jamie provides their registered email and correct password, they are authenticated and brought to their dashboard
+  1. → When Jamie provides an incorrect password, they see an error message and remain on the login page
+  2. → When Jamie's account has been deactivated, they see a message explaining their account status
+\`\`\`
+
+**With labels (example only - DO NOT use opinionated formats like Given/When/Then without asking the user first):**
+\`\`\`dotrequirements
+PAYMENT-REFUND-1: A customer, Alex, receives a refund after returning an item
+  0. Given → Alex purchased a laptop from the store 10 days ago
+  1. Given → Alex initiates a return through their order history
+  2. When → Alex's returned laptop is received and inspected at the warehouse
+  3. Then → Alex receives a refund to their original payment method within 5 business days
+  4. Then → Alex receives an email confirmation with the refund amount and expected timeline
+\`\`\`
+
+## Referencing Requirements in Tests
+
+**Use \`requirement()\` as the test description** - it returns a string:
+
+\`\`\`typescript
+import { describe, it, expect } from 'vitest';
+import { requirement } from '@popoverai/dotrequirements/test';
+
+describe(requirement('AUTH-LOGIN-1'), () => {
+  describe(requirement('AUTH-LOGIN-1.given'), () => {
+    // Arrange: Create Jamie's account
+  });
+
+  describe(requirement('AUTH-LOGIN-1.when'), () => {
+    // Act: Submit login with valid credentials
+
+    it(requirement('AUTH-LOGIN-1.then'), () => {
+      // Assert: Jamie is authenticated
+    });
+  });
+});
+\`\`\`
+
+**Test Style Principles:**
+
+**1. Use requirement() AS the description**: Don't put requirement() inside test body or in comments.
+- ✅ \`test(requirement('AUTH-LOGIN-1'), () => { /* test code */ })\`
+- ✅ \`it(requirement('LOGIN-1.then'), () => { /* assert */ })\`
+- ❌ \`test("user can log in", () => { requirement('AUTH-LOGIN-1'); /* test code */ })\`
+- ❌ \`// LOGIN-1: User can log in\` (comment instead of using requirement() as description)
+
+**2. Comments describe the TEST, not the requirement**: Don't copy requirement text verbatim.
+- ✅ \`describe(requirement('REQ-1.0'), () => { // registered user, valid credentials\`
+- ❌ \`describe(requirement('REQ-1.0'), () => { // 0. When a registered user provides valid credentials, they are authenticated\` (verbatim copy is a red flag)
+- Note: Comments should reflect what the test actually does, not just repeat what the requirement says
+
+**3. Structure tests to match requirements**: Nest describe/it blocks for structured requirements.
+- ✅ For structured requirements: \`describe(requirement('LOGIN-1.given'))\` nested with \`describe(requirement('LOGIN-1.when'))\` and \`it(requirement('LOGIN-1.then'))\`
+- ✅ For simple requirements: \`test(requirement('AUTH-LOGIN-1'), () => { /* arrange, act, assert all in one */ })\`
+
+**Path formats:**
+- \`requirement('AUTH-LOGIN-1')\` - root requirement
+- \`requirement('AUTH-LOGIN-1.0')\` - by numeric position
+- \`requirement('AUTH-LOGIN-1.given')\` - by label (case-insensitive)
+- \`requirement('AUTH-LOGIN-1.given#1')\` - disambiguate duplicate labels`;
+    return textResponse(`# Requirements File Template\n\nHere's a comprehensive template for \`${filePath}\` with format and style guidance:\n\n\`\`\`markdown\n${template}\`\`\`\n\n## Next Steps\n\n1. **Create file**: Use Write tool to create \`${filePath}\` based on this template\n2. **Refine style** (optional): Call \`style_check\` for AI feedback on style and best practices\n3. **Validate syntax**: Call \`validate_requirements\` to verify format is correct\n4. **Push to Convex**: Call \`push_requirements\` to sync requirements to data layer\n\n**Note**: Requirements files can be colocated with code (\`src/auth.requirements.md\`) or centralized in \`.requirements/\` directory.`);
+}
+/**
+ * Handler for validate_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-AUTHOR-2.0: When the file has valid syntax, the response confirms validation passed
+ * - MCP-AUTHOR-2.1: When the file has syntax errors, the response lists each error with location
+ * - MCP-AUTHOR-2.2: Validation does not require network access or cloud credentials
+ * - MCP-AUTHOR-2.3: When the file does not exist, an error is returned
+ */
+export async function handleValidateRequirements(args, context) {
+    const { filePath } = args;
+    // MCP-AUTHOR-2.2: Validation works offline - just use workspaceRoot
+    const fullPath = resolve(context.workspaceRoot, filePath);
+    // MCP-AUTHOR-2.3: Check if file exists
+    if (!existsSync(fullPath)) {
+        return errorResponse(`File not found: ${filePath}`);
+    }
+    try {
+        // MCP-AUTHOR-2.0 & MCP-AUTHOR-2.1: Parse and validate
+        const parsed = parseRequirementsFromFile(fullPath);
+        const reqCount = Object.keys(parsed.requirements).length;
+        // Check push readiness
+        const pushValidation = validateForPush(parsed.metadata);
+        let headline;
+        let pushDetails = '';
+        if (!pushValidation.valid) {
+            headline = `❌ \`${filePath}\` - Not push-ready\n- ${pushValidation.reason}`;
+        }
+        else {
+            const actionLabel = pushValidation.action === 'create' ? 'Will create new document' : 'Will update existing document';
+            headline = `✓ \`${filePath}\` - ${actionLabel}`;
+            if (pushValidation.warning) {
+                pushDetails = `\n- ⚠️ ${pushValidation.warning}`;
+            }
+        }
+        return textResponse(`${headline}${pushDetails}\n\n**Metadata:**\n- Version: ${parsed.metadata.version ?? '(none)'}\n- Document: ${parsed.metadata.document?.title || '(none)'}\n- Document ID: ${parsed.metadata.document?.id || '(none)'}\n\n**Requirements:** ${reqCount} root requirement(s) found`);
+    }
+    catch (error) {
+        // MCP-AUTHOR-2.1: Syntax errors are returned with details
+        return {
+            content: [{ type: 'text', text: `✗ Validation failed for \`${filePath}\`:\n\n${error instanceof Error ? error.message : String(error)}` }],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=authoring.js.map

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

@@ -0,0 +1,44 @@
+/**
+ * Coverage handlers for MCP tools
+ *
+ * Provides cloud coverage query functionality:
+ * - get_requirement_coverage: Coverage for a specific requirement
+ * - get_project_coverage_summary: Project-wide coverage summary
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for get_requirement_coverage tool
+ */
+export interface GetRequirementCoverageArgs {
+    requirementKey: string;
+    projectId?: string;
+}
+/**
+ * Arguments for get_project_coverage_summary tool
+ */
+export interface GetProjectCoverageSummaryArgs {
+    branch?: string;
+    sinceTimestamp?: number;
+    projectId?: string;
+}
+/**
+ * Handler for get_requirement_coverage tool
+ *
+ * Requirements covered:
+ * - MCP-COVERAGE-1.0: When credentials are valid, the response shows when the requirement was last tested
+ * - MCP-COVERAGE-1.1: The response includes the most recent branch and test file where coverage was recorded
+ * - MCP-COVERAGE-1.2: When the requirement has no coverage records, the response indicates this
+ * - MCP-COVERAGE-1.3: When credentials are missing or invalid, an error explains how to authenticate
+ */
+export declare function handleGetRequirementCoverage(args: GetRequirementCoverageArgs, context: HandlerContext): Promise<ToolResponse>;
+/**
+ * Handler for get_project_coverage_summary tool
+ *
+ * Requirements covered:
+ * - MCP-COVERAGE-2.0: The response summarizes which requirements have been tested and which have not
+ * - MCP-COVERAGE-2.1: When a branch filter is provided, coverage results include only records from that branch
+ * - MCP-COVERAGE-2.2: When sinceTimestamp is provided, only coverage recorded after that time is included
+ * - MCP-COVERAGE-2.3: When credentials are missing or invalid, an error explains how to authenticate
+ */
+export declare function handleGetProjectCoverageSummary(args: GetProjectCoverageSummaryArgs, context: HandlerContext): Promise<ToolResponse>;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/mcp/handlers/coverage.js

@@ -0,0 +1,105 @@
+/**
+ * Coverage handlers for MCP tools
+ *
+ * Provides cloud coverage query functionality:
+ * - get_requirement_coverage: Coverage for a specific requirement
+ * - get_project_coverage_summary: Project-wide coverage summary
+ */
+import { textResponse, errorResponse } from './types.js';
+import { CONVEX_URL, getRequirementCoverage as queryRequirementCoverage, getProjectCoverage as queryProjectCoverage, } from '../convexClient.js';
+/**
+ * Handler for get_requirement_coverage tool
+ *
+ * Requirements covered:
+ * - MCP-COVERAGE-1.0: When credentials are valid, the response shows when the requirement was last tested
+ * - MCP-COVERAGE-1.1: The response includes the most recent branch and test file where coverage was recorded
+ * - MCP-COVERAGE-1.2: When the requirement has no coverage records, the response indicates this
+ * - MCP-COVERAGE-1.3: When credentials are missing or invalid, an error explains how to authenticate
+ */
+export async function handleGetRequirementCoverage(args, context) {
+    const { requirementKey, projectId } = args;
+    // MCP-COVERAGE-1.3: Get project credentials (throws if not configured)
+    let project;
+    try {
+        project = await context.getProjectFromDiscovery(projectId);
+    }
+    catch (error) {
+        return errorResponse(`Coverage query requires project credentials. Run \`dotrequirements link\` to connect to cloud.\n\nError: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Query cloud for coverage
+    const coverage = await queryRequirementCoverage(requirementKey, project.projectId, project.projectSecret, CONVEX_URL);
+    // MCP-COVERAGE-1.2: No coverage records
+    if (!coverage.lastTestedAt) {
+        return textResponse(`**${requirementKey}** has not been tested yet.`);
+    }
+    // MCP-COVERAGE-1.0: Show when requirement was last tested
+    const lastTested = new Date(coverage.lastTestedAt);
+    // MCP-COVERAGE-1.1: Include branch and test file
+    const testLocation = coverage.testFile
+        ? `\n**Test Location:** \`${coverage.testFile}${coverage.testLine ? `:${coverage.testLine}` : ''}\``
+        : '';
+    let branchInfo = `\n**Branch:** ${coverage.branch}`;
+    if (coverage.allBranches.length > 1) {
+        const otherBranches = coverage.allBranches
+            .filter((b) => b.branch !== coverage.branch)
+            .map((b) => `- ${b.branch}: ${new Date(b.lastTestedAt).toISOString()}`)
+            .join('\n');
+        branchInfo += `\n\n**Also tested on:**\n${otherBranches}`;
+    }
+    return textResponse(`# Coverage for ${requirementKey}\n\n**Last Tested:** ${lastTested.toISOString()}${branchInfo}${testLocation}`);
+}
+/**
+ * Handler for get_project_coverage_summary tool
+ *
+ * Requirements covered:
+ * - MCP-COVERAGE-2.0: The response summarizes which requirements have been tested and which have not
+ * - MCP-COVERAGE-2.1: When a branch filter is provided, coverage results include only records from that branch
+ * - MCP-COVERAGE-2.2: When sinceTimestamp is provided, only coverage recorded after that time is included
+ * - MCP-COVERAGE-2.3: When credentials are missing or invalid, an error explains how to authenticate
+ */
+export async function handleGetProjectCoverageSummary(args, context) {
+    const { branch, sinceTimestamp, projectId } = args;
+    // MCP-COVERAGE-2.3: Get project credentials (throws if not configured)
+    let project;
+    try {
+        project = await context.getProjectFromDiscovery(projectId);
+    }
+    catch (error) {
+        return errorResponse(`Coverage query requires project credentials. Run \`dotrequirements link\` to connect to cloud.\n\nError: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Query cloud for project coverage with optional filters
+    const coverage = await queryProjectCoverage(project.projectId, project.projectSecret, CONVEX_URL, { branch, sinceTimestamp });
+    // MCP-COVERAGE-2.0: Calculate and display coverage summary
+    const total = coverage.tested.length + coverage.untested.length;
+    const percentage = total > 0 ? ((coverage.tested.length / total) * 100).toFixed(1) : '0.0';
+    // MCP-COVERAGE-2.1 & MCP-COVERAGE-2.2: Show filter info if provided
+    let filterInfo = '';
+    if (branch) {
+        filterInfo += `\n**Branch:** ${branch}`;
+    }
+    if (sinceTimestamp) {
+        filterInfo += `\n**Since:** ${new Date(sinceTimestamp).toISOString()}`;
+    }
+    let testedSection = '';
+    if (coverage.tested.length > 0) {
+        const testedList = coverage.tested
+            .map((t) => {
+            const date = new Date(t.lastTestedAt).toISOString();
+            const location = t.testFile
+                ? ` (\`${t.testFile}${t.testLine ? `:${t.testLine}` : ''}\`)`
+                : '';
+            return `- **${t.requirementKey}** [${t.branch}]: ${date}${location}`;
+        })
+            .join('\n');
+        testedSection = `\n\n## Tested Requirements (${coverage.tested.length})\n\n${testedList}`;
+    }
+    let untestedSection = '';
+    if (coverage.untested.length > 0) {
+        const untestedList = coverage.untested
+            .map((key) => `- ${key}`)
+            .join('\n');
+        untestedSection = `\n\n## Untested Requirements (${coverage.untested.length})\n\n${untestedList}`;
+    }
+    return textResponse(`# Project Coverage Summary\n\n**Total Requirements:** ${total}\n**Coverage:** ${percentage}%${filterInfo}${testedSection}${untestedSection}`);
+}
+//# sourceMappingURL=coverage.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * debug_mcp_environment handler
+ *
+ * Returns diagnostic information about the MCP server environment.
+ * Useful for debugging configuration issues.
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for debug_mcp_environment tool
+ */
+export interface DebugMcpEnvironmentArgs {
+}
+/**
+ * Handler for debug_mcp_environment tool
+ */
+export declare function handleDebugMcpEnvironment(_args: DebugMcpEnvironmentArgs, context: HandlerContext): Promise<ToolResponse>;
+//# sourceMappingURL=debug.d.ts.map

package/dist/mcp/handlers/debug.js

@@ -0,0 +1,37 @@
+/**
+ * debug_mcp_environment handler
+ *
+ * Returns diagnostic information about the MCP server environment.
+ * Useful for debugging configuration issues.
+ */
+import { textResponse } from './types.js';
+/**
+ * Handler for debug_mcp_environment tool
+ */
+export async function handleDebugMcpEnvironment(_args, context) {
+    // Check for Antigravity-specific env vars
+    const antigravityVars = Object.entries(context.env)
+        .filter(([key]) => key.startsWith('GEMINI_') || key.startsWith('ANTIGRAVITY_'))
+        .map(([key, value]) => `  ${key}: ${value}`)
+        .join('\n');
+    // Show discovered projects from env vars
+    const projectList = Array.from(context.projectPaths.entries())
+        .map(([id, path]) => `  ${id}: ${path}`)
+        .join('\n');
+    const text = `# MCP Server Environment Debug Info
+
+**process.cwd():** ${process.cwd()}
+**WORKSPACE_ROOT:** ${context.workspaceRoot}
+**REQUIREMENTS_DIR env:** ${context.env.REQUIREMENTS_DIR || '(not set)'}
+**HOME:** ${context.env.HOME || '(not set)'}
+**PWD:** ${context.env.PWD || '(not set)'}
+**OLDPWD:** ${context.env.OLDPWD || '(not set)'}
+
+**Antigravity/Gemini env vars:**
+${antigravityVars || '(none found)'}
+
+**Projects from PROJ_* env vars:**
+${projectList || '(none found)'}`;
+    return textResponse(text);
+}
+//# sourceMappingURL=debug.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * get_requirement handler
+ *
+ * Retrieves a specific requirement by ID with its full tree and test coverage.
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for get_requirement tool
+ */
+export interface GetRequirementArgs {
+    id: string;
+    projectId?: string;
+}
+/**
+ * Handler for get_requirement tool
+ *
+ * Requirements covered:
+ * - MCP-GET-1.0: When the ID matches a root requirement, the full tree is returned
+ * - MCP-GET-1.1: When the ID matches a child requirement, that subtree is returned
+ * - MCP-GET-1.2: When the ID does not exist, an error message is returned
+ * - MCP-GET-1.3: When a requirement is retrieved, test references are shown with file path and line number
+ */
+export declare function handleGetRequirement(args: GetRequirementArgs, context: HandlerContext): Promise<ToolResponse>;
+//# sourceMappingURL=get.d.ts.map

package/dist/mcp/handlers/get.js

@@ -0,0 +1,64 @@
+/**
+ * get_requirement handler
+ *
+ * Retrieves a specific requirement by ID with its full tree and test coverage.
+ */
+import { textResponse } from './types.js';
+import { glob } from 'glob';
+import { getRequirementTree, formatRequirementTree, } from '../requirements.js';
+import { findFilesWithRequirement, findTestCodeForRequirement, } from '../testCodeExtractor.js';
+/**
+ * Handler for get_requirement tool
+ *
+ * Requirements covered:
+ * - MCP-GET-1.0: When the ID matches a root requirement, the full tree is returned
+ * - MCP-GET-1.1: When the ID matches a child requirement, that subtree is returned
+ * - MCP-GET-1.2: When the ID does not exist, an error message is returned
+ * - MCP-GET-1.3: When a requirement is retrieved, test references are shown with file path and line number
+ */
+export async function handleGetRequirement(args, context) {
+    const { id, projectId } = args;
+    const project = await context.getProjectFromDiscovery(projectId);
+    const requirements = await context.getRequirements(projectId);
+    // Get the tree starting from this ID
+    // MCP-GET-1.0: Full tree for root requirement
+    // MCP-GET-1.1: Subtree for child requirement
+    const tree = getRequirementTree(requirements, id);
+    // MCP-GET-1.2: Return error if not found
+    if (tree.length === 0) {
+        return textResponse(`Requirement "${id}" not found`);
+    }
+    const root = tree[0];
+    const formatted = formatRequirementTree(tree);
+    // MCP-GET-1.3: Find test files that reference this requirement
+    const testFiles = await glob('**/*.{test,spec}.{js,jsx,ts,tsx}', {
+        cwd: project.path,
+        absolute: true,
+        ignore: ['**/node_modules/**', '**/dist/**', '**/build/**'],
+    });
+    const matchingFiles = findFilesWithRequirement(testFiles, id);
+    const testCodeSections = [];
+    for (const file of matchingFiles) {
+        const testRefs = findTestCodeForRequirement(file, id);
+        // Deduplicate by removing nested blocks - keep only outermost blocks
+        const deduplicated = testRefs.filter((ref, i) => {
+            // Check if this ref is contained within any other ref
+            const isNested = testRefs.some((other, j) => {
+                if (i === j)
+                    return false;
+                // other contains ref if it starts before or at the same line and ends after or at the same line
+                return other.startLine <= ref.startLine && other.endLine >= ref.endLine &&
+                    (other.startLine < ref.startLine || other.endLine > ref.endLine);
+            });
+            return !isNested;
+        });
+        for (const ref of deduplicated) {
+            testCodeSections.push(`**${ref.requirementId}** tested in \`${ref.file}:${ref.startLine}-${ref.endLine}\`:\n\n\`\`\`typescript\n${ref.code}\n\`\`\``);
+        }
+    }
+    const testSection = testCodeSections.length > 0
+        ? `\n\n## Test Coverage (${testCodeSections.length} reference(s)):\n\n${testCodeSections.join('\n\n---\n\n')}`
+        : '\n\n## Test Coverage\n\nNo tests found referencing this requirement.';
+    return textResponse(`# ${id}\n\n**Document:** ${root.documentTitle}\n**Source:** ${root.sourceFile}\n\n## Requirement Tree (${tree.length} node(s)):\n\n\`\`\`\n${formatted}\n\`\`\`${testSection}`);
+}
+//# sourceMappingURL=get.js.map