@popoverai/dotrequirements 0.27.4 → 0.28.0

package/dist/push/core.js

@@ -1,20 +1,12 @@
 /**
- * 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
+ * Shared parse-and-write-back primitives for syncing local requirements files
+ * to the cloud. The comparator-driven sync path (`packages/cli/src/sync/`)
+ * consumes these; the former dry-run/execute push pipeline was retired with the
+ * `push` command (its behavior now lives in the sync executor).
  */
 import * as fs from "node:fs";
-import * as path from "node:path";
-import { ConvexHttpClient } from "convex/browser";
 import YAML from "yaml";
-import { api } from "../convex.js";
-import { buildRequirementsFile, getAllRequirements, parseRequirementKey, parseRequirementsFromFile, } from "../schema/index.js";
+import { getAllRequirements, parseRequirementKey, parseRequirementsFromFile, } from "../schema/index.js";
 import { extractFrontmatterBlock, stripFrontmatterBlock, } from "../schema/parser-core.js";
 /** Base URL of the web app, where synced documents are reviewed. */
 export const WEB_APP_URL = "https://app.dotrequirements.io";
@@ -26,7 +18,7 @@ export const WEB_APP_URL = "https://app.dotrequirements.io";
  */
 export function extractMarkdownContent(rawContent) {
     // Shared CRLF-normalizing helper (SYNC-FORMAT-1): the stripped body is
-    // pushed as the document's canonical markdownContent (SYNC-ARCH-1), so a
+    // synced as the document's canonical markdownContent (SYNC-ARCH-1), so a
     // CRLF-authored file must not leak its frontmatter fence into the cloud
     // body.
     return stripFrontmatterBlock(rawContent);
@@ -55,11 +47,11 @@ function extractRawFrontmatter(rawContent) {
     return undefined;
 }
 /**
- * DOC-HEADER-14: merge the validated (and push-updated) metadata over the raw
+ * DOC-HEADER-14: merge the validated (and sync-updated) metadata over the raw
  * frontmatter so unrecognized keys survive the rewrite while the fields the
- * push owns (document ID, pulledAt, defaultPrefix, version) stay updated.
+ * sync owns (document ID, pulledAt, defaultPrefix, version) stay updated.
  */
-function mergeMetadataWithRawFrontmatter(metadata, rawFrontmatter) {
+export function mergeMetadataWithRawFrontmatter(metadata, rawFrontmatter) {
     if (!rawFrontmatter) {
         return metadata;
     }
@@ -77,11 +69,11 @@ function mergeMetadataWithRawFrontmatter(metadata, rawFrontmatter) {
     return merged;
 }
 /**
- * Parse files for push. Returns parsed files with metadata and content.
+ * Parse files for sync. Returns parsed files with metadata and content.
  *
  * Throws (via `parseRequirementsFromFile`) if any file is syntactically
  * invalid. Callers that need one bad file not to abort the batch should parse
- * files individually and collect failures (see the MCP push handler, #45).
+ * files individually and collect failures.
  */
 export function parseFilesForPush(filePaths) {
     const parsedFiles = [];
@@ -128,11 +120,11 @@ export function parseFilesForPush(filePaths) {
 /**
  * SYNC-FAIL-4.0: parse files one at a time so a single invalid file cannot
  * abort the batch — its failure is collected per file while the valid files
- * still parse. Shared by the CLI push command and the MCP push handler (#45)
- * so their isolation semantics cannot drift.
+ * still parse.
  *
  * Note: cross-file checks that need the whole batch (e.g. SYNC-FAIL-3
- * duplicate document IDs) are enforced downstream in dryRunPush, not here.
+ * duplicate document IDs) are enforced by the sync path against the local
+ * snapshot, not here.
  */
 export function parseFilesForPushIndividually(filePaths) {
     const parsedFiles = [];
@@ -154,7 +146,7 @@ export function parseFilesForPushIndividually(filePaths) {
     return { parsedFiles, totalRequirements, parseFailures };
 }
 /**
- * SYNC-FAIL-3: two ParsedFiles carrying the same document.id would both push
+ * SYNC-FAIL-3: two ParsedFiles carrying the same document.id would both sync
  * as updates to one cloud document — last writer wins and the first spec is
  * silently destroyed. Abort instead, naming both files and the shared id.
  */
@@ -170,252 +162,9 @@ export function assertNoDuplicateDocumentIds(parsedFiles) {
                 `  ${existingPath}\n` +
                 `  ${file.filePath}\n` +
                 `Each file must map to its own cloud document. Remove the "id:" line ` +
-                `from the copy's frontmatter so it pushes as a new document, then push again.`);
+                `from the copy's frontmatter so it syncs as a new document, then sync again.`);
         }
         filesByDocId.set(docId, file.filePath);
     }
 }
-// ============================================================================
-// Dry Run
-// ============================================================================
-/**
- * Execute dry run phase: validate all files against Convex and detect conflicts.
- */
-export async function dryRunPush(parsedFiles, credentials) {
-    // SYNC-FAIL-3.0: callers that assemble ParsedFiles themselves (e.g. the
-    // MCP handler parses files one at a time) still abort before any cloud write
-    assertNoDuplicateDocumentIds(parsedFiles);
-    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 = [];
-    const importWarnings = [];
-    const synced = [];
-    const writeBackWarnings = [];
-    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 rawResult = (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,
-                // IMPORT-2: forward the CTS run marker when the file is stamped
-                runMarker: file.metadata.ctsRun,
-                dryRun: false,
-            }));
-            // The server returns a structured result iff we sent a runMarker
-            const pushResult = typeof rawResult === "string" ? rawResult : rawResult.documentId;
-            if (typeof rawResult !== "string") {
-                const status = rawResult.importStatus;
-                if (status === "invalid_marker" ||
-                    status === "unsupported_version" ||
-                    status === "already_used") {
-                    // IMPORT-3.2/3.3: loud, never fatal
-                    importWarnings.push({ fileName, status });
-                }
-            }
-            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;
-                created++;
-            }
-            else {
-                // Update pulledAt to reflect this push
-                file.metadata.pulledAt = new Date().toISOString();
-                file.metadata.version = (file.metadata.version || 0) + 1;
-                updated++;
-            }
-            // SYNC-FAIL-2: the local write-back is separate from the cloud save —
-            // the cloud document already exists at this point, so a write-back
-            // failure is a warning on a synced document, never a push failure
-            // (which would invite a retry that mints a duplicate cloud document).
-            try {
-                // DOC-HEADER-14: unrecognized frontmatter keys survive the rewrite
-                const updatedContent = buildRequirementsFile(mergeMetadataWithRawFrontmatter(file.metadata, file.rawFrontmatter), file.markdownContent);
-                fs.writeFileSync(file.filePath, updatedContent, "utf-8");
-            }
-            catch (writeErr) {
-                writeBackWarnings.push({
-                    fileName,
-                    filePath: file.filePath,
-                    documentId: pushResult,
-                    error: writeErr instanceof Error ? writeErr.message : String(writeErr),
-                });
-            }
-            // SYNC-LAND-1: every synced document gets its web URL in the result
-            synced.push({
-                fileName,
-                documentId: pushResult,
-                url: `${WEB_APP_URL}/documents/${pushResult}`,
-            });
-        }
-        catch (err) {
-            errors.push({
-                fileName,
-                filePath: file.filePath,
-                error: errorDisplayMessage(err),
-            });
-        }
-    }
-    return {
-        created,
-        updated,
-        errors,
-        importWarnings,
-        synced,
-        writeBackWarnings,
-    };
-}
-/**
- * Servers throw ConvexError({kind, message}) for expected failures (e.g.
- * LIMITS-4.2's limit error); the client-side Error message embeds that data
- * as JSON. Surface the human-readable message it carries instead of the blob.
- */
-function errorDisplayMessage(err) {
-    const data = err.data;
-    const fromData = humanMessage(data);
-    if (fromData)
-        return fromData;
-    const message = err instanceof Error ? err.message : String(err);
-    // ConvexError messages may embed the data JSON directly or after a
-    // "ConvexError:" prefix — try the trailing {...} chunk
-    const jsonStart = message.indexOf("{");
-    if (jsonStart !== -1) {
-        try {
-            const parsed = JSON.parse(message.slice(jsonStart));
-            const fromMessage = humanMessage(parsed);
-            if (fromMessage)
-                return fromMessage;
-        }
-        catch {
-            // fall through to the raw message
-        }
-    }
-    return message;
-}
-function humanMessage(data) {
-    if (typeof data === "string") {
-        try {
-            return humanMessage(JSON.parse(data));
-        }
-        catch {
-            return undefined;
-        }
-    }
-    if (data &&
-        typeof data === "object" &&
-        "message" in data &&
-        typeof data.message === "string") {
-        return data.message;
-    }
-    return undefined;
-}
 //# sourceMappingURL=core.js.map

