@popoverai/dotrequirements 0.15.0 → 0.17.0

package/dist/commands/push.d.ts

@@ -2,10 +2,5 @@ interface PushOptions {
     yes?: boolean;
 }
 export declare function pushCommand(file: string | undefined, options: PushOptions): Promise<void>;
-/**
- * Extract markdown content from a file, stripping YAML frontmatter.
- * Exported for testing.
- */
-export declare function extractMarkdownContent(rawContent: string): string;
 export {};
 //# sourceMappingURL=push.d.ts.map

package/dist/commands/push.js

@@ -1,13 +1,11 @@
 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 { 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';
 export async function pushCommand(file, options) {
     try {
         console.log(`Preparing to push requirements to ${brand} cloud...\n`);
@@ -35,164 +33,42 @@ export async function pushCommand(file, options) {
         }
         // 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 = [];
+        const { parsedFiles, totalRequirements } = parseFilesForPush(filesToPush);
+        // Log file parsing progress
         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,
-                    },
-                });
+            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`);
             }
-        }
-        // 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 });
-                    }
-                }
+            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
-        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();
-        }
+        displayDryRunSummary(dryRunResult);
         // Check if there's anything to push
-        const pushableFiles = [...updates, ...creates, ...notFound];
-        if (pushableFiles.length === 0) {
+        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 = conflicts.length > 0;
+            const hasConflicts = dryRunResult.conflicts.length > 0;
             const prompt = hasConflicts
                 ? 'Continue with push? (will overwrite cloud changes) [y/N] '
                 : 'Continue with push? [y/N] ';
@@ -204,59 +80,35 @@ export async function pushCommand(file, options) {
         }
         // 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 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);
-            // 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++;
-                }
+            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}`);
             }
-            catch (err) {
-                console.error(`  ✗ Failed: ${fileName} - ${err.message}`);
+            else if (isCreate) {
+                console.log(`  ✓ Created: ${fileName} → ${file.metadata.document?.id}`);
+            }
+            else {
+                console.log(`  ✓ Updated: ${fileName}`);
             }
         }
         console.log(`\n✓ Push complete!`);
-        if (created > 0) {
-            console.log(`  Created: ${created} document(s)`);
+        if (result.created > 0) {
+            console.log(`  Created: ${result.created} document(s)`);
         }
-        if (updated > 0) {
-            console.log(`  Updated: ${updated} document(s)`);
+        if (result.updated > 0) {
+            console.log(`  Updated: ${result.updated} document(s)`);
         }
-        if (created === 0 && updated === 0) {
+        if (result.created === 0 && result.updated === 0) {
             console.log('  No documents were pushed.');
         }
     }
@@ -266,16 +118,47 @@ export async function pushCommand(file, options) {
     }
 }
 /**
- * Extract markdown content from a file, stripping YAML frontmatter.
- * Exported for testing.
+ * Display the dry run summary.
  */
-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);
+function displayDryRunSummary(dryRunResult) {
+    const { updates, creates, notFound, invalid, conflicts } = dryRunResult;
+    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();
     }
