@popoverai/dotrequirements 0.23.0 → 0.24.0

package/dist/commands/pull.js

@@ -1,130 +1,125 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import { ConvexHttpClient } from 'convex/browser';
-import { getConvexUrl } from '../config.js';
-import { buildRequirementsFile } from '../schema/index.js';
-import { api } from '../convex.js';
-import { brand } from '../utils/brand.js';
-import { findRequirementsFiles } from '../mcp/requirements.js';
-import { getProjectCredentials } from '../utils/project-settings.js';
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ConvexHttpClient } from "convex/browser";
+import { getConvexUrl } from "../config.js";
+import { api } from "../convex.js";
+import { findRequirementsFiles } from "../requirements/index.js";
+import { buildRequirementsFile } from "../schema/index.js";
+import { brand } from "../utils/brand.js";
+import { getProjectCredentials } from "../utils/project-settings.js";
 export async function pullCommand(options) {
-    try {
-        // Connect to Convex
-        const convexUrl = getConvexUrl();
-        const client = new ConvexHttpClient(convexUrl);
-        let documents;
-        let projectName;
-        let isShareTokenFlow = false;
-        // SHARE-TOKEN-CLI-1: Handle share token flow (no project config needed)
-        if (options.share) {
-            isShareTokenFlow = true;
-            console.log(`Pulling requirements with share token...`);
-            try {
-                // SHARE-TOKEN-CLI-1.1: Pass only projectSecret, no projectSlug
-                // The authzQueryReadOnly wrapper will resolve project from the token
-                const result = await client.query(api.documents.queries.exportProjectForCli, {
-                    projectAuth: {
-                        projectSecret: options.share,
-                    },
-                });
-                documents = result.documents;
-                projectName = result.projectName;
-                // SHARE-TOKEN-CLI-1.2: Display project name in output
-                console.log(`\nProject: "${projectName}"`);
-            }
-            catch (error) {
-                // SHARE-TOKEN-CLI-2: Handle invalid/revoked tokens gracefully
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                if (errorMessage.includes('Invalid share token')) {
-                    throw new Error('Invalid share token. The token may be incorrect or has been revoked.\n' +
-                        'Please request a new share token from your team.');
-                }
-                throw error;
-            }
+    // Connect to Convex
+    const convexUrl = getConvexUrl();
+    const client = new ConvexHttpClient(convexUrl);
+    let documents;
+    let projectName;
+    let isShareTokenFlow = false;
+    // SHARE-TOKEN-CLI-1: Handle share token flow (no project config needed)
+    if (options.share) {
+        isShareTokenFlow = true;
+        console.log(`Pulling requirements with share token...`);
+        try {
+            // SHARE-TOKEN-CLI-1.1: Pass only projectSecret, no projectSlug
+            // The authzQueryReadOnly wrapper will resolve project from the token
+            const result = await client.query(api.documents.queries.exportProjectForCli, {
+                projectAuth: {
+                    projectSecret: options.share,
+                },
+            });
+            documents = result.documents;
+            projectName = result.projectName;
+            // SHARE-TOKEN-CLI-1.2: Display project name in output
+            console.log(`\nProject: "${projectName}"`);
         }
-        else {
-            console.log(`Syncing requirements from ${brand} cloud...`);
-            // Get project credentials from .requirements/project-settings.json
-            // This throws helpful errors if project not found or not connected to cloud
-            const credentials = getProjectCredentials();
-            // Allow --project flag to override, but still need secret from settings
-            const projectId = options.project ?? credentials.projectId;
-            const projectSecret = credentials.projectSecret;
-            // Fetch documents
-            if (options.document) {
-                // Fetch specific document
-                const doc = await client.query(api.documents.queries.exportForCli, {
-                    projectAuth: {
-                        projectSlug: projectId,
-                        projectSecret,
-                    },
-                    target: { type: 'document', id: options.document },
-                    documentId: options.document,
-                });
-                documents = doc ? [doc] : [];
-            }
-            else if (projectId) {
-                // Fetch all documents for project
-                // SYNC-ARCH-3.1: Use projectSlug (not projectId) since env stores the slug
-                const result = await client.query(api.documents.queries.exportProjectForCli, {
-                    projectAuth: {
-                        projectSlug: projectId,
-                        projectSecret,
-                    },
-                });
-                documents = result.documents;
-                projectName = result.projectName;
-            }
-            else {
-                throw new Error('Either --project or --document must be specified');
+        catch (error) {
+            // SHARE-TOKEN-CLI-2: Handle invalid/revoked tokens gracefully
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage.includes("Invalid share token")) {
+                throw new Error("Invalid share token. The token may be incorrect or has been revoked.\n" +
+                    "Please request a new share token from your team.");
             }
+            throw error;
         }
-        if (documents.length === 0) {
-            console.log('No documents found.');
-            return;
-        }
-        // Ensure .requirements/ directory exists (for new documents)
-        const requirementsDir = path.join(process.cwd(), '.requirements');
-        if (!fs.existsSync(requirementsDir)) {
-            fs.mkdirSync(requirementsDir, { recursive: true });
+    }
+    else {
+        console.log(`Syncing requirements from ${brand} cloud...`);
+        // Get project credentials from .requirements/project-settings.json
+        // This throws helpful errors if project not found or not connected to cloud
+        const credentials = getProjectCredentials();
+        // Allow --project flag to override, but still need secret from settings
+        const projectId = options.project ?? credentials.projectId;
+        const projectSecret = credentials.projectSecret;
+        // Fetch documents
+        if (options.document) {
+            // Fetch specific document
+            const doc = await client.query(api.documents.queries.exportForCli, {
+                projectAuth: {
+                    projectSlug: projectId,
+                    projectSecret,
+                },
+                target: { type: "document", id: options.document },
+                documentId: options.document,
+            });
+            documents = doc ? [doc] : [];
         }
-        // Build index of existing files by document ID (search entire workspace)
-        const existingFilesByDocId = await buildDocumentIdIndex(process.cwd());
-        // Write each document as a Markdown file
-        for (const doc of documents) {
-            // Check if an existing file has this document ID
-            const existingFilePath = existingFilesByDocId.get(doc.documentId);
-            const filePath = existingFilePath ?? path.join(requirementsDir, sanitizeFileName(doc.title) + '.requirements.md');
-            const fileName = path.basename(filePath);
-            // Build metadata with pulledAt for conflict detection
-            // SYNC-CLI-EDIT-2: pulledAt is compared with cloud updatedAt during push
-            const metadata = {
-                pulledAt: new Date().toISOString(),
-                version: doc.version,
-                document: {
-                    id: doc.documentId,
-                    title: doc.title,
-                    defaultPrefix: doc.defaultPrefix,
+        else if (projectId) {
+            // Fetch all documents for project
+            // SYNC-ARCH-3.1: Use projectSlug (not projectId) since env stores the slug
+            const result = await client.query(api.documents.queries.exportProjectForCli, {
+                projectAuth: {
+                    projectSlug: projectId,
+                    projectSecret,
                 },
-            };
-            // SYNC-ARCH-1: Use markdownContent directly from cloud (source of truth)
-            // No need to rebuild from requirements - just combine with frontmatter
-            const fileContent = buildRequirementsFile(metadata, doc.markdownContent);
-            fs.writeFileSync(filePath, fileContent, 'utf-8');
-            console.log(`✓ Synced: ${fileName} (version ${doc.version})`);
+            });
+            documents = result.documents;
+            projectName = result.projectName;
         }
-        console.log(`\nSuccessfully synced ${documents.length} document(s) to .requirements/`);
-        // SHARE-TOKEN-CLI-3: Show next steps for share token users
-        if (isShareTokenFlow) {
-            console.log('\n─────────────────────────────────────────────────────────');
-            console.log('Next steps to get full access (push, coverage):');
-            console.log('  Run: dotrequirements link');
-            console.log('─────────────────────────────────────────────────────────');
+        else {
+            throw new Error("Either --project or --document must be specified");
         }
     }
-    catch (error) {
-        // Re-throw to let the CLI error handler display it cleanly
-        throw error;
+    if (documents.length === 0) {
+        console.log("No documents found.");
+        return;
+    }
+    // Ensure .requirements/ directory exists (for new documents)
+    const requirementsDir = path.join(process.cwd(), ".requirements");
+    if (!fs.existsSync(requirementsDir)) {
+        fs.mkdirSync(requirementsDir, { recursive: true });
+    }
+    // Build index of existing files by document ID (search entire workspace)
+    const existingFilesByDocId = await buildDocumentIdIndex(process.cwd());
+    // Write each document as a Markdown file
+    for (const doc of documents) {
+        // Check if an existing file has this document ID
+        const existingFilePath = existingFilesByDocId.get(doc.documentId);
+        const filePath = existingFilePath ??
+            path.join(requirementsDir, `${sanitizeFileName(doc.title)}.requirements.md`);
+        const fileName = path.basename(filePath);
+        // Build metadata with pulledAt for conflict detection
+        // SYNC-CLI-EDIT-2: pulledAt is compared with cloud updatedAt during push
+        const metadata = {
+            pulledAt: new Date().toISOString(),
+            version: doc.version,
+            document: {
+                id: doc.documentId,
+                title: doc.title,
+                defaultPrefix: doc.defaultPrefix,
+            },
+        };
+        // SYNC-ARCH-1: Use markdownContent directly from cloud (source of truth)
+        // No need to rebuild from requirements - just combine with frontmatter
+        const fileContent = buildRequirementsFile(metadata, doc.markdownContent);
+        fs.writeFileSync(filePath, fileContent, "utf-8");
+        console.log(`✓ Synced: ${fileName} (version ${doc.version})`);
+    }
+    console.log(`\nSuccessfully synced ${documents.length} document(s) to .requirements/`);
+    // SHARE-TOKEN-CLI-3: Show next steps for share token users
+    if (isShareTokenFlow) {
+        console.log("\n─────────────────────────────────────────────────────────");
+        console.log("Next steps to get full access (push, coverage):");
+        console.log("  Run: dotrequirements link");
+        console.log("─────────────────────────────────────────────────────────");
     }
 }
 /**
@@ -133,8 +128,8 @@ export async function pullCommand(options) {
 function sanitizeFileName(title) {
     return title
         .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '');
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
 }
 /**
  * Build an index mapping document IDs to their file paths.
@@ -159,7 +154,7 @@ async function buildDocumentIdIndex(workspaceRoot) {
  */
 function extractDocumentIdFromFile(filePath) {
     try {
-        const content = fs.readFileSync(filePath, 'utf-8');
+        const content = fs.readFileSync(filePath, "utf-8");
         // Match document.id in YAML frontmatter - handles both inline and nested formats
         // Inline: document: { id: "abc123", ... }
         // Nested (id: can appear at any position within the indented document block):

package/dist/commands/push.js

@@ -1,120 +1,114 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import * as readline from 'readline';
-import { brand } from '../utils/brand.js';
-import { findRequirementsFiles } from '../mcp/requirements.js';
-import { getProjectCredentials } from '../utils/project-settings.js';
-import { getConvexUrl } from '../config.js';
-import { parseFilesForPush, dryRunPush, executePush, } from '../push/index.js';
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { getConvexUrl } from "../config.js";
+import { dryRunPush, executePush, parseFilesForPush, } from "../push/index.js";
+import { findRequirementsFiles } from "../requirements/index.js";
+import { brand } from "../utils/brand.js";
+import { getProjectCredentials } from "../utils/project-settings.js";
 export async function pushCommand(file, options) {
-    try {
-        console.log(`Preparing to push requirements to ${brand} cloud...\n`);
-        // Get project credentials from .requirements/project-settings.json
-        // This throws helpful errors if project not found or not connected to cloud
-        const { projectId, projectSecret } = getProjectCredentials();
-        // Determine which files to push
-        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];
+    console.log(`Preparing to push requirements to ${brand} cloud...\n`);
+    // Get project credentials from .requirements/project-settings.json
+    // This throws helpful errors if project not found or not connected to cloud
+    const { projectId, projectSecret } = getProjectCredentials();
+    // Determine which files to push
+    let filesToPush;
+    if (file) {
+        // Push specific file
+        const filePath = path.resolve(file);
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`File not found: ${file}`);
         }
-        else {
-            // SYNC-DISCOVERY-1.0: Push all *.requirements.md files in workspace (not just .requirements/)
-            const workspaceRoot = process.cwd();
-            filesToPush = await findRequirementsFiles(workspaceRoot);
-            if (filesToPush.length === 0) {
-                console.log('No *.requirements.md files found. Nothing to push.');
-                return;
-            }
-        }
-        // Parse all local files
-        console.log('Parsing local requirements...');
-        const { parsedFiles, totalRequirements } = parseFilesForPush(filesToPush);
-        // Log file parsing progress
-        for (const file of parsedFiles) {
-            const fileName = path.basename(file.filePath);
-            const doc = file.metadata.document;
-            if (doc?.defaultPrefix && !file.metadata.document?.defaultPrefix) {
-                console.log(`  Reading ${fileName}...`);
-                console.log(`    Inferred defaultPrefix "${doc.defaultPrefix}" from first requirement`);
-            }
-            else {
-                console.log(`  Reading ${fileName}...`);
-            }
-        }
-        console.log(`\nFound ${totalRequirements} requirement(s) in ${parsedFiles.length} document(s).\n`);
-        // Build credentials
-        const credentials = {
-            projectId,
-            projectSecret,
-            convexUrl: getConvexUrl(),
-        };
-        // Phase 1: Dry run
-        console.log('Validating documents...');
-        const dryRunResult = await dryRunPush(parsedFiles, credentials);
-        // Display unified summary
-        displayDryRunSummary(dryRunResult);
-        // Check if there's anything to push
-        const pushableCount = dryRunResult.updates.length +
-            dryRunResult.creates.length +
-            dryRunResult.notFound.length;
-        if (pushableCount === 0) {
-            console.log('No valid documents to push.');
+        filesToPush = [filePath];
+    }
+    else {
+        // SYNC-DISCOVERY-1.0: Push all *.requirements.md files in workspace (not just .requirements/)
+        const workspaceRoot = process.cwd();
+        filesToPush = await findRequirementsFiles(workspaceRoot);
+        if (filesToPush.length === 0) {
+            console.log("No *.requirements.md files found. Nothing to push.");
             return;
         }
-        // Single confirmation prompt
-        if (!options.yes) {
-            const hasConflicts = dryRunResult.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;
-            }
+    }
+    // Parse all local files
+    console.log("Parsing local requirements...");
+    const { parsedFiles, totalRequirements } = parseFilesForPush(filesToPush);
+    // Log file parsing progress
+    for (const file of parsedFiles) {
+        const fileName = path.basename(file.filePath);
+        const doc = file.metadata.document;
+        if (doc?.defaultPrefix && !file.metadata.document?.defaultPrefix) {
+            console.log(`  Reading ${fileName}...`);
+            console.log(`    Inferred defaultPrefix "${doc.defaultPrefix}" from first requirement`);
         }
-        // Phase 2: Execute push
-        console.log('\nPushing documents to cloud...');
-        const result = await executePush(dryRunResult, credentials);
-        // Display results
-        for (const { file, result: dryResult } of [
-            ...dryRunResult.updates,
-            ...dryRunResult.creates,
-            ...dryRunResult.notFound,
-        ]) {
-            const fileName = path.basename(file.filePath);
-            const isCreate = dryResult.action === 'create' || dryResult.action === 'not_found';
-            // Check if this file had an error
-            const error = result.errors.find((e) => e.fileName === fileName);
-            if (error) {
-                console.log(`  ✗ Failed: ${fileName} - ${error.error}`);
-            }
-            else if (isCreate) {
-                console.log(`  ✓ Created: ${fileName} → ${file.metadata.document?.id}`);
-            }
-            else {
-                console.log(`  ✓ Updated: ${fileName}`);
-            }
+        else {
+            console.log(`  Reading ${fileName}...`);
         }
-        console.log(`\n✓ Push complete!`);
-        if (result.created > 0) {
-            console.log(`  Created: ${result.created} document(s)`);
+    }
+    console.log(`\nFound ${totalRequirements} requirement(s) in ${parsedFiles.length} document(s).\n`);
+    // Build credentials
+    const credentials = {
+        projectId,
+        projectSecret,
+        convexUrl: getConvexUrl(),
+    };
+    // Phase 1: Dry run
+    console.log("Validating documents...");
+    const dryRunResult = await dryRunPush(parsedFiles, credentials);
+    // Display unified summary
+    displayDryRunSummary(dryRunResult);
+    // Check if there's anything to push
+    const pushableCount = dryRunResult.updates.length +
+        dryRunResult.creates.length +
+        dryRunResult.notFound.length;
+    if (pushableCount === 0) {
+        console.log("No valid documents to push.");
+        return;
+    }
+    // Single confirmation prompt
+    if (!options.yes) {
+        const hasConflicts = dryRunResult.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...");
+    const result = await executePush(dryRunResult, credentials);
+    // Display results
+    for (const { file, result: dryResult } of [
+        ...dryRunResult.updates,
+        ...dryRunResult.creates,
+        ...dryRunResult.notFound,
+    ]) {
+        const fileName = path.basename(file.filePath);
+        const isCreate = dryResult.action === "create" || dryResult.action === "not_found";
+        // Check if this file had an error
+        const error = result.errors.find((e) => e.fileName === fileName);
+        if (error) {
+            console.log(`  ✗ Failed: ${fileName} - ${error.error}`);
         }
-        if (result.updated > 0) {
-            console.log(`  Updated: ${result.updated} document(s)`);
+        else if (isCreate) {
+            console.log(`  ✓ Created: ${fileName} → ${file.metadata.document?.id}`);
         }
-        if (result.created === 0 && result.updated === 0) {
-            console.log('  No documents were pushed.');
+        else {
+            console.log(`  ✓ Updated: ${fileName}`);
         }
     }
-    catch (error) {
-        // Re-throw to let the CLI error handler display it cleanly
-        throw error;
+    console.log(`\n✓ Push complete!`);
+    if (result.created > 0) {
+        console.log(`  Created: ${result.created} document(s)`);
+    }
+    if (result.updated > 0) {
+        console.log(`  Updated: ${result.updated} document(s)`);
+    }
+    if (result.created === 0 && result.updated === 0) {
+        console.log("  No documents were pushed.");
     }
 }
 /**
@@ -122,14 +116,14 @@ export async function pushCommand(file, options) {
  */
 function displayDryRunSummary(dryRunResult) {
     const { updates, creates, notFound, invalid, conflicts } = dryRunResult;
-    console.log('\n=== Push Summary ===\n');
+    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})` : '';
+            const conflictNote = hasConflict ? " ⚠️  [cloud changed since pull]" : "";
+            const warningNote = result.warning ? ` (${result.warning})` : "";
             console.log(`  ~ ${fileName}${conflictNote}${warningNote}`);
         }
         console.log();
@@ -138,7 +132,7 @@ function displayDryRunSummary(dryRunResult) {
         console.log(`New documents (${creates.length}):`);
         for (const { file, result } of creates) {
             const fileName = path.basename(file.filePath);
-            const warningNote = result.warning ? ` (${result.warning})` : '';
+            const warningNote = result.warning ? ` (${result.warning})` : "";
             console.log(`  + ${fileName}${warningNote}`);
         }
         console.log();
@@ -171,7 +165,7 @@ function confirm(question) {
     return new Promise((resolve) => {
         rl.question(question, (answer) => {
             rl.close();
-            resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+            resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
         });
     });
 }

package/dist/commands/report.d.ts

@@ -1,7 +1,11 @@
+import { type CoverageEntry } from "../requirements/coverage.js";
 interface ReportOptions {
-    format?: 'console' | 'json' | 'markdown';
+    source?: "local" | "cloud";
+    format?: "console" | "json" | "markdown";
     requirement?: string;
+    branch?: string;
+    since?: number;
 }
 export declare function reportCommand(options: ReportOptions): Promise<void>;
-export {};
+export type { CoverageEntry };
 //# sourceMappingURL=report.d.ts.map