@popoverai/dotrequirements 0.13.0 → 0.15.0

package/dist/mcp/index.js

@@ -2,13 +2,13 @@
 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, } from './convexClient.js';
 import { discoverProjects, resolveProject, } from '../utils/project-discovery.js';
-import { isLocalOnlyProject, CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE } from '../utils/local-project.js';
+import { getCredentialsFromEnv } from '../utils/project-settings.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -33,6 +33,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 = `
 
 ---
@@ -58,6 +61,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 = [];
@@ -211,7 +228,7 @@ const tools = [
     },
     {
         name: 'get_requirement_coverage',
-        description: 'Get test coverage information for a specific requirement from dot•requirements cloud. Shows when the requirement was last tested, on which branch, and in which test file. Requires DOTREQUIREMENTS_PROJECT_SECRET to be configured.',
+        description: 'Get test coverage information for a specific requirement from dot•requirements cloud. Shows when the requirement was last tested, on which branch, and in which test file. Requires project to be linked to cloud (run `dotrequirements link`).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -229,7 +246,7 @@ const tools = [
     },
     {
         name: 'get_project_coverage_summary',
-        description: 'Get a summary of test coverage for all requirements in the project from dot•requirements cloud. Shows which requirements have been tested and which haven\'t. Optionally filter by branch or time range. Requires DOTREQUIREMENTS_PROJECT_SECRET to be configured.',
+        description: 'Get a summary of test coverage for all requirements in the project from dot•requirements cloud. Shows which requirements have been tested and which haven\'t. Optionally filter by branch or time range. Requires project to be linked to cloud (run `dotrequirements link`).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -279,7 +296,7 @@ const tools = [
     },
     {
         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 DOTREQUIREMENTS_PROJECT_SECRET environment variable.',
+        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: {
@@ -301,7 +318,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 DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured.',
+        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: {
@@ -309,6 +326,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"',
@@ -319,7 +341,7 @@ const tools = [
     },
     {
         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 DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured.',
+        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: {
@@ -416,7 +438,7 @@ Fill in:
 After capturing requirements:
 1. Implement the feature
 2. Write tests that reference requirements using \`requirement('REQ-ID')\`
-3. Use the test writing skill/prompt for guidance on test structure`,
+3. See your project's context file (CLAUDE.md/AGENTS.md) for test structure guidance`,
                     },
                 },
             ],
@@ -900,31 +922,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 DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured in your .env file.',
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                // AUTHZ-2.1: Check if project is local-only
-                if (isLocalOnlyProject(config.projectId)) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE,
-                            },
-                        ],
-                        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: [
@@ -959,31 +957,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 DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured in your .env file.',
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                // AUTHZ-2.1: Check if project is local-only
-                if (isLocalOnlyProject(config.projectId)) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE,
-                            },
-                        ],
-                        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 = '';
@@ -1311,35 +1285,11 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                 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 environment variables:\n- DOTREQUIREMENTS_PROJECT_ID\n- DOTREQUIREMENTS_PROJECT_SECRET',
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                const convexUrl = config.convexUrl;
-                const projectId = config.projectId;
-                const projectSecret = config.projectSecret;
-                // AUTHZ-2.1: Check if project is local-only
-                if (isLocalOnlyProject(projectId)) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE,
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
+                const convexUrl = CONVEX_URL;
+                const projectId = project.projectId;
+                const projectSecret = project.projectSecret;
                 // Determine files to push
                 const requirementsDir = path.resolve(project.path, '.requirements');
                 let filesToPush;
