@ranger-testing/ranger-cli 1.0.10 → 1.0.12

package/build/skills/feature-tracker/start.md

@@ -0,0 +1,93 @@
+# Starting a Feature Session
+
+At the START of any coding session, check if there's an existing feature to resume before creating a new one.
+
+## Resume by Git Context
+
+Features are automatically associated with the git repo and branch when created. Use `resume` to find and activate a matching feature:
+
+```bash
+ranger feature resume
+```
+
+This command:
+1. Detects current git repo URL and branch name
+2. Searches for in-progress features matching that context
+3. If found, sets it as the active feature
+4. If multiple matches, prompts you to select one
+
+## Check Current Status
+
+After resuming (or if you already have an active feature):
+
+```bash
+ranger feature show
+```
+
+This displays:
+- Feature name and ID
+- Current status (in_progress, blocked, completed)
+- Git context (repo, branch)
+- Checklist with item statuses
+
+## List Active Features
+
+If `resume` doesn't find a match, list all active features:
+
+```bash
+ranger feature list --status in_progress
+```
+
+Or list features for the current branch specifically:
+
+```bash
+ranger feature list --current-branch
+```
+
+## Set Active Feature Manually
+
+If you know the feature ID:
+
+```bash
+ranger feature use feat_abc123
+```
+
+## Decision Tree
+
+```
+Start Session
+     │
+     ▼
+ranger feature resume
+     │
+     ├── Feature found? ──YES──▶ ranger feature show
+     │                                    │
+     │                                    ▼
+     │                           Continue working
+     │
+     └── No match? ──▶ ranger feature list --status in_progress
+                              │
+                              ├── Found one? ──▶ ranger feature use <id>
+                              │
+                              └── None exist? ──▶ See create.md
+```
+
+## Example
+
+```bash
+# Start of session
+$ ranger feature resume
+
+Searching for features matching: github.com/myorg/myapp / feature/auth...
+
+✅ Resumed feature: User Authentication (feat_abc123)
+
+🔄 User Authentication (feat_abc123)
+   Status: in_progress
+   Branch: feature/auth
+
+   Checklist:
+   1. ✅ Login flow works
+   2. ⬜ Signup creates account
+   3. ⬜ Password reset sends email
+```

package/build/skills/feature-tracker/verify.md

