@popoverai/dotrequirements 0.27.4 → 0.28.0

package/dist/commands/sync.js

@@ -0,0 +1,182 @@
+/**
+ * `dotreq sync` — reconcile the repo and the cloud under a direction/authority
+ * mode (SYNC-MODE-*). The daily gesture is the unmarked form; flags narrow
+ * direction (`--cloud-contributes` / `--repo-contributes`) or assign authority
+ * (`--repo-wins` / `--cloud-wins`).
+ */
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { executePlan } from "../sync/execute.js";
+import { acquireCloudSnapshot, acquireLocalSnapshot, compareSnapshots, duplicateLocalDocumentIds, filterByScope, resolutionHint, } from "../sync/index.js";
+import { buildPlan, resolveMode, } from "../sync/plan.js";
+import { brand } from "../utils/brand.js";
+import { resolveCloudAuth } from "./sync-common.js";
+/**
+ * The CLI entry point: exits non-zero on unresolved trouble (SYNC-MODE-1.5,
+ * SYNC-FAIL-1/4). `init`/`link` call `syncCommand` directly instead — their
+ * success is linking/onboarding, and a conflict in one spec file must not fail
+ * the whole command (the report lines still print).
+ */
+export async function syncCliAction(scope, options) {
+    const result = await syncCommand(scope, options);
+    if (result === "trouble") {
+        process.exitCode = 1;
+    }
+}
+export async function syncCommand(scope, options) {
+    const workspaceRoot = process.cwd();
+    // SHARE-TOKEN-CLI-1.3: a read-only token can only bring requirements down.
+    let mode;
+    if (options.share) {
+        mode = "cloud_contributes";
+        if (options.repoWins || options.cloudWins || options.repoContributes) {
+            console.log("A share token is read-only — syncing the cloud's requirements down only; other mode flags are ignored.");
+        }
+    }
+    else {
+        mode = resolveMode(options);
+    }
+    const auth = resolveCloudAuth(options);
+    const [local, cloud] = await Promise.all([
+        acquireLocalSnapshot(workspaceRoot),
+        acquireCloudSnapshot(auth),
+    ]);
+    // SYNC-MODE-4.4 (and 4.4.0 for --yes): an empty repo is indistinguishable from a wrong working
+    // directory or a failed checkout — never treat it as intent to delete every
+    // cloud document. --yes does not override: it consents to listed deletions,
+    // not to this. (Cloud deletion has no recovery path; the mirror-image case
+    // — cloud-wins deleting local files — is recoverable via git.)
+    if (mode === "repo_wins" &&
+        local.documents.length === 0 &&
+        cloud.documents.length > 0) {
+        throw new Error(`Refusing to sync --repo-wins: no requirement documents found under ${workspaceRoot}, ` +
+            `but the cloud project has ${cloud.documents.length}. An empty repo usually means a wrong ` +
+            `working directory or a failed checkout, and proceeding would permanently delete every ` +
+            `cloud document. If the repo's requirements really are gone on purpose, delete the cloud ` +
+            `documents from the web app instead.`);
+    }
+    // SHARE-TOKEN-CLI-1.2: show whose project this is.
+    if (options.share) {
+        console.log(`Project: "${cloud.projectName}"`);
+    }
+    // SYNC-FAIL-3: two files claiming one document id would both write it — abort
+    // before any write, naming both files and the shared id.
+    const dupes = duplicateLocalDocumentIds(local);
+    if (dupes.length > 0) {
+        const d = dupes[0];
+        throw new Error(`Two files claim the same document ID "${d.documentId}":\n` +
+            d.filePaths.map((p) => `  ${p}`).join("\n") +
+            `\nEach file must map to its own cloud document. Remove the "id:" line from the copy's frontmatter, then sync again.`);
+    }
+    const comparison = compareSnapshots(local, cloud);
+    const { documents, unmatched } = filterByScope(comparison, scope, workspaceRoot);
+    for (const token of unmatched) {
+        console.log(`No document matched scope "${token}".`);
+    }
+    const plan = buildPlan(documents, mode);
+    // SYNC-MODE-4: name every deletion before writing anything.
+    const deletions = plan.filter((p) => p.action === "cloud_delete" || p.action === "local_delete");
+    if (deletions.length > 0) {
+        // SYNC-MODE-4.3: a non-interactive run cannot consent — refuse rather than
+        // hanging on a prompt that will never answer (or worse, deleting silently).
+        if (!options.yes && !process.stdin.isTTY) {
+            throw new Error(`This sync would delete ${deletions.length} document(s), and there is no terminal to confirm on. ` +
+                `Re-run with --yes to consent to the deletions listed by \`dotreq diff\`.`);
+        }
+        if (!(await confirmDeletions(deletions, options.yes))) {
+            console.log("Sync cancelled.");
+            return "cancelled";
+        }
+    }
+    if (plan.every((p) => p.action === "skip")) {
+        console.log(`✓ Repo and ${brand} cloud are already in sync.`);
+        return "clean";
+    }
+    console.log(`\nSyncing with ${brand} cloud...`);
+    const outcome = await executePlan(plan, cloud, auth, workspaceRoot);
+    // Report.
+    if (outcome.cloudCreated)
+        console.log(`  Created in cloud: ${outcome.cloudCreated}`);
+    if (outcome.cloudUpdated)
+        console.log(`  Updated in cloud: ${outcome.cloudUpdated}`);
+    if (outcome.cloudDeleted)
+        console.log(`  Deleted from cloud: ${outcome.cloudDeleted}`);
+    if (outcome.localWritten)
+        console.log(`  Written locally: ${outcome.localWritten}`);
+    if (outcome.localDeleted)
+        console.log(`  Deleted locally: ${outcome.localDeleted}`);
+    for (const conflict of outcome.conflicts) {
+        console.log(`  ! conflict: ${path.basename(conflict.filePath ?? conflict.title)} — ${resolutionHint(conflict)}`);
+    }
+    for (const invalid of outcome.invalid) {
+        console.log(`  ✗ invalid file: ${path.basename(invalid.filePath ?? invalid.title)}${invalid.error ? ` — ${invalid.error}` : ""}`);
+    }
+    for (const err of outcome.errors) {
+        console.log(`  ✗ failed: ${err.name} — ${err.error}`);
+    }
+    // IMPORT-3: marker failures are loud but never fatal.
+    for (const { name, status } of outcome.importWarnings) {
+        if (status === "already_used") {
+            console.log(`  ⚠ ${name}: this file's import marker was already used, so its requirements were saved as natively authored (they count toward your plan's requirement limit). Re-running codebase-to-spec produces a fresh marker.`);
+        }
+        else {
+            console.log(`  ⚠ ${name}: this file's import marker was not recognized — your CLI may need updating. Its requirements were saved as natively authored (they count toward your plan's requirement limit).`);
+        }
+    }
+    // SYNC-FAIL-2.1: saved to cloud, but the local file couldn't be updated —
+    // give the re-link recovery step so a retry doesn't mint a duplicate.
+    for (const w of outcome.writeBackWarnings) {
+        console.log(`  ⚠ ${w.name}: saved to the cloud, but the local file could not be updated (${w.error}). ` +
+            `To avoid creating a duplicate, add "id: ${w.documentId}" under "document:" in ${w.filePath}, then sync again.`);
+    }
+    // SYNC-LAND-1: land the user on their synced documents.
+    if (outcome.synced.length > 0) {
+        console.log(`\nReview in ${brand}:`);
+        for (const s of outcome.synced)
+            console.log(`  ${s.name} → ${s.url}`);
+    }
+    const hadTrouble = outcome.conflicts.length > 0 ||
+        outcome.invalid.length > 0 ||
+        outcome.errors.length > 0;
+    if (hadTrouble) {
+        console.log("\n⚠ Sync completed with unresolved items (see above).");
+    }
+    else {
+        console.log("\n✓ Sync complete.");
+    }
+    // SHARE-TOKEN-CLI-3: point the onboarding user at full access.
+    if (options.share) {
+        console.log("\n─────────────────────────────────────────────────────────");
+        console.log("Next steps to get full access (sync to cloud, coverage):");
+        console.log("  Run: dotrequirements link");
+        console.log("─────────────────────────────────────────────────────────");
+    }
+    return hadTrouble ? "trouble" : "clean";
+}
+async function confirmDeletions(deletions, skip) {
+    const cloudDeletes = deletions.filter((d) => d.action === "cloud_delete");
+    const localDeletes = deletions.filter((d) => d.action === "local_delete");
+    console.log("\nThis will PERMANENTLY delete:");
+    for (const d of cloudDeletes) {
+        console.log(`  from cloud: ${d.doc.title}`);
+    }
+    for (const d of localDeletes) {
+        console.log(`  from disk:  ${d.doc.filePath ? path.basename(d.doc.filePath) : d.doc.title}`);
+    }
+    if (skip) {
+        console.log("(--yes: proceeding without confirmation)");
+        return true;
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question("\nContinue? [y/N] ", (answer) => {
+            rl.close();
+            const a = answer.trim().toLowerCase();
+            resolve(a === "y" || a === "yes");
+        });
+    });
+}
+//# sourceMappingURL=sync.js.map

