@popoverai/dotrequirements 0.27.4 → 0.29.0

package/dist/commands/pull.js

@@ -1,230 +0,0 @@
-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 { extractFrontmatterBlock } from "../schema/parser-core.js";
-import { brand } from "../utils/brand.js";
-import { getProjectCredentials } from "../utils/project-settings.js";
-export async function pullCommand(options) {
-    // 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.
-            // Production redacts ConvexError messages to "Server Error" but
-            // preserves error.data — check both, or the friendly message only
-            // ever appears against dev deployments.
-            const data = error.data;
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            if (data?.message === "Invalid share token" ||
-                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;
-        }
-    }
-    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");
-        }
-    }
-    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());
-    // SYNC-WEB-CREATE-2.0: track paths claimed during this pull so colliding
-    // titles don't silently overwrite each other within one operation
-    const usedPaths = new Set(existingFilesByDocId.values());
-    // 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);
-        let filePath;
-        if (existingFilePath) {
-            filePath = existingFilePath;
-        }
-        else {
-            // SYNC-WEB-CREATE-2.1: an all-symbols title sanitizes to nothing —
-            // fall back to the document ID rather than a hidden ".requirements.md"
-            const baseName = sanitizeFileName(doc.title) || doc.documentId;
-            let candidate = path.join(requirementsDir, `${baseName}.requirements.md`);
-            // SYNC-WEB-CREATE-2.0: disambiguate later collisions with a numeric
-            // suffix; also avoid clobbering an on-disk file that belongs to a
-            // different (or no) document
-            let suffix = 2;
-            while (usedPaths.has(candidate) || fs.existsSync(candidate)) {
-                candidate = path.join(requirementsDir, `${baseName}-${suffix}.requirements.md`);
-                suffix++;
-            }
-            filePath = candidate;
-        }
-        usedPaths.add(filePath);
-        const fileName = path.basename(filePath);
-        // IMPORT-1: carry the CTS run marker forward from the existing local
-        // file — pull rebuilds frontmatter from cloud data, and silently dropping
-        // the marker would strip a committed spec's import credential before a
-        // teammate ever pushes it
-        let existingCtsRun;
-        if (existingFilePath && fs.existsSync(existingFilePath)) {
-            const match = fs
-                .readFileSync(existingFilePath, "utf-8")
-                .match(/^ctsRun: (.+)$/m);
-            existingCtsRun = match?.[1].trim();
-        }
-        // 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,
-            ...(existingCtsRun ? { ctsRun: existingCtsRun } : {}),
-            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("─────────────────────────────────────────────────────────");
-    }
-}
-/**
- * Sanitize document title for use as filename
- */
-function sanitizeFileName(title) {
-    return title
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-}
-/**
- * Build an index mapping document IDs to their file paths.
- * Scans existing .requirements.md files across the entire workspace and extracts document.id from frontmatter.
- * SYNC-DISCOVERY-2.0: Uses the same discovery logic as push and MCP.
- */
-async function buildDocumentIdIndex(workspaceRoot) {
-    const index = new Map();
-    // Use the same file discovery as MCP and push
-    const allFiles = await findRequirementsFiles(workspaceRoot);
-    for (const filePath of allFiles) {
-        const docId = extractDocumentIdFromFile(filePath);
-        if (docId) {
-            index.set(docId, filePath);
-        }
-    }
-    return index;
-}
-/**
- * Extract document.id from a requirements file's frontmatter.
- * Returns undefined if the file can't be read or doesn't have a document ID.
- * SYNC-DISCOVERY-3: only the leading YAML frontmatter block is consulted —
- * a document id quoted in body prose or a fenced example must never mark
- * the file as owning that document.
- */
-function extractDocumentIdFromFile(filePath) {
-    try {
-        const fileContent = fs.readFileSync(filePath, "utf-8");
-        // Isolate the leading ---...--- frontmatter block; no frontmatter means
-        // the file is unlinked to any cloud document (SYNC-DISCOVERY-3.2).
-        // Shared helper normalizes CRLF (SYNC-FORMAT-1) so a Windows-saved file
-        // keeps matching its document and is updated in place (SYNC-DISCOVERY-2.1).
-        const content = extractFrontmatterBlock(fileContent);
-        if (content === undefined) {
-            return undefined;
-        }
-        // 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):
-        //   document:
-        //     title: Some Title
-        //     defaultPrefix: REQ
-        //     id: abc123
-        const inlineMatch = content.match(/document:\s*\{[^}]*id:\s*["']?([^"',}\s]+)/);
-        if (inlineMatch) {
-            return inlineMatch[1];
-        }
-        // Match id: anywhere within the document block (allows other properties before it)
-        const nestedMatch = content.match(/document:\s*\n(?:[ \t]+[^\n]*\n)*?[ \t]+id:\s*["']?([^"'\s\n]+)/);
-        if (nestedMatch) {
-            return nestedMatch[1];
-        }
-        return undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-//# sourceMappingURL=pull.js.map

package/dist/commands/push.d.ts

@@ -1,6 +0,0 @@
-interface PushOptions {
-    yes?: boolean;
-}
-export declare function pushCommand(file: string | undefined, options: PushOptions): Promise<void>;
-export {};
-//# sourceMappingURL=push.d.ts.map

package/dist/commands/push.js

@@ -1,244 +0,0 @@
-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, parseFilesForPushIndividually, } 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) {
-    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];
-    }
-    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 local files. SYNC-FAIL-4: one invalid file is skipped while the
-    // rest of the batch still pushes — same helper as the MCP push handler.
-    console.log("Parsing local requirements...");
-    const { parsedFiles, totalRequirements, parseFailures } = parseFilesForPushIndividually(filesToPush);
-    // Log file parsing progress
-    for (const file of parsedFiles) {
-        const fileName = path.basename(file.filePath);
-        const doc = file.metadata.document;
-        console.log(`  Reading ${fileName}...`);
-        // DOC-HEADER-11.4: parseFilesForPush mutates the metadata when it infers
-        // the prefix, so the flag it returns is the only record of the inference
-        if (doc?.defaultPrefix && file.inferredDefaultPrefix) {
-            console.log(`    Inferred defaultPrefix "${doc.defaultPrefix}" from first requirement`);
-        }
-    }
-    // SYNC-FAIL-4.1: every file in the push failed to parse — report each
-    // skipped file, then fail honestly instead of dry-running nothing
-    if (parsedFiles.length === 0) {
-        for (const failure of parseFailures) {
-            console.log(`  ✗ Skipped ${path.basename(failure.filePath)}: ${failure.error}`);
-        }
-        console.log("\nNo valid documents to push.");
-        process.exitCode = 1;
-        return;
-    }
-    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, parseFailures);
-    // 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.");
-        // SYNC-FAIL-4.1: every file in the push was invalid — whether it failed
-        // local parse or dry-run validation — so the command must fail honestly,
-        // matching the MCP handler's merged rule
-        if (parseFailures.length > 0 || dryRunResult.invalid.length > 0) {
-            process.exitCode = 1;
-        }
-        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 — match by full path, since two pushed
-        // files can share a basename
-        const error = result.errors.find((e) => e.filePath === file.filePath);
-        if (error) {
-            console.log(`  ✗ Failed: ${fileName} - ${error.error}`);
-        }
-        else if (isCreate) {
-            console.log(`  ✓ Created: ${fileName} → ${file.metadata.document?.id}`);
-        }
-        else {
-            console.log(`  ✓ Updated: ${fileName}`);
-        }
-    }
-    // SYNC-FAIL-2.1: the cloud save succeeded but the local file couldn't be
-    // updated — name the file, say the cloud is fine, and give the recovery
-    // step that re-links the file instead of minting a duplicate on retry
-    if (result.writeBackWarnings?.length > 0) {
-        console.log();
-        for (const warning of result.writeBackWarnings) {
-            console.log(`⚠ ${warning.fileName}: saved to the cloud, but the local file could not be updated (${warning.error}). ` +
-                `To avoid creating a duplicate, add "id: ${warning.documentId}" under "document:" in the frontmatter of ${warning.filePath}, then push again.`);
-        }
-    }
-    // IMPORT-3: marker failures are loud but never fatal
-    if (result.importWarnings.length > 0) {
-        console.log();
-        for (const { fileName, status } of result.importWarnings) {
-            if (status === "already_used") {
-                console.log(`⚠ ${fileName}: 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(`⚠ ${fileName}: 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-1: a failed push must not masquerade as success — agents and
-    // scripts drive this command and rely on the exit code to tell the truth
-    const failed = result.errors.length;
-    const syncedCount = result.created + result.updated;
-    if (failed > 0) {
-        process.exitCode = 1;
-        if (syncedCount === 0) {
-            console.log(`\n✗ Push failed: ${failed} document(s) could not be saved.`);
-        }
-        else {
-            console.log(`\n⚠ Push incomplete: ${syncedCount} document(s) synced, ${failed} failed.`);
-        }
-    }
-    else {
-        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 (failed === 0 && syncedCount === 0) {
-        console.log("  No documents were pushed.");
-    }
-    // SYNC-LAND-1: land the user on their spec, not at a dead end
-    if (result.synced.length > 0) {
-        console.log("\nReview in dot•requirements:");
-        for (const doc of result.synced) {
-            console.log(`  ${doc.fileName} → ${doc.url}`);
-        }
-    }
-}
-/**
- * Display the dry run summary.
- */
-function displayDryRunSummary(dryRunResult, parseFailures = []) {
-    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();
-    }
-    // SYNC-FAIL-4.0: local parse failures surface alongside dry-run invalids,
-    // each named by file, while the rest of the batch proceeds
-    const skipped = [
-        ...parseFailures.map((failure) => ({
-            fileName: path.basename(failure.filePath),
-            error: failure.error,
-        })),
-        ...invalid.map(({ file, result }) => ({
-            fileName: path.basename(file.filePath),
-            error: result.error,
-        })),
-    ];
-    if (skipped.length > 0) {
-        console.log(`Skipped - invalid files (${skipped.length}):`);
-        for (const { fileName, error } of skipped) {
-            console.log(`  ✗ ${fileName}: ${error}`);
-        }
-        console.log();
-    }
-}
-/**
- * Prompt user for confirmation
- */
-function confirm(question) {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-    return new Promise((resolve) => {
-        rl.question(question, (answer) => {
-            rl.close();
-            resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
-        });
-    });
-}
-//# sourceMappingURL=push.js.map