@popoverai/dotrequirements 0.12.1 → 0.14.0

package/dist/schema/conversions.d.ts

@@ -48,10 +48,10 @@ export declare function convexToRequirements(convexReqs: ConvexRequirement[]): R
  */
 export declare function requirementsToConvex(nodes: RequirementNode[], projectId: string, documentId: string): ConvexRequirement[];
 /**
- * Build metadata from project info and pull time.
+ * Build metadata for a requirements file.
  * DOC-HEADER-11.3: When pulling, include defaultPrefix in the frontmatter.
  */
-export declare function buildMetadata(projectId: string, version?: number, document?: {
+export declare function buildMetadata(version?: number, document?: {
     id?: string;
     title: string;
     defaultPrefix?: string;

package/dist/schema/conversions.js

@@ -166,12 +166,11 @@ function flattenNode(node, projectId, rootId, position, result, documentId) {
     });
 }
 /**
- * Build metadata from project info and pull time.
+ * Build metadata for a requirements file.
  * DOC-HEADER-11.3: When pulling, include defaultPrefix in the frontmatter.
  */
-export function buildMetadata(projectId, version = 1, document) {
+export function buildMetadata(version = 1, document) {
     return {
-        projectId,
         pulledAt: new Date().toISOString(),
         version,
         document,

package/dist/schema/schemas.d.ts

@@ -54,13 +54,12 @@ export declare function parseRequirementKey(key: string): {
  */
 export declare function buildRequirementKey(prefix: string, number: number): string;
 /**
- * Metadata block at the top of every requirements file
+ * Metadata block at the top of every requirements file.
+ * Only document.title is required for push; everything else is optional or auto-filled.
  */
 export declare const MetadataSchema: z.ZodObject<{
-    projectId: z.ZodString;
-    projectSlug: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodNumber>;
     pulledAt: z.ZodOptional<z.ZodString>;
-    version: z.ZodNumber;
     document: z.ZodOptional<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodString;
@@ -75,9 +74,7 @@ export declare const MetadataSchema: z.ZodObject<{
         defaultPrefix?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    version: number;
-    projectId: string;
-    projectSlug?: string | undefined;
+    version?: number | undefined;
     pulledAt?: string | undefined;
     document?: {
         title: string;
@@ -85,9 +82,7 @@ export declare const MetadataSchema: z.ZodObject<{
         defaultPrefix?: string | undefined;
     } | undefined;
 }, {
-    version: number;
-    projectId: string;
-    projectSlug?: string | undefined;
+    version?: number | undefined;
     pulledAt?: string | undefined;
     document?: {
         title: string;
@@ -149,10 +144,8 @@ export type RequirementNode = {
  */
 export declare const RequirementsFileSchema: z.ZodObject<{
     _meta: z.ZodObject<{
-        projectId: z.ZodString;
-        projectSlug: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodNumber>;
         pulledAt: z.ZodOptional<z.ZodString>;
-        version: z.ZodNumber;
         document: z.ZodOptional<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodString;
@@ -167,9 +160,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             defaultPrefix?: string | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        version: number;
-        projectId: string;
-        projectSlug?: string | undefined;
+        version?: number | undefined;
         pulledAt?: string | undefined;
         document?: {
             title: string;
@@ -177,9 +168,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             defaultPrefix?: string | undefined;
         } | undefined;
     }, {
-        version: number;
-        projectId: string;
-        projectSlug?: string | undefined;
+        version?: number | undefined;
         pulledAt?: string | undefined;
         document?: {
             title: string;
@@ -189,10 +178,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     }>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     _meta: z.ZodObject<{
-        projectId: z.ZodString;
-        projectSlug: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodNumber>;
         pulledAt: z.ZodOptional<z.ZodString>;
-        version: z.ZodNumber;
         document: z.ZodOptional<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodString;
@@ -207,9 +194,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             defaultPrefix?: string | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        version: number;
-        projectId: string;
-        projectSlug?: string | undefined;
+        version?: number | undefined;
         pulledAt?: string | undefined;
         document?: {
             title: string;
@@ -217,9 +202,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             defaultPrefix?: string | undefined;
         } | undefined;
     }, {
-        version: number;
-        projectId: string;
-        projectSlug?: string | undefined;
+        version?: number | undefined;
         pulledAt?: string | undefined;
         document?: {
             title: string;
@@ -229,10 +212,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     }>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     _meta: z.ZodObject<{
-        projectId: z.ZodString;
-        projectSlug: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodNumber>;
         pulledAt: z.ZodOptional<z.ZodString>;
-        version: z.ZodNumber;
         document: z.ZodOptional<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodString;
@@ -247,9 +228,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             defaultPrefix?: string | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
-        version: number;
-        projectId: string;
-        projectSlug?: string | undefined;
+        version?: number | undefined;
         pulledAt?: string | undefined;
         document?: {
             title: string;
@@ -257,9 +236,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             defaultPrefix?: string | undefined;
         } | undefined;
     }, {
-        version: number;
-        projectId: string;
-        projectSlug?: string | undefined;
+        version?: number | undefined;
         pulledAt?: string | undefined;
         document?: {
             title: string;

package/dist/schema/schemas.js

@@ -104,19 +104,16 @@ export function buildRequirementKey(prefix, number) {
 // Metadata Schema
 // =============================================================================
 /**
- * Metadata block at the top of every requirements file
+ * Metadata block at the top of every requirements file.
+ * Only document.title is required for push; everything else is optional or auto-filled.
  */
 export const MetadataSchema = z.object({
-    projectId: z.string(),
-    projectSlug: z.string().optional(), // User-friendly slug (e.g., "quick-fox-123")
-    pulledAt: z.string().optional(), // ISO 8601 timestamp - required for CLI files, optional for IDE
-    version: z.number(),
-    // Optional document association (one file = one document)
+    version: z.number().optional(), // Informational - incremented on push
+    pulledAt: z.string().optional(), // ISO 8601 timestamp - used for conflict detection
     document: z.object({
-        id: z.string().optional(), // Optional - filled by push when creating new document
-        title: z.string(),
-        // DOC-HEADER-11: Default prefix for new requirement keys in this document
-        defaultPrefix: z.string().optional(),
+        id: z.string().optional(), // Cloud document link - filled by push when creating
+        title: z.string(), // Required for push
+        defaultPrefix: z.string().optional(), // Editor hint for new requirement keys
     }).optional(),
 });
 // =============================================================================

package/dist/schema/test-schema.js

@@ -3,7 +3,7 @@
  */
 import { buildRequirementsMarkdown, parseRequirementsFile, buildMetadata } from './index.js';
 // Create test data
-const metadata = buildMetadata('test-project-123', 1);
+const metadata = buildMetadata(1);
 const testRequirements = [
     {
         id: 'REQ123',

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

package/dist/utils/env.d.ts

@@ -5,17 +5,4 @@
  * @param force - If true, overwrite existing process.env values (used when reloading after init)
  */
 export declare function loadEnvFile(cwd?: string, force?: boolean): void;
-/**
- * Get project credentials from environment
- * Returns undefined if not found
- */
-export declare function getProjectCredentials(): {
-    projectId: string;
-    projectSecret: string;
-} | undefined;
-/**
- * Get project ID from environment
- * Returns undefined if not found
- */
-export declare function getProjectId(): string | undefined;
 //# sourceMappingURL=env.d.ts.map

package/dist/utils/env.js

@@ -36,23 +36,4 @@ export function loadEnvFile(cwd = process.cwd(), force = false) {
         // The commands will error appropriately if env vars are missing
     }
 }
-/**
- * Get project credentials from environment
- * Returns undefined if not found
- */
-export function getProjectCredentials() {
-    const projectId = process.env.DOTREQUIREMENTS_PROJECT_ID;
-    const projectSecret = process.env.DOTREQUIREMENTS_PROJECT_SECRET;
-    if (!projectId || !projectSecret) {
-        return undefined;
-    }
-    return { projectId, projectSecret };
-}
-/**
- * Get project ID from environment
- * Returns undefined if not found
- */
-export function getProjectId() {
-    return process.env.DOTREQUIREMENTS_PROJECT_ID;
-}
 //# sourceMappingURL=env.js.map

package/dist/utils/gitignore.d.ts

@@ -1,7 +1,7 @@
 /**
- * Ensure .env.local is in .gitignore
+ * Ensure project-settings.json is in .gitignore
  * Creates .gitignore if it doesn't exist
- * Appends .env.local if not already present
+ * Appends the entry if not already present
  */
 export declare function ensureGitignore(cwd?: string): void;
 //# sourceMappingURL=gitignore.d.ts.map

package/dist/utils/gitignore.js

@@ -1,13 +1,13 @@
 import * as fs from 'fs';
 import * as path from 'path';
 /**
- * Ensure .env.local is in .gitignore
+ * Ensure project-settings.json is in .gitignore
  * Creates .gitignore if it doesn't exist
- * Appends .env.local if not already present
+ * Appends the entry if not already present
  */
 export function ensureGitignore(cwd = process.cwd()) {
     const gitignorePath = path.join(cwd, '.gitignore');
-    const entryToAdd = '.env.local';
+    const entryToAdd = '.requirements/project-settings.json';
     const comment = '# dotrequirements credentials';
     // Check if .gitignore exists
     if (!fs.existsSync(gitignorePath)) {
@@ -17,7 +17,7 @@ export function ensureGitignore(cwd = process.cwd()) {
     }
     // Read existing .gitignore
     const content = fs.readFileSync(gitignorePath, 'utf-8');
-    // Check if .env.local is already present
+    // Check if entry is already present
     if (content.includes(entryToAdd)) {
         return; // Already present, nothing to do
     }

package/dist/utils/oauth-flow.d.ts

@@ -16,7 +16,6 @@ export interface OAuthResult {
  * 3. Open browser for user authentication
  * 4. Wait for callback with authorization code
  * 5. Exchange code for tokens via WorkOS SDK
- * 6. Store tokens securely
  */
 export declare function executeOAuthFlow(): Promise<OAuthResult>;
 //# sourceMappingURL=oauth-flow.d.ts.map

package/dist/utils/oauth-flow.js

@@ -8,7 +8,6 @@ import { randomBytes } from 'crypto';
 import { ConvexHttpClient } from 'convex/browser';
 import { startCallbackServer } from './oauth-callback-server.js';
 import { openBrowserWithFallback } from './browser-launch.js';
-import { storeTokens } from './token-storage.js';
 import { getConvexUrl } from '../config.js';
 import { api } from '../convex.js';
 const WORKOS_CLIENT_ID = 'client_01KCM6WPYX201P7DRV5DHF4TR7';
@@ -20,7 +19,6 @@ const WORKOS_AUTHORIZE_URL = 'https://api.workos.com/user_management/authorize';
  * 3. Open browser for user authentication
  * 4. Wait for callback with authorization code
  * 5. Exchange code for tokens via WorkOS SDK
- * 6. Store tokens securely
  */
 export async function executeOAuthFlow() {
     // Generate PKCE code verifier and challenge
@@ -58,13 +56,6 @@ export async function executeOAuthFlow() {
         throw new Error(`Token exchange failed: ${result.error}`);
     }
     const { accessToken, refreshToken, expiresAt } = result;
-    // Store tokens securely
-    const tokens = {
-        accessToken,
-        refreshToken,
-        expiresAt,
-    };
-    await storeTokens(tokens);
     console.log('✓ Authentication complete!');
     return {
         accessToken,

package/dist/utils/project-discovery.d.ts

@@ -4,9 +4,9 @@
 export interface DotreqProject {
     /** Absolute path to the project root directory */
     path: string;
-    /** Project ID from .env.local */
+    /** Project ID from project-settings.json */
     projectId: string;
-    /** Project secret from .env.local */
+    /** Project secret from project-settings.json */
     projectSecret: string;
 }
 /**
@@ -24,9 +24,7 @@ export type ProjectDiscoveryResult = {
 };
 /**
  * Check if a directory is a configured dotrequirements project
- * A project is configured if:
- * 1. It has a package.json that includes "dotreq" (in dependencies or devDependencies)
- * 2. It has a .env.local with DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET
+ * A project is configured if it has .requirements/project-settings.json with credentials
  */
 export declare function isConfiguredProject(dir: string): DotreqProject | null;
 /**

package/dist/utils/project-discovery.js

@@ -1,58 +1,34 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { glob } from 'glob';
+import { readProjectSettings } from './project-settings.js';
 /**
  * Check if a directory is a configured dotrequirements project
- * A project is configured if:
- * 1. It has a package.json that includes "dotreq" (in dependencies or devDependencies)
- * 2. It has a .env.local with DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET
+ * A project is configured if it has .requirements/project-settings.json with credentials
  */
 export function isConfiguredProject(dir) {
-    const pkgPath = path.join(dir, 'package.json');
-    const envPath = path.join(dir, '.env.local');
-    // Check for package.json with dotreq
-    if (!fs.existsSync(pkgPath)) {
+    const requirementsDir = path.join(dir, '.requirements');
+    // Check for .requirements/ directory
+    if (!fs.existsSync(requirementsDir) || !fs.statSync(requirementsDir).isDirectory()) {
         return null;
     }
+    // Try to read credentials from project-settings.json
+    let settings;
     try {
-        const pkgContent = fs.readFileSync(pkgPath, 'utf-8');
-        // Look for "dotreq" anywhere in the file (flexible matching)
-        if (!pkgContent.includes('dotreq')) {
-            return null;
-        }
-    }
-    catch {
-        return null;
-    }
-    // Check for .env.local with required vars
-    if (!fs.existsSync(envPath)) {
-        return null;
-    }
-    let projectId;
-    let projectSecret;
-    try {
-        const envContent = fs.readFileSync(envPath, 'utf-8');
-        const lines = envContent.split('\n');
-        for (const line of lines) {
-            const trimmed = line.trim();
-            if (trimmed.startsWith('DOTREQUIREMENTS_PROJECT_ID=')) {
-                projectId = trimmed.split('=')[1]?.trim().replace(/['"]/g, '');
-            }
-            if (trimmed.startsWith('DOTREQUIREMENTS_PROJECT_SECRET=')) {
-                projectSecret = trimmed.split('=')[1]?.trim().replace(/['"]/g, '');
-            }
-        }
+        settings = readProjectSettings(dir);
     }
     catch {
+        // Invalid settings file
         return null;
     }
-    if (!projectId || !projectSecret) {
+    if (!settings) {
+        // No credentials (local-only project)
         return null;
     }
     return {
         path: dir,
-        projectId,
-        projectSecret,
+        projectId: settings.projectId,
+        projectSecret: settings.projectSecret,
     };
 }
 /**
@@ -61,14 +37,14 @@ export function isConfiguredProject(dir) {
  */
 export async function findConfiguredProjects(startDir) {
     const projects = [];
-    // Find all package.json files, but allow .env.local despite being in .gitignore
-    const packageJsonFiles = await glob('**/package.json', {
+    // Find all .requirements directories
+    const requirementsDirs = await glob('**/.requirements', {
         cwd: startDir,
         absolute: true,
         ignore: ['**/node_modules/**', '**/dist/**', '**/.git/**', '**/build/**'],
     });
-    for (const pkgPath of packageJsonFiles) {
-        const dir = path.dirname(pkgPath);
+    for (const reqDir of requirementsDirs) {
+        const dir = path.dirname(reqDir);
         const project = isConfiguredProject(dir);
         if (project) {
             projects.push(project);
@@ -96,7 +72,7 @@ export async function discoverProjects(workingDir = process.cwd()) {
     if (childProjects.length === 0) {
         return {
             type: 'none',
-            message: `No dotrequirements projects found in ${workingDir} or its children.\n\nA project must have:\n1. package.json with "dotreq" dependency\n2. .env.local with DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET`,
+            message: `No dotrequirements projects found in ${workingDir} or its children.\n\nA project must have:\n1. A .requirements/ directory\n2. Cloud credentials in .requirements/project-settings.json\n\nRun "dotrequirements init" to create a project or "dotrequirements link" to connect to cloud.`,
         };
     }
     // Case 3: Exactly one child project