@ranger-testing/ranger-cli 1.0.1 → 1.0.3

package/build/agents/bug-basher.md

@@ -0,0 +1,259 @@
+---
+name: bug-basher
+description: "Explores new features via browser to find bugs. Analyzes git diff to understand changes, generates exploration ideas, then systematically tests them to document any issues found."
+tools: Glob, Grep, Read, Bash, 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_evaluate, mcp__ranger-browser__browser_console_messages, mcp__ranger-browser__browser_network_requests, mcp__ranger-browser__browser_tabs, mcp__ranger-browser__browser_navigate_back, mcp__ranger__get_product_docs
+model: sonnet
+color: red
+---
+
+You are a Bug Basher agent. Your job is to explore newly developed features like a curious, slightly mischievous user would - clicking around, trying unexpected inputs, and hunting for bugs. Unlike quality advocates who verify specific flows work, you're an explorer looking for what might break.
+
+You analyze the git diff to understand what changed, then systematically explore those areas in the browser to find issues before real users do.
+
+# Your Workflow
+
+## Step 1: Analyze What Changed
+
+First, understand the scope of changes to know where to focus your exploration:
+
+1. **Determine the default branch:**
+   ```bash
+   DEFAULT_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d' ' -f5)
+   ```
+
+2. **Get the diff against the default branch:**
+   ```bash
+   git diff $DEFAULT_BRANCH...HEAD --name-only  # List changed files
+   git diff $DEFAULT_BRANCH...HEAD              # Full diff for context
+   ```
+
+3. **Understand the changes:**
+   - Use `Read` to examine modified files in detail
+   - Focus on UI components, routes, API interactions, state management
+   - Identify:
+     - New features or pages added
+     - Existing features modified
+     - Components that interact with the changed code
+     - Edge cases implied by the code (error handlers, validation, conditionals)
+
+4. **Get product context:**
+   - Call `mcp__ranger__get_product_docs` to understand the broader product
+   - Map changed files to pages/features in the sitemap
+   - Understand how changes fit into the larger application
+
+## Step 2: Generate Exploration Ideas
+
+Based on your analysis, create a list of things to explore. Think like a curious user and a skeptical tester:
+
+### Categories of Exploration
+
+1. **Happy Path Variations:**
+   - Different valid inputs (short, long, special characters, unicode)
+   - Different sequences of actions to achieve the same goal
+   - Different starting states
+
+2. **Edge Cases:**
+   - Empty states (no data, first-time user)
+   - Boundary conditions (max length, min values, limits)
+   - Rapid actions (double-click, fast typing, spam submit)
+
+3. **Error Conditions:**
+   - Invalid inputs (wrong format, missing required fields)
+   - Network issues (what happens if requests fail?)
+   - Permission/authentication edge cases
+
+4. **Integration Points:**
+   - How does this feature interact with others?
+   - Navigation to/from the feature
+   - State persistence across page refreshes
+   - Browser back/forward behavior
+
+5. **Visual & UX:**
+   - Responsive behavior (if applicable)
+   - Loading states and transitions
+   - Error message clarity
+   - Accessibility concerns
+
+### Present Your Exploration Plan
+
+Before diving in, share your exploration plan with the user:
+- What areas you'll focus on
+- What kinds of issues you'll look for
+- Estimated scope of exploration
+
+Ask if there are specific areas they want you to prioritize or skip.
+
+## Step 3: Explore in the Browser
+
+Now systematically work through your exploration ideas:
+
+1. **Navigate to the feature:**
+   - Use `browser_navigate` to go to the relevant page
+   - Use `browser_snapshot` to understand the current state
+
+2. **Explore methodically:**
+   - Work through your exploration ideas one by one
+   - Try unexpected things a real user might do
+   - Pay attention to:
+     - Console errors (`browser_console_messages`)
+     - Failed network requests (`browser_network_requests`)
+     - Unexpected UI states
+     - Missing feedback or confusing behavior
+
+3. **Document as you go:**
+   - Take screenshots of interesting states (`browser_take_screenshot`)
+   - Note any unexpected behavior, even if not clearly a bug
+   - Track what you've explored vs. what's remaining
+
+4. **Follow your curiosity:**
+   - If something seems off, dig deeper
+   - Try variations of actions that seem to cause issues
+   - Look for patterns in bugs (similar issues across features)
+
+## Step 4: Document Issues Found
+
+For each issue discovered, document it clearly:
+
+### Issue Report Format
+
+```
+## Issue: [Brief Title]
+
+**Severity:** Blocker | Major | Minor | Cosmetic
+
+**Location:** [URL/Page/Component]
+
+**Steps to Reproduce:**
+1. [Step 1]
+2. [Step 2]
+3. ...
+
+**Expected Behavior:**
+[What should happen]
+
+**Actual Behavior:**
+[What actually happens]
+
+**Evidence:**
+- Screenshot: [filename if taken]
+- Console errors: [any relevant errors]
+- Network failures: [any failed requests]
+
+**Notes:**
+[Any additional context, theories about cause, related issues]
+```
+
+### Severity Guidelines
+
+- **Blocker:** Feature is completely broken, data loss, security issue
+- **Major:** Feature partially works but core functionality impaired
+- **Minor:** Feature works but has noticeable issues affecting UX
+- **Cosmetic:** Visual glitches, typos, minor polish issues
+
+## Step 5: Summarize Findings
+
+After exploration, provide a summary:
+
+1. **Overview:**
+   - How much of the feature was explored
+   - Overall quality assessment
+   - Number and severity of issues found
+
+2. **Issues by Severity:**
+   - List blockers first, then major, minor, cosmetic
+   - Group related issues together
+
+3. **Areas Not Explored:**
+   - What you didn't have time to test
+   - What needs different setup/data to test
+   - Suggested follow-up exploration
+
+4. **Positive Observations:**
+   - What works well
+   - Good UX patterns noticed
+   - Robust error handling found
+
+# Guidelines
+
+## Think Like Different Users
+
+- **The Hurried User:** Clicks fast, doesn't read instructions, takes shortcuts
+- **The Confused User:** Doesn't understand the UI, tries wrong things first
+- **The Thorough User:** Fills every field, reads every message, explores every option
+- **The Malicious User:** Tries to break things, enters weird data, looks for exploits
+
+## Be Systematic but Creative
+
+- Have a plan, but don't be afraid to deviate when something interesting appears
+- Track what you've tested to avoid repetition
+- Balance breadth (covering more areas) with depth (thoroughly testing one area)
+
+## Communicate Clearly
+
+- Explain what you're about to explore before doing it
+- Report issues as you find them, don't wait until the end
+- Be specific about reproduction steps - someone else needs to reproduce this
+- Screenshots are invaluable - take them liberally
+
+## Know When to Stop
+
+- If you find a blocker, report it immediately - no point testing more
+- If you've found several major issues, summarize and stop - feature needs work
+- Time-box exploration if the feature is large
+
+# Example Interaction
+
+**User:** Explore the new settings page I just built
+
+**Bug Basher:**
+
+1. Analyzes git diff to see what changed
+2. Reads changed files to understand the feature
+3. Gets product docs for context
+4. Presents exploration plan:
+
+> "I've analyzed your changes. You've added a new Settings page with sections for Profile, Notifications, and Privacy. Here's my exploration plan:
+>
+> **Areas to explore:**
+> 1. Profile editing - name, email, avatar upload
+> 2. Notification toggles - all combinations, persistence
+> 3. Privacy settings - data export, account deletion flow
+> 4. Navigation - getting to/from settings, section switching
+> 5. Edge cases - empty states, invalid inputs, rapid toggling
+>
+> I'll focus especially on the avatar upload (file handling is often buggy) and the account deletion flow (critical user action). Should I proceed, or would you like me to prioritize differently?"
+
+5. Explores the feature:
+
+> "Starting exploration. Navigating to /settings..."
+>
+> [Takes snapshot, sees profile section]
+>
+> "Testing profile editing first. Trying a very long name (200 characters)..."
+>
+> [Types long name, clicks save]
+>
+> "**Issue Found:** The long name is accepted but truncates in the header display, cutting off mid-word. Taking screenshot..."
+>
+> "Moving on to avatar upload. Trying a large file (10MB)..."
+>
+> [Uploads file]
+>
+> "Upload seems to hang with no progress indicator. Checking network requests... The request is still pending after 30 seconds. Checking console... No errors, but no feedback to user either."
+>
+> "**Issue Found:** Large avatar uploads have no progress indicator and may timeout silently."
+
+6. Summarizes findings:
+
+> "**Exploration Summary**
+>
+> Explored: Profile section (100%), Notifications (80%), Privacy (50%)
+>
+> **Issues Found: 4**
+> - 1 Major: Avatar upload hangs on large files with no feedback
+> - 2 Minor: Long names truncate poorly, notification toggle has no confirmation
+> - 1 Cosmetic: Privacy section header misaligned on narrow viewport
+>
+> **Not Explored:** Account deletion (needs confirmation about test account), Data export (long-running operation)
+>
+> **Overall:** The feature is functional but needs polish. The avatar upload issue should be addressed before release. Would you like details on any specific issue?"

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,130 +1,46 @@
 #!/usr/bin/env node
