@popoverai/dotrequirements 0.22.0 → 0.23.0

package/README.md

@@ -182,18 +182,21 @@ dotreq browsertest LOGIN-1 --json
 
 **Configuration required:**
 
-Browser testing requires credentials in `project-settings.json`:
+Browser testing needs a Stagehand model and the API key for that model's provider in `project-settings.json`:
 
 ```json
 {
   "defaultURL": "https://your-app.com",
   "browserTest": {
-    "geminiApiKey": "your-gemini-api-key"
+    "modelName": "gateway/anthropic/claude-haiku-4-5",
+    "modelApiKey": "your-api-key"
   }
 }
 ```
 
-Optional settings: `vercelBypassSecret`, `browserbaseApiKey`, `browserbaseProjectId`.
+Pick any Stagehand-supported model. Example values: `gateway/anthropic/claude-haiku-4-5` (Vercel AI Gateway key), `google/gemini-3-flash-preview` (Gemini key).
+
+Optional settings: `vercelBypassSecret`, `browserbaseApiKey`, `browserbaseProjectId`. Setting both Browserbase fields switches runs from LOCAL (spawns Playwright on your machine) to BROWSERBASE (managed cloud browsers).
 
 ### `dotreq mcp-setup`
 

package/dist/cli.js

@@ -78,7 +78,6 @@ program
     .command('browsertest <requirement-key> [url]')
     .description('Run browser-based acceptance test for a requirement')
     .option('--json', 'Output results as JSON')
-    .option('--useAgent', 'Encourage Claude to use the Agent tool for multi-step tasks')
     .action(wrapCommand(browserTestCommand));
 program
     .command('prepare')

package/dist/commands/browsertest.d.ts

@@ -1,6 +1,5 @@
 interface BrowserTestOptions {
     json?: boolean;
-    useAgent?: boolean;
 }
 export declare function browserTestCommand(requirementKey: string, url: string | undefined, options: BrowserTestOptions): Promise<void>;
 export {};

package/dist/commands/browsertest.js

@@ -44,11 +44,22 @@ export async function browserTestCommand(requirementKey, url, options) {
         console.log('Either provide a URL argument or add "defaultURL" to .requirements/project-settings.json');
         process.exit(1);
     }
-    // 3. Check for required credentials
+    // 3. Resolve model config
+    const modelName = settings?.browserTest?.modelName;
+    const modelApiKey = settings?.browserTest?.modelApiKey;
     const geminiApiKey = settings?.browserTest?.geminiApiKey;