package/dist/push/index.d.ts

@@ -1,8 +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.
+ * Shared parse-and-write-back primitives for syncing local requirements files
+ * to the cloud, consumed by the comparator-driven sync path.
  */
-export { type CloudDocumentMetadata, type ConflictInfo, type DryRunResult, type DryRunResultItem, dryRunPush, executePush, extractMarkdownContent, type FileWithDryRun, type ParsedFile, type ParseFailure, type PushCredentials, type PushResult, parseFilesForPush, parseFilesForPushIndividually, WEB_APP_URL, } from "./core.js";
+export { assertNoDuplicateDocumentIds, extractMarkdownContent, mergeMetadataWithRawFrontmatter, type ParsedFile, type ParseFailure, parseFilesForPush, parseFilesForPushIndividually, WEB_APP_URL, } from "./core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/push/index.js

@@ -1,10 +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.
+ * Shared parse-and-write-back primitives for syncing local requirements files
+ * to the cloud, consumed by the comparator-driven sync path.
  */
-export { dryRunPush, executePush, 
+export { assertNoDuplicateDocumentIds, 
 // Functions
-extractMarkdownContent, parseFilesForPush, parseFilesForPushIndividually, WEB_APP_URL, } from "./core.js";
+extractMarkdownContent, mergeMetadataWithRawFrontmatter, parseFilesForPush, parseFilesForPushIndividually, WEB_APP_URL, } from "./core.js";
 //# sourceMappingURL=index.js.map

