@popoverai/dotrequirements 0.18.0 → 0.20.0

package/README.md

@@ -96,8 +96,26 @@ Initialize a new project. Creates `.requirements/` directory, example files, and
 ```bash
 dotreq init
 dotreq init --name my-project
+dotreq init --invite abc123xyz
 ```
 
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--name <name>` | Set project name (skips prompt) |
+| `--invite <token>` | Join a team using an invite token |
+
+**Joining a team via invite:**
+
+If a team admin shares an invite command with you, join the team and connect in one step:
+
+```bash
+npx dotrequirements init --invite abc123xyz
+```
+
+This shows the team name, prompts you to sign in, adds you to the team, and lets you select a project.
+
 ### `dotreq link`
 
 Link your local environment to an existing project (when you already have a project in dot•requirements cloud).
@@ -146,6 +164,37 @@ dotreq test
 dotreq test --file .requirements/auth.requirements.md
 ```
 
+### `dotreq browsertest`
+
+Run browser-based acceptance tests against requirements. Uses AI-powered browser automation to verify that your application behaves as specified.
+
+```bash
+dotreq browsertest LOGIN-1
+dotreq browsertest LOGIN-1 https://example.com
+dotreq browsertest LOGIN-1 --json
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output results as JSON (for CI/CD integration) |
+
+**Configuration required:**
+
+Browser testing requires credentials in `project-settings.json`:
+
+```json
+{
+  "defaultURL": "https://your-app.com",
+  "browserTest": {
+    "geminiApiKey": "your-gemini-api-key"
+  }
+}
+```
+
+Optional settings: `vercelBypassSecret`, `browserbaseApiKey`, `browserbaseProjectId`.
+
 ### `dotreq mcp-setup`
 
 Configure the MCP server for AI assistants (Claude Code, Cursor, etc.).

package/dist/cli.js

@@ -5,6 +5,7 @@ import { linkCommand } from './commands/link.js';
 import { pullCommand } from './commands/pull.js';
 import { pushCommand } from './commands/push.js';
 import { testCommand } from './commands/test.js';
+import { browserTestCommand } from './commands/browsertest.js';
 import { mcpCommand } from './commands/mcp.js';
 import { mcpSetupCommand } from './commands/mcp-setup.js';
 import { loadEnvFile } from './utils/env.js';
@@ -47,6 +48,7 @@ program
     .command('init')
     .description('Initialize a new dotrequirements project')
     .option('-n, --name <name>', 'Project name (defaults to package.json name or directory name)')
+    .option('-i, --invite <token>', 'Join a team using an invite token')
     .action(wrapCommand(initCommand));
 program
     .command('link')
@@ -69,6 +71,11 @@ program
     .description('Validate requirements files in .requirements/')
     .option('-f, --file <path>', 'Specific file to validate')
     .action(wrapCommand(testCommand));
+program
+    .command('browsertest <requirement-key> [url]')
+    .description('Run browser-based acceptance test for a requirement')
+    .option('--json', 'Output results as JSON')
+    .action(wrapCommand(browserTestCommand));
 program
     .command('mcp')
     .description('Start the MCP (Model Context Protocol) server for AI assistant integration')

package/dist/commands/browsertest.d.ts

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

package/dist/commands/browsertest.js

@@ -0,0 +1,167 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { getProjectInfo, readProjectSettings, } from '../utils/project-settings.js';
+import { loadAllRequirements, getRequirementTree, formatRequirement, } from '../mcp/requirements.js';
+const execFileAsync = promisify(execFile);
+export async function browserTestCommand(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. Check for required credentials
+    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');
+        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.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 { stdout } = await execFileAsync('npx', ['@popoverai/browser-automation', 'test', targetURL, ...assertions], { env, maxBuffer: 10 * 1024 * 1024 });
+        // 9. Parse results
+        let results;
+        try {
+            results = JSON.parse(stdout.trim());
+        }
+        catch {
+            console.error('Error: Could not parse browser-automation output');
+            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 results = JSON.parse(error.stdout.trim());
+                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=browsertest.js.map

package/dist/commands/init.d.ts

@@ -1,5 +1,6 @@
 interface InitOptions {
     name?: string;
+    invite?: string;
 }
 export declare function initCommand(options?: InitOptions): Promise<void>;
 export {};

package/dist/commands/init.js

@@ -25,6 +25,19 @@ export async function initCommand(options = {}) {
             console.log('Use "dotrequirements link" to connect or reconnect to cloud.\n');
             return;
         }
+        // MEMBERSHIP-18: If invite token provided, use invite flow
+        if (options.invite) {
+            const initSucceeded = await inviteFlow(cwd, options.invite);
+            if (initSucceeded) {
+                console.log('\nDocumentation: https://docs.dotrequirements.io/getting-started');
+                console.log('By using this service, you agree to our Terms: https://app.dotrequirements.io/terms');
+                const setupMcp = await promptConfirm('\nConfigure AI assistant integration?', true);
+                if (setupMcp) {
+                    await mcpSetupCommand();
+                }
+            }
+            return;
+        }
         // INIT-1: Ask user whether to authenticate
         const authChoice = await promptChoice('Do you want to authenticate before initializing a project? (Recommended)', [
             { title: 'Yes', value: 'yes' },
@@ -290,6 +303,101 @@ async function connectExistingProjectFlow(cwd, client, team) {
     console.log('  1. Review the requirements in .requirements/');
     console.log('  2. Add the test harness to your test setup (see README)');
 }
+/**
+ * MEMBERSHIP-18: Invite flow - join a team using an invite token
+ * Returns true if successfully joined and connected
+ */
+async function inviteFlow(cwd, token) {
+    // MEMBERSHIP-18.0: Validate token before auth (no auth needed for this query)
+    const client = new ConvexHttpClient(getConvexUrl());
+    console.log('Validating invite token...');
+    const inviteInfo = await client.query(api.teamInvites.queries.getInviteInfo, { token });
+    // MEMBERSHIP-18.3: Handle invalid tokens
+    if (!inviteInfo.valid) {
+        const errorMessages = {
+            invalid: 'This invite token is not valid.',
+            expired: 'This invite token has expired.',
+            already_used: 'This invite token has already been used.',
+        };
+        const message = errorMessages[inviteInfo.error] || 'Invalid invite token.';
+        console.error(`\n✗ ${message}`);
+        console.log('Please ask the team admin for a new invite link.\n');
+        return false;
+    }
+    console.log(`\nYou've been invited to join team "${inviteInfo.teamName}"\n`);
+    // MEMBERSHIP-18.1: Auth flow
+    let oauthResult;
+    try {
+        oauthResult = await executeOAuthFlow();
+        console.log();
+    }
+    catch (error) {
+        console.error('\nAuthentication failed:', error instanceof Error ? error.message : String(error));
+        console.log('Please try again later.\n');
+        return false;
+    }
+    // Set up authenticated client
+    client.setAuth(oauthResult.accessToken);
+    // Ensure default team (this also claims any pending email invites via MEMBERSHIP-4)
+    await client.mutation(api.teams.mutations.ensureDefaultTeam, {});
+    // MEMBERSHIP-18.1: Accept invite (joins team, marks token used)
+    // MEMBERSHIP-18.2: If already a member, continue gracefully
+    try {
+        await client.action(api.polar.acceptTeamInvite, { token });
+        console.log(`✓ Joined team "${inviteInfo.teamName}"`);
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        if (errorMessage.includes('already a member')) {
+            console.log(`Already a member of "${inviteInfo.teamName}"`);
+        }
+        else {
+            throw err;
+        }
+    }
+    // MEMBERSHIP-18.1.0: Select project from team
+    const teamId = inviteInfo.teamId;
+    // Get team tier for secret expiry prompt
+    const teams = await client.query(api.teams.queries.listForUserWithUsage);
+    const team = teams.find((t) => t.teamId === teamId);
+    const tier = team?.tier || 'free';
+    const selectedProject = await selectProject(client, teamId);
+    if (!selectedProject) {
+        console.log('Initialization cancelled.');
+        return false;
+    }
+    // AUTHZ-3: Prompt for secret expiry (paid tier only)
+    const expiryDays = await promptExpiryDays(tier);
+    // Get or create secret for this project
+    console.log('\nGetting project credentials...');
+    const secretResult = await getOrCreateProjectSecret(client, selectedProject.projectId, expiryDays);
+    const projectId = selectedProject.projectSlug || selectedProject.projectId;
+    const secret = secretResult.secret;
+    if (secretResult.created) {
+        console.log('✓ Created new project secret');
+    }
+    else {
+        console.log('✓ Retrieved existing project secret');
+    }
+    // Write credentials to project-settings.json
+    writeProjectSettings(cwd, { projectId, projectSecret: secret });
+    console.log('✓ Wrote credentials to .requirements/project-settings.json');
+    // Create directory structure
+    await createRequirementsDirectory(cwd, projectId);
+    // Update .gitignore
+    ensureGitignore(cwd);
+    console.log('✓ Updated .gitignore\n');
+    // Pull existing requirements from cloud
+    console.log('Pulling requirements from cloud...');
+    await pullCommand({ project: projectId });
+    console.log(`\n✓ Successfully connected to project: ${selectedProject.projectName}`);
+    console.log(`  Project ID: ${projectId}`);
+    // Show guidance
+    console.log('\nNext steps:');
+    console.log('  1. Review the requirements in .requirements/');
+    console.log('  2. Add the test harness to your test setup (see README)');
+    return true;
+}
 /**
  * INIT-5: Create .requirements/ directory with README and example
  */

