@ranger-testing/ranger-cli 1.0.2 → 1.0.4

package/build/agents/ui-verifier.md

@@ -0,0 +1,100 @@
+---
+name: ui-verifier
+description: "Lightweight agent that opens a browser and clicks through a UI flow to verify it works. Returns immediately when bugs are found. Provide a URL to visit and a detailed summary of the functionality to be verified."
+tools: mcp__ranger-browser__browser_navigate, mcp__ranger-browser__browser_snapshot, mcp__ranger-browser__browser_take_screenshot, mcp__ranger-browser__browser_click, mcp__ranger-browser__browser_type, mcp__ranger-browser__browser_hover, mcp__ranger-browser__browser_select_option, mcp__ranger-browser__browser_press_key, mcp__ranger-browser__browser_fill_form, mcp__ranger-browser__browser_wait_for, mcp__ranger-browser__browser_console_messages, mcp__ranger-browser__browser_network_requests, mcp__ranger-browser__browser_tabs, mcp__ranger-browser__browser_navigate_back
+model: opus
+color: blue
+---
+
+You are a UI Verifier agent. Your ONLY job is to click through a UI flow and report bugs immediately when you find them.
+
+You do NOT:
+- Analyze code or git diffs
+- Suggest tests
+- Draft test cases
+- Do anything other than verify UI functionality
+
+# Input
+
+You will receive:
+1. A URL or starting point
+2. A description of the feature/flow to verify
+3. Expected behavior
+
+# Your Workflow
+
+## 1. Navigate and Take Initial Snapshot
+
+```
+browser_navigate → URL
+browser_snapshot → see the page
+```
+
+## 2. Click Through the Flow
+
+Follow the described user flow step by step:
+- Use `browser_click`, `browser_type`, `browser_fill_form`, etc.
+- Take `browser_snapshot` after each significant action
+- Watch for anything that doesn't match expected behavior
+
+## 3. Return Immediately on Bugs
+
+**CRITICAL:** As soon as you encounter a bug that blocks functionality or clearly doesn't match expectations:
+
+1. Take a screenshot with `browser_take_screenshot`
+2. Check `browser_console_messages` for errors
+3. **STOP and return to the main agent** with:
+   - What you were trying to do
+   - What you expected
+   - What actually happened
+   - The screenshot/evidence
+   - Severity: `BLOCKER` (can't proceed), `MAJOR` (wrong behavior), or `MINOR` (polish issue)
+
+**Do NOT continue testing other parts of the flow.** The main agent needs to fix the issue first.
+
+## 4. If Everything Works
+
+If you complete the entire flow without issues:
+- Return a brief summary: "Verified [flow name]. All steps completed successfully."
+- List the key actions you took
+
+# Example Returns
+
+## Bug Found (return immediately)
+
+```
+BUG FOUND - BLOCKER
+
+Trying to: Submit the login form
+Expected: Navigate to dashboard
+Actual: Form submission does nothing, no error shown
+
+Console errors:
+- TypeError: Cannot read property 'submit' of undefined
+
+Screenshot: [attached]
+
+Recommend: Check the form submission handler
+```
+
+## Success
+
+```
+VERIFIED - Login Flow
+
+All steps completed:
+1. Navigated to /login
+2. Entered email and password
+3. Clicked submit
+4. Successfully redirected to /dashboard
+5. User name displayed correctly in header
+
+No issues found.
+```
+
+# Guidelines
+
+- Be fast - don't over-test, just verify the described flow
+- Be specific - exact error messages, exact steps
+- Be visual - always include screenshots for bugs
+- Return early - don't waste time if something is broken

package/build/cli.js

@@ -1,45 +1,46 @@
 #!/usr/bin/env node
 import yargs from 'yargs/yargs';
-import { addEnv, start, useEnv } from './commands/index.js';
+import { addEnv, start, useEnv, updateEnv } from './commands/index.js';
 import dotenv from 'dotenv';
 dotenv.config();
 // Setup yargs CLI
 yargs(process.argv.slice(2))
     .version('1.0.0')
-    .command('add env <app-name> <env-type>', 'Add environment configuration', (yargs) => {
-    return yargs
-        .positional('app-name', {
+    .command('add env <env-name>', 'Add environment configuration', (yargs) => {
+    return yargs.positional('env-name', {
         type: 'string',
-        description: 'Name of the application',
+        description: 'Name of the environment (e.g., local, staging, prod)',
         demandOption: true,
-    })
-        .positional('env-type', {
+    });
+}, async (argv) => {
+    await addEnv(argv['env-name']);
+})
+    .command('use <env-name>', 'Switch to using a specific environment', (yargs) => {
+    return yargs.positional('env-name', {
         type: 'string',
-        description: 'Environment type (local or ci)',
-        choices: ['local', 'ci'],
+        description: 'Name of the environment',
         demandOption: true,
     });
 }, async (argv) => {
-    await addEnv(argv['app-name'], argv['env-type']);
+    await useEnv(argv['env-name']);
 })
-    .command('use <app-name> <env-type>', 'Switch to using a specific environment', (yargs) => {
-    return yargs
-        .positional('app-name', {
+    .command('update env <env-name>', 'Update authentication for an existing environment', (yargs) => {
+    return yargs.positional('env-name', {
         type: 'string',
-        description: 'Name of the application',
+        description: 'Name of the environment to update',
         demandOption: true,
-    })
-        .positional('env-type', {
+    });
+}, async (argv) => {
+    await updateEnv(argv['env-name']);
+})
+    .command('start <token>', 'Initialize Ranger in your project', (yargs) => {
+    return yargs.positional('token', {
         type: 'string',
-        description: 'Environment type',
-        choices: ['local', 'ci'],
+        description: 'Ranger API token with MCP access',
         demandOption: true,
     });
 }, async (argv) => {
-    await useEnv(argv['app-name'], argv['env-type']);
-})
-    .command('start', 'Initialize Ranger in your project', () => { }, async () => {
-    await start();
+    await start(argv.token);
 })
     .demandCommand(1, 'You must specify a command')
     .help()

package/build/commands/addEnv.js

@@ -3,23 +3,17 @@ import { join } from 'path';
 import { existsSync } from 'fs';
 import inquirer from 'inquirer';
 import { chromium } from 'playwright';
-import { loadMcpConfig, saveMcpConfig, hasRangerServer, setRangerServer, setRangerBrowser, } from './utils/mcpConfig.js';
+import { loadMcpConfig, saveMcpConfig, hasRangerServer, setRangerBrowser, } from './utils/mcpConfig.js';
 import { installAgent } from './utils/agents.js';
-export async function addEnv(appName, envType) {
-    const appDir = join(process.cwd(), '.ranger', appName);
-    const envDir = join(appDir, envType);
-    // Create app directory if it doesn't exist
-    if (!existsSync(appDir)) {
-        await mkdir(appDir, { recursive: true });
-        console.log(`✓ Created app directory: ${appDir}`);
-    }
+export async function addEnv(envName) {
+    const envDir = join(process.cwd(), '.ranger', envName);
     // Check if env already exists
     if (existsSync(envDir)) {
         const { overwrite } = await inquirer.prompt([
             {
                 type: 'confirm',
                 name: 'overwrite',
-                message: `Environment "${envType}" already exists. Overwrite?`,
+                message: `Environment "${envName}" already exists. Overwrite?`,
                 default: false,
             },
         ]);
@@ -28,23 +22,6 @@ export async function addEnv(appName, envType) {
             return;
         }
     }
-    // Prompt for target URL
-    const { targetUrl } = await inquirer.prompt([
-        {
-            type: 'input',
-            name: 'targetUrl',
-            message: 'What is the target URL for this environment?',
-            validate: (input) => {
-                try {
-                    new URL(input);
-                    return true;
-                }
-                catch {
-                    return 'Please enter a valid URL (e.g., https://example.com)';
-                }
-            },
-        },
-    ]);
     // Prompt for auth requirement
     const { requiresAuth } = await inquirer.prompt([
         {
@@ -66,7 +43,7 @@ export async function addEnv(appName, envType) {
         const browser = await chromium.launch({ headless: false });
         const context = await browser.newContext();
         const page = await context.newPage();
-        await page.goto(targetUrl);
+        await page.goto('about:blank');
         // Wait for browser to be closed by user
         storageStatePath = await new Promise((resolve) => {
             // Save storage state when page closes (before context is destroyed)
@@ -86,8 +63,7 @@ export async function addEnv(appName, envType) {
     }
     // Write config.json
     const config = {
-        type: envType,
-        targetUrl,
+        name: envName,
         browser: {
             isolated: true,
             browserName: 'chromium',
@@ -109,54 +85,19 @@ export async function addEnv(appName, envType) {
     console.log(`✓ Created config: ${configPath}`);
     // Load existing .mcp.json or create new one
     const mcpConfig = await loadMcpConfig();
-    // Only prompt for token if ranger server doesn't exist
+    // Check if ranger server is configured
     if (!hasRangerServer(mcpConfig)) {
-        const { token } = await inquirer.prompt([
-            {
-                type: 'password',
-                name: 'token',
-                message: 'Enter your Ranger API token:',
-                mask: '*',
-                validate: (input) => {
-                    if (!input || input.trim().length === 0) {
-                        return 'API token is required';
-                    }
-                    return true;
-                },
-            },
-        ]);
-        // Validate API token
-        const mcpServerUrl = process.env.MCP_SERVER_URL ||
-            'https://mcp-server-301751771437.us-central1.run.app';
-        console.log('Validating API token...');
-        try {
-            const response = await fetch(`${mcpServerUrl}/me`, {
-                method: 'GET',
-                headers: {
-                    Authorization: `Bearer ${token}`,
-                },
-            });
-            if (!response.ok) {
-                console.error(`\n❌ Authentication failed: ${response.status} ${response.statusText}`);
-                console.error('Please check your API token and try again.');
-                process.exit(1);
-            }
-            console.log('✓ API token validated successfully');
-        }
-        catch (error) {
-            console.error('\n❌ Failed to connect to MCP server:', error instanceof Error ? error.message : error);
-            console.error('Please check your network connection and server URL.');
-            process.exit(1);
-        }
-        // Add ranger server config
-        setRangerServer(mcpConfig, token, mcpServerUrl);
+        console.error('\nRanger Tests MCP is not initialized.');
+        console.error('   To initialize, run: ranger start <token>');
+        process.exit(1);
     }
-    // Always update ranger-browser with the config path
+    // Update ranger-browser with the config path
     setRangerBrowser(mcpConfig, configPath);
     await saveMcpConfig(mcpConfig);
     console.log(`✓ Updated .mcp.json configuration`);
     // Copy browser-based agents to .claude/agents
     await installAgent('quality-advocate');
     await installAgent('bug-basher');
-    console.log(`\n✅ Environment "${envType}" configured for app "${appName}"`);
+    await installAgent('ui-verifier');
+    console.log(`\n✅ Environment "${envName}" configured`);
 }

package/build/commands/index.js

@@ -1,3 +1,4 @@
 export { addEnv } from './addEnv.js';
 export { start } from './start.js';
 export { useEnv } from './useEnv.js';
+export { updateEnv } from './updateEnv.js';

package/build/commands/start.js

@@ -1,26 +1,10 @@
 import { mkdir, readFile, appendFile, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { existsSync } from 'fs';
-import inquirer from 'inquirer';
 import { loadMcpConfig, saveMcpConfig, setRangerServer, } from './utils/mcpConfig.js';
 import { installAgent } from './utils/agents.js';
-export async function start() {
+export async function start(token) {
     console.log('\n🚀 Ranger Setup\n');
-    // Prompt for API token
-    const { token } = await inquirer.prompt([
-        {
-            type: 'password',
-            name: 'token',
-            message: 'Enter your Ranger API token:',
-            mask: '*',
-            validate: (input) => {
-                if (!input || input.trim().length === 0) {
-                    return 'API token is required';
-                }
-                return true;
-            },
-        },
-    ]);
     // Validate API token
     const mcpServerUrl = process.env.MCP_SERVER_URL ||
         'https://mcp-server-301751771437.us-central1.run.app';
@@ -83,6 +67,6 @@ export async function start() {
     // Log next steps
     console.log('\n✅ Ranger setup complete!\n');
     console.log('Next steps:');
-    console.log('  Add an environment for your app:');
-    console.log('     ranger add env <app-name> local\n');
+    console.log('  Add an environment:');
+    console.log('     ranger add env local\n');
 }

package/build/commands/updateEnv.js

@@ -0,0 +1,59 @@
+import { writeFile, readFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { chromium } from 'playwright';
+export async function updateEnv(envName) {
+    const envDir = join(process.cwd(), '.ranger', envName);
+    const configPath = join(envDir, 'config.json');
+    const authPath = join(envDir, 'auth.json');
+    // Check if env exists
+    if (!existsSync(envDir)) {
+        console.error(`\nEnvironment "${envName}" not found.`);
+        console.error(`   Run first: ranger add env ${envName}`);
+        process.exit(1);
+    }
+    // Check if config exists
+    if (!existsSync(configPath)) {
+        console.error(`\nConfig not found at ${configPath}`);
+        console.error(`   Run first: ranger add env ${envName}`);
+        process.exit(1);
+    }
+    // Load existing config
+    const configContent = await readFile(configPath, 'utf-8');
+    const config = JSON.parse(configContent);
+    // Check if existing auth state exists
+    const hasExistingAuth = existsSync(authPath);
+    console.log('\n📋 Authentication Update');
+    console.log('   A browser will open with your existing session (if any).');
+    console.log('   Update your authentication as needed.');
+    console.log('   When you are done, close the browser.\n');
+    // Launch Playwright browser with existing storage state if available
+    const browser = await chromium.launch({ headless: false });
+    const contextOptions = hasExistingAuth ? { storageState: authPath } : {};
+    const context = await browser.newContext(contextOptions);
+    const page = await context.newPage();
+    await page.goto('about:blank');
+    // Wait for browser to be closed by user
+    await new Promise((resolve) => {
+        page.on('close', async () => {
+            try {
+                console.log('Saving authentication state...');
+                await context.storageState({ path: authPath });
+                resolve();
+            }
+            catch {
+                // Context may already be closed
+                resolve();
+            }
+        });
+    });
+    await browser.close();
+    console.log(`\n✓ Auth state saved to: ${authPath}`);
+    // Update config to reference the auth file
+    config.browser = config.browser || {};
+    config.browser.contextOptions = config.browser.contextOptions || {};
+    config.browser.contextOptions.storageState = authPath;
+    await writeFile(configPath, JSON.stringify(config, null, 2));
+    console.log(`✓ Updated config: ${configPath}`);
+    console.log(`\n✅ Environment "${envName}" authentication updated`);
+}

package/build/commands/useEnv.js

@@ -2,26 +2,19 @@ import { join } from 'path';
 import { existsSync } from 'fs';
 import { loadMcpConfig, saveMcpConfig, setRangerBrowser, } from './utils/mcpConfig.js';
 import { installAgent } from './utils/agents.js';
-export async function useEnv(appName, envType) {
-    const appDir = join(process.cwd(), '.ranger', appName);
-    const envDir = join(appDir, envType);
+export async function useEnv(envName) {
+    const envDir = join(process.cwd(), '.ranger', envName);
     const configPath = join(envDir, 'config.json');
-    // Check app exists
-    if (!existsSync(appDir)) {
-        console.error(`\n❌ App "${appName}" not found.`);
-        console.error(`   Run first: ranger-dev add app ${appName}`);
-        process.exit(1);
-    }
     // Check env exists
     if (!existsSync(envDir)) {
-        console.error(`\n❌ Environment "${envType}" not found for app "${appName}".`);
-        console.error(`   Run first: ranger-dev add env ${appName} ${envType}`);
+        console.error(`\n❌ Environment "${envName}" not found.`);
+        console.error(`   Run first: ranger add env ${envName}`);
         process.exit(1);
     }
     // Check config exists
     if (!existsSync(configPath)) {
         console.error(`\n❌ Config not found at ${configPath}`);
-        console.error(`   Run first: ranger-dev add env ${appName} ${envType}`);
+        console.error(`   Run first: ranger add env ${envName}`);
         process.exit(1);
     }
     // Load and update MCP config
@@ -31,5 +24,5 @@ export async function useEnv(appName, envType) {
     // Install browser-based agents if they don't exist
     await installAgent('quality-advocate');
     await installAgent('bug-basher');
-    console.log(`\n✅ Now using environment "${envType}" for app "${appName}"`);
+    console.log(`\n✅ Now using environment "${envName}"`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ranger-testing/ranger-cli",
-    "version": "1.0.2",
+    "version": "1.0.4",
     "type": "module",
     "bin": {
       "ranger": "./build/cli.js",
@@ -8,7 +8,8 @@
     },
     "scripts": {
       "build": "tsc && cp -r src/agents build/ && chmod 755 build/cli.js",
-      "dev": "tsx src/cli.ts"
+      "dev": "tsx src/cli.ts",
+      "postinstall": "npx playwright install chromium"
     },
     "files": ["build"],
     "dependencies": {