-import { readdir, mkdir, copyFile, writeFile } from 'fs/promises';
-import { join, resolve, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { existsSync } from 'fs';
-import { execSync } from 'child_process';
 import yargs from 'yargs/yargs';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-async function initAgents(targetDir, token, serverUrl) {
-    const resolvedDir = resolve(targetDir);
-    console.log(`Initializing Claude Code agents in: ${resolvedDir}`);
-    // Validate API token by checking /me endpoint
-    const mcpServerUrl = serverUrl ||
-        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);
-    }
-    // Create .claude/agents directory
-    const claudeAgentsDir = join(resolvedDir, '.claude', 'agents');
-    if (!existsSync(claudeAgentsDir)) {
-        await mkdir(claudeAgentsDir, { recursive: true });
-        console.log(`✓ Created directory: ${claudeAgentsDir}`);
-    }
-    // Copy all agent files from agents directory
-    // When running tsx cli.ts: __dirname is packages/cli, so agents is './agents'
-    // When built: __dirname is packages/cli/build, so agents is '../agents'
-    const sourceAgentsDir = existsSync(join(__dirname, 'agents'))
-        ? join(__dirname, 'agents')
-        : join(__dirname, '..', 'agents');
-    try {
-        const agentFiles = await readdir(sourceAgentsDir);
-        const mdFiles = agentFiles.filter((file) => file.endsWith('.md'));
-        if (mdFiles.length === 0) {
-            console.warn('Warning: No agent files found in source directory');
-        }
-        for (const file of mdFiles) {
-            const sourcePath = join(sourceAgentsDir, file);
-            const targetPath = join(claudeAgentsDir, file);
-            await copyFile(sourcePath, targetPath);
-            console.log(`✓ Created agent: ${file}`);
-        }
-    }
-    catch (error) {
-        console.error('Error copying agent files:', error);
-        process.exit(1);
-    }
-    // Create .mcp.json config
-    const mcpConfig = {
-        mcpServers: {
-            ranger: {
-                type: 'http',
-                url: `${mcpServerUrl}/mcp`,
-                headers: {
-                    Authorization: `Bearer ${token}`,
-                },
-            },
-            'ranger-browser': {
-                command: 'npx',
-                args: ['@ranger-testing/playwright', 'run-mcp-server'],
-            },
-        },
-    };
-    const mcpConfigPath = join(resolvedDir, '.mcp.json');
-    await writeFile(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
-    console.log(`✓ Created .mcp.json configuration`);
-    // Check that @ranger-testing/playwright is installed globally
-    try {
-        execSync('npm list -g @ranger-testing/playwright', {
-            stdio: 'pipe',
-        });
-        console.log('✓ @ranger-testing/playwright is installed globally');
-    }
-    catch (error) {
-        console.error('\n┌─────────────────────────────────────────────────────┐');
-        console.error('│  ❌ Missing required dependency                      │');
-        console.error('├─────────────────────────────────────────────────────┤');
-        console.error('│  @ranger-testing/playwright is not installed.       │');
-        console.error('│                                                     │');
-        console.error('│  Please install it globally first:                  │');
-        console.error('│  npm install -g @ranger-testing/playwright          │');
-        console.error('└─────────────────────────────────────────────────────┘\n');
-        process.exit(1);
-    }
-    console.log('\n✅ Claude Code agents initialized successfully!');
-}
+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('init-agents [dir]', 'Initialize Claude Code agents in the specified directory', (yargs) => {
-    return yargs
-        .positional('dir', {
+    .command('add env <env-name>', 'Add environment configuration', (yargs) => {
+    return yargs.positional('env-name', {
         type: 'string',
-        description: 'Target directory (defaults to current directory)',
-        default: process.cwd(),
-    })
-        .option('token', {
-        alias: 't',
+        description: 'Name of the environment (e.g., local, staging, prod)',
+        demandOption: true,
+    });
+}, 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: 'Authentication token for the MCP server',
+        description: 'Name of the environment',
         demandOption: true,
-    })
-        .option('url', {
-        alias: 'u',
+    });
+}, async (argv) => {
+    await useEnv(argv['env-name']);
+})
+    .command('update env <env-name>', 'Update authentication for an existing environment', (yargs) => {
+    return yargs.positional('env-name', {
         type: 'string',
-        description: 'MCP server URL (defaults to MCP_SERVER_URL env or production server)',
+        description: 'Name of the environment to update',
+        demandOption: true,
+    });
+}, async (argv) => {
+    await updateEnv(argv['env-name']);
+})
+    .command('start <token>', 'Initialize Ranger in your project', (yargs) => {
+    return yargs.positional('token', {
+        type: 'string',
+        description: 'Ranger API token with MCP access',
+        demandOption: true,
     });
 }, async (argv) => {
-    await initAgents(argv.dir, argv.token, argv.url);
+    await start(argv.token);
 })
     .demandCommand(1, 'You must specify a command')
     .help()

package/build/commands/addApp.js

@@ -0,0 +1,21 @@
+import { mkdir } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+export async function addApp(appName) {
+    const rangerDir = join(process.cwd(), '.ranger');
+    const appDir = join(rangerDir, appName);
+    // Create .ranger/ if needed
+    if (!existsSync(rangerDir)) {
+        await mkdir(rangerDir, { recursive: true });
+        console.log(`Created .ranger/ directory`);
+    }
+    // Create .ranger/<app-name>/
+    if (existsSync(appDir)) {
+        console.log(`App "${appName}" already exists at ${appDir}`);
+        return;
+    }
+    await mkdir(appDir, { recursive: true });
+    console.log(`\n✅ Created app: ${appName}`);
+    console.log(`   Location: ${appDir}`);
+    console.log(`\nNext step: Run 'ranger-dev add env ${appName} local' to configure an environment.`);
+}

package/build/commands/addEnv.js

@@ -0,0 +1,103 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import inquirer from 'inquirer';
+import { chromium } from 'playwright';
+import { loadMcpConfig, saveMcpConfig, hasRangerServer, setRangerBrowser, } from './utils/mcpConfig.js';
+import { installAgent } from './utils/agents.js';
+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 "${envName}" already exists. Overwrite?`,
+                default: false,
+            },
+        ]);
+        if (!overwrite) {
+            console.log('Aborted.');
+            return;
+        }
+    }
+    // Prompt for auth requirement
+    const { requiresAuth } = await inquirer.prompt([
+        {
+            type: 'confirm',
+            name: 'requiresAuth',
+            message: 'Does this application require authentication?',
+            default: false,
+        },
+    ]);
+    // Create env directory
+    await mkdir(envDir, { recursive: true });
+    const authPath = join(envDir, 'auth.json');
+    let storageStatePath = undefined;
+    if (requiresAuth) {
+        console.log('\n📋 Authentication Setup');
+        console.log('   A browser will open. Please log in to your application.');
+        console.log('   When you are done logging in, close the browser.\n');
+        // Launch Playwright browser
+        const browser = await chromium.launch({ headless: false });
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        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)
+            page.on('close', async () => {
+                try {
+                    console.log('Saving authentication state...');
+                    await context.storageState({ path: authPath });
+                    resolve(authPath);
+                }
+                catch {
+                    // Context may already be closed
+                }
+            });
+        });
+        await browser.close();
+        console.log(`\n✓ Auth state saved to: ${authPath}`);
+    }
+    // Write config.json
+    const config = {
+        name: envName,
+        browser: {
+            isolated: true,
+            browserName: 'chromium',
+            launchOptions: {
+                headless: false,
+            },
+            contextOptions: {
+                permissions: ['clipboard-read', 'clipboard-write'],
+                extraHTTPHeaders: {},
+                storageState: storageStatePath || undefined,
+            },
+        },
+        capabilities: ['core', 'tabs', 'install', 'pdf', 'vision'],
+        imageResponses: 'allow',
+        saveTrace: true,
+    };
+    const configPath = join(envDir, 'config.json');
+    await writeFile(configPath, JSON.stringify(config, null, 2));
+    console.log(`✓ Created config: ${configPath}`);
+    // Load existing .mcp.json or create new one
+    const mcpConfig = await loadMcpConfig();
+    // Check if ranger server is configured
+    if (!hasRangerServer(mcpConfig)) {
+        console.error('\nRanger Tests MCP is not initialized.');
+        console.error('   To initialize, run: ranger start <token>');
+        process.exit(1);
+    }
+    // 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');
+    await installAgent('ui-verifier');
+    console.log(`\n✅ Environment "${envName}" configured`);
+}

package/build/commands/index.js

@@ -0,0 +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/initAgents.js

@@ -0,0 +1,84 @@
+import { readdir, mkdir, copyFile } from 'fs/promises';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync, readdirSync } from 'fs';
+import { execSync } from 'child_process';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export async function initAgents(targetDir) {
+    const resolvedDir = resolve(targetDir);
+    // Check that .ranger/<app>/local exists
+    const rangerDir = join(resolvedDir, '.ranger');
+    if (!existsSync(rangerDir)) {
+        console.error('\n❌ No .ranger directory found.');
+        console.error('   Run first: ranger-dev add app <app-name>');
+        console.error('   Then: ranger-dev add env <app-name> local');
+        process.exit(1);
+    }
+    // Check for at least one app with a local env
+    const apps = readdirSync(rangerDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    const hasLocalEnv = apps.some((app) => existsSync(join(rangerDir, app, 'local')));
+    if (!hasLocalEnv) {
+        console.error('\n❌ No local environment configured.');
+        console.error('   Run first: ranger-dev add env <app-name> local');
+        process.exit(1);
+    }
+    // Check that .mcp.json exists
+    const mcpConfigPath = join(resolvedDir, '.mcp.json');
+    if (!existsSync(mcpConfigPath)) {
+        console.error('\n❌ No .mcp.json found.');
+        console.error('   This should have been created when you ran: ranger-dev add env <app-name> local');
+        process.exit(1);
+    }
+    console.log(`Initializing Claude Code agents in: ${resolvedDir}`);
+    // Create .claude/agents directory
+    const claudeAgentsDir = join(resolvedDir, '.claude', 'agents');
+    if (!existsSync(claudeAgentsDir)) {
+        await mkdir(claudeAgentsDir, { recursive: true });
+        console.log(`✓ Created directory: ${claudeAgentsDir}`);
+    }
+    // Copy all agent files from agents directory
+    // When running tsx cli.ts: __dirname is packages/cli/commands, so agents is '../agents'
+    // When built: __dirname is packages/cli/build/commands, so agents is '../../agents'
+    const sourceAgentsDir = existsSync(join(__dirname, '..', 'agents'))
+        ? join(__dirname, '..', 'agents')
+        : join(__dirname, '..', '..', 'agents');
+    try {
+        const agentFiles = await readdir(sourceAgentsDir);
+        const mdFiles = agentFiles.filter((file) => file.endsWith('.md'));
+        if (mdFiles.length === 0) {
+            console.warn('Warning: No agent files found in source directory');
+        }
+        for (const file of mdFiles) {
+            const sourcePath = join(sourceAgentsDir, file);
+            const targetPath = join(claudeAgentsDir, file);
+            await copyFile(sourcePath, targetPath);
+            console.log(`✓ Created agent: ${file}`);
+        }
+    }
+    catch (error) {
+        console.error('Error copying agent files:', error);
+        process.exit(1);
+    }
+    // Check that @ranger-testing/playwright is installed globally
+    try {
+        execSync('npm list -g @ranger-testing/playwright', {
+            stdio: 'pipe',
+        });
+        console.log('✓ @ranger-testing/playwright is installed globally');
+    }
+    catch (error) {
+        console.error('\n┌─────────────────────────────────────────────────────┐');
+        console.error('│  ❌ Missing required dependency                      │');
+        console.error('├─────────────────────────────────────────────────────┤');
+        console.error('│  @ranger-testing/playwright is not installed.       │');
+        console.error('│                                                     │');
+        console.error('│  Please install it globally first:                  │');
+        console.error('│  npm install -g @ranger-testing/playwright          │');
+        console.error('└─────────────────────────────────────────────────────┘\n');
+        process.exit(1);
+    }
+    console.log('\n✅ Claude Code agents initialized successfully!');
+}

package/build/commands/start.js

@@ -0,0 +1,72 @@
+import { mkdir, readFile, appendFile, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { loadMcpConfig, saveMcpConfig, setRangerServer, } from './utils/mcpConfig.js';
+import { installAgent } from './utils/agents.js';
+export async function start(token) {
+    console.log('\n🚀 Ranger Setup\n');
+    // 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);
+    }
+    // Load or create .mcp.json and set ranger server
+    const mcpConfig = await loadMcpConfig();
+    setRangerServer(mcpConfig, token, mcpServerUrl);
+    await saveMcpConfig(mcpConfig);
+    console.log('✓ Created/updated .mcp.json with Ranger MCP server');
+    // Create .ranger/ directory
+    const rangerDir = join(process.cwd(), '.ranger');
+    if (!existsSync(rangerDir)) {
+        await mkdir(rangerDir, { recursive: true });
+        console.log('✓ Created .ranger/ directory');
+    }
+    else {
+        console.log('✓ .ranger/ directory already exists');
+    }
+    // Copy e2e-test-recommender agent to .claude/agents
+    await installAgent('e2e-test-recommender');
+    // Update .gitignore
+    const gitignorePath = join(process.cwd(), '.gitignore');
+    const gitignoreEntries = ['.ranger-mcp', '.ranger/**/local*'];
+    if (existsSync(gitignorePath)) {
+        const existingContent = await readFile(gitignorePath, 'utf-8');
+        const missingEntries = gitignoreEntries.filter((entry) => !existingContent.includes(entry));
+        if (missingEntries.length > 0) {
+            const newContent = '\n# Ranger\n' + missingEntries.join('\n') + '\n';
+            await appendFile(gitignorePath, newContent);
+            console.log('✓ Updated .gitignore with Ranger entries');
+        }
+        else {
+            console.log('✓ .gitignore already contains Ranger entries');
+        }
+    }
+    else {
+        const content = '# Ranger\n' + gitignoreEntries.join('\n') + '\n';
+        await writeFile(gitignorePath, content);
+        console.log('✓ Created .gitignore with Ranger entries');
+    }
+    // Log next steps
+    console.log('\n✅ Ranger setup complete!\n');
+    console.log('Next steps:');
+    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

@@ -0,0 +1,28 @@
+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(envName) {
+    const envDir = join(process.cwd(), '.ranger', envName);
+    const configPath = join(envDir, 'config.json');
+    // Check env exists
+    if (!existsSync(envDir)) {
+        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 add env ${envName}`);
+        process.exit(1);
+    }
+    // Load and update MCP config
+    const mcpConfig = await loadMcpConfig();
+    setRangerBrowser(mcpConfig, configPath);
+    await saveMcpConfig(mcpConfig);
+    // Install browser-based agents if they don't exist
+    await installAgent('quality-advocate');
+    await installAgent('bug-basher');
+    console.log(`\n✅ Now using environment "${envName}"`);
+}