package/dist/convex.d.ts

@@ -39,6 +39,14 @@ export declare const api: {
             ensureDefaultTeam: any;
         };
     };
+    teamInvites: {
+        queries: {
+            getInviteInfo: any;
+        };
+    };
+    polar: {
+        acceptTeamInvite: any;
+    };
     projectSecrets: {
         queries: {
             getOwnSecret: any;

package/dist/convex.js

@@ -41,6 +41,14 @@ export const api = {
             ensureDefaultTeam: 'teams/mutations:ensureDefaultTeam',
         },
     },
+    teamInvites: {
+        queries: {
+            getInviteInfo: 'teamInvites/queries:getInviteInfo',
+        },
+    },
+    polar: {
+        acceptTeamInvite: 'polar:acceptTeamInvite',
+    },
     projectSecrets: {
         queries: {
             getOwnSecret: 'projectSecrets/queries:getOwnSecret',

package/dist/templates/context-file-section.md

@@ -4,6 +4,10 @@ This project uses dotrequirements for requirements tracking. Requirements live i
 
 ### Workflow
 
+**Plan mode:** When planning behavioral changes, your plan should ALWAYS begin
+with a step to write or update requirements. Implementation starts with
+requirements, so your plan should too.
+
 **ALWAYS follow this workflow when changing system behavior** (new features, bug fixes, any behavioral change). Only pure refactoring (same behavior, different code) may skip requirements.
 
 1. **Find or write requirements** - Check `.requirements/` for existing specs; write new ones if needed

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

@@ -1,9 +1,20 @@
+/**
+ * Browser test configuration
+ */
+export interface BrowserTestSettings {
+    geminiApiKey?: string;
+    vercelBypassSecret?: string;
+    browserbaseApiKey?: string;
+    browserbaseProjectId?: string;
+}
 /**
  * Project credentials stored in project-settings.json
  */
 export interface ProjectSettings {
     projectId: string;
     projectSecret: string;
+    defaultURL?: string;
+    browserTest?: BrowserTestSettings;
 }
 /**
  * Project status indicating whether it's connected to cloud

package/dist/utils/project-settings.js

@@ -68,10 +68,32 @@ export function readProjectSettings(projectRoot) {
         typeof parsed.projectSecret !== 'string') {
         throw new Error('project-settings.json is invalid: missing projectId or projectSecret');
     }
-    return {
-        projectId: parsed.projectId,
-        projectSecret: parsed.projectSecret,
+    const record = parsed;
+    const settings = {
+        projectId: record.projectId,
+        projectSecret: record.projectSecret,
     };
+    // Optional fields
+    if (typeof record.defaultURL === 'string') {
+        settings.defaultURL = record.defaultURL;
+    }
+    if (typeof record.browserTest === 'object' && record.browserTest !== null) {
+        const bt = record.browserTest;
+        settings.browserTest = {};
+        if (typeof bt.geminiApiKey === 'string') {
+            settings.browserTest.geminiApiKey = bt.geminiApiKey;
+        }
+        if (typeof bt.vercelBypassSecret === 'string') {
+            settings.browserTest.vercelBypassSecret = bt.vercelBypassSecret;
+        }
+        if (typeof bt.browserbaseApiKey === 'string') {
+            settings.browserTest.browserbaseApiKey = bt.browserbaseApiKey;
+        }
+        if (typeof bt.browserbaseProjectId === 'string') {
+            settings.browserTest.browserbaseProjectId = bt.browserbaseProjectId;
+        }
+    }
+    return settings;
 }
 /**
  * Write project settings to .requirements/project-settings.json

package/package.json

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