@popoverai/dotrequirements 0.26.1 → 0.27.0

package/dist/mcp/index.js

@@ -1,634 +0,0 @@
-#!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { loadAllRequirements, } from "../requirements/index.js";
-import { discoverProjects, resolveProject, } from "../utils/project-discovery.js";
-import { getCredentialsFromEnv } from "../utils/project-settings.js";
-import { handleCreateRequirementDocument, handleDebugMcpEnvironment, handleGetRequirement, handleGetRequirementsByTest, handleGetTestsByRequirement, handleList, handlePushRequirements, handleReport, handleReviewTest, handleSearchRequirements, handleStyleCheck, handleValidateRequirements, } from "./handlers/index.js";
-// Read version from package.json
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const packageJson = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8"));
-const VERSION = packageJson.version;
-// Get project paths from environment variables
-// Supports both PROJ_* pattern (Antigravity) and REQUIREMENTS_DIR fallback
-function getProjectPathsFromEnv() {
-    const projects = new Map();
-    // Check for PROJ_* env vars (project ID -> path mapping)
-    for (const [key, value] of Object.entries(process.env)) {
-        if (key.startsWith("PROJ_") && value) {
-            const projectId = key.substring(5); // Remove 'PROJ_' prefix
-            projects.set(projectId, value);
-        }
-    }
-    return projects;
-}
-// 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");
-let cachedDiscoveryResult = null;
-// Requirements are loaded fresh on every call. A long-lived in-memory cache
-// silently served stale data when .requirements/*.md files were created or
-// edited mid-session, which is the primary authoring workflow the MCP server
-// is meant to support. If this ever becomes a measured performance concern,
-// invalidate via directory mtime rather than reintroducing a lifetime cache.
-async function getRequirements(projectId) {
-    const project = await getProjectFromDiscovery(projectId);
-    const { flattened } = await loadAllRequirements(project.path);
-    return flattened;
-}
-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 = [];
-        // Validate all env var projects
-        for (const [, path] of PROJECT_PATHS.entries()) {
-            const project = isConfiguredProject(path);
-            if (project) {
-                projects.push(project);
-            }
-        }
-        // Build discovery result from env var projects
-        if (projects.length === 0) {
-            cachedDiscoveryResult = {
-                type: "none",
-                message: "No valid dotrequirements projects found in PROJ_* environment variables",
-            };
-        }
-        else if (projects.length === 1) {
-            cachedDiscoveryResult = { type: "single", project: projects[0] };
-        }
-        else {
-            cachedDiscoveryResult = { type: "multiple", projects };
-        }
-        return resolveProject(cachedDiscoveryResult, projectId);
-    }
-    // Fall back to filesystem discovery if no PROJ_* env vars
-    if (!cachedDiscoveryResult) {
-        cachedDiscoveryResult = await discoverProjects(WORKSPACE_ROOT);
-    }
-    return resolveProject(cachedDiscoveryResult, projectId);
-}
-// Invalidate the project-discovery cache. Requirements are no longer cached,
-// so this only resets discovery state. Exported for testing.
-export function invalidateCache() {
-    cachedDiscoveryResult = null;
-}
-// Tool definitions
-const tools = [
-    {
-        name: "debug_mcp_environment",
-        description: "DEBUG TOOL: Returns diagnostic information about the MCP server environment (working directory, env vars, etc.)",
-        inputSchema: {
-            type: "object",
-            properties: {},
-            required: [],
-        },
-    },
-    {
-        name: "search_requirements",
-        description: "Search requirements by text or regex query. Searches requirement IDs, content, and labels. Returns matching requirements with their full context.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                query: {
-                    type: "string",
-                    description: "Text or regex pattern to search for in requirement IDs, content, or labels",
-                },
-                useRegex: {
-                    type: "boolean",
-                    description: "If true, treat query as a regular expression (default: false)",
-                },
-                projectId: {
-                    type: "string",
-                    description: "Optional: Specify which project to search (required when multiple projects exist)",
-                },
-            },
-            required: ["query"],
-        },
-    },
-    {
-        name: "get_requirement",
-        description: 'Get a requirement and all its children, including test coverage information. Accepts any requirement path (e.g., "REQ-123" returns the root and all children, "REQ-123.0" returns that node and its children). Shows which tests reference this requirement and includes the test code.',
-        inputSchema: {
-            type: "object",
-            properties: {
-                id: {
-                    type: "string",
-                    description: 'The requirement ID or path (e.g., "REQ-123" for root, "REQ-123.0" for child)',
-                },
-                projectId: {
-                    type: "string",
-                    description: "Optional: Specify which project to search (required when multiple projects exist)",
-                },
-            },
-            required: ["id"],
-        },
-    },
-    {
-        name: "list_requirements",
-        description: "List requirements in the workspace. Defaults to every root requirement (summary of IDs and content with child counts). Set untested to true to filter to only the root requirements that have no requirement() references in the codebase.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                untested: {
-                    type: "boolean",
-                    description: "When true, return only root requirements that have no test references (default: false)",
-                },
-                projectId: {
-                    type: "string",
-                    description: "Optional: Specify which project to search (required when multiple projects exist)",
-                },
-            },
-            required: [],
-        },
-    },
-    {
-        name: "get_requirements_by_test",
-        description: "Get the semantic meaning of requirement() references in a test file. Returns requirement content with line numbers where they are referenced.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                testFile: {
-                    type: "string",
-                    description: "Path to the test file to analyze",
-                },
-                projectId: {
-                    type: "string",
-                    description: "Optional: Specify which project to search (required when multiple projects exist)",
-                },
-            },
-            required: ["testFile"],
-        },
-    },
-    {
-        name: "get_tests_by_requirement",
-        description: "Show which requirements from a requirements file have test coverage. Returns a coverage report showing which requirements are tested and where the tests are located. This is the inverse of get_requirements_by_test.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                requirementsFile: {
-                    type: "string",
-                    description: 'Path to the requirements file (e.g., ".requirements/auth.requirements.md")',
-                },
-                projectId: {
-                    type: "string",
-                    description: "Optional: Specify which project to search (required when multiple projects exist)",
-                },
-            },
-            required: ["requirementsFile"],
-        },
-    },
-    {
-        name: "report_coverage",
-        description: "Display test coverage for the project's requirements. Defaults to local source (most recent test run on this machine, requires `dotrequirements harness prepare` to have run); set source to cloud to query the dot•requirements cloud-persisted record (requires project to be linked via `dotrequirements link`). Optional requirementKey scopes to a single requirement; branch / sinceTimestamp filter cloud-source results.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                source: {
-                    type: "string",
-                    enum: ["local", "cloud"],
-                    description: "Where to read coverage from (default: local)",
-                },
-                requirementKey: {
-                    type: "string",
-                    description: 'Optional: scope to a single requirement (e.g., "REQ-123"). For local source, also includes that requirement\'s children.',
-                },
-                branch: {
-                    type: "string",
-                    description: 'Cloud-only: filter coverage to a specific git branch (e.g., "main")',
-                },
-                sinceTimestamp: {
-                    type: "number",
-                    description: "Cloud-only: only include coverage recorded after this timestamp (milliseconds since epoch)",
-                },
-                projectId: {
-                    type: "string",
-                    description: "Optional: specify which project to use (required when multiple projects exist)",
-                },
-            },
-            required: [],
-        },
-    },
-    {
-        name: "create_requirement_document",
-        description: "Returns a well-formatted Markdown template that demonstrates the requirements file format. Use this to understand the format before creating requirements files. AI should use this template as a reference, then use filesystem tools (Read/Write) to create actual files.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                filePath: {
-                    type: "string",
-                    description: 'Optional: Suggested file path for documentation purposes (e.g., ".requirements/auth.requirements.md")',
-                },
-            },
-            required: [],
-        },
-    },
-    {
-        name: "validate_requirements",
-        description: "Validate a requirements Markdown file's schema. Returns detailed error messages on syntax problems. Works offline (no network/auth required). Use this to verify files before pushing.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                filePath: {
-                    type: "string",
-                    description: 'Path to the Markdown file to validate (e.g., ".requirements/auth.requirements.md")',
-                },
-            },
-            required: ["filePath"],
-        },
-    },
-    {
-        name: "push_requirements",
-        description: "Push local requirements from .requirements/ directory to dot•requirements cloud. First call returns diff summary for user review. Second call with confirmed=true executes the push. Requires project to be linked to cloud (run `dotrequirements link`).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                filePath: {
-                    type: "string",
-                    description: 'Optional: Push specific file only (e.g., ".requirements/auth.requirements.md"). If omitted, pushes all files.',
-                },
-                confirmed: {
-                    type: "boolean",
-                    description: "Set to true to execute the push after reviewing the diff. First call should omit this.",
-                },
-                projectId: {
-                    type: "string",
-                    description: "Optional: Specify which project to use (required when multiple projects exist)",
-                },
-            },
-            required: [],
-        },
-    },
-    {
-        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.*). 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: {
-                filePath: {
-                    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"',
-                },
-            },
-            required: ["filePath"],
-        },
-    },
-    {
-        name: "review_test",
-        description: "Comprehensively review a test file for both style and semantic correctness. Checks if tests actually validate what the requirements specify (not just style). Loads referenced requirements and validates that test setup, actions, and assertions match requirement preconditions, triggers, and outcomes. Requires project to be linked to cloud (run `dotrequirements link`).",
-        inputSchema: {
-            type: "object",
-            properties: {
-                testFilePath: {
-                    type: "string",
-                    description: 'Path to the test file to review (e.g., "src/auth.test.ts")',
-                },
-                projectId: {
-                    type: "string",
-                    description: "Optional: Specify which project to use (required when multiple projects exist)",
-                },
-            },
-            required: ["testFilePath"],
-        },
-    },
-];
-// Prompt definitions
-const prompts = [
-    {
-        name: "capture-requirements",
-        description: "Guide the user through capturing requirements for a new feature before implementation",
-    },
-    {
-        name: "write-tests",
-        description: "Guide writing tests that reference and validate requirements",
-    },
-];
-// Create server (exported for testing with InMemoryTransport)
-export const server = new Server({
-    name: "dotrequirements",
-    version: VERSION,
-}, {
-    capabilities: {
-        tools: {},
-        prompts: {},
-    },
-});
-// Handle list tools
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools };
-});
-// Handle list prompts
-server.setRequestHandler(ListPromptsRequestSchema, async () => {
-    return { prompts };
-});
-// Handle get prompt
-server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-    const { name } = request.params;
-    if (name === "capture-requirements") {
-        return {
-            messages: [
-                {
-                    role: "user",
-                    content: {
-                        type: "text",
-                        text: `# Capture Requirements for New Feature
-
-Let's document what this feature should do before building it.
-
-## Questions to Ask
-
-1. What problem does this solve for users?
-2. What are the key behaviors we need to support?
-3. Are there edge cases or error conditions to handle?
-4. How will we know it works correctly?
-
-## Workflow
-
-### Step 1: Create Requirements Document
-
-Use \`create_requirement_document\` to get a template with:
-- Format guidance (discovers existing patterns in your codebase)
-- Style principles for writing clear, testable requirements
-- Examples of well-written requirements
-
-Fill in:
-- Project ID (from .env.local)
-- Document title
-- Requirement IDs, descriptions, and expected behaviors
-
-### Step 2: Validate & Refine (Optional)
-
-- \`validate_requirements\` - Check syntax is correct (works offline)
-- \`style_check\` - Get AI-powered feedback on writing quality and clarity
-
-### Step 3: Push to Cloud
-
-- \`push_requirements\` - Sync to dot•requirements cloud
-  - First call shows a diff preview
-  - Second call with \`confirmed: true\` executes the push
-
-### Step 4: Implement & Test
-
-After capturing requirements:
-1. Implement the feature
-2. Write tests that reference requirements using \`requirement('REQ-ID')\`
-3. See your project's context file (CLAUDE.md/AGENTS.md) for test structure guidance`,
-                    },
-                },
-            ],
-        };
-    }
-    if (name === "write-tests") {
-        return {
-            messages: [
-                {
-                    role: "user",
-                    content: {
-                        type: "text",
-                        text: `# Write Tests for Requirements
-
-Let's write tests that validate the requirements.
-
-## Core Principles
-
-### 1. Use requirement() AS the test description
-
-\`\`\`typescript
-// ✅ Good - requirement() is the description
-test(requirement('AUTH-1'), () => { /* test code */ });
-describe(requirement('LOGIN-1.given'), () => { /* setup */ });
-it(requirement('LOGIN-1.then'), () => { /* assert */ });
-
-// ❌ Bad - requirement() in body or comments
-test("user can log in", () => { requirement('AUTH-1'); /* test code */ });
-// LOGIN-1: User can log in
-\`\`\`
-
-### 2. Structure tests to match requirement hierarchy
-
-For structured requirements, nest describe/it blocks:
-
-\`\`\`typescript
-describe(requirement('LOGIN-1'), () => {
-  describe(requirement('LOGIN-1.given'), () => {
-    // Arrange: Set up preconditions
-  });
-
-  describe(requirement('LOGIN-1.when'), () => {
-    // Act: Trigger the behavior
-
-    it(requirement('LOGIN-1.then'), () => {
-      // Assert: Verify outcome
-    });
-  });
-});
-\`\`\`
-
-For simple requirements, one test block is fine:
-
-\`\`\`typescript
-test(requirement('AUTH-1'), () => {
-  // arrange, act, assert all in one
-});
-\`\`\`
-
-### 3. Comments describe the TEST, not the requirement
-
-\`\`\`typescript
-// ✅ Good - comment explains test implementation
-describe(requirement('REQ-1.0'), () => {
-  // Mock user with valid credentials
-});
-
-// ❌ Bad - verbatim copy of requirement text
-describe(requirement('REQ-1.0'), () => {
-  // 0. When a registered user provides valid credentials, they are authenticated
-});
-\`\`\`
-
-### 4. NEVER document coverage in comments
-
-Our MCP tools track coverage automatically. Don't create a second source of truth.
-
-\`\`\`typescript
-// ❌ Bad - creates second source of truth
-/**
- * Requirements coverage:
- * - AUTH-9.0: Backend creates project ✓
- * - AUTH-9.1: CLI writes to .env.local ✓
- */
-
-// ✅ Good - use MCP tools to check coverage
-// Use get_requirement, get_requirements_by_test
-\`\`\`
-
-## Requirement Path Formats
-
-- \`requirement('AUTH-1')\` - root requirement
-- \`requirement('AUTH-1.0')\` - by numeric position
-- \`requirement('AUTH-1.given')\` - by label (case-insensitive)
-- \`requirement('AUTH-1.given#1')\` - disambiguate duplicate labels
-- \`requirement('AUTH-1.then.and')\` - nested label path
-
-## Workflow
-
-After writing tests:
-
-1. Run tests to ensure they don't throw errors
-2. **ALWAYS run \`review_test\`** on the test file to validate tests actually check what requirements specify
-3. Fix any issues identified by the review
-
-## MCP Tools for Test Writing
-
-- \`get_requirement\` - Get requirement tree with existing coverage
-- \`get_requirements_by_test\` - See requirements referenced in a test file
-- \`list_requirements\` (with \`untested: true\`) - Find requirements without tests
-- \`review_test\` - Validate test actually checks what requirement specifies (run after writing tests)`,
-                    },
-                },
-            ],
-        };
-    }
-    throw new Error(`Unknown prompt: ${name}`);
-});
-/**
- * MCP-ARGS-1: find required arguments (per the tool's inputSchema) that are
- * missing from a call, so we can fail with a self-explaining error before the
- * handler runs — a missing argument must never surface as an internal crash.
- */
-function findMissingRequiredArgs(toolName, args) {
-    const tool = tools.find((t) => t.name === toolName);
-    if (!tool)
-        return undefined; // unknown tools get their own error downstream
-    const schema = tool.inputSchema;
-    const required = schema.required ?? [];
-    const missing = required.filter((key) => args?.[key] === undefined || args?.[key] === null);
-    if (missing.length === 0)
-        return undefined;
-    return { missing, accepted: Object.keys(schema.properties ?? {}) };
-}
-// Handle tool calls
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-    // Refresh cache for each request to pick up changes
-    invalidateCache();
-    // MCP-ARGS-1.2: reject calls missing required arguments before dispatch
-    const argCheck = findMissingRequiredArgs(name, args);
-    if (argCheck) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Missing required argument(s) for ${name}: ${argCheck.missing.join(", ")}. Accepted arguments: ${argCheck.accepted.join(", ")}.`,
-                },
-            ],
-            isError: true,
-        };
-    }
-    // Create handler context for extracted handlers
-    const handlerContext = {
-        getRequirements,
-        getProjectFromDiscovery,
-        workspaceRoot: WORKSPACE_ROOT,
-        projectPaths: PROJECT_PATHS,
-        env: process.env,
-    };
-    try {
-        switch (name) {
-            case "debug_mcp_environment":
-                return handleDebugMcpEnvironment({}, handlerContext);
-            case "search_requirements":
-                return handleSearchRequirements(args, handlerContext);
-            case "get_requirement":
-                return handleGetRequirement(args, handlerContext);
-            case "list_requirements":
-                return handleList(args, handlerContext);
-            case "get_requirements_by_test":
-                return handleGetRequirementsByTest(args, handlerContext);
-            case "get_tests_by_requirement":
-                return handleGetTestsByRequirement(args, handlerContext);
-            case "report_coverage":
-                return handleReport(args, handlerContext);
-            case "create_requirement_document":
-                return handleCreateRequirementDocument(args, handlerContext);
-            case "validate_requirements":
-                return handleValidateRequirements(args, handlerContext);
-            case "push_requirements":
-                return handlePushRequirements(args, handlerContext);
-            case "style_check":
-                return handleStyleCheck(args, handlerContext, {
-                    useEnvAuth: USE_ENV_AUTH,
-                    apiBaseUrl: process.env.DOTREQUIREMENTS_API_URL,
-                });
-            case "review_test":
-                return handleReviewTest(args, handlerContext, { apiBaseUrl: process.env.DOTREQUIREMENTS_API_URL });
-            default:
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Unknown tool: ${name}`,
-                        },
-                    ],
-                    isError: true,
-                };
-        }
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
-// Start server (exported for CLI command to call directly)
-export async function main() {
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error("dot•requirements MCP server running");
-    console.error("WORKSPACE_ROOT:", WORKSPACE_ROOT);
-    console.error("process.cwd():", process.cwd());
-    console.error("REQUIREMENTS_DIR env:", process.env.REQUIREMENTS_DIR);
-}
-// Only run when executed directly, not when imported (enables InMemoryTransport testing)
-if (import.meta.url === `file://${process.argv[1]}`) {
-    main().catch(console.error);
-}
-//# sourceMappingURL=index.js.map