package/dist/requirements/style-guide.js

@@ -312,9 +312,9 @@ ${body}
 ## Next Steps
 
 1. **Create file**: Save this template as \`${filePath}\` and edit it for your feature
-2. **Refine style** (optional): Run \`style-check\` (or call the \`style_check\` MCP tool) for AI feedback
-3. **Validate syntax**: Run \`validate\` (or call the \`validate\` MCP tool) to verify format
-4. **Push to cloud**: Run \`dotrequirements push\` (or call the \`push_requirements\` MCP tool) to sync
+2. **Refine style** (optional): Run \`style-check\` for AI feedback
+3. **Validate syntax**: Run \`validate\` to verify format
+4. **Sync to cloud**: Run \`dotrequirements sync\` to reconcile the repo and the cloud
 
 **Note**: Requirements files can be colocated with code (\`src/auth.requirements.md\`) or centralized in \`.requirements/\` directory.`;
 }

package/dist/schema/schemas.js

@@ -140,7 +140,7 @@ export function validateForPush(metadata) {
     if (!metadata.document) {
         return {
             valid: false,
-            reason: "Missing document section. Add a document section with a title to push this file.",
+            reason: "Missing document section. Add a document section with a title to sync this file.",
         };
     }
     // Must have title

package/dist/sync/compare.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The repo/cloud comparator (DIFF-*). A pure function of two snapshots: it
+ * reads no disk and makes no network calls. `dotreq diff` renders its result,
+ * `dotreq sync` acts on it, CI asserts on it.
+ */
+import type { CloudSnapshot, ComparisonResult, LocalSnapshot } from "./types.js";
+/**
+ * Two local files carrying the same document id would both pair to one cloud
+ * document and both try to write it — last writer wins, silently destroying the
+ * first (SYNC-FAIL-3). Return the offending ids with their file paths so the
+ * caller can abort before any write.
+ */
+export declare function duplicateLocalDocumentIds(local: LocalSnapshot): Array<{
+    documentId: string;
+    filePaths: string[];
+}>;
+/**
+ * Compare the whole repo against the whole cloud, pairing documents by id.
+ */
+export declare function compareSnapshots(local: LocalSnapshot, cloud: CloudSnapshot): ComparisonResult;
+//# sourceMappingURL=compare.d.ts.map