@popoverai/dotrequirements 0.14.0 → 0.16.0

package/dist/push/core.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared push logic for CLI and MCP.
+ *
+ * This module contains the core push functionality that both the CLI push command
+ * and MCP push_requirements tool use. It handles:
+ * - Parsing local files
+ * - Dry run validation with Convex
+ * - Conflict detection
+ * - Executing the push
+ * - Updating local files with document IDs and timestamps
+ */
+import type { Metadata } from '../schema/index.js';
+export interface PushCredentials {
+    projectId: string;
+    projectSecret: string;
+    convexUrl: string;
+}
+/**
+ * Parsed file ready for push.
+ * SYNC-ARCH-1: Documents are the sync unit, not individual requirements.
+ */
+export interface ParsedFile {
+    filePath: string;
+    metadata: Metadata;
+    /** Raw file content (markdown with frontmatter stripped) */
+    markdownContent: string;
+    /** Requirement count for display */
+    requirementCount: number;
+}
+/**
+ * Cloud document metadata for conflict detection.
+ * SYNC-CLI-EDIT-2: Compare pulledAt with cloud updatedAt.
+ */
+export interface CloudDocumentMetadata {
+    documentId: string;
+    version: number;
+    updatedAt: number;
+}
+/**
+ * Dry run result from saveWithRequirements.
+ */
+export interface DryRunResultItem {
+    dryRun: true;
+    action: 'create' | 'update' | 'not_found' | 'invalid';
+    documentId?: string;
+    title?: string;
+    warning?: string;
+    error?: string;
+}
+/**
+ * File with its dry run result.
+ */
+export interface FileWithDryRun {
+    file: ParsedFile;
+    result: DryRunResultItem;
+}
+/**
+ * Conflict information for a file.
+ */
+export interface ConflictInfo {
+    item: FileWithDryRun;
+    cloudMeta: CloudDocumentMetadata;
+}
+/**
+ * Result of the dry run phase.
+ */
+export interface DryRunResult {
+    updates: FileWithDryRun[];
+    creates: FileWithDryRun[];
+    notFound: FileWithDryRun[];
+    invalid: FileWithDryRun[];
+    conflicts: ConflictInfo[];
+    totalRequirements: number;
+}
+/**
+ * Result of the execute phase.
+ */
+export interface PushResult {
+    created: number;
+    updated: number;
+    errors: Array<{
+        fileName: string;
+        error: string;
+    }>;
+}
+/**
+ * Extract markdown content from a file, stripping YAML frontmatter.
+ */
+export declare function extractMarkdownContent(rawContent: string): string;
+/**
+ * Parse files for push. Returns parsed files with metadata and content.
+ */
+export declare function parseFilesForPush(filePaths: string[]): {
+    parsedFiles: ParsedFile[];
+    totalRequirements: number;
+};
+/**
+ * Execute dry run phase: validate all files against Convex and detect conflicts.
+ */
+export declare function dryRunPush(parsedFiles: ParsedFile[], credentials: PushCredentials): Promise<DryRunResult>;
+/**
+ * Execute the push: save all pushable files to Convex and update local files.
+ */
+export declare function executePush(dryRunResult: DryRunResult, credentials: PushCredentials): Promise<PushResult>;
+//# sourceMappingURL=core.d.ts.map

package/dist/push/core.js

