@popoverai/dotrequirements 0.11.0

package/dist/commands/push.js

@@ -0,0 +1,310 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ConvexHttpClient } from 'convex/browser';
+import { getConvexUrl } from '../config.js';
+import { parseRequirementsFromFile, getAllRequirements, parseRequirementKey, buildRequirementsFile } from '../schema/index.js';
+import { api } from '../convex.js';
+import * as readline from 'readline';
+import { isLocalOnlyProject, CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE } from '../utils/local-project.js';
+import { brand } from '../utils/brand.js';
+export async function pushCommand(file, options) {
+    try {
+        console.log(`Preparing to push requirements to ${brand} cloud...\n`);
+        // Verify project credentials are configured
+        const projectId = process.env.DOTREQUIREMENTS_PROJECT_ID;
+        const projectSecret = process.env.DOTREQUIREMENTS_PROJECT_SECRET;
+        if (!projectId || !projectSecret) {
+            throw new Error('Project credentials not found. Either:\n' +
+                '  1. Run "dotreq init" to initialize the project, or\n' +
+                '  2. Set DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET in .env.local');
+        }
+        // AUTHZ-2.0: Check if project is local-only
+        if (isLocalOnlyProject(projectId)) {
+            throw new Error(CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE);
+        }
+        // Determine which files to push
+        const requirementsDir = path.join(process.cwd(), '.requirements');
+        if (!fs.existsSync(requirementsDir)) {
+            console.log('No .requirements/ directory found. Nothing to push.');
+            return;
+        }
+        let filesToPush;
+        if (file) {
+            // Push specific file
+            const filePath = path.resolve(file);
+            if (!fs.existsSync(filePath)) {
+                throw new Error(`File not found: ${file}`);
+            }
+            filesToPush = [filePath];
+        }
+        else {
+            // Push all *.requirements.md files in .requirements/
+            const files = fs.readdirSync(requirementsDir);
+            filesToPush = files
+                .filter(f => f.endsWith('.requirements.md'))
+                .map(f => path.join(requirementsDir, f));
+            if (filesToPush.length === 0) {
+                console.log('No *.requirements.md files found in .requirements/. Nothing to push.');
+                return;
+            }
+        }
+        // Parse all local files
+        console.log('Parsing local requirements...');
+        const parsedFiles = [];
+        let totalRequirements = 0;
+        for (const filePath of filesToPush) {
+            const fileName = path.basename(filePath);
+            console.log(`  Reading ${fileName}...`);
+            // Read raw file content
+            const rawContent = fs.readFileSync(filePath, 'utf-8');
+            // Parse to get metadata and requirements
+            const parsed = parseRequirementsFromFile(filePath);
+            const flatRequirements = getAllRequirements(parsed.requirements);
+            // Extract markdown content (everything after frontmatter)
+            const markdownContent = extractMarkdownContent(rawContent);
+            // DOC-HEADER-11.1/11.2: Infer prefix from first requirement if not specified
+            const doc = parsed.metadata.document;
+            if (doc && !doc.defaultPrefix && flatRequirements.length > 0) {
+                const firstReq = flatRequirements[0];
+                if (firstReq) {
+                    const parsedKey = parseRequirementKey(firstReq.id);
+                    if (parsedKey) {
+                        doc.defaultPrefix = parsedKey.prefix;
+                        console.log(`    Inferred defaultPrefix "${doc.defaultPrefix}" from first requirement`);
+                    }
+                }
+            }
+            parsedFiles.push({
+                filePath,
+                metadata: parsed.metadata,
+                markdownContent,
+                requirementCount: flatRequirements.length,
+            });
+            totalRequirements += flatRequirements.length;
+        }
+        console.log(`\nFound ${totalRequirements} requirement(s) in ${parsedFiles.length} document(s).\n`);
+        // Connect to Convex
+        const convexUrl = getConvexUrl();
+        const client = new ConvexHttpClient(convexUrl);
+        // Phase 1: Dry run to categorize all files
+        console.log('Validating documents...');
+        const dryRunResults = [];
+        for (const file of parsedFiles) {
+            const doc = file.metadata.document;
+            const fileName = path.basename(file.filePath);
+            if (!doc) {
+                // No document section - mark as invalid locally
+                dryRunResults.push({
+                    file,
+                    result: {
+                        dryRun: true,
+                        action: 'invalid',
+                        title: fileName,
+                        error: 'Missing document section in frontmatter',
+                    },
+                });
+                continue;
+            }
+            try {
+                const result = await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
+                    projectAuth: {
+                        projectSlug: projectId,
+                        projectSecret,
+                    },
+                    target: { type: 'project', slug: projectId },
+                    documentId: doc.id,
+                    title: doc.title,
+                    markdownContent: file.markdownContent,
+                    defaultPrefix: doc.defaultPrefix,
+                    dryRun: true,
+                });
+                dryRunResults.push({ file, result });
+            }
+            catch (err) {
+                dryRunResults.push({
+                    file,
+                    result: {
+                        dryRun: true,
+                        action: 'invalid',
+                        title: doc.title,
+                        error: err.message,
+                    },
+                });
+            }
+        }
+        // Categorize results
+        const updates = dryRunResults.filter(r => r.result.action === 'update');
+        const creates = dryRunResults.filter(r => r.result.action === 'create');
+        const notFound = dryRunResults.filter(r => r.result.action === 'not_found');
+        const invalid = dryRunResults.filter(r => r.result.action === 'invalid');
+        // Check for conflicts on updates (cloud changed since last pull)
+        const conflicts = [];
+        if (updates.length > 0) {
+            const docIds = updates.map(u => u.result.documentId);
+            const cloudMetadata = await client.query(api.documents.queries.getDocumentsMetadata, {
+                projectAuth: {
+                    projectSlug: projectId,
+                    projectSecret,
+                },
+                target: { type: 'project', slug: projectId },
+                documentIds: docIds,
+            });
+            const cloudMetaByDocId = new Map(cloudMetadata.map((m) => [m.documentId, m]));
+            for (const item of updates) {
+                const docId = item.result.documentId;
+                const cloudMeta = cloudMetaByDocId.get(docId);
+                if (cloudMeta && item.file.metadata.pulledAt) {
+                    const pulledAtMs = new Date(item.file.metadata.pulledAt).getTime();
+                    if (cloudMeta.updatedAt > pulledAtMs) {
+                        conflicts.push({ item, cloudMeta });
+                    }
+                }
+            }
+        }
+        // Display unified summary
+        console.log('\n=== Push Summary ===\n');
+        if (updates.length > 0) {
+            console.log(`Updated documents (${updates.length}):`);
+            for (const { file, result } of updates) {
+                const fileName = path.basename(file.filePath);
+                const hasConflict = conflicts.some(c => c.item.file === file);
+                const conflictNote = hasConflict ? ' ⚠️  [cloud changed since pull]' : '';
+                const warningNote = result.warning ? ` (${result.warning})` : '';
+                console.log(`  ~ ${fileName}${conflictNote}${warningNote}`);
+            }
+            console.log();
+        }
+        if (creates.length > 0) {
+            console.log(`New documents (${creates.length}):`);
+            for (const { file, result } of creates) {
+                const fileName = path.basename(file.filePath);
+                const warningNote = result.warning ? ` (${result.warning})` : '';
+                console.log(`  + ${fileName}${warningNote}`);
+            }
+            console.log();
+        }
+        if (notFound.length > 0) {
+            console.log(`Documents not found in cloud (${notFound.length}) - will create new:`);
+            for (const { file, result } of notFound) {
+                const fileName = path.basename(file.filePath);
+                console.log(`  ! ${fileName} (ID: ${result.documentId})`);
+            }
+            console.log();
+        }
+        if (invalid.length > 0) {
+            console.log(`Skipped - invalid files (${invalid.length}):`);
+            for (const { file, result } of invalid) {
+                const fileName = path.basename(file.filePath);
+                console.log(`  ✗ ${fileName}: ${result.error}`);
+            }
+            console.log();
+        }
+        // Check if there's anything to push
+        const pushableFiles = [...updates, ...creates, ...notFound];
+        if (pushableFiles.length === 0) {
+            console.log('No valid documents to push.');
+            return;
+        }
+        // Single confirmation prompt
+        if (!options.yes) {
+            const hasConflicts = conflicts.length > 0;
+            const prompt = hasConflicts
+                ? 'Continue with push? (will overwrite cloud changes) [y/N] '
+                : 'Continue with push? [y/N] ';
+            const confirmed = await confirm(prompt);
+            if (!confirmed) {
+                console.log('Push cancelled.');
+                return;
+            }
+        }
+        // Phase 2: Execute push
+        console.log('\nPushing documents to cloud...');
+        let created = 0;
+        let updated = 0;
+        for (const { file, result } of pushableFiles) {
+            const doc = file.metadata.document;
+            const fileName = path.basename(file.filePath);
+            // For not_found, clear the ID so we create a new document
+            const effectiveDocId = result.action === 'not_found' ? undefined : doc.id;
+            try {
+                const pushResult = await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
+                    projectAuth: {
+                        projectSlug: projectId,
+                        projectSecret,
+                    },
+                    target: { type: 'project', slug: projectId },
+                    documentId: effectiveDocId,
+                    title: doc.title,
+                    markdownContent: file.markdownContent,
+                    defaultPrefix: doc.defaultPrefix,
+                    dryRun: false,
+                });
+                const isCreate = result.action === 'create' || result.action === 'not_found';
+                if (isCreate) {
+                    // New document - write ID back to file
+                    doc.id = pushResult;
+                    file.metadata.pulledAt = new Date().toISOString();
+                    file.metadata.version = 1;
+                    const updatedContent = buildRequirementsFile(file.metadata, file.markdownContent);
+                    fs.writeFileSync(file.filePath, updatedContent, 'utf-8');
+                    console.log(`  ✓ Created: ${fileName} → ${pushResult}`);
+                    created++;
+                }
+                else {
+                    // Update pulledAt to reflect this push
+                    file.metadata.pulledAt = new Date().toISOString();
+                    file.metadata.version = (file.metadata.version || 0) + 1;
+                    const updatedContent = buildRequirementsFile(file.metadata, file.markdownContent);
+                    fs.writeFileSync(file.filePath, updatedContent, 'utf-8');
+                    console.log(`  ✓ Updated: ${fileName}`);
+                    updated++;
+                }
+            }
+            catch (err) {
+                console.error(`  ✗ Failed: ${fileName} - ${err.message}`);
+            }
+        }
+        console.log(`\n✓ Push complete!`);
+        if (created > 0) {
+            console.log(`  Created: ${created} document(s)`);
+        }
+        if (updated > 0) {
+            console.log(`  Updated: ${updated} document(s)`);
+        }
+        if (created === 0 && updated === 0) {
+            console.log('  No documents were pushed.');
+        }
+    }
+    catch (error) {
+        // Re-throw to let the CLI error handler display it cleanly
+        throw error;
+    }
+}
+/**
+ * Extract markdown content from a file, stripping YAML frontmatter.
+ * Exported for testing.
+ */
+export function extractMarkdownContent(rawContent) {
+    // Match YAML frontmatter: starts with ---, ends with ---
+    const frontmatterMatch = rawContent.match(/^---\n[\s\S]*?\n---\n*/);
+    if (frontmatterMatch) {
+        return rawContent.slice(frontmatterMatch[0].length);
+    }
+    return rawContent;
+}
+/**
+ * Prompt user for confirmation
+ */
+function confirm(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+        });
+    });
+}
+//# sourceMappingURL=push.js.map

package/dist/commands/test.d.ts

@@ -0,0 +1,6 @@
+interface TestOptions {
+    file?: string;
+}
+export declare function testCommand(options: TestOptions): Promise<void>;
+export {};
+//# sourceMappingURL=test.d.ts.map

package/dist/commands/test.js

@@ -0,0 +1,78 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseRequirementsFromFile } from '../schema/index.js';
+export async function testCommand(options) {
+    try {
+        console.log('Parsing and validating requirements...');
+        const requirementsDir = path.join(process.cwd(), '.requirements');
+        if (!fs.existsSync(requirementsDir)) {
+            console.error('Error: .requirements/ directory not found.');
+            console.log('Run "dotrequirements pull" first to sync requirements.');
+            process.exit(1);
+        }
+        // Get files to test
+        let files;
+        if (options.file) {
+            files = [options.file];
+        }
+        else {
+            files = fs
+                .readdirSync(requirementsDir)
+                .filter((f) => f.endsWith('.requirements.md'))
+                .map((f) => path.join(requirementsDir, f));
+        }
+        if (files.length === 0) {
+            console.log('No Markdown requirements files found to test.');
+            return;
+        }
+        let totalRequirements = 0;
+        let passCount = 0;
+        let failCount = 0;
+        for (const filePath of files) {
+            const fileName = path.basename(filePath);
+            console.log(`\nTesting: ${fileName}`);
+            try {
+                // Parse and validate using shared schema module
+                const { metadata, requirements } = parseRequirementsFromFile(filePath);
+                // Count total requirements (root + all descendants)
+                let count = 0;
+                for (const req of requirements) {
+                    count += countRequirementsInTree(req);
+                }
+                totalRequirements += count;
+                console.log(`  ✓ Valid structure (${count} requirement(s))`);
+                console.log(`  ✓ Version: ${metadata.version}`);
+                console.log(`  ✓ Last sync: ${metadata.pulledAt}`);
+                passCount++;
+            }
+            catch (error) {
+                console.error(`  ✗ Validation failed:`, error);
+                failCount++;
+            }
+        }
+        console.log(`\n${'='.repeat(50)}`);
+        console.log(`Total files: ${files.length}`);
+        console.log(`Passed: ${passCount}`);
+        console.log(`Failed: ${failCount}`);
+        console.log(`Total requirements: ${totalRequirements}`);
+        if (failCount > 0) {
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        // Re-throw to let the CLI error handler display it cleanly
+        throw error;
+    }
+}
+/**
+ * Recursively count requirements in a tree (1 for root + all descendants)
+ */
+function countRequirementsInTree(node) {
+    let count = 1; // Count this node
+    // Count all children
+    for (const child of node.children) {
+        count += countRequirementsInTree(child);
+    }
+    return count;
+}
+//# sourceMappingURL=test.js.map

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Get the Convex deployment URL
+ */
+export declare function getConvexUrl(): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,16 @@
+/**
+ * Production Convex deployment URL
+ * All users connect to the same backend
+ */
+const CONVEX_URL = 'https://data.dotrequirements.io';
+/**
+ * Get the Convex deployment URL
+ */
+export function getConvexUrl() {
+    // Show deprecation warning if user has CONVEX_URL in their env
+    if (process.env.CONVEX_URL) {
+        console.warn('⚠️  CONVEX_URL is no longer needed and will be ignored. You can safely remove it from your .env.local');
+    }
+    return CONVEX_URL;
+}
+//# sourceMappingURL=config.js.map

package/dist/convex.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Convex API stub for CLI usage
+ * This will be replaced with actual generated types when linked to the Convex backend
+ */
+export declare const api: {
+    documents: {
+        queries: {
+            exportForCli: any;
+            exportProjectForCli: any;
+            checkDocumentsExist: any;
+            getDocumentsMetadata: any;
+        };
+        mutations: {
+            create: any;
+            update: any;
+        };
+        saveWithRequirements: {
+            saveWithRequirements: any;
+        };
+    };
+    requirements: {
+        queries: {
+            listByProject: any;
+        };
+        mutations: {
+            bulkUpdate: any;
+        };
+    };
+    projects: {
+        mutations: {
+            create: any;
+        };
+    };
+    teams: {
+        queries: {
+            listForUserWithUsage: any;
+        };
+    };
+    projectSecrets: {
+        queries: {
+            getOwnSecret: any;
+            listOwnSecretsForTeam: any;
+        };
+        mutations: {
+            ensureOwnSecret: any;
+            revokeOwnSecret: any;
+        };
+    };
+    lib: {
+        authActions: {
+            exchangeAuthorizationCode: any;
+            refreshAccessToken: any;
+        };
+    };
+};
+//# sourceMappingURL=convex.d.ts.map

package/dist/convex.js

@@ -0,0 +1,58 @@
+/**
+ * Convex API stub for CLI usage
+ * This will be replaced with actual generated types when linked to the Convex backend
+ */
+export const api = {
+    documents: {
+        queries: {
+            exportForCli: 'documents/queries:exportForCli',
+            exportProjectForCli: 'documents/queries:exportProjectForCli',
+            checkDocumentsExist: 'documents/queries:checkDocumentsExist',
+            // SYNC-CLI-EDIT-2: Get document metadata for conflict detection
+            getDocumentsMetadata: 'documents/queries:getDocumentsMetadata',
+        },
+        mutations: {
+            create: 'documents/mutations:create',
+            update: 'documents/mutations:update',
+        },
+        // SYNC-ARCH-1: Save document with requirements derivation
+        saveWithRequirements: {
+            saveWithRequirements: 'documents/saveWithRequirements:saveWithRequirements',
+        },
+    },
+    requirements: {
+        queries: {
+            listByProject: 'requirements/queries:listByProject',
+        },
+        mutations: {
+            bulkUpdate: 'requirements/mutations:bulkUpdate',
+        },
+    },
+    projects: {
+        mutations: {
+            create: 'projects/mutations:create',
+        },
+    },
+    teams: {
+        queries: {
+            listForUserWithUsage: 'teams/queries:listForUserWithUsage',
+        },
+    },
+    projectSecrets: {
+        queries: {
+            getOwnSecret: 'projectSecrets/queries:getOwnSecret',
+            listOwnSecretsForTeam: 'projectSecrets/queries:listOwnSecretsForTeam',
+        },
+        mutations: {
+            ensureOwnSecret: 'projectSecrets/mutations:ensureOwnSecret',
+            revokeOwnSecret: 'projectSecrets/mutations:revokeOwnSecret',
+        },
+    },
+    lib: {
+        authActions: {
+            exchangeAuthorizationCode: 'lib/authActions:exchangeAuthorizationCode',
+            refreshAccessToken: 'lib/authActions:refreshAccessToken',
+        },
+    },
+};
+//# sourceMappingURL=convex.js.map

package/dist/harness/cache.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Cache management for the test harness.
+ *
+ * Manages the .requirements/.cache/ directory with:
+ * - lookup.json: Pre-resolved requirements for fast path resolution
+ * - tracking.jsonl: Append-only tracking of requirement() calls (cross-process safe)
+ * - coverage.json: Deduplication cache for cloud reporting
+ */
+import { type RequirementNode } from '../schema/index.js';
+/**
+ * Tracking entry for a single requirement() call.
+ * Stored as one JSON object per line in tracking.jsonl
+ */
+export interface TrackingEntry {
+    /** Full requirement path (e.g., 'REQ-123.given' or 'REQ-123.0.1') */
+    requirementKey: string;
+    /** Source file and line (e.g., 'auth.test.ts:42') */
+    callerLocation: string;
+    /** Timestamp of the call */
+    timestamp: number;
+    /** Test run ID for grouping */
+    testRunId: string;
+}
+/**
+ * Structure of the lookup.json cache
+ */
+export interface LookupCache {
+    /** When the cache was generated */
+    generatedAt: string;
+    /** Map of requirement ID to flattened requirement data */
+    requirements: Record<string, {
+        id: string;
+        label: string;
+        content: string;
+    }>;
+}
+/**
+ * Structure of the coverage.json cache (for cloud deduplication)
+ */
+export interface CoverageCache {
+    current: {
+        testRunId: string;
+        timestamp: number;
+        requirementKeys: string[];
+    } | null;
+    previous: {
+        testRunId: string;
+        timestamp: number;
+        requirementKeys: string[];
+    } | null;
+}
+/**
+ * Find the nearest .requirements directory by walking up from startDir
+ */
+export declare function findRequirementsDir(startDir?: string): string | null;
+/**
+ * Find the project root (directory containing .requirements)
+ */
+export declare function findProjectRoot(startDir?: string): string | null;
+/**
+ * Get the cache directory path, creating it if necessary
+ */
+export declare function getCacheDir(requirementsDir: string, create?: boolean): string;
+/**
+ * Find the dotrequirements project root by looking for .env.local with credentials.
+ * Falls back to finding .requirements directory if no credentials found.
+ */
+export declare function findProjectRootWithCredentials(startDir?: string): string;
+/**
+ * Find all *.requirements.md files under project root
+ */
+export declare function findRequirementsFiles(projectRoot: string): string[];
+/**
+ * Write the lookup cache with all pre-parsed requirements
+ */
+export declare function writeLookupCache(requirementsDir: string, requirements: RequirementNode[]): void;
+/**
+ * Read the lookup cache, returning null if not found or invalid
+ */
+export declare function readLookupCache(requirementsDir: string): LookupCache | null;
+/**
+ * Generate and store a unique test run ID
+ */
+export declare function initTestRunId(requirementsDir: string): string;
+/**
+ * Get the current test run ID, or null if not initialized
+ */
+export declare function getTestRunId(requirementsDir: string): string | null;
+/**
+ * Clean up the test run ID file
+ */
+export declare function cleanupTestRunId(requirementsDir: string): void;
+/**
+ * Write the project root to cache (for cross-process persistence).
+ * This allows test workers to find the lookup cache even after cwd changes.
+ */
+export declare function writeProjectRoot(requirementsDir: string, projectRoot: string): void;
+/**
+ * Read the project root from cache, returning null if not found.
+ */
+export declare function readProjectRoot(requirementsDir: string): string | null;
+/**
+ * Try to find the project root from any known .requirements cache directory.
+ * Walks up from cwd looking for .requirements/.cache/project-root file.
+ */
+export declare function findCachedProjectRoot(startDir?: string): string | null;
+/**
+ * Clear tracking data for a new test run
+ */
+export declare function clearTrackingFile(requirementsDir: string): void;
+/**
+ * Append a tracking entry to the JSONL file (cross-process safe)
+ */
+export declare function appendTrackingEntry(requirementsDir: string, entry: TrackingEntry): void;
+/**
+ * Read all tracking entries from the JSONL file
+ */
+export declare function readTrackingEntries(requirementsDir: string): TrackingEntry[];
+/**
+ * Delete the tracking file after finalize
+ */
+export declare function deleteTrackingFile(requirementsDir: string): void;
+/**
+ * Read the coverage cache for cloud deduplication
+ */
+export declare function readCoverageCache(requirementsDir: string): CoverageCache;
+/**
+ * Update the coverage cache after reporting
+ */
+export declare function updateCoverageCache(requirementsDir: string, testRunId: string, requirementKeys: string[]): void;
+/**
+ * Check if a requirement needs reporting based on coverage cache
+ */
+export declare function needsReporting(requirementKey: string, cache: CoverageCache): boolean;
+//# sourceMappingURL=cache.d.ts.map