@popoverai/dotrequirements 0.23.0 → 0.24.0

package/dist/codebase-to-spec/validate.js

@@ -0,0 +1,130 @@
+/**
+ * Local schema validation for a partial-spec file.
+ *
+ * Mirrors the existing `dotrequirements validate` path (and the
+ * `mcp__dotrequirements__validate_requirements` MCP tool), but works on
+ * partial files — which lack YAML frontmatter — by synthesizing a minimal
+ * wrapper before running the canonical parser.
+ *
+ * This is a deterministic syntax check: it catches things like missing
+ * `→`/`->` arrows, malformed position paths, indentation/position mismatches,
+ * and duplicate IDs — things the AI-driven style-check is not guaranteed
+ * to notice.
+ *
+ * Convention from CLAUDE.md: validate before style-check. Validate is the
+ * cheap, deterministic gate; style-check is the AI clarity pass.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier worker runs a local schema validator on its draft,
+ *   then a local style-check, applying feedback from each.
+ */
+import { readFileSync } from "node:fs";
+import { parseRequirementsFile } from "../schema/parser.js";
+import { ValidationError } from "../schema/schemas.js";
+/**
+ * Wrap a partial in a synthetic frontmatter envelope so the canonical
+ * Markdown-with-frontmatter parser can validate it.
+ */
+function wrapPartial(partialBody) {
+    return [
+        "---",
+        "document:",
+        '  title: "Codebase-to-spec partial"',
+        "---",
+        "",
+        partialBody,
+    ].join("\n");
+}
+/**
+ * Validate a partial-spec file. Reads the file, synthesizes a frontmatter
+ * envelope, and delegates to the canonical parser. Errors are surfaced as
+ * a single human-readable string so the calling agent can act on them as
+ * MUST FIX items.
+ */
+export function runValidate(options) {
+    let content;
+    try {
+        content = readFileSync(options.partialPath, "utf-8");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `Could not read ${options.partialPath}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // Sanity check: the partial should contain at least one fenced
+    // dotrequirements block. A partial with no blocks is also a syntax error
+    // worth surfacing as MUST FIX.
+    if (!/```dotrequirements\s/.test(content)) {
+        return {
+            ok: false,
+            error: "No `dotrequirements` fenced code blocks found in partial. Every requirement must live inside a ```dotrequirements ... ``` block.",
+        };
+    }
+    try {
+        const parsed = parseRequirementsFile(wrapPartial(content));
+        return {
+            ok: true,
+            requirementCount: parsed.requirements.length,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: describeValidationError(err),
+        };
+    }
+}
+/**
+ * The canonical parser wraps low-level failures (e.g. "Each criterion line
+ * must contain the delimiter `->` or `→`") inside a high-level ValidationError
+ * (e.g. "Failed to parse requirement FOO-001"). We want both — the high-level
+ * context tells the agent which block to fix, the low-level reason tells it
+ * what to fix.
+ */
+function describeValidationError(err) {
+    if (err instanceof ValidationError) {
+        const parts = [err.message];
+        let cursor = err.cause;
+        while (cursor instanceof Error) {
+            // Don't repeat the same message twice if the wrapper just rethrew.
+            if (cursor.message && cursor.message !== parts[parts.length - 1]) {
+                parts.push(cursor.message);
+            }
+            cursor = cursor.cause;
+        }
+        return parts.join(" — ");
+    }
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+/**
+ * Format a ValidateResult as the Markdown feedback block the specifier
+ * agent reads on stdout. Mirrors the severity-categorized shape produced
+ * by `runStyleCheck`, so the prompt can describe them uniformly.
+ */
+export function formatValidateFeedback(result) {
+    if (result.ok) {
+        return [
+            "# Schema validation: PASS",
+            "",
+            `${result.requirementCount ?? 0} requirement block(s) parsed cleanly.`,
+            "",
+            "No syntax issues. Proceed to the style-check step.",
+            "",
+        ].join("\n");
+    }
+    return [
+        "# Schema validation: FAIL",
+        "",
+        "## MUST FIX",
+        "",
+        `- ${result.error}`,
+        "",
+        "Fix the syntax issue above with the Edit tool, then re-run validate.",
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=validate.js.map

package/dist/commands/acceptance-test.d.ts

@@ -0,0 +1,6 @@
+interface AcceptanceTestOptions {
+    json?: boolean;
+}
+export declare function acceptanceTestCommand(requirementKey: string, url: string | undefined, options: AcceptanceTestOptions): Promise<void>;
+export {};
+//# sourceMappingURL=acceptance-test.d.ts.map

package/dist/commands/acceptance-test.js

@@ -0,0 +1,212 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { formatRequirement, getRequirementTree, loadAllRequirements, } from "../requirements/index.js";
+import { getProjectInfo, readProjectSettings, } from "../utils/project-settings.js";
+const execFileAsync = promisify(execFile);
+function extractResults(parsed) {
+    if (Array.isArray(parsed))
+        return parsed;
+    if (parsed && typeof parsed === "object") {
+        const obj = parsed;
+        // { results: [...] } format
+        if (Array.isArray(obj.results))
+            return obj.results;
+        // { structured_output: { results: [...] } } format
+        if (obj.structured_output && typeof obj.structured_output === "object") {
+            const so = obj.structured_output;
+            if (Array.isArray(so.results))
+                return so.results;
+        }
+    }
+    throw new Error("Unexpected browser-automation output format");
+}
+export async function acceptanceTestCommand(requirementKey, url, options) {
+    // 1. Find project and load settings
+    const projectInfo = getProjectInfo();
+    if (!projectInfo) {
+        console.error("Error: No dotrequirements project found.");
+        console.log('Run "dotrequirements init" to create one.');
+        process.exit(1);
+    }
+    let settings;
+    try {
+        settings = readProjectSettings(projectInfo.rootPath);
+    }
+    catch (err) {
+        // Settings file exists but is invalid
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+    // 2. Determine URL
+    const targetURL = url || settings?.defaultURL;
+    if (!targetURL) {
+        console.error("Error: No URL provided and no defaultURL in project-settings.json.");
+        console.log('Either provide a URL argument or add "defaultURL" to .requirements/project-settings.json');
+        process.exit(1);
+    }
+    // 3. Resolve model config
+    const modelName = settings?.browserTest?.modelName;
+    const modelApiKey = settings?.browserTest?.modelApiKey;
+    const geminiApiKey = settings?.browserTest?.geminiApiKey;
+    if (!modelName && !modelApiKey && !geminiApiKey) {
+        console.error("Error: no browser-test model configured in project-settings.json.");
+        console.log("Add a block like:\n" +
+            '  "browserTest": {\n' +
+            '    "modelName": "gateway/anthropic/claude-haiku-4-5",\n' +
+            '    "modelApiKey": "..."\n' +
+            "  }\n" +
+            "to .requirements/project-settings.json. See the docs for supported models.");
+        process.exit(1);
+    }
+    if ((modelName && !modelApiKey) || (modelApiKey && !modelName)) {
+        console.error("Error: browserTest.modelName and browserTest.modelApiKey must be set together.");
+        process.exit(1);
+    }
+    // 4. Load requirements
+    const { flattened } = await loadAllRequirements(projectInfo.rootPath);
+    if (flattened.length === 0) {
+        console.error("Error: No requirements found in .requirements/");
+        process.exit(1);
+    }
+    // 5. Find the requirement tree
+    const requirementTree = getRequirementTree(flattened, requirementKey);
+    if (requirementTree.length === 0) {
+        console.error(`Error: Requirement "${requirementKey}" not found.`);
+        process.exit(1);
+    }
+    // 6. Format each requirement as an assertion
+    const assertions = requirementTree.map((req) => formatRequirement(req));
+    // 7. Build environment with injected secrets
+    const env = { ...process.env };
+    // env var keeps the key out of process listings (not a CLI flag)
+    if (modelApiKey) {
+        env.MODEL_API_KEY = modelApiKey;
+    }
+    else if (geminiApiKey) {
+        env.GEMINI_API_KEY = geminiApiKey;
+    }
+    if (settings?.browserTest?.vercelBypassSecret) {
+        env.VERCEL_AUTOMATION_BYPASS_SECRET =
+            settings.browserTest.vercelBypassSecret;
+    }
+    if (settings?.browserTest?.browserbaseApiKey) {
+        env.BROWSERBASE_API_KEY = settings.browserTest.browserbaseApiKey;
+    }
+    if (settings?.browserTest?.browserbaseProjectId) {
+        env.BROWSERBASE_PROJECT_ID = settings.browserTest.browserbaseProjectId;
+    }
+    // 8. Run browser-automation
+    if (!options.json) {
+        console.log(`Testing ${requirementKey} against ${targetURL}...\n`);
+    }
+    try {
+        const modelFlags = modelName ? ["--modelName", modelName] : [];
+        const { stdout } = await execFileAsync("npx", [
+            "@popoverai/browser-automation",
+            "test",
+            ...modelFlags,
+            targetURL,
+            ...assertions,
+        ], { env, maxBuffer: 10 * 1024 * 1024 });
+        // 9. Parse results
+        let results;
+        try {
+            const parsed = JSON.parse(stdout.trim());
+            results = extractResults(parsed);
+        }
+        catch (parseErr) {
+            console.error("Error: Could not parse browser-automation output");
+            console.error(parseErr.message);
+            console.error(stdout);
+            process.exit(1);
+        }
+        // 10. Display results
+        if (options.json) {
+            outputJson(requirementTree, results);
+        }
+        else {
+            displayResults(requirementTree, results);
+        }
+        // 11. Exit with appropriate code
+        const failedCount = results.filter((r) => r.status !== "passed").length;
+        if (failedCount > 0) {
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        const error = err;
+        // browser-automation returns exit code 1 on failure, but still outputs JSON
+        if (error.stdout) {
+            try {
+                const parsed = JSON.parse(error.stdout.trim());
+                const results = extractResults(parsed);
+                if (options.json) {
+                    outputJson(requirementTree, results);
+                }
+                else {
+                    displayResults(requirementTree, results);
+                }
+                process.exit(1);
+            }
+            catch {
+                // Not JSON, show raw output
+                console.error("browser-automation error:");
+                if (error.stdout)
+                    console.error(error.stdout);
+                if (error.stderr)
+                    console.error(error.stderr);
+                process.exit(1);
+            }
+        }
+        else {
+            console.error(`Error running browser-automation: ${error.message}`);
+            if (error.stderr)
+                console.error(error.stderr);
+            process.exit(1);
+        }
+    }
+}
+function displayResults(requirements, results) {
+    let passedCount = 0;
+    let failedCount = 0;
+    for (let i = 0; i < requirements.length; i++) {
+        const req = requirements[i];
+        const result = results[i];
+        if (!result) {
+            console.log(`  ? ${req.id}: No result`);
+            failedCount++;
+            continue;
+        }
+        const indent = "  ".repeat(req.path.length);
+        const label = req.label ? ` (${req.label})` : "";
+        const icon = result.status === "passed" ? "\u2713" : "\u2717";
+        console.log(`${indent}${icon} ${req.id}${label}: ${req.content}`);
+        if (result.status !== "passed" && result.notes) {
+            console.log(`${indent}  \u2192 ${result.notes}`);
+        }
+        if (result.status === "passed") {
+            passedCount++;
+        }
+        else {
+            failedCount++;
+        }
+    }
+    console.log();
+    if (failedCount === 0) {
+        console.log(`${passedCount}/${requirements.length} passed`);
+    }
+    else {
+        console.log(`${passedCount}/${requirements.length} passed, ${failedCount} failed`);
+    }
+}
+function outputJson(requirements, results) {
+    const combined = requirements.map((req, i) => ({
+        id: req.id,
+        label: req.label || null,
+        content: req.content,
+        status: results[i]?.status || "blocked",
+        notes: results[i]?.notes || null,
+    }));
+    console.log(JSON.stringify(combined, null, 2));
+}
+//# sourceMappingURL=acceptance-test.js.map

package/dist/commands/ai-setup.d.ts

@@ -0,0 +1,5 @@
+/**
+ * AI setup command - configures the MCP server for AI assistants
+ */
+export declare function aiSetupCommand(): Promise<void>;
+//# sourceMappingURL=ai-setup.d.ts.map