@@ -1448,7 +1398,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);
@@ -1480,22 +1430,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) {
@@ -1503,36 +1504,14 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                         content: [
                             {
                                 type: 'text',
-                                text: `Style check requires DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured in your .env or .env.local file.\n\nError: ${error instanceof Error ? error.message : String(error)}`,
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                const config = loadConvexConfig(project.path);
-                if (!config) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: 'Style check requires DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured in your .env or .env.local file.',
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                // AUTHZ-2.1: Check if project is local-only
-                if (isLocalOnlyProject(config.projectId)) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE,
+                                text: `Style check requires project credentials. Run \`dotrequirements link\` to connect to cloud.\n\nError: ${error instanceof Error ? error.message : String(error)}`,
                             },
                         ],
                         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';
@@ -1543,9 +1522,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,
                         }),
@@ -1563,11 +1542,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}`,
                             },
                         ],
                     };
@@ -1663,30 +1645,8 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                     });
                 }
                 // Get Convex config
-                const config = loadConvexConfig(project.path);
-                if (!config) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: 'Test review requires DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured in your .env or .env.local file.',
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                // AUTHZ-2.1: Check if project is local-only
-                if (isLocalOnlyProject(config.projectId)) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE,
-                            },
-                        ],
-                        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';
@@ -1697,8 +1657,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
  */

package/dist/templates/context-file-section.md

@@ -0,0 +1,59 @@
+## Requirements-First Development
+
+This project uses dotrequirements for requirements tracking. Requirements live in `.requirements/*.requirements.md`.
+
+### Workflow
+
+When adding new functionality (not bug fixes or refactoring):
+
+1. **Draft requirements** - Write in `.requirements/*.requirements.md`
+2. **Style-check** - Run `mcp__dotrequirements__style_check` on the file
+3. **Get approval** - Present requirements, wait for go-ahead
+4. **Implement** - Build the feature
+5. **Write tests** - Reference requirements with `requirement()`
+6. **Run tests** - Verify everything passes
+7. **Review tests** - Run `mcp__dotrequirements__review_test` to validate coverage
+
+### Requirements Syntax
+
+```dotrequirements
+REQ-ID: Short description of expected behavior
+  0. Given -> Precondition that must be true
+  1. When -> Action or trigger
+  2. Then -> Expected outcome
+    2.0. And -> Additional outcome detail
+```
+
+- First line: `KEY: description`
+- Criteria: `position. Label -> content` (Given/When/Then structure)
+- Nesting: Indent with 2 spaces, use `x.y` position paths
+- Delimiter: `->` or the arrow character
+
+### Test Usage
+
+Use `requirement()` AS the test description:
+
+```typescript
+import { requirement } from '@popoverai/dotrequirements/test';
+
+test(requirement('REQ-ID'), () => { /* test the requirement */ });
+test(requirement('REQ-ID.0'), () => { /* test specific criterion */ });
+```
+
+### MCP Tools
+
+**Exploration:**
+- `list_all_requirements` - Overview of all requirements
+- `get_requirement` - Requirement tree with test coverage
+- `search_requirements` - Search by text/regex
+
+**Authoring:**
+- `create_requirement_document` - Get template with format guidance
+- `validate_requirements` - Check syntax (works offline)
+- `style_check` - AI feedback on clarity
+- `push_requirements` - Sync to cloud
+
+**Testing:**
+- `get_requirements_by_test` - See requirements a test file covers
+- `list_untested_requirements` - Find gaps in coverage
+- `review_test` - Validate tests match requirement intent

package/dist/utils/context-file.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Get the appropriate context file name for a platform
+ */
+export declare function getContextFileName(platform: string): string | null;
+/**
+ * Find the git root directory
+ */
+export declare function findGitRoot(): Promise<string | null>;
+/**
+ * Find the dotrequirements section in file content
+ * Returns the start/end indices and content, or null if not found
+ */
+export declare function findDotrequirementsSection(content: string): {
+    start: number;
+    end: number;
+    content: string;
+} | null;
+/**
+ * Wrap content in section markers
+ */
+export declare function wrapInSectionMarkers(content: string): string;
+/**
+ * Append or update the dotrequirements section in a context file
+ * - If file doesn't exist, creates it with just the section
+ * - If file exists without section, appends section at end
+ * - If file exists with section, replaces the section
+ *
+ * Returns: { action: 'created' | 'appended' | 'updated', existingContent?: string }
+ */
+export declare function appendOrUpdateSection(filePath: string, sectionContent: string): {
+    action: 'created' | 'appended' | 'updated';
+    existingContent?: string;
+};
+/**
+ * Get the full path to the context file for a platform
+ */
+export declare function getContextFilePath(platform: string): Promise<string | null>;
+//# sourceMappingURL=context-file.d.ts.map

package/dist/utils/context-file.js

@@ -0,0 +1,94 @@
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { findUp } from 'find-up';
+const SECTION_START = '<!-- dotrequirements:start -->';
+const SECTION_END = '<!-- dotrequirements:end -->';
+/**
+ * Platform to context file mapping
+ */
+const PLATFORM_CONTEXT_FILES = {
+    'claude-code': 'CLAUDE.md',
+    'cursor': 'AGENTS.md',
+    'codex': 'AGENTS.md',
+    'github-copilot': 'AGENTS.md',
+    'antigravity': 'GEMINI.md',
+};
+/**
+ * Get the appropriate context file name for a platform
+ */
+export function getContextFileName(platform) {
+    return PLATFORM_CONTEXT_FILES[platform] ?? null;
+}
+/**
+ * Find the git root directory
+ */
+export async function findGitRoot() {
+    const gitDir = await findUp('.git', { type: 'directory' });
+    return gitDir ? dirname(gitDir) : null;
+}
+/**
+ * Find the dotrequirements section in file content
+ * Returns the start/end indices and content, or null if not found
+ */
+export function findDotrequirementsSection(content) {
+    const startIdx = content.indexOf(SECTION_START);
+    if (startIdx === -1)
+        return null;
+    const endIdx = content.indexOf(SECTION_END, startIdx);
+    if (endIdx === -1)
+        return null;
+    return {
+        start: startIdx,
+        end: endIdx + SECTION_END.length,
+        content: content.slice(startIdx, endIdx + SECTION_END.length),
+    };
+}
+/**
+ * Wrap content in section markers
+ */
+export function wrapInSectionMarkers(content) {
+    return `${SECTION_START}\n${content}\n${SECTION_END}`;
+}
+/**
+ * Append or update the dotrequirements section in a context file
+ * - If file doesn't exist, creates it with just the section
+ * - If file exists without section, appends section at end
+ * - If file exists with section, replaces the section
+ *
+ * Returns: { action: 'created' | 'appended' | 'updated', existingContent?: string }
+ */
+export function appendOrUpdateSection(filePath, sectionContent) {
+    const wrappedContent = wrapInSectionMarkers(sectionContent);
+    if (!existsSync(filePath)) {
+        // Create new file with just the section
+        writeFileSync(filePath, wrappedContent + '\n', 'utf-8');
+        return { action: 'created' };
+    }
+    const existingFile = readFileSync(filePath, 'utf-8');
+    const existingSection = findDotrequirementsSection(existingFile);
+    if (!existingSection) {
+        // Append section to end of file
+        const separator = existingFile.endsWith('\n') ? '\n' : '\n\n';
+        writeFileSync(filePath, existingFile + separator + wrappedContent + '\n', 'utf-8');
+        return { action: 'appended' };
+    }
+    // Replace existing section
+    const newContent = existingFile.slice(0, existingSection.start) +
+        wrappedContent +
+        existingFile.slice(existingSection.end);
+    writeFileSync(filePath, newContent, 'utf-8');
+    return { action: 'updated', existingContent: existingSection.content };
+}
+/**
+ * Get the full path to the context file for a platform
+ */
+export async function getContextFilePath(platform) {
+    const fileName = getContextFileName(platform);
+    if (!fileName)
+        return null;
+    const gitRoot = await findGitRoot();
+    if (!gitRoot)
+        return null;
+    return join(gitRoot, fileName);
+}
+//# sourceMappingURL=context-file.js.map