@@ -0,0 +1,143 @@
+# Verifying Checklist Items
+
+After implementing code for a checklist item, verify it works in the browser. This creates evidence (screenshots, traces, logs) that the implementation is complete.
+
+## Basic Command
+
+```bash
+ranger verify-feature \
+  --url "<starting url>" \
+  --task "<what to verify>"
+```
+
+## Required: Active Feature
+
+`verify-feature` requires an active feature. If you don't have one:
+
+```bash
+ranger feature resume   # or
+ranger feature use <id>
+```
+
+## The Verification Flow
+
+1. **Select checklist item** - CLI prompts which item this verifies
+2. **Run browser verification** - Agent executes the task in a real browser
+3. **Evaluate results** - Agent determines if the checklist item is satisfied
+4. **Update status** - Item is marked verified, partial, blocked, or failed
+5. **Link evidence** - Session trace is attached to the item
+
+## Options
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--url` | Yes | Starting URL for the verification |
+| `--task` | No | What to verify (defaults to item description) |
+| `--item` | No | Item index to verify (skips selection prompt) |
+| `--new-item` | No | Create and verify a new item |
+
+## Writing Good Task Descriptions
+
+The `--task` is what the verification agent will actually do. Be VERY specific:
+
+**Bad:**
+```bash
+--task "Test login"
+```
+
+**Good:**
+```bash
+--task "Navigate to /login. Enter test@example.com in email field and password123 in password field. Click the Submit button. Verify a loading spinner appears. Verify redirect to /dashboard within 5 seconds. Verify the user's name appears in the header."
+```
+
+## Using Item Description as Task
+
+If your checklist item has a detailed description, you can omit `--task`:
+
+```bash
+# Item 1: "User can log in with valid credentials - sees loading state - redirects to dashboard"
+ranger verify-feature --url "http://localhost:3000/login" --item 1
+```
+
+The item's description becomes the task automatically.
+
+## Evaluation Results
+
+After verification, the agent evaluates if the result satisfies the checklist item:
+
+| Result | Meaning | Item Status |
+|--------|---------|-------------|
+| **Verified** | Task completed, requirements met | ✅ Verified |
+| **Partial** | Some aspects work, others don't | ⬜ Pending (session linked) |
+| **Blocked** | Bug or error prevents completion | 🛑 Blocked |
+| **Failed** | Task couldn't be executed | ⬜ Pending (issues documented) |
+
+## Examples
+
+### Basic Verification
+
+```bash
+ranger verify-feature \
+  --url "http://localhost:3000/login" \
+  --task "Log in with test@example.com / password123, verify redirect to dashboard"
+```
+
+### Verify Specific Item
+
+```bash
+# Skip the selection prompt, verify item 2 directly
+ranger verify-feature \
+  --url "http://localhost:3000/signup" \
+  --task "Complete signup flow with new email" \
+  --item 2
+```
+
+### Create and Verify New Item
+
+```bash
+# Add a new checklist item and verify it in one command
+ranger verify-feature \
+  --url "http://localhost:3000/settings" \
+  --task "Change profile photo and verify it updates" \
+  --new-item "User can update profile photo from settings page"
+```
+
+## After Verification
+
+Check progress:
+
+```bash
+ranger feature show
+```
+
+If all non-canceled items are verified, the feature auto-completes:
+
+```
+✅ User Authentication (feat_abc123)
+   Status: completed
+   ...
+```
+
+## Evidence Captured
+
+Each verification creates:
+- **Playwright trace** - Full browser session replay
+- **Screenshots** - Captured during execution
+- **Conversation log** - Agent's reasoning and actions
+- **Session summary** - What was done and found
+
+Access evidence via the report or dashboard.
+
+## Troubleshooting
+
+### "No active feature"
+Run `ranger feature resume` or `ranger feature use <id>` first.
+
+### "No active environment"
+Run `ranger use <env-name>` to set an environment with browser access.
+
+### Verification times out
+The agent has 59 minutes max. For very long flows, break into smaller checklist items.
+
+### Wrong item marked
+Use `ranger feature manage --reset <index>` to reset an item, then re-verify.

package/package.json

@@ -1,31 +1,34 @@
 {
     "name": "@ranger-testing/ranger-cli",
-    "version": "1.0.10",
+    "version": "1.0.12",
     "type": "module",
     "bin": {
-      "ranger": "./build/cli.js",
-      "ranger-dev": "./build/cli.js"
+        "ranger": "./build/cli.js",
+        "ranger-dev": "./build/cli.js"
     },
     "scripts": {
-      "build": "tsc && npm run obfuscate && cp -r src/skills build/ && chmod 755 build/cli.js",
-      "obfuscate": "node scripts/obfuscate.cjs",
-      "dev": "tsx src/cli.ts"
+        "build": "tsc && npm run obfuscate && cp -r src/skills build/ && chmod 755 build/cli.js",
+        "obfuscate": "node scripts/obfuscate.cjs",
+        "dev": "tsx src/cli.ts",
+        "check-playwright-version": "node scripts/check-playwright-version.cjs"
     },
-    "files": ["build"],
+    "files": [
+        "build"
+    ],
     "dependencies": {
-      "@anthropic-ai/claude-agent-sdk": "^0.1.0",
-      "dotenv": "^16.4.5",
-      "inquirer": "^9.2.12",
-      "keytar": "^7.9.0",
-      "playwright": "^1.40.0",
-      "yargs": "^17.7.2",
-      "zod": "^3.23.8"
+        "@anthropic-ai/claude-agent-sdk": "^0.1.0",
+        "dotenv": "^16.4.5",
+        "inquirer": "^9.2.12",
+        "keytar": "^7.9.0",
+        "playwright": "^1.57.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",
-      "javascript-obfuscator": "^4.1.1",
-      "typescript": "^5.0.0"
+        "@types/inquirer": "^9.0.7",
+        "@types/node": "^22.0.0",
+        "@types/yargs": "^17.0.32",
+        "javascript-obfuscator": "^4.1.1",
+        "typescript": "^5.0.0"
     }
-  }
+}

package/build/agents/bug-basher.md

@@ -1,259 +0,0 @@
----
-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?"