package/build/commands/utils/agents.js

@@ -0,0 +1,45 @@
+import { mkdir, readdir, copyFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function getSourceAgentsDir() {
+    // Check multiple possible locations for the agents directory
+    const possiblePaths = [
+        join(__dirname, '..', '..', 'agents'),
+        join(__dirname, '..', '..', '..', 'agents'),
+    ];
+    for (const p of possiblePaths) {
+        if (existsSync(p)) {
+            return p;
+        }
+    }
+    return possiblePaths[0];
+}
+export async function installAgent(agentName) {
+    const claudeAgentsDir = join(process.cwd(), '.claude', 'agents');
+    if (!existsSync(claudeAgentsDir)) {
+        await mkdir(claudeAgentsDir, { recursive: true });
+    }
+    const sourceAgentsDir = getSourceAgentsDir();
+    try {
+        const agentFiles = await readdir(sourceAgentsDir);
+        const agentFile = agentFiles.find((f) => f.includes(agentName));
+        if (agentFile) {
+            const sourcePath = join(sourceAgentsDir, agentFile);
+            const targetPath = join(claudeAgentsDir, agentFile);
+            await copyFile(sourcePath, targetPath);
+            console.log(`✓ Added agent: ${agentFile}`);
+            return true;
+        }
+        else {
+            console.warn(`Warning: ${agentName} agent not found in source directory`);
+            return false;
+        }
+    }
+    catch (error) {
+        console.error('Error copying agent file:', error);
+        return false;
+    }
+}

package/build/commands/utils/mcpConfig.js

@@ -0,0 +1,47 @@
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+export function getMcpConfigPath() {
+    return join(process.cwd(), '.mcp.json');
+}
+export async function loadMcpConfig() {
+    const mcpConfigPath = getMcpConfigPath();
+    if (existsSync(mcpConfigPath)) {
+        try {
+            const existingConfig = await readFile(mcpConfigPath, 'utf-8');
+            return JSON.parse(existingConfig);
+        }
+        catch {
+            // If parse fails, start fresh
+            return { mcpServers: {} };
+        }
+    }
+    return { mcpServers: {} };
+}
+export async function saveMcpConfig(config) {
+    const mcpConfigPath = getMcpConfigPath();
+    await writeFile(mcpConfigPath, JSON.stringify(config, null, 2));
+}
+export function hasRangerServer(config) {
+    return !!config.mcpServers.ranger;
+}
+export function setRangerServer(config, token, serverUrl) {
+    config.mcpServers.ranger = {
+        type: 'http',
+        url: `${serverUrl}/mcp`,
+        headers: {
+            Authorization: `Bearer ${token}`,
+        },
+    };
+}
+export function setRangerBrowser(config, configPath) {
+    config.mcpServers['ranger-browser'] = {
+        command: 'npx',
+        args: [
+            '@ranger-testing/playwright',
+            'run-mcp-server',
+            '--config',
+            configPath,
+        ],
+    };
+}

package/build/test-auth.js

@@ -0,0 +1,13 @@
+import { chromium } from 'playwright';
+async function main() {
+    const browser = await chromium.launch({ headless: false });
+    const context = await browser.newContext({
+        storageState: '/Users/adwithmukherjee/dev/lavender-core/lavender-core/.ranger/debug-tool/local/auth.json',
+    });
+    const page = await context.newPage();
+    await page.goto('http://localhost:3000');
+    // Keep browser open
+    console.log('Browser opened. Press Ctrl+C to close.');
+    await new Promise(() => { });
+}
+main().catch(console.error);

package/package.json

@@ -1,20 +1,25 @@
 {
     "name": "@ranger-testing/ranger-cli",
-    "version": "1.0.1",
+    "version": "1.0.3",
     "type": "module",
     "bin": {
-      "ranger": "./build/cli.js"
+      "ranger": "./build/cli.js",
+      "ranger-dev": "./build/cli.js"
     },
     "scripts": {
-      "build": "tsc && chmod 755 build/cli.js",
-      "dev": "tsx cli.ts"
+      "build": "tsc && cp -r src/agents build/ && chmod 755 build/cli.js",
+      "dev": "tsx src/cli.ts"
     },
-    "files": ["build", "agents"],
+    "files": ["build"],
     "dependencies": {
-      "zod": "^3.23.8",
-      "yargs": "^17.7.2"
+      "dotenv": "^16.4.5",
+      "inquirer": "^9.2.12",
+      "playwright": "^1.40.0",
+      "yargs": "^17.7.2",
+      "zod": "^3.23.8"
     },
     "devDependencies": {
+      "@types/inquirer": "^9.0.7",
       "@types/node": "^22.0.0",
       "@types/yargs": "^17.0.32",
       "typescript": "^5.0.0"