@popoverai/dotrequirements 0.26.1 → 0.26.2

package/dist/mcp/handlers/push.js

@@ -6,7 +6,7 @@
  */
 import { existsSync } from "node:fs";
 import { basename, resolve } from "node:path";
-import { dryRunPush, executePush, parseFilesForPush, } from "../../push/index.js";
+import { dryRunPush, executePush, parseFilesForPushIndividually, } from "../../push/index.js";
 import { findRequirementsFiles } from "../../requirements/index.js";
 import { CONVEX_URL } from "../convexClient.js";
 import { errorResponse, textResponse } from "./types.js";
@@ -46,24 +46,60 @@ export async function handlePushRequirements(args, context) {
             return textResponse("No *.requirements.md files found. Nothing to push.");
         }
     }
-    // Parse files
-    const { parsedFiles, totalRequirements } = parseFilesForPush(filesToPush);
+    // Parse files. #45/SYNC-FAIL-4: one invalid file does not abort the whole
+    // push — its failure is surfaced in the preview's "Skipped - Invalid"
+    // section while valid files still push. Same helper as the CLI command.
+    const { parsedFiles, totalRequirements, parseFailures } = parseFilesForPushIndividually(filesToPush);
     // Build credentials
     const credentials = {
         projectId: project.projectId,
         projectSecret: project.projectSecret,
         convexUrl: CONVEX_URL,
     };
-    // Run dry run (always, even when confirmed - ensures fresh state)
-    const dryRunResult = await dryRunPush(parsedFiles, credentials);
+    // Run dry run (always, even when confirmed - ensures fresh state).
+    // SYNC-FAIL-3: two files claiming the same document ID abort the push
+    // before any cloud write — surface that as a clean error result naming
+    // both files rather than an unhandled throw.
+    let dryRunResult;
+    try {
+        dryRunResult = await dryRunPush(parsedFiles, credentials);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("claim the same document ID")) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `✗ Push aborted: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        throw error;
+    }
+    // #45: Merge dry-run invalids (missing document section, cloud validation)
+    // with local parse failures so both are surfaced together, each named by
+    // filename.
+    const allInvalid = [
+        ...dryRunResult.invalid.map(({ file, result }) => ({
+            fileName: basename(file.filePath),
+            error: result.error ?? "invalid",
+        })),
+        ...parseFailures.map(({ filePath, error }) => ({
+            fileName: basename(filePath),
+            error,
+        })),
+    ];
     // Check if there's anything to push
     const pushableCount = dryRunResult.updates.length +
         dryRunResult.creates.length +
         dryRunResult.notFound.length;
-    if (pushableCount === 0 && dryRunResult.invalid.length > 0) {
+    if (pushableCount === 0 && allInvalid.length > 0) {
         // Only invalid files
-        const invalidList = dryRunResult.invalid
-            .map(({ file, result }) => `- ${basename(file.filePath)}: ${result.error}`)
+        const invalidList = allInvalid
+            .map(({ fileName, error }) => `- ${fileName}: ${error}`)
             .join("\n");
         return {
             content: [
@@ -106,11 +142,10 @@ export async function handlePushRequirements(args, context) {
             }
             summary += "\n";
         }
-        if (dryRunResult.invalid.length > 0) {
-            summary += `## Skipped - Invalid (${dryRunResult.invalid.length})\n`;
-            for (const { file, result } of dryRunResult.invalid) {
-                const fileName = basename(file.filePath);
-                summary += `- ✗ ${fileName}: ${result.error}\n`;
+        if (allInvalid.length > 0) {
+            summary += `## Skipped - Invalid (${allInvalid.length})\n`;
+            for (const { fileName, error } of allInvalid) {
+                summary += `- ✗ ${fileName}: ${error}\n`;
             }
             summary += "\n";
         }
@@ -158,6 +193,17 @@ export async function handlePushRequirements(args, context) {
                 output += `- ${fileName}: ${error}\n`;
             }
         }
