@popoverai/dotrequirements 0.22.0 → 0.24.0

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

@@ -0,0 +1,183 @@
+/**
+ * Pipeline summary generation.
+ *
+ * Reads cached artifacts to assemble a structured summary of what the
+ * pipeline produced. Surfaced both as JSON (parseable by wrappers like the
+ * skill) and as a short human-readable block.
+ *
+ * Requirements covered:
+ * - CTS-PRESENT-4: Final pipeline summary is surfaced
+ * - CTS-OBSERVE-2 (partial): structured failure information available
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { sanitizeAreaName } from "./fan-out.js";
+import { parseOutlineReview, parseSpecReview, } from "./schemas.js";
+/**
+ * Count top-level requirements in a file by counting fenced
+ * \`\`\`dotrequirements blocks. Each block represents one root requirement
+ * (CTS-OBSERVE-2 counts each requirement ID once, excluding child criteria).
+ */
+function countRequirementsInFile(path) {
+    if (!existsSync(path))
+        return 0;
+    const content = readFileSync(path, "utf-8");
+    const matches = content.match(/```dotrequirements\b/g);
+    return matches ? matches.length : 0;
+}
+/**
+ * Look at outline-review-N.json files in the cache and return how many turns
+ * ran and what the final verdict was. Returns {turnsUsed: 0, finalVerdict: null}
+ * if no review artifacts exist.
+ */
+function summarizeOutlineReview(paths) {
+    let n = 0;
+    let lastReviewPath = null;
+    while (true) {
+        const path = paths.outlineReviewTurn(n + 1);
+        if (!existsSync(path))
+            break;
+        n++;
+        lastReviewPath = path;
+    }
+    if (!lastReviewPath)
+        return { turnsUsed: 0, finalVerdict: null, residualNotes: [] };
+    try {
+        const review = parseOutlineReview(readFileSync(lastReviewPath, "utf-8"));
+        const notes = [];
+        // Surface unresolved findings as residual notes if verdict isn't 'approved'.
+        if (review.verdict !== "approved") {
+            for (const cat of [
+                ["coverage_gap", review.coverage_gaps],
+                ["framing_error", review.framing_errors],
+                ["granularity", review.granularity_issues],
+                ["file_assignment", review.file_assignment_issues],
+            ]) {
+                for (const note of cat[1]) {
+                    notes.push(`outline.${cat[0]}: ${note}`);
+                }
+            }
+        }
+        return { turnsUsed: n, finalVerdict: review.verdict, residualNotes: notes };
+    }
+    catch {
+        return { turnsUsed: n, finalVerdict: null, residualNotes: [] };
+    }
+}
+function summarizeSpecReview(paths) {
+    let n = 0;
+    let lastReviewPath = null;
+    while (true) {
+        const path = paths.specReviewTurn(n + 1);
+        if (!existsSync(path))
+            break;
+        n++;
+        lastReviewPath = path;
+    }
+    if (!lastReviewPath)
+        return { turnsUsed: 0, finalVerdict: null, residualNotes: [] };
+    try {
+        const review = parseSpecReview(readFileSync(lastReviewPath, "utf-8"));
+        const notes = [];
+        if (review.verdict !== "approved") {
+            for (const cat of [
+                ["coverage_gap", review.coverage_gaps],
+                ["framing_error", review.framing_errors],
+                ["cross_area", review.cross_area_issues],
+                ["internal_mechanics", review.internal_mechanics_drift],
+            ]) {
+                for (const note of cat[1]) {
+                    notes.push(`spec.${cat[0]}: ${note}`);
+                }
+            }
+        }
+        return { turnsUsed: n, finalVerdict: review.verdict, residualNotes: notes };
+    }
+    catch {
+        return { turnsUsed: n, finalVerdict: null, residualNotes: [] };
+    }
+}
+function summarizeSpecifiers(outline, paths) {
+    let completed = 0;
+    const missingAreas = [];
+    for (const area of outline.areas) {
+        const partialPath = paths.partial(sanitizeAreaName(area.name));
+        if (!existsSync(partialPath)) {
+            missingAreas.push(area.name);
+            continue;
+        }
+        const content = readFileSync(partialPath, "utf-8").trim();
+        if (!content ||
+            content.startsWith("_(missing partial") ||
+            content.startsWith("_(no files")) {
+            missingAreas.push(area.name);
+            continue;
+        }
+        completed++;
+    }
+    return { completed, missing: missingAreas.length, missingAreas };
+}
+export function buildPipelineSummary(input) {
+    const { outline, paths, outputPaths } = input;
+    const outlineReview = summarizeOutlineReview(paths);
+    const specReview = summarizeSpecReview(paths);
+    const specifiers = summarizeSpecifiers(outline, paths);
+    // Count top-level requirements across all written .requirements/ files.
+    let totalRequirements = 0;
+    for (const path of outputPaths) {
+        totalRequirements += countRequirementsInFile(path);
+    }
+    // Fall back to counting the final cached spec if nothing was written (e.g.
+    // dry-run / interrupted) — that way the summary still reflects what the
+    // pipeline produced.
+    if (totalRequirements === 0 && existsSync(paths.specFinal)) {
+        totalRequirements = countRequirementsInFile(paths.specFinal);
+    }
+    return {
+        totalAreas: outline.areas.length,
+        totalRequirements,
+        outline: outlineReview,
+        specifiers,
+        specReview,
+        outputs: { paths: outputPaths },
+    };
+}
+/**
+ * Render a short human-readable block for the summary. Designed to fit on a
+ * small number of lines (CTS-PRESENT-4.2). Wrappers that want richer
+ * presentation can read the JSON form instead.
+ */
+export function renderSummaryText(summary) {
+    const lines = [];
+    lines.push(`Pipeline summary:`);
+    lines.push(`  Areas:               ${summary.totalAreas}`);
+    lines.push(`  Top-level reqs:      ${summary.totalRequirements}`);
+    lines.push(`  Outline review:      ${summary.outline.turnsUsed} turn(s), verdict: ${summary.outline.finalVerdict ?? "n/a"}`);
+    lines.push(`  Specifiers:          ${summary.specifiers.completed} completed, ${summary.specifiers.missing} missing`);
+    lines.push(`  Spec review:         ${summary.specReview.turnsUsed} turn(s), verdict: ${summary.specReview.finalVerdict ?? "n/a"}`);
+    lines.push(`  Output files:`);
+    for (const path of summary.outputs.paths) {
+        lines.push(`    - ${path}`);
+    }
+    if (summary.outline.residualNotes.length ||
+        summary.specReview.residualNotes.length) {
+        lines.push(``);
+        lines.push(`  Residual notes (worth reviewing manually):`);
+        for (const note of [
+            ...summary.outline.residualNotes,
+            ...summary.specReview.residualNotes,
+        ]) {
+            lines.push(`    - ${note}`);
+        }
+    }
+    if (summary.specifiers.missingAreas.length) {
+        lines.push(``);
+        lines.push(`  Missing specifier output for:`);
+        for (const area of summary.specifiers.missingAreas) {
+            lines.push(`    - ${area}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Suppress unused-var warning. */
+void statSync;
+//# sourceMappingURL=summary.js.map

package/dist/codebase-to-spec/validate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+export interface ValidateOptions {
+    /** Path to the partial-spec file to validate. */
+    partialPath: string;
+}
+export interface ValidateResult {
+    /** True if the partial parsed cleanly. */
+    ok: boolean;
+    /** Human-readable error message when `ok === false`. */
+    error?: string;
+    /** Number of requirement blocks found (when `ok === true`). */
+    requirementCount?: number;
+}
+/**
+ * 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 declare function runValidate(options: ValidateOptions): ValidateResult;
+/**
+ * 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 declare function formatValidateFeedback(result: ValidateResult): string;
+//# sourceMappingURL=validate.d.ts.map

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