@popoverai/dotrequirements 0.27.4 → 0.28.0

package/dist/templates/requirements-readme.js

@@ -6,8 +6,7 @@ export function generateRequirementsReadme() {
 
 This directory contains requirements for the project. Requirements can be:
 - Hand-authored locally in Markdown files
-- Generated via \`dotrequirements pull\` from dot•requirements cloud
-- Synced bidirectionally with \`dotrequirements push\`
+- Synced bidirectionally with dot•requirements cloud via \`dotrequirements sync\`
 
 ## File Format
 
@@ -21,8 +20,8 @@ Requirements use the \`*.requirements.md\` naming pattern. See the [Requirements
 
 ## Commands
 
-- \`dotrequirements pull\` - Sync requirements from cloud
-- \`dotrequirements push\` - Push local requirements to cloud
+- \`dotrequirements sync\` - Reconcile requirements with the cloud (both directions)
+- \`dotrequirements diff\` - Show how the repo and the cloud differ (read-only)
 - \`dotrequirements validate\` - Validate requirement files
 
 Learn more: https://dotrequirements.io

package/dist/templates/requirements-readme.ts

@@ -6,8 +6,7 @@ export function generateRequirementsReadme(): string {
 
 This directory contains requirements for the project. Requirements can be:
 - Hand-authored locally in Markdown files
-- Generated via \`dotrequirements pull\` from dot•requirements cloud
-- Synced bidirectionally with \`dotrequirements push\`
+- Synced bidirectionally with dot•requirements cloud via \`dotrequirements sync\`
 
 ## File Format
 
@@ -21,8 +20,8 @@ Requirements use the \`*.requirements.md\` naming pattern. See the [Requirements
 
 ## Commands
 
-- \`dotrequirements pull\` - Sync requirements from cloud
-- \`dotrequirements push\` - Push local requirements to cloud
+- \`dotrequirements sync\` - Reconcile requirements with the cloud (both directions)
+- \`dotrequirements diff\` - Show how the repo and the cloud differ (read-only)
 - \`dotrequirements validate\` - Validate requirement files
 
 Learn more: https://dotrequirements.io

package/dist/templates/skills/codebase-to-spec/SKILL.md

@@ -92,8 +92,8 @@ The spec is written; this step is about what the user does with it. End the run
 
 1. If no cloud credentials exist, run `{{DOTREQ_CLI}} link --yes --json` via Bash. The user completes login in the browser; everything else is yours.
 2. If link exits with code 2, its JSON is a `decision_needed` — multiple teams, existing projects, or a plan at its project limit. Relay the options conversationally (they are the user's choice, not yours), then retry link with the chosen option's `retryFlag` appended.
-3. Once linked, run `{{DOTREQ_CLI}} push --yes`. Present each document's web URL from the output as the place the user's team reviews it.
-4. Hand over the share mechanics from link's JSON, matched to the teammate's surface: the `inviteUrl` for a teammate who will review in the web platform, and the `sharePullCommand` for a teammate working in their IDE. If link omitted one (e.g. the user isn't a team admin), hand over what's there without apology.
+3. Once linked, run `{{DOTREQ_CLI}} sync --repo-contributes --yes`. Present each document's web URL from the output as the place the user's team reviews it.
+4. Hand over the share mechanics from link's JSON, matched to the teammate's surface: the `inviteUrl` for a teammate who will review in the web platform, and the `shareSyncCommand` for a teammate working in their IDE. If link omitted one (e.g. the user isn't a team admin), hand over what's there without apology.
 5. With the spec in the cloud, offer to set up the assistant you are running as to work from the spec going forward — framed as that outcome ("I can work from this spec in future sessions"), not as configuration. On acceptance, run `{{DOTREQ_CLI}} ai-setup --assistant <id>` with the identifier for this assistant (e.g. `claude-code`).
 
 If the user declines the team-review offer, note that it stands for later and don't repeat the pitch.

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

@@ -41,7 +41,6 @@ export interface ProjectInfo {
  * Returns undefined if either is missing.
  */
 export declare function getCredentialsFromEnv(): ProjectSettings | undefined;
-export declare function setAuthFromEnv(enabled: boolean): void;
 /**
  * Find the project root by walking up from startDir looking for .requirements/ folder
  * Returns the directory containing .requirements/, or undefined if not found
@@ -66,8 +65,15 @@ export declare function writeProjectSettings(projectRoot: string, settings: Proj
  * Returns undefined if no project found
  */
 export declare function getProjectInfo(startDir?: string): ProjectInfo | undefined;
+export declare function setPreferEnvCredentials(enabled: boolean): void;
 /**
- * Get project credentials, throwing helpful error if not available
+ * Get project credentials, throwing a helpful error if not available.
+ *
+ * AUTHZ-6: the settings file wins when present; the environment is the fallback
+ * when no settings file is on disk. A local checkout's binding is never
+ * overridden by an ambient environment (AUTHZ-6.0), while a CI checkout with no
+ * settings file authenticates from DOTREQ_PROJECT_ID / DOTREQ_PROJECT_SECRET
+ * (AUTHZ-6.1) — no flag required.
  */
 export declare function getProjectCredentials(startDir?: string): ProjectSettings;
 //# sourceMappingURL=project-settings.d.ts.map

package/dist/utils/project-settings.js

@@ -18,19 +18,6 @@ export function getCredentialsFromEnv() {
     }
     return undefined;
 }
-/**
- * AUTHZ-6: explicit CI/CD credential injection. Set by the global
- * --auth-from-env flag (cli.ts preAction hook); when enabled,
- * getProjectCredentials reads DOTREQ_PROJECT_ID / DOTREQ_PROJECT_SECRET
- * instead of file-based discovery. Without the flag those variables are
- * ignored entirely — the explicit opt-in prevents credential conflicts
- * between local and CI environments. (Previously the retired MCP server's
- * --auth-from-env; ported to the CLI with identical semantics.)
- */
-let authFromEnv = false;
-export function setAuthFromEnv(enabled) {
-    authFromEnv = enabled;
-}
 /**
  * Find the project root by walking up from startDir looking for .requirements/ folder
  * Returns the directory containing .requirements/, or undefined if not found
@@ -167,25 +154,61 @@ export function getProjectInfo(startDir = process.cwd()) {
     };
 }
 /**
- * Get project credentials, throwing helpful error if not available
+ * SYNC-ALIAS-1.3: the retired `--auth-from-env` global flag survives as a
+ * deprecated alias for the commands already in users' CI (the doc-site taught
+ * `dotreq --auth-from-env push`). When set, environment credentials replace
+ * file discovery entirely — the flag's original semantics — so an old
+ * invocation behaves identically.
+ */
+let preferEnvCredentials = false;
+export function setPreferEnvCredentials(enabled) {
+    preferEnvCredentials = enabled;
+}
+/**
+ * Get project credentials, throwing a helpful error if not available.
+ *
+ * AUTHZ-6: the settings file wins when present; the environment is the fallback
+ * when no settings file is on disk. A local checkout's binding is never
+ * overridden by an ambient environment (AUTHZ-6.0), while a CI checkout with no
+ * settings file authenticates from DOTREQ_PROJECT_ID / DOTREQ_PROJECT_SECRET
+ * (AUTHZ-6.1) — no flag required.
  */
 export function getProjectCredentials(startDir = process.cwd()) {
-    // AUTHZ-6.0 / 6.1: with the explicit flag, env credentials replace
-    // file-based discovery entirely
-    if (authFromEnv) {
+    // SYNC-ALIAS-1.3: deprecated --auth-from-env keeps its original semantics —
+    // env replaces file discovery entirely.
+    if (preferEnvCredentials) {
         const envCredentials = getCredentialsFromEnv();
         if (!envCredentials) {
-            throw new Error("--auth-from-env requires both DOTREQ_PROJECT_ID and DOTREQ_PROJECT_SECRET environment variables to be set.");
+            throw new Error("Both DOTREQ_PROJECT_ID and DOTREQ_PROJECT_SECRET must be set to authenticate from the environment.");
         }
         return envCredentials;
     }
-    const info = getProjectInfo(startDir);
-    if (!info) {
-        throw new Error('No dotrequirements project found. Run "dotrequirements init" to create one.');
+    // File wins: a present, valid settings file is authoritative. readProjectSettings
+    // throws on a present-but-invalid file, surfacing it rather than silently
+    // falling through to the environment.
+    const root = findProjectRoot(startDir);
+    if (root) {
+        const settings = readProjectSettings(root);
+        if (settings)
+            return settings;
+    }
+    // No settings file on disk — fall back to the environment (AUTHZ-6.1).
+    const envCredentials = getCredentialsFromEnv();
+    if (envCredentials) {
+        // AUTHZ-6.1: announce the fallback, on stderr so it never pollutes stdout
+        // that a caller may be parsing.
+        process.stderr.write("Authenticating from the DOTREQ_PROJECT_ID / DOTREQ_PROJECT_SECRET environment variables.\n");
+        return envCredentials;
     }
-    if (!info.credentials) {
-        throw new Error('Project is not connected to cloud. Run "dotrequirements link" to connect.');
+    // AUTHZ-6.2: exactly one variable set is a misconfiguration, not a silent
+    // no-op — name both.
+    if (process.env.DOTREQ_PROJECT_ID || process.env.DOTREQ_PROJECT_SECRET) {
+        throw new Error("Both DOTREQ_PROJECT_ID and DOTREQ_PROJECT_SECRET must be set to authenticate from the environment.");
+    }
+    // AUTHZ-6.3 / AUTHZ-2: neither a settings file nor environment credentials.
+    if (!root) {
+        throw new Error('No dotrequirements project found. Run "dotrequirements init" to create one.');
     }
-    return info.credentials;
+    throw new Error("Cloud features require authentication. Run 'dotrequirements link'.");
 }
 //# sourceMappingURL=project-settings.js.map

package/package.json

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

package/dist/commands/pull.d.ts

@@ -1,8 +0,0 @@
-interface PullOptions {
-    project?: string;
-    document?: string;
-    share?: string;
-}
-export declare function pullCommand(options: PullOptions): Promise<void>;
-export {};
-//# sourceMappingURL=pull.d.ts.map

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