+        // SYNC-FAIL-2.1: cloud save succeeded but the local file couldn't be
+        // updated — name the file, say the cloud is fine, and give the recovery
+        // step so a retry doesn't mint a duplicate document.
+        if (result.writeBackWarnings?.length > 0) {
+            output += `\n**Warnings:**\n`;
+            for (const warning of result.writeBackWarnings) {
+                output +=
+                    `- ⚠ ${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.\n`;
+            }
+        }
         // SYNC-LAND-1: where each synced document lives in the web app
         if (result.synced.length > 0) {
             output += `\n**Review in dot•requirements:**\n`;

package/dist/mcp/handlers/review.d.ts

@@ -13,6 +13,7 @@ export interface StyleCheckArgs {
     filePath: string;
     requirementKeys?: string[];
     model?: string;
+    projectId?: string;
 }
 /**
  * Arguments for review_test tool

package/dist/mcp/handlers/review.js

@@ -6,11 +6,12 @@
  * - review_test: Comprehensively review tests for semantic correctness
  */
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname } from "node:path";
 import { fetchReviewTestFeedback, fetchStyleCheckFeedback, } from "../../requirements/cloud-ai.js";
+import { findRequirementsInFile } from "../../requirements/grep.js";
 import { filterRequirementsByKeys, formatRequirementTree, getRequirementTree, } from "../../requirements/index.js";
 import { discoverProjects, } from "../../utils/project-discovery.js";