-    return rawContent;
 }
 /**
  * Prompt user for confirmation

package/dist/harness/cache.d.ts

@@ -70,7 +70,8 @@ export declare function findRequirementsFiles(projectRoot: string): string[];
  */
 export declare function writeLookupCache(requirementsDir: string, requirements: RequirementNode[]): void;
 /**
- * Read the lookup cache, returning null if not found or invalid
+ * Read the lookup cache, returning null if not found, invalid, or stale.
+ * Cache is considered stale if any .requirements.md file is newer than the cache.
  */
 export declare function readLookupCache(requirementsDir: string): LookupCache | null;
 /**

package/dist/harness/cache.js

@@ -101,7 +101,28 @@ export function writeLookupCache(requirementsDir, requirements) {
     fs.writeFileSync(lookupPath, JSON.stringify(lookup, null, 2));
 }
 /**
- * Read the lookup cache, returning null if not found or invalid
+ * Check if any source file is newer than the cache file.
+ * Returns true if cache is stale and should be invalidated.
+ */
+function isCacheStale(requirementsDir, cacheMtime) {
+    const projectRoot = path.dirname(requirementsDir);
+    const sourceFiles = findRequirementsFiles(projectRoot);
+    for (const file of sourceFiles) {
+        try {
+            const stat = fs.statSync(file);
+            if (stat.mtimeMs > cacheMtime) {
+                return true;
+            }
+        }
+        catch {
+            // File might have been deleted, ignore
+        }
+    }
+    return false;
+}
+/**
+ * Read the lookup cache, returning null if not found, invalid, or stale.
+ * Cache is considered stale if any .requirements.md file is newer than the cache.
  */
 export function readLookupCache(requirementsDir) {
     const cacheDir = getCacheDir(requirementsDir);
@@ -109,6 +130,16 @@ export function readLookupCache(requirementsDir) {
     if (!fs.existsSync(lookupPath)) {
         return null;
     }
+    // Check if cache is stale (any source file newer than cache)
+    try {
+        const cacheStat = fs.statSync(lookupPath);
+        if (isCacheStale(requirementsDir, cacheStat.mtimeMs)) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
     try {
         const content = fs.readFileSync(lookupPath, 'utf-8');
         return JSON.parse(content);

package/dist/mcp/convexClient.d.ts

@@ -47,5 +47,12 @@ export declare function getProjectCoverage(projectId: string, projectSecret: str
     }>;
     untested: string[];
 }>;
+/**
+ * PROJ-CONTEXT-7: Query Convex for project context (AI style guidelines)
+ */
+export declare function getProjectContext(projectId: string, projectSecret: string, convexUrl: string): Promise<{
+    projectContext: string | null;
+    requirementsStyleContext: string | null;
+} | null>;
 export {};
 //# sourceMappingURL=convexClient.d.ts.map

package/dist/mcp/convexClient.js

@@ -47,7 +47,11 @@ export async function getRequirementCoverage(requirementKey, projectId, projectS
     if (!response.ok) {
         throw new Error(`Failed to query coverage: ${response.statusText}`);
     }
-    return await response.json();
+    const json = await response.json();
+    if (json.status === 'error') {
+        throw new Error(`Convex query failed: ${json.errorMessage}`);
+    }
+    return json.value;
 }
 /**
  * Query Convex for project coverage summary
@@ -76,6 +80,50 @@ export async function getProjectCoverage(projectId, projectSecret, convexUrl, op
     if (!response.ok) {
         throw new Error(`Failed to query coverage: ${response.statusText}`);
     }
-    return await response.json();
+    const json = await response.json();
+    if (json.status === 'error') {
+        throw new Error(`Convex query failed: ${json.errorMessage}`);
+    }
+    return json.value;
+}
+/**
+ * PROJ-CONTEXT-7: Query Convex for project context (AI style guidelines)
+ */
+export async function getProjectContext(projectId, projectSecret, convexUrl) {
+    try {
+        const response = await fetch(`${convexUrl}/api/query`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                path: 'projects/queries:get',
+                args: {
+                    projectAuth: {
+                        projectSlug: projectId,
+                        projectSecret,
+                    },
+                    target: {
+                        type: 'project',
+                        slug: projectId,
+                    },
+                },
+                format: 'json',
+            }),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const json = await response.json();
+        if (json.status === 'error' || !json.value) {
+            return null;
+        }
+        return {
+            projectContext: json.value.projectContext ?? null,
+            requirementsStyleContext: json.value.requirementsStyleContext ?? null,
+        };
+    }
+    catch {
+        // Non-fatal: return null if query fails
+        return null;
+    }
 }
 //# sourceMappingURL=convexClient.js.map

package/dist/mcp/handlers/authoring.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Authoring handlers for MCP tools
+ *
+ * Provides document creation and validation:
+ * - create_requirement_document: Generate requirements template with format guidance
+ * - validate_requirements: Validate requirements file syntax offline
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for create_requirement_document tool
+ */
+export interface CreateRequirementDocumentArgs {
+    filePath?: string;
+}
+/**
+ * Arguments for validate_requirements tool
+ */
+export interface ValidateRequirementsArgs {
+    filePath: string;
+}
+/**
+ * Handler for create_requirement_document tool
+ *
+ * Requirements covered:
+ * - MCP-AUTHOR-1.0: The template includes format guidance with code block examples
+ * - MCP-AUTHOR-1.1: The template includes guidance on concrete examples, concise prose, and testable conditions
+ * - MCP-AUTHOR-1.2: When the project has requirementsStyleContext configured, it is included in the template
+ * - MCP-AUTHOR-1.3: When cloud credentials are unavailable, the template works without the custom context
+ */
+export declare function handleCreateRequirementDocument(args: CreateRequirementDocumentArgs, context: HandlerContext): Promise<ToolResponse>;
+/**
+ * Handler for validate_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-AUTHOR-2.0: When the file has valid syntax, the response confirms validation passed
+ * - MCP-AUTHOR-2.1: When the file has syntax errors, the response lists each error with location
+ * - MCP-AUTHOR-2.2: Validation does not require network access or cloud credentials
+ * - MCP-AUTHOR-2.3: When the file does not exist, an error is returned
+ */
+export declare function handleValidateRequirements(args: ValidateRequirementsArgs, context: HandlerContext): Promise<ToolResponse>;
+//# sourceMappingURL=authoring.d.ts.map