-    if (!geminiApiKey) {
-        console.error('Error: browserTest.geminiApiKey not found in project-settings.json.');
-        console.log('Add "browserTest": { "geminiApiKey": "..." } to .requirements/project-settings.json');
+    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
@@ -67,7 +78,13 @@ export async function browserTestCommand(requirementKey, url, options) {
     const assertions = requirementTree.map((req) => formatRequirement(req));
     // 7. Build environment with injected secrets
     const env = { ...process.env };
-    env.GEMINI_API_KEY = geminiApiKey;
+    // 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;
     }
@@ -82,7 +99,8 @@ export async function browserTestCommand(requirementKey, url, options) {
         console.log(`Testing ${requirementKey} against ${targetURL}...\n`);
     }
     try {
-        const { stdout } = await execFileAsync('npx', ['@popoverai/browser-automation', 'test', ...(options.useAgent ? ['--useAgent'] : []), targetURL, ...assertions], { env, maxBuffer: 10 * 1024 * 1024 });
+        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 {

package/dist/mcp/index.js

@@ -33,17 +33,16 @@ const PROJECT_PATHS = getProjectPathsFromEnv();
 // Parse --auth-from-env flag for CI/CD environments
 // When set, credentials are read from DOTREQ_PROJECT_ID and DOTREQ_PROJECT_SECRET env vars
 const USE_ENV_AUTH = process.argv.includes('--auth-from-env');
-// Cache for loaded requirements (refreshed on each tool call for now)
-let cachedRequirements = new Map();
 let cachedDiscoveryResult = null;
+// Requirements are loaded fresh on every call. A long-lived in-memory cache
+// silently served stale data when .requirements/*.md files were created or
+// edited mid-session, which is the primary authoring workflow the MCP server
+// is meant to support. If this ever becomes a measured performance concern,
+// invalidate via directory mtime rather than reintroducing a lifetime cache.
 async function getRequirements(projectId) {
     const project = await getProjectFromDiscovery(projectId);
-    const cacheKey = project.projectId;
-    if (!cachedRequirements.has(cacheKey)) {
-        const { flattened } = await loadAllRequirements(project.path);
-        cachedRequirements.set(cacheKey, flattened);
-    }
-    return cachedRequirements.get(cacheKey);
+    const { flattened } = await loadAllRequirements(project.path);
+    return flattened;
 }
 async function getProjectFromDiscovery(projectId) {
     const { isConfiguredProject } = await import('../utils/project-discovery.js');
@@ -92,10 +91,9 @@ async function getProjectFromDiscovery(projectId) {
     }
     return resolveProject(cachedDiscoveryResult, projectId);
 }
-// Invalidate cache (call before operations that should see fresh data)
-// Exported for testing
+// Invalidate the project-discovery cache. Requirements are no longer cached,
+// so this only resets discovery state. Exported for testing.
 export function invalidateCache() {
-    cachedRequirements.clear();
     cachedDiscoveryResult = null;
 }
 // Tool definitions

package/dist/schema/browser.d.ts

@@ -9,4 +9,6 @@ export { DEFAULT_DELIMITER, buildRequirementsMarkdown, buildRequirementMarkdown,
 export type { ConvexRequirement, } from './conversions.js';
 export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequirementKeys, groupByRoot, constructKey, parseKey, } from './conversions.js';
 export { DELIMITER_PATTERN, parseCriterionLine, parseRootLine, parseRequirementBlock, extractRequirementBlocks, parseRequirementBlocksFromMarkdown, flattenRequirementTree, findRequirementById, getAllRequirements, } from './parser-core.js';
+export { buildScenarioFromRequirements, requirementTreeToScenario, } from './scenario.js';
+export type { Scenario, ScenarioStep, ScenarioAssertionSource, BuildScenarioOptions, } from './scenario.js';
 //# sourceMappingURL=browser.d.ts.map

package/dist/schema/browser.js

@@ -21,4 +21,6 @@ export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequi
 export { DELIMITER_PATTERN, parseCriterionLine, parseRootLine, parseRequirementBlock, extractRequirementBlocks, parseRequirementBlocksFromMarkdown, flattenRequirementTree, findRequirementById, getAllRequirements, } from './parser-core.js';
 // NOTE: parser.ts and resolver.ts are excluded because they use Node.js 'fs' module.
 // Use parser-core.ts functions above for browser/Convex environments.
+// Scenario building (pure TypeScript - browser-safe, used by Convex Node actions)
+export { buildScenarioFromRequirements, requirementTreeToScenario, } from './scenario.js';
 //# sourceMappingURL=browser.js.map

package/dist/schema/index.d.ts

@@ -11,4 +11,6 @@ export { buildRequirementsMarkdown, buildRequirementMarkdown, buildRequirementsF
 export { parseRequirementPath, parsePathSegment, findChildrenByLabel, resolvePathSegment, resolveRequirementPath, resolveToNumericPath, getAllLabelPaths, checkPathAmbiguity, } from './resolver.js';
 export type { ConvexRequirement, } from './conversions.js';
 export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequirementKeys, groupByRoot, constructKey, parseKey, } from './conversions.js';
+export { buildScenarioFromRequirements, requirementTreeToScenario, } from './scenario.js';
+export type { Scenario, ScenarioStep, ScenarioAssertionSource, BuildScenarioOptions, } from './scenario.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/schema/index.js

@@ -21,4 +21,6 @@ export { buildRequirementsMarkdown, buildRequirementMarkdown, buildRequirementsF
 // Path resolution
 export { parseRequirementPath, parsePathSegment, findChildrenByLabel, resolvePathSegment, resolveRequirementPath, resolveToNumericPath, getAllLabelPaths, checkPathAmbiguity, } from './resolver.js';
 export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequirementKeys, groupByRoot, constructKey, parseKey, } from './conversions.js';
+// Scenario building (for browser-automation / runScenario)
+export { buildScenarioFromRequirements, requirementTreeToScenario, } from './scenario.js';
 //# sourceMappingURL=index.js.map

package/dist/schema/scenario.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Scenario builder — turns a requirement tree into a browser-automation Scenario.
+ *
+ * Used by both the CLI (via `dotreq browsertest`) and the Convex Node action
+ * (`testCoverage/browserRun:run`) so the two paths produce identical scenarios
+ * for the same input.
+ *
+ * Naive passthrough: every requirement node with non-empty content becomes
+ * exactly one assertion keyed by its numeric-path id (e.g. "LOGIN-1" for the
+ * root, "LOGIN-1.0" for the first criterion). No arrange/act steps are
+ * emitted; Stagehand's hybrid agent is expected to infer setup from the
+ * assertion list. See BROWSER-RUN-3 in
+ * .requirements/testing-tab-browser-run.requirements.md.
+ *
+ * Types here are defined locally to avoid adding `@popoverai/browser-automation`
+ * as a runtime dependency of this package. They are structurally compatible
+ * with browser-automation's exported `Scenario` / `Step` types and can be
+ * passed directly to `runScenario`.
+ */
+import type { RequirementNode } from "./schemas.js";
+/**
+ * One step in a scenario. Structurally compatible with
+ * `@popoverai/browser-automation`'s `Step` type.
+ */
+export interface ScenarioStep {
+    step: "arrange" | "act" | "assert";
+    description: string;
+    url?: string;
+    key?: string;
+}
+/**
+ * One entry in the `Scenario.variables` map. Structurally compatible with
+ * `@popoverai/browser-automation`'s `Variable` type — the `value` is what
+ * gets substituted into the scenario, and the optional `description` gives
+ * the agent extra context about what the substitution represents.
+ */
+export interface ScenarioVariable {
+    value: string;
+    description?: string;
+}
+export type ScenarioVariables = Record<string, ScenarioVariable>;
+/**
+ * A scenario passed to `runScenario`. Structurally compatible with
+ * `@popoverai/browser-automation`'s `Scenario` type.
+ */
+export interface Scenario {
+    baseUrl: string;
+    steps: ScenarioStep[];
+    variables?: ScenarioVariables;
+}
+/**
+ * One requirement contributing an assertion to a scenario. The minimum shape
+ * the builder needs so callers sourcing requirements from different backends
+ * (Markdown files via `RequirementNode`, Convex rows, etc.) can all use it.
+ */
+export interface ScenarioAssertionSource {
+    /** Full requirement key including path, e.g. "LOGIN-1" or "LOGIN-1.0.1". */
+    id: string;
+    /** Requirement text; becomes the assertion's `description`. */
+    content: string;
+}
+export interface BuildScenarioOptions {
+    /**
+     * The requirements contributing assertions, in the order they should be
+     * evaluated. Every entry with non-empty `content` becomes one `assert` step.
+     */
+    assertions: ScenarioAssertionSource[];
+    /** Target URL the scenario runs against; becomes `Scenario.baseUrl`. */
+    baseUrl: string;
+    /**
+     * Optional Stagehand variable substitutions. Used to inject secrets
+     * (test-user credentials, bypass tokens) into assertion descriptions
+     * without exposing them to the language model in plaintext.
+     */
+    variables?: Record<string, string>;
+}
+/**
+ * Build a `Scenario` from a list of requirement assertion sources.
+ *
+ * Throws if the resulting scenario would have zero assertions
+ * (browser-automation rejects scenarios with no asserts).
+ */
+export declare function buildScenarioFromRequirements(opts: BuildScenarioOptions): Scenario;
+/**
+ * Convenience wrapper for callers that have a `RequirementNode` tree (root
+ * plus nested children). Flattens the tree to the order produced by
+ * `flattenRequirementTree` (pre-order: root first, then each subtree), then
+ * delegates to `buildScenarioFromRequirements`.
+ */
+export declare function requirementTreeToScenario(root: RequirementNode, opts: Omit<BuildScenarioOptions, "assertions">): Scenario;
+//# sourceMappingURL=scenario.d.ts.map

package/dist/schema/scenario.js

@@ -0,0 +1,82 @@
+/**
+ * Scenario builder — turns a requirement tree into a browser-automation Scenario.
+ *
+ * Used by both the CLI (via `dotreq browsertest`) and the Convex Node action
+ * (`testCoverage/browserRun:run`) so the two paths produce identical scenarios
+ * for the same input.
+ *
+ * Naive passthrough: every requirement node with non-empty content becomes
+ * exactly one assertion keyed by its numeric-path id (e.g. "LOGIN-1" for the
+ * root, "LOGIN-1.0" for the first criterion). No arrange/act steps are
+ * emitted; Stagehand's hybrid agent is expected to infer setup from the
+ * assertion list. See BROWSER-RUN-3 in
+ * .requirements/testing-tab-browser-run.requirements.md.
+ *
+ * Types here are defined locally to avoid adding `@popoverai/browser-automation`
+ * as a runtime dependency of this package. They are structurally compatible
+ * with browser-automation's exported `Scenario` / `Step` types and can be
+ * passed directly to `runScenario`.
+ */
+/**
+ * Pre-order flatten: root first, then each subtree's nodes in order.
+ * Inlined here (rather than imported from `parser.ts`) so this module stays
+ * free of Node-only dependencies and can be re-exported from the browser
+ * entry point.
+ */
+function flattenTree(node) {
+    const result = [node];
+    for (const child of node.children) {
+        result.push(...flattenTree(child));
+    }
+    return result;
+}
+/**
+ * Build a `Scenario` from a list of requirement assertion sources.
+ *
+ * Throws if the resulting scenario would have zero assertions
+ * (browser-automation rejects scenarios with no asserts).
+ */
+export function buildScenarioFromRequirements(opts) {
+    const { assertions, baseUrl, variables } = opts;
+    if (!baseUrl || baseUrl.trim().length === 0) {
+        throw new Error("buildScenarioFromRequirements: baseUrl is required");
+    }
+    const steps = [];
+    for (const source of assertions) {
+        const description = source.content.trim();
+        if (description.length === 0)
+            continue;
+        steps.push({
+            step: "assert",
+            description,
+            key: source.id,
+        });
+    }
+    if (steps.length === 0) {
+        throw new Error("buildScenarioFromRequirements: requirement tree has no nodes with content; cannot build a scenario");
+    }
+    const scenario = { baseUrl, steps };
+    if (variables && Object.keys(variables).length > 0) {
+        // Callers pass a flat Record<string, string> for ergonomics; wrap each
+        // entry as `{ value }` so the scenario matches runScenario's expected
+        // Variables shape. Callers with richer values can set variables on the
+        // returned scenario directly before invocation.
+        scenario.variables = Object.fromEntries(Object.entries(variables).map(([key, value]) => [key, { value }]));
+    }
+    return scenario;
+}
+/**
+ * Convenience wrapper for callers that have a `RequirementNode` tree (root
+ * plus nested children). Flattens the tree to the order produced by
+ * `flattenRequirementTree` (pre-order: root first, then each subtree), then
+ * delegates to `buildScenarioFromRequirements`.
+ */
+export function requirementTreeToScenario(root, opts) {
+    const flat = flattenTree(root);
+    const assertions = flat.map((node) => ({
+        id: node.id,
+        content: node.content,
+    }));
+    return buildScenarioFromRequirements({ ...opts, assertions });
+}
+//# sourceMappingURL=scenario.js.map

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

@@ -1,7 +1,8 @@
-/**
- * Browser test configuration
- */
+/** Browser test configuration. */
 export interface BrowserTestSettings {
+    modelName?: string;
+    modelApiKey?: string;
+    /** @deprecated Backward-compat fallback; use modelName + modelApiKey instead. */
     geminiApiKey?: string;
     vercelBypassSecret?: string;
     browserbaseApiKey?: string;

package/dist/utils/project-settings.js

@@ -80,6 +80,12 @@ export function readProjectSettings(projectRoot) {
     if (typeof record.browserTest === 'object' && record.browserTest !== null) {
         const bt = record.browserTest;
         settings.browserTest = {};
+        if (typeof bt.modelName === 'string') {
+            settings.browserTest.modelName = bt.modelName;
+        }
+        if (typeof bt.modelApiKey === 'string') {
+            settings.browserTest.modelApiKey = bt.modelApiKey;
+        }
         if (typeof bt.geminiApiKey === 'string') {
             settings.browserTest.geminiApiKey = bt.geminiApiKey;
         }

package/package.json

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