package/dist/convex.d.ts

@@ -20,11 +20,11 @@ export declare const api: {
             exportForCli: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
             exportProjectForCli: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
             checkDocumentsExist: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
-            getDocumentsMetadata: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
         };
         mutations: {
             create: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             update: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            deleteForCli: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
         };
         saveWithRequirements: {
             saveWithRequirements: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;

package/dist/convex.js

@@ -24,12 +24,12 @@ export const api = {
             exportForCli: query("documents/queries:exportForCli"),
             exportProjectForCli: query("documents/queries:exportProjectForCli"),
             checkDocumentsExist: query("documents/queries:checkDocumentsExist"),
-            // SYNC-CLI-EDIT-2: Get document metadata for conflict detection
-            getDocumentsMetadata: query("documents/queries:getDocumentsMetadata"),
         },
         mutations: {
             create: mutation("documents/mutations:create"),
             update: mutation("documents/mutations:update"),
+            // SYNC-MODE-3: delete a cloud document from the CLI (repo-wins)
+            deleteForCli: mutation("documents/mutations:deleteForCli"),
         },
         // SYNC-ARCH-1: Save document with requirements derivation
         saveWithRequirements: {

package/dist/push/core.d.ts

@@ -1,22 +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 type { Metadata } from "../schema/index.js";
-export interface PushCredentials {
-    projectId: string;
-    projectSecret: string;
-    convexUrl: string;
-}
 /**
- * Parsed file ready for push.
+ * Parsed file ready to sync.
  * SYNC-ARCH-1: Documents are the sync unit, not individual requirements.
  */
 export interface ParsedFile {
@@ -28,111 +18,31 @@ export interface ParsedFile {
     requirementCount: number;
     /**
      * DOC-HEADER-14: the frontmatter exactly as the user wrote it, including
-     * keys the schema doesn't recognize — merged back on the post-push rewrite
+     * keys the schema doesn't recognize — merged back on the post-sync rewrite
      * so those keys survive.
      */
     rawFrontmatter?: Record<string, unknown>;
     /** DOC-HEADER-11.4: true when defaultPrefix was inferred from the first requirement rather than read from frontmatter */
     inferredDefaultPrefix?: boolean;
 }
-/**
- * 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;
-}
-/**
- * Outcome of run-marker handling for one pushed file (IMPORT-2/3).
- * Mirrors the server's ImportStatus.
- */
-export type ImportStatus = "imported" | "invalid_marker" | "unsupported_version" | "already_used" | "ignored_update" | "none";
 /** Base URL of the web app, where synced documents are reviewed. */
 export declare const WEB_APP_URL = "https://app.dotrequirements.io";
-/**
- * Result of the execute phase.
- */
-export interface PushResult {
-    created: number;
-    updated: number;
-    /** filePath disambiguates when two pushed files share a basename */
-    errors: Array<{
-        fileName: string;
-        filePath: string;
-        error: string;
-    }>;
-    /** IMPORT-3: marker failures that must be surfaced to the user, per file */
-    importWarnings: Array<{
-        fileName: string;
-        status: Extract<ImportStatus, "invalid_marker" | "unsupported_version" | "already_used">;
-    }>;
-    /** SYNC-LAND-1: each successfully synced document, with its web URL */
-    synced: Array<{
-        fileName: string;
-        documentId: string;
-        url: string;
-    }>;
-    /**
-     * SYNC-FAIL-2: cloud save succeeded but the local file write-back failed.
-     * These documents are synced (counted in created/updated and listed in
-     * `synced`) — the warning carries what the user needs to re-link the file
-     * without creating a duplicate.
-     */
-    writeBackWarnings: Array<{
-        fileName: string;
-        filePath: string;
-        documentId: 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.
+ * DOC-HEADER-14: merge the validated (and sync-updated) metadata over the raw
+ * frontmatter so unrecognized keys survive the rewrite while the fields the
+ * sync owns (document ID, pulledAt, defaultPrefix, version) stay updated.
+ */
+export declare function mergeMetadataWithRawFrontmatter(metadata: Metadata, rawFrontmatter: Record<string, unknown> | undefined): Metadata;
+/**
+ * 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 declare function parseFilesForPush(filePaths: string[]): {
     parsedFiles: ParsedFile[];
@@ -145,11 +55,11 @@ export interface ParseFailure {
 /**
  * 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 declare function parseFilesForPushIndividually(filePaths: string[]): {
     parsedFiles: ParsedFile[];
@@ -157,17 +67,9 @@ export declare function parseFilesForPushIndividually(filePaths: string[]): {
     parseFailures: ParseFailure[];
 };
 /**
- * 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.
  */
 export declare function assertNoDuplicateDocumentIds(parsedFiles: ParsedFile[]): void;
-/**
- * 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