-import { errorResponse, textResponse } from "./types.js";
+import { errorResponse, resolveProjectFilePath, textResponse, } from "./types.js";
 const STYLE_CHECK_GUIDANCE = `
 
 ---
@@ -32,9 +33,20 @@ const STYLE_CHECK_GUIDANCE = `
  * - MCP-REVIEW-1.3: When cloud credentials are unavailable, an error explains how to authenticate
  */
 export async function handleStyleCheck(args, context, options) {
-    const { filePath, requirementKeys, model } = args;
+    const { filePath, requirementKeys, model, projectId } = args;
     const { useEnvAuth = false, apiBaseUrl = "https://app.dotrequirements.io" } = options ?? {};
-    const fullPath = resolve(context.workspaceRoot, filePath);
+    // #49: Resolve against the discovered project.path (matching push) with a
+    // workspaceRoot fallback, so a relative path that push accepts also works
+    // here in PROJ_*-based setups. Discovery may throw without credentials — that
+    // is fine, we then fall back to workspaceRoot.
+    let styleProjectPath;
+    try {
+        styleProjectPath = (await context.getProjectFromDiscovery(projectId)).path;
+    }
+    catch {
+        styleProjectPath = undefined;
+    }
+    const fullPath = resolveProjectFilePath(filePath, styleProjectPath, context.workspaceRoot);
     if (!existsSync(fullPath)) {
         return errorResponse(`File not found: ${filePath}`);
     }
@@ -73,7 +85,14 @@ export async function handleStyleCheck(args, context, options) {
     const fileDir = dirname(fullPath);
     let project;
     try {
-        if (useEnvAuth) {
+        if (projectId) {
+            // #48: PROJ-CONTEXT-6 — an explicit projectId disambiguates a
+            // multi-project workspace. Thread it straight through to discovery
+            // (matching review_test/push/report) instead of the file-directory
+            // auto-detect path, which cannot choose among multiple projects.
+            project = await context.getProjectFromDiscovery(projectId);
+        }
+        else if (useEnvAuth) {
             // Using env auth - go straight to context
             project = await context.getProjectFromDiscovery();
         }
@@ -88,8 +107,14 @@ export async function handleStyleCheck(args, context, options) {
                 project = result.project;
             }
             else {
-                // Multiple projects - can't auto-detect which one to use
-                throw new Error("Multiple projects found - cannot auto-detect for this file");
+                // #48: Multiple projects — can't auto-detect. The remedy is to pass
+                // projectId (not `dotrequirements link`, which is already satisfied);
+                // list the available projects so the caller can choose.
+                const available = result.projects
+                    .map((p) => p.projectId)
+                    .filter(Boolean)
+                    .join(", ");
+                return errorResponse(`Multiple projects found. Specify the \`projectId\` parameter to choose one${available ? ` (available: ${available})` : ""}.`);
             }
         }
     }
@@ -130,7 +155,17 @@ export async function handleStyleCheck(args, context, options) {
 export async function handleReviewTest(args, context, options) {
     const { testFilePath, projectId } = args;
     const { apiBaseUrl = "https://app.dotrequirements.io" } = options ?? {};
-    const fullPath = resolve(context.workspaceRoot, testFilePath);
+    // #49: Resolve against the discovered project.path (matching push) with a
+    // workspaceRoot fallback. Discovery may throw without credentials — fall back
+    // to workspaceRoot; the credential error is reported later.
+    let reviewProjectPath;
+    try {
+        reviewProjectPath = (await context.getProjectFromDiscovery(projectId)).path;
+    }
+    catch {
+        reviewProjectPath = undefined;
+    }
+    const fullPath = resolveProjectFilePath(testFilePath, reviewProjectPath, context.workspaceRoot);
     if (!existsSync(fullPath)) {
         return errorResponse(`File not found: ${testFilePath}`);
     }
@@ -141,12 +176,12 @@ export async function handleReviewTest(args, context, options) {
     }
     // Read test file contents
     const testFileContents = readFileSync(fullPath, "utf-8");
-    // Extract requirement IDs from the test file using regex
-    const requirementIdMatches = testFileContents.matchAll(/requirement\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g);
-    const requirementIds = new Set();
-    for (const match of requirementIdMatches) {
-        requirementIds.add(match[1]);
-    }
+    // #43: Extract requirement IDs via the shared AST-based extractor so that
+    // multi-arg calls (`requirement("A", "B")`) and options-bearing calls
+    // (`requirement("A", { ... })`) are captured — the old single-string regex
+    // matched neither.
+    const references = await findRequirementsInFile(fullPath);
+    const requirementIds = new Set(references.map((ref) => ref.requirementId));
     // MCP-REVIEW-2.5: Get project credentials
     let project;
     try {
@@ -159,9 +194,17 @@ export async function handleReviewTest(args, context, options) {
     const allRequirements = await context.getRequirements(projectId);
     // Group requirement IDs by their root to avoid sending duplicate trees
     // e.g., NAV-3.0, NAV-3.1, NAV-3.2 all belong to root NAV-3
+    //
+    // #42: A reference may be a bare root (`AUTH-1`), an index child (`AUTH-1.0`),
+    // or a label path (`AUTH-1.given`). Normalize each reference to its root id
+    // (the substring before the first dot) before matching — the same approach
+    // getReferencedRequirementIds uses — so label-path refs resolve instead of
+    // being reported as non-existent.
     const rootToTestedIds = new Map();
     for (const reqId of requirementIds) {
-        const req = allRequirements.find((r) => r.id === reqId || r.rootId === reqId);
+        const dotIndex = reqId.indexOf(".");
+        const refRootId = dotIndex > 0 ? reqId.substring(0, dotIndex) : reqId;
+        const req = allRequirements.find((r) => r.rootId === refRootId);
         if (req) {
             if (!rootToTestedIds.has(req.rootId)) {
                 rootToTestedIds.set(req.rootId, new Set());

package/dist/mcp/handlers/test-mapping.js

@@ -7,7 +7,7 @@ import { existsSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { findAllTestReferences, findRequirementsInFile, } from "../../requirements/grep.js";
 import { getRequirementById } from "../../requirements/index.js";
-import { errorResponse, textResponse } from "./types.js";
+import { errorResponse, resolveProjectFilePath, textResponse, } from "./types.js";
 /**
  * Handler for get_requirements_by_test tool
  *
@@ -18,14 +18,26 @@ import { errorResponse, textResponse } from "./types.js";
  */
 export async function handleGetRequirementsByTest(args, context) {
     const { testFile, projectId } = args;
+    // #49: Resolve against the discovered project.path (matching push) with a
+    // workspaceRoot fallback, so a relative path works in PROJ_*-based setups.
+    let projectPath;
+    try {
+        projectPath = (await context.getProjectFromDiscovery(projectId)).path;
+    }
+    catch {
+        projectPath = undefined;
+    }
     // MCP-MAP-1.2: Check if file exists before processing
-    const fullPath = resolve(context.workspaceRoot, testFile);
+    const fullPath = resolveProjectFilePath(testFile, projectPath, context.workspaceRoot);
     if (!existsSync(fullPath)) {
         return errorResponse(`Test file not found: ${testFile}`);
     }
     const requirements = await context.getRequirements(projectId);
-    // MCP-MAP-1.0: Find all requirement references in the test file
-    const refs = await findRequirementsInFile(testFile);
+    // MCP-MAP-1.0: Find all requirement references in the test file.
+    // #44: Pass the already-resolved absolute path — findRequirementsInFile
+    // resolves relative paths against process.cwd(), which is not the workspace
+    // root when the MCP server runs from a different directory.
+    const refs = await findRequirementsInFile(fullPath);
     if (refs.length === 0) {
         return textResponse(`No requirement references found in "${testFile}"`);
     }
@@ -50,7 +62,18 @@ export async function handleGetRequirementsByTest(args, context) {
 export async function handleGetTestsByRequirement(args, context) {
     const { requirementsFile, projectId } = args;
     const { workspaceRoot } = context;
-    const fullPath = resolve(workspaceRoot, requirementsFile);
+    // #49: Resolve against the discovered project.path (matching push) with a
+    // workspaceRoot fallback, so a relative path works in PROJ_*-based setups.
+    // The same base root anchors sourceFile comparison, test scanning, and the
+    // relative paths in the output.
+    let projectPath;
+    try {
+        projectPath = (await context.getProjectFromDiscovery(projectId)).path;
+    }
+    catch {
+        projectPath = undefined;
+    }
+    const fullPath = resolveProjectFilePath(requirementsFile, projectPath, workspaceRoot);
     // Verify file exists
     if (!existsSync(fullPath)) {
         return errorResponse(`Requirements file not found: ${requirementsFile}`);
@@ -59,23 +82,35 @@ export async function handleGetTestsByRequirement(args, context) {
     if (!requirementsFile.endsWith(".requirements.md")) {
         return errorResponse(`File must be a requirements file: *.requirements.md`);
     }
+    // Anchor all subsequent path work to the root that actually contains the
+    // requirements file, so sourceFile comparison and test discovery agree.
+    const baseRoot = projectPath ?? workspaceRoot;
     // Load all requirements from this file
     const requirements = await context.getRequirements(projectId);
-    const fileRequirements = requirements.filter((req) => resolve(workspaceRoot, req.sourceFile) === fullPath);
+    const fileRequirements = requirements.filter((req) => resolve(baseRoot, req.sourceFile) === fullPath);
     if (fileRequirements.length === 0) {
         return textResponse(`No requirements found in "${requirementsFile}"`);
     }
     // Get unique root requirement IDs from this file
     const rootIds = new Set(fileRequirements.map((req) => req.rootId));
     // Find all test references in the workspace
-    const allTestRefs = await findAllTestReferences(workspaceRoot);
-    // Build coverage map: requirement ID -> list of test references
+    const allTestRefs = await findAllTestReferences(baseRoot);
+    // Build coverage map keyed by ROOT id. A reference may be a bare root
+    // (`AUTH-1`), an index child (`AUTH-1.0`), or a label path (`AUTH-1.given`).
+    // #47: Normalize each reference to its root id (the substring before the
+    // first dot) before keying — the same normalization as the tests-for fix —
+    // so label-path refs match numeric requirement ids instead of rendering as
+    // "(requirement not found)".
     const coverageMap = new Map();
     for (const ref of allTestRefs) {
-        if (!coverageMap.has(ref.requirementId)) {
-            coverageMap.set(ref.requirementId, []);
+        const dotIndex = ref.requirementId.indexOf(".");
+        const refRootId = dotIndex > 0
+            ? ref.requirementId.substring(0, dotIndex)
+            : ref.requirementId;
+        if (!coverageMap.has(refRootId)) {
+            coverageMap.set(refRootId, []);
         }
-        coverageMap.get(ref.requirementId).push(ref);
+        coverageMap.get(refRootId).push(ref);
     }
     // MCP-MAP-2.0: Categorize requirements as covered or not covered
     const covered = [];
@@ -114,7 +149,7 @@ export async function handleGetTestsByRequirement(args, context) {
             }
             output += `- **${id}**: ${tests.length} test${tests.length === 1 ? "" : "s"}\n`;
             for (const [file, lines] of testsByFile.entries()) {
-                const relPath = relative(workspaceRoot, file);
+                const relPath = relative(baseRoot, file);
                 const lineList = lines.sort((a, b) => a - b).join(", ");
                 output += `  - \`${relPath}\` (lines ${lineList})\n`;
             }

package/dist/mcp/handlers/types.d.ts

@@ -64,6 +64,20 @@ export interface HandlerContext {
  * The args parameter contains tool-specific arguments.
  */
 export type ToolHandler<TArgs = Record<string, unknown>> = (args: TArgs, context: HandlerContext) => Promise<ToolResponse>;
+/**
+ * Resolve a user-supplied relative file path to an absolute path.
+ *
+ * #49: The MCP server's workspaceRoot is its process cwd, but in PROJ_*-based
+ * (Antigravity) setups the discovered project.path is the real project root and
+ * differs from cwd. push_requirements resolves against project.path; the other
+ * file-taking handlers historically resolved against workspaceRoot, so the same
+ * relative path worked for push but not for validate/style/review/mapping.
+ *
+ * This resolves against project.path first (matching push) and falls back to
+ * workspaceRoot when the file is not present there, so both layouts work.
+ * Absolute paths are returned unchanged.
+ */
+export declare function resolveProjectFilePath(filePath: string, projectPath: string | undefined, workspaceRoot: string): string;
 /**
  * Helper to create a text response
  */

package/dist/mcp/handlers/types.js

@@ -5,6 +5,33 @@
  * and returns an MCP tool response. This enables unit testing without
  * the full MCP server infrastructure.
  */
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+/**
+ * Resolve a user-supplied relative file path to an absolute path.
+ *
+ * #49: The MCP server's workspaceRoot is its process cwd, but in PROJ_*-based
+ * (Antigravity) setups the discovered project.path is the real project root and
+ * differs from cwd. push_requirements resolves against project.path; the other
+ * file-taking handlers historically resolved against workspaceRoot, so the same
+ * relative path worked for push but not for validate/style/review/mapping.
+ *
+ * This resolves against project.path first (matching push) and falls back to
+ * workspaceRoot when the file is not present there, so both layouts work.
+ * Absolute paths are returned unchanged.
+ */
+export function resolveProjectFilePath(filePath, projectPath, workspaceRoot) {
+    if (isAbsolute(filePath)) {
+        return filePath;
+    }
+    if (projectPath) {
+        const fromProject = resolve(projectPath, filePath);
+        if (existsSync(fromProject)) {
+            return fromProject;
+        }
+    }
+    return resolve(workspaceRoot, filePath);
+}
 /**
  * Helper to create a text response
  */

package/dist/mcp/index.js

@@ -301,6 +301,10 @@ const tools = [
                     type: "string",
                     description: 'Optional: AI model to use for style checking (default: "anthropic/claude-haiku-4.5"). Supported models: "anthropic/claude-haiku-4.5", "google/gemini-3-flash"',
                 },
+                projectId: {
+                    type: "string",
+                    description: "Optional: Specify which project to use (required when multiple projects exist)",
+                },
             },
             required: ["filePath"],
         },

package/dist/push/core.d.ts

@@ -26,6 +26,14 @@ export interface ParsedFile {
     markdownContent: string;
     /** Requirement count for display */
     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
+     * 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.
@@ -85,8 +93,10 @@ export declare const WEB_APP_URL = "https://app.dotrequirements.io";
 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 */
@@ -100,6 +110,18 @@ export interface PushResult {
         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.
@@ -107,11 +129,39 @@ export interface PushResult {
 export declare function extractMarkdownContent(rawContent: string): string;
 /**
  * Parse files for push. 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).
  */
 export declare function parseFilesForPush(filePaths: string[]): {
     parsedFiles: ParsedFile[];
     totalRequirements: number;
 };
+export interface ParseFailure {
+    filePath: string;
+    error: string;
+}
+/**
+ * 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.
+ *
+ * Note: cross-file checks that need the whole batch (e.g. SYNC-FAIL-3
+ * duplicate document IDs) are enforced downstream in dryRunPush, not here.
+ */
+export declare function parseFilesForPushIndividually(filePaths: string[]): {
+    parsedFiles: ParsedFile[];
+    totalRequirements: number;
+    parseFailures: ParseFailure[];
+};
+/**
+ * SYNC-FAIL-3: two ParsedFiles carrying the same document.id would both push
+ * 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.
  */