@@ -0,0 +1,216 @@
+/**
+ * Shared push logic for CLI and MCP.
+ *
+ * This module contains the core push functionality that both the CLI push command
+ * and MCP push_requirements tool use. It handles:
+ * - Parsing local files
+ * - Dry run validation with Convex
+ * - Conflict detection
+ * - Executing the push
+ * - Updating local files with document IDs and timestamps
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { ConvexHttpClient } from 'convex/browser';
+import { parseRequirementsFromFile, getAllRequirements, parseRequirementKey, buildRequirementsFile, } from '../schema/index.js';
+import { api } from '../convex.js';
+// ============================================================================
+// Parsing
+// ============================================================================
+/**
+ * Extract markdown content from a file, stripping YAML frontmatter.
+ */
+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;
+}
+/**
+ * Parse files for push. Returns parsed files with metadata and content.
+ */
+export function parseFilesForPush(filePaths) {
+    const parsedFiles = [];
+    let totalRequirements = 0;
+    for (const filePath of filePaths) {
+        // 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;
+                }
+            }
+        }
+        parsedFiles.push({
+            filePath,
+            metadata: parsed.metadata,
+            markdownContent,
+            requirementCount: flatRequirements.length,
+        });
+        totalRequirements += flatRequirements.length;
+    }
+    return { parsedFiles, totalRequirements };
+}
+// ============================================================================
+// Dry Run
+// ============================================================================
+/**
+ * Execute dry run phase: validate all files against Convex and detect conflicts.
+ */
+export async function dryRunPush(parsedFiles, credentials) {
+    const client = new ConvexHttpClient(credentials.convexUrl);
+    const dryRunResults = [];
+    // Phase 1: Dry run to categorize all files
+    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: credentials.projectId,
+                    projectSecret: credentials.projectSecret,
+                },
+                target: { type: 'project', slug: credentials.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: credentials.projectId,
+                projectSecret: credentials.projectSecret,
+            },
+            target: { type: 'project', slug: credentials.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 });
+                }
+            }
+        }
+    }
+    return {
+        updates,
+        creates,
+        notFound,
+        invalid,
+        conflicts,
+        totalRequirements: parsedFiles.reduce((sum, f) => sum + f.requirementCount, 0),
+    };
+}
+// ============================================================================
+// Execute Push
+// ============================================================================
+/**
+ * Execute the push: save all pushable files to Convex and update local files.
+ */
+export async function executePush(dryRunResult, credentials) {
+    const client = new ConvexHttpClient(credentials.convexUrl);
+    const pushableFiles = [
+        ...dryRunResult.updates,
+        ...dryRunResult.creates,
+        ...dryRunResult.notFound,
+    ];
+    let created = 0;
+    let updated = 0;
+    const errors = [];
+    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: credentials.projectId,
+                    projectSecret: credentials.projectSecret,
+                },
+                target: { type: 'project', slug: credentials.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');
+                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');
+                updated++;
+            }
+        }
+        catch (err) {
+            errors.push({ fileName, error: err.message });
+        }
+    }
+    return { created, updated, errors };
+}
+//# sourceMappingURL=core.js.map

package/dist/push/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Push Module
+ *
+ * Shared push logic for syncing local requirements files to the cloud.
+ * Used by both CLI push command and MCP push_requirements tool.
+ */
+export { type PushCredentials, type ParsedFile, type CloudDocumentMetadata, type DryRunResultItem, type FileWithDryRun, type ConflictInfo, type DryRunResult, type PushResult, extractMarkdownContent, parseFilesForPush, dryRunPush, executePush, } from './core.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/push/index.js

@@ -0,0 +1,10 @@
+/**
+ * Push Module
+ *
+ * Shared push logic for syncing local requirements files to the cloud.
+ * Used by both CLI push command and MCP push_requirements tool.
+ */
+export { 
+// Functions
+extractMarkdownContent, parseFilesForPush, dryRunPush, executePush, } from './core.js';
+//# sourceMappingURL=index.js.map

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

@@ -20,6 +20,15 @@ export interface ProjectInfo {
     /** Credentials if cloud-connected */
     credentials?: ProjectSettings;
 }
+/**
+ * Get project credentials from environment variables.
+ * Used in CI/CD environments where credentials are passed via env vars
+ * rather than stored in project-settings.json.
+ *
+ * Requires both DOTREQ_PROJECT_ID and DOTREQ_PROJECT_SECRET to be set.
+ * Returns undefined if either is missing.
+ */
+export declare function getCredentialsFromEnv(): ProjectSettings | undefined;
 /**
  * Find the project root by walking up from startDir looking for .requirements/ folder
  * Returns the directory containing .requirements/, or undefined if not found

package/dist/utils/project-settings.js

@@ -2,6 +2,22 @@ import * as fs from 'fs';
 import * as path from 'path';
 const REQUIREMENTS_DIR = '.requirements';
 const SETTINGS_FILE = 'project-settings.json';
+/**
+ * Get project credentials from environment variables.
+ * Used in CI/CD environments where credentials are passed via env vars
+ * rather than stored in project-settings.json.
+ *
+ * Requires both DOTREQ_PROJECT_ID and DOTREQ_PROJECT_SECRET to be set.
+ * Returns undefined if either is missing.
+ */
+export function getCredentialsFromEnv() {
+    const projectId = process.env.DOTREQ_PROJECT_ID;
+    const projectSecret = process.env.DOTREQ_PROJECT_SECRET;
+    if (projectId && projectSecret) {
+        return { projectId, projectSecret };
+    }
+    return undefined;
+}
 /**
  * Find the project root by walking up from startDir looking for .requirements/ folder
  * Returns the directory containing .requirements/, or undefined if not found

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {