@ranger-testing/ranger-cli 1.0.1 → 1.0.2

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/cli.js

@@ -1,130 +1,45 @@
 #!/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 } 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) => {
+    .command('add env <app-name> <env-type>', 'Add environment configuration', (yargs) => {
     return yargs
-        .positional('dir', {
+        .positional('app-name', {
         type: 'string',
-        description: 'Target directory (defaults to current directory)',
-        default: process.cwd(),
+        description: 'Name of the application',
+        demandOption: true,
     })
-        .option('token', {
-        alias: 't',
+        .positional('env-type', {
         type: 'string',
-        description: 'Authentication token for the MCP server',
+        description: 'Environment type (local or ci)',
+        choices: ['local', 'ci'],
+        demandOption: true,
+    });
+}, async (argv) => {
+    await addEnv(argv['app-name'], argv['env-type']);
+})
+    .command('use <app-name> <env-type>', 'Switch to using a specific environment', (yargs) => {
+    return yargs
+        .positional('app-name', {
+        type: 'string',
+        description: 'Name of the application',
         demandOption: true,
     })
-        .option('url', {
-        alias: 'u',
+        .positional('env-type', {
         type: 'string',
-        description: 'MCP server URL (defaults to MCP_SERVER_URL env or production server)',
+        description: 'Environment type',
+        choices: ['local', 'ci'],
+        demandOption: true,
     });
 }, async (argv) => {
-    await initAgents(argv.dir, argv.token, argv.url);
+    await useEnv(argv['app-name'], argv['env-type']);
+})
+    .command('start', 'Initialize Ranger in your project', () => { }, async () => {
+    await start();
 })
     .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,162 @@
+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, setRangerServer, 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}`);
+    }
+    // Check if env already exists
+    if (existsSync(envDir)) {
+        const { overwrite } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'overwrite',
+                message: `Environment "${envType}" already exists. Overwrite?`,
+                default: false,
+            },
+        ]);
+        if (!overwrite) {
+            console.log('Aborted.');
+            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([
+        {
+            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(targetUrl);
+        // 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 = {
+        type: envType,
+        targetUrl,
+        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();
+    // Only prompt for token if ranger server doesn't exist
+    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);
+    }
+    // Always 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}"`);
+}

package/build/commands/index.js

@@ -0,0 +1,3 @@
+export { addEnv } from './addEnv.js';
+export { start } from './start.js';
+export { useEnv } from './useEnv.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,88 @@
+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() {
+    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';
+    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 for your app:');
+    console.log('     ranger add env <app-name> local\n');
+}

package/build/commands/useEnv.js

@@ -0,0 +1,35 @@
+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);
+    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}`);
+        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}`);
+        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 "${envType}" for app "${appName}"`);
+}

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.2",
     "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"