@ranger-testing/ranger-cli 1.1.6 → 2.0.0

package/build/cli.js

@@ -18,53 +18,282 @@ function findProjectRoot() {
 // Load .env from project root (not just cwd)
 dotenv.config({ path: join(findProjectRoot(), '.env') });
 import yargs from 'yargs/yargs';
-import { addEnv, clean, login, start, useEnv, updateEnv, update, skillup, envList, hook, } from './commands/index.js';
+import { addEnv, clean, login, start, setupCi, useEnv, updateEnv, update, skillup, envList, hook, } from './commands/index.js';
 import { authEncrypt } from './commands/authEncrypt.js';
 import { status } from './commands/status.js';
 import { configSet, configGet, configList, configUnset, } from './commands/config.js';
-import { dataMcpServer } from './commands/dataMcpServer.js';
-import { verifyInBrowser } from './commands/verifyInBrowser.js';
 import { verifyFeature } from './commands/verifyFeature.js';
-import { featureCreate, featureList, featureShow, featureResume, featureSessions, featureConcludeSession, featureAddChecklistItem, featureGetFeedback, featureDelete, featureRestore, } from './commands/feature.js';
-import { generateMarkdownReport, collectScreenshots, } from './commands/utils/reportGenerator.js';
+import { featureCreate, featureList, featureShow, featureResume, featureAddScenario, featureEditScenario, featureGetReview, featureDelete, featureRestore, } from './commands/feature.js';
 import { logDesirePath, getErrorType, sanitizeArgs, } from './commands/utils/desirePathLog.js';
 import { getCurrentVersion } from './commands/utils/version.js';
+import { withTelemetry, getCurrentCollector, } from './commands/utils/telemetry.js';
+// Capture unhandled rejections for telemetry
+process.on('unhandledRejection', async (reason) => {
+    const collector = getCurrentCollector();
+    if (collector) {
+        await collector.trackCommandError(reason);
+    }
+    process.exitCode = 1;
+});
+const rawArgs = process.argv.slice(2);
+const TOP_LEVEL_HELP = `Usage: ranger <command> [options]
+
+Commands:
+  setup [token]               Initialize Ranger in your project
+  login                       Re-authenticate without full setup
+  skillup                     Install Ranger skills for Claude Code
+  clean                       Remove Ranger artifacts from the project
+  status                      Show version, org, skills, and profile status
+  update                      Update Ranger CLI to the latest version
+
+  profile <command>           Manage profiles (add/use/ls/update/config/encrypt-auth)
+    add <profile-name>        Add profile (options: --ci, --skip-auth)
+    use <profile-name>        Switch active profile
+    ls                        List profiles
+    update <profile-name>     Re-capture auth for a profile
+    encrypt-auth <profile>    Encrypt auth.json for safe git storage
+    config <command>          Set/get/list/unset profile config
+
+  create <name>               Create a feature review with scenarios
+  list                        List feature reviews
+  show [id]                   Show feature review details
+  resume [id]                 Resume a feature review
+  add-scenario <description>  Add a scenario to the active feature review
+  edit-scenario <description> Edit a scenario description
+  get-review [id]             Show reviewer feedback
+  delete [id]                 Soft delete a feature review
+  restore <id>                Restore a soft-deleted feature review
+
+  go                          Verify a scenario in the browser
+
+Run \`ranger <command> --help\` for details.`;
+const PROFILE_HELP = `Usage: ranger profile <command> [options]
+
+Commands:
+  add <profile-name>        Add profile (options: --ci, --skip-auth)
+  use <profile-name>        Switch active profile
+  ls                        List profiles
+  update <profile-name>     Re-capture auth for a profile
+  encrypt-auth <profile>    Encrypt auth.json for safe git storage
+  config <command>          Profile config (set/get/list/unset)
+
+Examples:
+  ranger profile add local
+  ranger profile encrypt-auth ci
+  ranger profile config set local headless true`;
+const PROFILE_CONFIG_HELP = `Usage: ranger profile config <command>
+
+Commands:
+  set <profile> <key> <value>    Set a config value
+  get <profile> <key>            Get a config value
+  list <profile>                 List all config for a profile
+  unset <profile> <key>          Remove a config value
+
+Keys:
+  userAgent        Browser user agent string
+  headless         Run browser in headless mode (true/false)
+  storageState     Path to auth state file (e.g., ./auth.json)
+  header.<name>    Custom HTTP header (e.g., header.X-Test-Mode)
+
+Examples:
+  ranger profile config set ci userAgent "Mozilla/5.0 (CI Bot)"
+  ranger profile config set ci headless true
+  ranger profile config set ci header.Authorization '\${AUTH_TOKEN}'`;
+function warnRenamed(oldUsage, newUsage) {
+    console.error(`\n${oldUsage} is now ${newUsage}\n`);
+}
+function argUsed(flag) {
+    return rawArgs.some((arg) => arg === flag || arg.startsWith(`${flag}=`));
+}
+function warnFlagRenamed(commandPrefix, oldFlag, newFlag) {
+    if (argUsed(oldFlag)) {
+        warnRenamed(`${commandPrefix} ${oldFlag}`, `${commandPrefix} ${newFlag}`);
+    }
+}
+async function runGoCommand(argv, isLegacy = false) {
+    if (isLegacy) {
+        warnRenamed('ranger verify-feature', 'ranger go');
+    }
+    warnFlagRenamed('ranger go', '--env', '--profile');
+    warnFlagRenamed('ranger go', '--task', '--notes');
+    warnFlagRenamed('ranger go', '--item', '--scenario');
+    const result = await verifyFeature({
+        profile: argv.profile ??
+            argv.env,
+        notes: argv.notes ??
+            argv.task,
+        scenario: argv.scenario ??
+            argv.item,
+        startPath: argv['start-path'],
+        debugOutcome: argv['debug-outcome'],
+    });
+    console.log('\n' + '='.repeat(60));
+    console.log(result.evaluation === 'verified'
+        ? ' VERIFIED'
+        : result.evaluation === 'incomplete'
+            ? ' INCOMPLETE'
+            : result.evaluation === 'partial'
+                ? ' PARTIAL'
+                : result.evaluation === 'blocked'
+                    ? ' BLOCKED'
+                    : ' FAILED');
+    console.log('='.repeat(60));
+    console.log(`Summary: ${result.summary}`);
+    console.log(`Evaluation: ${result.evaluation}`);
+    console.log(`Reason: ${result.evaluationReason}`);
+    if (result.issues?.length) {
+        console.log('\nIssues:');
+        result.issues.forEach((issue, i) => {
+            console.log(`\n${i + 1}. [${issue.severity}] ${issue.description}`);
+        });
+    }
+    process.exit(result.evaluation === 'verified' ? 0 : 1);
+}
 // Setup yargs CLI
 yargs(process.argv.slice(2))
+    .scriptName('ranger')
+    .usage(TOP_LEVEL_HELP)
     .version(getCurrentVersion())
-    .command('add env <env-name>', 'Add environment configuration', (yargs) => {
+    .command('create <name>', 'Create a new feature review with scenarios', (yargs) => {
     return yargs
-        .positional('env-name', {
+        .positional('name', {
         type: 'string',
-        description: 'Name of the environment (e.g., local, staging, prod)',
+        description: 'Feature review name',
         demandOption: true,
     })
-        .option('ci', {
+        .option('description', {
+        type: 'string',
+        alias: 'd',
+        description: 'Feature review description',
+    })
+        .option('scenario', {
+        type: 'array',
+        alias: 'c',
+        description: 'Scenarios (use multiple -c flags for multiple scenarios)',
+    })
+        .option('checklist', {
+        type: 'array',
+        hidden: true,
+    });
+}, async (argv) => {
+    warnFlagRenamed('ranger create', '--checklist', '--scenario');
+    const scenarios = argv.scenario ||
+        argv.checklist;
+    await withTelemetry('create', () => featureCreate(argv.name, {
+        description: argv.description,
+        scenarios,
+    }));
+})
+    .command('list', 'List all feature reviews', (yargs) => {
+    return yargs
+        .option('current-branch', {
         type: 'boolean',
-        description: 'Create CI environment (encrypted auth, committed to git)',
-        default: false,
+        description: 'Filter to feature reviews for current git branch',
+    })
+        .option('limit', {
+        type: 'number',
+        alias: 'l',
+        description: 'Maximum number of feature reviews to return',
+        default: 10,
     })
-        .option('no-auth', {
+        .option('offset', {
+        type: 'number',
+        alias: 'o',
+        description: 'Number of feature reviews to skip',
+        default: 0,
+    })
+        .option('include-deleted', {
         type: 'boolean',
-        description: 'Skip browser authentication (just save URL and settings)',
+        alias: 'd',
+        description: 'Include soft-deleted feature reviews',
         default: false,
     });
 }, async (argv) => {
-    await addEnv(argv['env-name'], {
-        ci: argv.ci,
-        noAuth: argv['no-auth'],
+    await withTelemetry('list', () => featureList({
+        currentBranch: argv['current-branch'],
+        limit: argv.limit,
+        offset: argv.offset,
+        includeDeleted: argv['include-deleted'],
+    }));
+})
+    .command('show [id]', 'Show feature review details (uses active feature review if no id)', (yargs) => {
+    return yargs.positional('id', {
+        type: 'string',
+        description: 'Feature review ID',
     });
+}, async (argv) => {
+    await withTelemetry('show', () => featureShow(argv.id));
 })
-    .command('use <env-name>', 'Switch to using a specific environment', (yargs) => {
-    return yargs.positional('env-name', {
+    .command('resume [id]', 'Find and use feature review matching current git context', (yargs) => {
+    return yargs.positional('id', {
         type: 'string',
-        description: 'Name of the environment',
+        description: 'Feature review ID (optional - bypasses search/prompt)',
+    });
+}, async (argv) => {
+    await withTelemetry('resume', () => featureResume(argv.id));
+})
+    .command('add-scenario <description>', 'Add a scenario to the active feature review', (yargs) => {
+    return yargs
+        .positional('description', {
+        type: 'string',
+        description: 'Scenario description',
         demandOption: true,
+    })
+        .option('id', {
+        type: 'string',
+        description: 'Feature review ID (uses active feature review if not provided)',
     });
 }, async (argv) => {
-    await useEnv(argv['env-name']);
+    await withTelemetry('add-scenario', () => featureAddScenario(argv.description, argv.id));
 })
-    .command('start [token]', 'Initialize Ranger in your project', (yargs) => {
+    .command('edit-scenario <description>', 'Edit a scenario description on the active feature review', (yargs) => {
+    return yargs
+        .positional('description', {
+        type: 'string',
+        description: 'New scenario description',
+        demandOption: true,
+    })
+        .option('scenario', {
+        type: 'number',
+        description: 'Scenario number to edit (1-based)',
+        demandOption: true,
+    })
+        .option('id', {
+        type: 'string',
+        description: 'Feature review ID (uses active feature review if not provided)',
+    });
+}, async (argv) => {
+    await withTelemetry('edit-scenario', () => featureEditScenario(argv.description, {
+        id: argv.id,
+        scenario: argv.scenario,
+    }));
+})
+    .command('get-review [id]', 'Show reviewer feedback (comments) for all scenarios', (yargs) => {
+    return yargs.positional('id', {
+        type: 'string',
+        description: 'Feature review ID (uses active feature review if not provided)',
+    });
+}, async (argv) => {
+    await withTelemetry('get-review', () => featureGetReview(argv.id));
+})
+    .command('delete [id]', 'Soft delete a feature review (uses active feature review if no id)', (yargs) => {
+    return yargs.positional('id', {
+        type: 'string',
+        description: 'Feature review ID',
+    });
+}, async (argv) => {
+    await withTelemetry('delete', () => featureDelete(argv.id));
+})
+    .command('restore <id>', 'Restore a soft-deleted feature review', (yargs) => {
+    return yargs.positional('id', {
+        type: 'string',
+        description: 'Feature review ID to restore',
+        demandOption: true,
+    });
+}, async (argv) => {
+    await withTelemetry('restore', () => featureRestore(argv.id));
+})
+    .command('setup [token]', 'Initialize Ranger in your project', (yargs) => {
     return yargs
         .positional('token', {
         type: 'string',
@@ -76,22 +305,331 @@ yargs(process.argv.slice(2))
         default: false,
     });
 }, async (argv) => {
-    await start(argv.token, {
+    await withTelemetry('start', (telemetry) => start(argv.token, {
         skipChromium: argv['skip-chromium'],
+    }, telemetry));
+})
+    .command('setup-ci <token>', 'Set up Ranger for CI (non-interactive)', (yargs) => {
+    return yargs
+        .positional('token', {
+        type: 'string',
+        description: 'Ranger API token',
+        demandOption: true,
+    })
+        .option('profile', {
+        type: 'string',
+        description: 'CI profile name (auto-detected if only one exists)',
+    })
+        .option('base-url', {
+        type: 'string',
+        description: 'Base URL for the app (creates/updates profile settings)',
+    })
+        .option('skip-chromium', {
+        type: 'boolean',
+        description: 'Skip Chromium browser installation',
+        default: false,
     });
+}, async (argv) => {
+    await withTelemetry('setup-ci', (telemetry) => setupCi(argv.token, {
+        profile: argv.profile,
+        baseUrl: argv['base-url'],
+        skipChromium: argv['skip-chromium'],
+    }, telemetry));
 })
     .command('login', 'Log in to Ranger via browser (re-authenticate without full setup)', () => { }, async () => {
-    await login();
+    await withTelemetry('login', () => login());
 })
     .command('skillup', 'Install Ranger skills for Claude Code', () => { }, async () => {
-    await skillup();
+    await withTelemetry('skillup', () => skillup());
+})
+    .command('clean', 'Remove all Ranger artifacts from the project', () => { }, async () => {
+    await withTelemetry('clean', () => clean());
+})
+    .command('profile', 'Manage profiles', (yargs) => {
+    return yargs
+        .usage(PROFILE_HELP)
+        .command('add <profile-name>', 'Add profile configuration', (yargs) => {
+        return yargs
+            .positional('profile-name', {
+            type: 'string',
+            description: 'Name of the profile (e.g., local, staging, prod)',
+            demandOption: true,
+        })
+            .option('ci', {
+            type: 'boolean',
+            description: 'Create CI profile (encrypted auth, committed to git)',
+            default: false,
+        })
+            .option('skip-auth', {
+            type: 'boolean',
+            description: 'Skip browser authentication (just save URL and settings)',
+            default: false,
+        });
+    }, async (argv) => {
+        await withTelemetry('profile add', (telemetry) => addEnv(argv['profile-name'], {
+            ci: argv.ci,
+            skipAuth: argv['skip-auth'],
+        }, telemetry));
+    })
+        .command('use <profile-name>', 'Switch to using a specific profile', (yargs) => {
+        return yargs.positional('profile-name', {
+            type: 'string',
+            description: 'Name of the profile',
+            demandOption: true,
+        });
+    }, async (argv) => {
+        await withTelemetry('profile use', () => useEnv(argv['profile-name']));
+    })
+        .command('encrypt-auth <profile>', 'Encrypt auth.json for a profile (allows committing to git)', (yargs) => {
+        return yargs.positional('profile', {
+            type: 'string',
+            description: 'Profile name',
+            demandOption: true,
+        });
+    }, async (argv) => {
+        await withTelemetry('profile encrypt-auth', () => authEncrypt(argv.profile));
+    })
+        .command('ls', 'List all profiles', () => { }, async () => {
+        await withTelemetry('profile ls', () => envList());
+    })
+        .command('update <profile-name>', 'Update authentication for an existing profile', (yargs) => {
+        return yargs.positional('profile-name', {
+            type: 'string',
+            description: 'Name of the profile to update',
+            demandOption: true,
+        });
+    }, async (argv) => {
+        await withTelemetry('profile update', (telemetry) => updateEnv(argv['profile-name'], telemetry));
+    })
+        .command('config', 'Manage profile configuration', (yargs) => {
+        return yargs
+            .usage(PROFILE_CONFIG_HELP)
+            .command('set <profile> <key> <value>', 'Set a config value', (yargs) => {
+            return yargs
+                .positional('profile', {
+                type: 'string',
+                description: 'Profile name',
+                demandOption: true,
+            })
+                .positional('key', {
+                type: 'string',
+                description: 'Config key (e.g., userAgent, header.X-Custom)',
+                demandOption: true,
+            })
+                .positional('value', {
+                type: 'string',
+                description: 'Config value',
+                demandOption: true,
+            });
+        }, async (argv) => {
+            await withTelemetry('profile config set', () => configSet(argv.profile, argv.key, argv.value));
+        })
+            .command('get <profile> <key>', 'Get a config value', (yargs) => {
+            return yargs
+                .positional('profile', {
+                type: 'string',
+                description: 'Profile name',
+                demandOption: true,
+            })
+                .positional('key', {
+                type: 'string',
+                description: 'Config key',
+                demandOption: true,
+            });
+        }, async (argv) => {
+            await withTelemetry('profile config get', () => configGet(argv.profile, argv.key));
+        })
+            .command('list <profile>', 'List all config for a profile', (yargs) => {
+            return yargs.positional('profile', {
+                type: 'string',
+                description: 'Profile name',
+                demandOption: true,
+            });
+        }, async (argv) => {
+            await withTelemetry('profile config list', () => configList(argv.profile));
+        })
+            .command('unset <profile> <key>', 'Remove a config value', (yargs) => {
+            return yargs
+                .positional('profile', {
+                type: 'string',
+                description: 'Profile name',
+                demandOption: true,
+            })
+                .positional('key', {
+                type: 'string',
+                description: 'Config key to remove',
+                demandOption: true,
+            });
+        }, async (argv) => {
+            await withTelemetry('profile config unset', () => configUnset(argv.profile, argv.key));
+        })
+            .demandCommand(1, 'You must specify a profile config subcommand');
+    })
+        .demandCommand(1, 'You must specify a profile subcommand');
+})
+    .command('status', 'Show Ranger status (version, skills, profiles)', () => { }, async () => {
+    await withTelemetry('status', () => status());
+})
+    .command('update', 'Update Ranger CLI to the latest version', () => { }, async () => {
+    await withTelemetry('update', () => update());
+})
+    .command('go', 'Verify a scenario in the browser (requires active feature review)', (yargs) => {
+    return yargs
+        .option('profile', {
+        type: 'string',
+        description: 'Profile to use (defaults to active profile)',
+    })
+        .option('notes', {
+        type: 'string',
+        description: 'Notes for verification (defaults to scenario description)',
+    })
+        .option('scenario', {
+        type: 'number',
+        description: 'Scenario index (1-based)',
+    })
+        .option('start-path', {
+        type: 'string',
+        description: 'Path to start on (appended to base URL, e.g., /dashboard)',
+    })
+        .option('debug-outcome', {
+        type: 'string',
+        hidden: true,
+        choices: [
+            'verified',
+            'partial',
+            'blocked',
+            'failed',
+            'incomplete',
+        ],
+    })
+        .option('env', {
+        type: 'string',
+        hidden: true,
+    })
+        .option('task', {
+        type: 'string',
+        hidden: true,
+    })
+        .option('item', {
+        type: 'number',
+        hidden: true,
+    });
+}, async (argv) => {
+    await runGoCommand(argv);
+})
+    // Legacy command shims (hidden from help)
+    .command('auth', false, (yargs) => {
+    return yargs
+        .command('encrypt <profile>', false, (yargs) => {
+        return yargs.positional('profile', {
+            type: 'string',
+            description: 'Profile name',
+            demandOption: true,
+        });
+    }, async (argv) => {
+        warnRenamed('ranger auth encrypt', 'ranger profile encrypt-auth');
+        await authEncrypt(argv.profile);
+    })
+        .demandCommand(1, 'You must specify an auth subcommand');
+}, () => { })
+    .command('start [token]', false, (yargs) => {
+    return yargs
+        .positional('token', {
+        type: 'string',
+        description: 'Ranger API token (omit to log in via browser)',
+    })
+        .option('skip-chromium', {
+        type: 'boolean',
+        description: 'Skip Chromium browser check and installation',
+        default: false,
+    });
+}, async (argv) => {
+    warnRenamed('ranger start', 'ranger setup');
+    await withTelemetry('start', (telemetry) => start(argv.token, {
+        skipChromium: argv['skip-chromium'],
+    }, telemetry));
+})
+    .command('verify-feature', false, (yargs) => {
+    return yargs
+        .option('env', {
+        type: 'string',
+        description: 'Profile to use (defaults to active profile)',
+    })
+        .option('task', {
+        type: 'string',
+        description: 'Task description (defaults to scenario description)',
+    })
+        .option('item', {
+        type: 'number',
+        description: 'Scenario index (1-based)',
+    })
+        .option('profile', {
+        type: 'string',
+        hidden: true,
+    })
+        .option('notes', {
+        type: 'string',
+        hidden: true,
+    })
+        .option('scenario', {
+        type: 'number',
+        hidden: true,
+    })
+        .option('start-path', {
+        type: 'string',
+        description: 'Path to start on (appended to base URL, e.g., /dashboard)',
+    })
+        .option('debug-outcome', {
+        type: 'string',
+        hidden: true,
+        choices: [
+            'verified',
+            'partial',
+            'blocked',
+            'failed',
+            'incomplete',
+        ],
+    });
+}, async (argv) => {
+    await runGoCommand(argv, true);
+})
+    .command('add env <env-name>', false, (yargs) => {
+    return yargs
+        .positional('env-name', {
+        type: 'string',
+        description: 'Name of the environment (e.g., local, staging, prod)',
+        demandOption: true,
+    })
+        .option('ci', {
+        type: 'boolean',
+        description: 'Create CI environment (encrypted auth, committed to git)',
+        default: false,
+    })
+        .option('skip-auth', {
+        type: 'boolean',
+        description: 'Skip browser authentication (just save URL and settings)',
+        default: false,
+    });
+}, async (argv) => {
+    warnRenamed('ranger add env', 'ranger profile add');
+    await withTelemetry('add env', (telemetry) => addEnv(argv['env-name'], {
+        ci: argv.ci,
+        skipAuth: argv['skip-auth'],
+    }, telemetry));
 })
-    .command('clean', 'Remove all Ranger artifacts from the project', async () => {
-    await clean();
+    .command('use <env-name>', false, (yargs) => {
+    return yargs.positional('env-name', {
+        type: 'string',
+        description: 'Name of the environment',
+        demandOption: true,
+    });
+}, async (argv) => {
+    warnRenamed('ranger use', 'ranger profile use');
+    await withTelemetry('use', () => useEnv(argv['env-name']));
 })
-    .command('config', 'Manage environment configuration', (yargs) => {
+    .command('config', false, (yargs) => {
     return yargs
-        .command('set <env> <key> <value>', 'Set a config value', (yargs) => {
+        .command('set <env> <key> <value>', false, (yargs) => {
         return yargs
             .positional('env', {
             type: 'string',
@@ -109,9 +647,10 @@ yargs(process.argv.slice(2))
             demandOption: true,
         });
     }, async (argv) => {
-        await configSet(argv.env, argv.key, argv.value);
+        warnRenamed('ranger config set', 'ranger profile config set');
+        await withTelemetry('config set', () => configSet(argv.env, argv.key, argv.value));
     })
-        .command('get <env> <key>', 'Get a config value', (yargs) => {
+        .command('get <env> <key>', false, (yargs) => {
         return yargs
             .positional('env', {
             type: 'string',
@@ -124,18 +663,20 @@ yargs(process.argv.slice(2))
             demandOption: true,
         });
     }, async (argv) => {
-        await configGet(argv.env, argv.key);
+        warnRenamed('ranger config get', 'ranger profile config get');
+        await withTelemetry('config get', () => configGet(argv.env, argv.key));
     })
-        .command('list <env>', 'List all config for an environment', (yargs) => {
+        .command('list <env>', false, (yargs) => {
         return yargs.positional('env', {
             type: 'string',
             description: 'Environment name',
             demandOption: true,
         });
     }, async (argv) => {
-        await configList(argv.env);
+        warnRenamed('ranger config list', 'ranger profile config list');
+        await withTelemetry('config list', () => configList(argv.env));
     })
-        .command('unset <env> <key>', 'Remove a config value', (yargs) => {
+        .command('unset <env> <key>', false, (yargs) => {
         return yargs
             .positional('env', {
             type: 'string',
@@ -148,368 +689,195 @@ yargs(process.argv.slice(2))
             demandOption: true,
         });
     }, async (argv) => {
-        await configUnset(argv.env, argv.key);
+        warnRenamed('ranger config unset', 'ranger profile config unset');
+        await withTelemetry('config unset', () => configUnset(argv.env, argv.key));
     })
-        .demandCommand(1, 'You must specify a config subcommand')
-        .epilogue(`Supported keys:
-  userAgent        Browser user agent string
-  headless         Run browser in headless mode (true/false)
-  storageState     Path to auth state file (e.g., ./auth.json)
-  header.<name>    Custom HTTP header (e.g., header.X-Test-Mode)
-
-Examples:
-  ranger config set ci userAgent "Mozilla/5.0 (CI Bot)"
-  ranger config set ci headless true
-  ranger config set ci header.Authorization '\${AUTH_TOKEN}'`);
-})
-    .command('auth', 'Manage authentication', (yargs) => {
-    return yargs
-        .command('encrypt <env>', 'Encrypt auth.json for an environment (allows committing to git)', (yargs) => {
-        return yargs.positional('env', {
-            type: 'string',
-            description: 'Environment name',
-            demandOption: true,
-        });
-    }, async (argv) => {
-        await authEncrypt(argv.env);
-    })
-        .demandCommand(1, 'You must specify an auth subcommand')
-        .epilogue(`Commands:
-  encrypt <env>    Encrypt auth.json for safe git storage
-
-Examples:
-  ranger auth encrypt local     # Encrypts .ranger/local/auth.json -> auth.json.enc
-  ranger auth encrypt ci        # Encrypts .ranger/ci/auth.json -> auth.json.enc`);
+        .demandCommand(1, 'You must specify a config subcommand');
 })
-    .command('env', 'Manage environments', (yargs) => {
+    .command('env', false, (yargs) => {
     return yargs
-        .command('ls', 'List all environments', () => { }, async () => {
-        await envList();
+        .command('ls', false, () => { }, async () => {
+        warnRenamed('ranger env ls', 'ranger profile ls');
+        await withTelemetry('env list', () => envList());
     })
-        .command('update <env-name>', 'Update authentication for an existing environment', (yargs) => {
+        .command('update <env-name>', false, (yargs) => {
         return yargs.positional('env-name', {
             type: 'string',
             description: 'Name of the environment to update',
             demandOption: true,
         });
     }, async (argv) => {
-        await updateEnv(argv['env-name']);
+        warnRenamed('ranger env update', 'ranger profile update');
+        await withTelemetry('env update', (telemetry) => updateEnv(argv['env-name'], telemetry));
     })
-        .demandCommand(1, 'You must specify an env subcommand, try ranger env help')
-        .epilogue(`Commands:
-  ls               List all environments
-  update <env>     Update authentication for an environment
-
-Examples:
-  ranger env ls              # List all environments
-  ranger env update local    # Update auth for local environment`);
-})
-    .command('data-mcp-server', 'Run MCP proxy server (reads local credentials)', async () => {
-    await dataMcpServer();
+        .demandCommand(1, 'You must specify an env subcommand');
 })
-    .command('verify-in-browser', false, (yargs) => {
+    .command('feature', false, (yargs) => {
     return yargs
-        .option('task', {
-        type: 'string',
-        description: 'Description of UI flow to verify',
-        demandOption: true,
-    })
-        .option('env', {
-        type: 'string',
-        description: 'Environment to use (defaults to active environment)',
-    })
-        .option('headed', {
-        type: 'boolean',
-        description: 'Run browser in headed mode (default: headless)',
-        default: false,
-    });
-}, async (argv) => {
-    const result = await verifyInBrowser(argv.task, {
-        env: argv.env,
-        headed: argv.headed,
-    });
-    console.log('\n' + '='.repeat(60));
-    console.log(result.success ? ' VERIFIED' : ' ISSUES FOUND');
-    console.log('='.repeat(60));
-    console.log(result.summary);
-    if (result.issues?.length) {
-        console.log('\nIssues:');
-        result.issues.forEach((issue, i) => {
-            console.log(`\n${i + 1}. [${issue.severity}] ${issue.description}`);
-            if (issue.screenshot)
-                console.log(`   Screenshot: ${issue.screenshot}`);
-        });
-    }
-    if (result.traceViewerUrl) {
-        console.log(`\nFull Trace: ${result.traceViewerUrl}`);
-    }
-    // Generate and output markdown report with delimiters
-    if (result.sessionId && result.sessionDir) {
-        const { screenshots } = await collectScreenshots(result.sessionDir);
-        const markdownReport = generateMarkdownReport({
-            sessionId: result.sessionId,
-            task: result.task || argv.task,
-            url: result.url || '',
-            success: result.success,
-            summary: result.summary,
-            issues: result.issues?.filter((issue) => issue.severity !== 'MINOR'),
-            screenshots,
-            durationMs: result.durationMs || 0,
-            traceViewerUrl: result.traceViewerUrl,
-        });
-        console.log('\n' + '='.repeat(60));
-        console.log('VERIFICATION_REPORT_START');
-        console.log('='.repeat(60));
-        console.log(markdownReport);
-        console.log('='.repeat(60));
-        console.log('VERIFICATION_REPORT_END');
-        console.log('='.repeat(60));
-    }
-    process.exit(result.success ? 0 : 1);
-})
-    .command('status', 'Show Ranger status (version, skills, environments)', () => { }, async () => {
-    await status();
-})
-    .command('update', 'Update Ranger CLI to the latest version', () => { }, async () => {
-    await update();
-})
-    .command('feature', 'Manage feature tracking', (yargs) => {
-    return yargs
-        .command('create <name>', 'Create a new feature with checklist', (yargs) => {
+        .command('create <name>', false, (yargs) => {
         return yargs
             .positional('name', {
             type: 'string',
-            description: 'Feature name',
+            description: 'Feature review name',
             demandOption: true,
         })
             .option('description', {
             type: 'string',
             alias: 'd',
-            description: 'Feature description',
+            description: 'Feature review description',
         })
             .option('checklist', {
             type: 'array',
             alias: 'c',
-            description: 'Checklist items (use multiple -c flags for multiple items)',
+            description: 'Scenarios (use multiple -c flags for multiple scenarios)',
+        })
+            .option('scenario', {
+            type: 'array',
+            hidden: true,
         });
     }, async (argv) => {
-        await featureCreate(argv.name, {
+        warnRenamed('ranger feature create', 'ranger create');
+        warnFlagRenamed('ranger create', '--checklist', '--scenario');
+        const scenarios = argv.scenario ||
+            argv.checklist;
+        await withTelemetry('feature create', () => featureCreate(argv.name, {
             description: argv.description,
-            checklist: argv.checklist,
-        });
+            scenarios,
+        }));
     })
-        .command('list', 'List all features', (yargs) => {
+        .command('list', false, (yargs) => {
         return yargs
             .option('current-branch', {
             type: 'boolean',
-            description: 'Filter to features for current git branch',
+            description: 'Filter to feature reviews for current git branch',
         })
             .option('limit', {
             type: 'number',
             alias: 'l',
-            description: 'Maximum number of features to return',
+            description: 'Maximum number of feature reviews to return',
             default: 10,
         })
             .option('offset', {
             type: 'number',
             alias: 'o',
-            description: 'Number of features to skip',
+            description: 'Number of feature reviews to skip',
             default: 0,
         })
             .option('include-deleted', {
             type: 'boolean',
             alias: 'd',
-            description: 'Include soft-deleted features',
+            description: 'Include soft-deleted feature reviews',
             default: false,
         });
     }, async (argv) => {
-        await featureList({
+        warnRenamed('ranger feature list', 'ranger list');
+        await withTelemetry('feature list', () => featureList({
             currentBranch: argv['current-branch'],
             limit: argv.limit,
             offset: argv.offset,
             includeDeleted: argv['include-deleted'],
-        });
+        }));
     })
-        .command('show [id]', 'Show feature details (uses active feature if no id)', (yargs) => {
+        .command('show [id]', false, (yargs) => {
         return yargs.positional('id', {
             type: 'string',
-            description: 'Feature ID',
+            description: 'Feature review ID',
         });
     }, async (argv) => {
-        await featureShow(argv.id);
+        warnRenamed('ranger feature show', 'ranger show');
+        await withTelemetry('feature show', () => featureShow(argv.id));
     })
-        .command('resume [id]', 'Find and use feature matching current git context', (yargs) => {
+        .command('resume [id]', false, (yargs) => {
         return yargs.positional('id', {
             type: 'string',
-            description: 'Feature ID (optional - bypasses search/prompt)',
+            description: 'Feature review ID (optional - bypasses search/prompt)',
         });
     }, async (argv) => {
-        await featureResume(argv.id);
+        warnRenamed('ranger feature resume', 'ranger resume');
+        await withTelemetry('feature resume', () => featureResume(argv.id));
     })
-        .command('sessions [id]', 'List sessions for a feature', (yargs) => {
-        return yargs.positional('id', {
-            type: 'string',
-            description: 'Feature ID (uses active feature if not provided)',
-        });
-    }, async (argv) => {
-        await featureSessions(argv.id);
-    })
-        .command('conclude-session [id]', 'End the current session (even with incomplete items)', (yargs) => {
-        return yargs.positional('id', {
-            type: 'string',
-            description: 'Feature ID (uses active feature if not provided)',
-        });
-    }, async (argv) => {
-        await featureConcludeSession(argv.id);
-    })
-        .command('add-checklist-item <description>', 'Add a checklist item to the active feature', (yargs) => {
+        .command('add-checklist-item <description>', false, (yargs) => {
         return yargs
             .positional('description', {
             type: 'string',
-            description: 'Checklist item description',
+            description: 'Scenario description',
             demandOption: true,
         })
             .option('id', {
             type: 'string',
-            description: 'Feature ID (uses active feature if not provided)',
+            description: 'Feature review ID (uses active feature review if not provided)',
         });
     }, async (argv) => {
-        await featureAddChecklistItem(argv.description, argv.id);
+        warnRenamed('ranger feature add-checklist-item', 'ranger add-scenario');
+        await withTelemetry('feature add-checklist-item', () => featureAddScenario(argv.description, argv.id));
     })
-        .command('get-feedback [id]', 'Show reviewer feedback (comments) for all action items', (yargs) => {
+        .command('get-feedback [id]', false, (yargs) => {
         return yargs.positional('id', {
             type: 'string',
-            description: 'Feature ID (uses active feature if not provided)',
+            description: 'Feature review ID (uses active feature review if not provided)',
         });
     }, async (argv) => {
-        await featureGetFeedback(argv.id);
+        warnRenamed('ranger feature get-feedback', 'ranger get-review');
+        await withTelemetry('feature get-feedback', () => featureGetReview(argv.id));
     })
-        .command('delete [id]', 'Soft delete a feature (uses active feature if no id)', (yargs) => {
+        .command('delete [id]', false, (yargs) => {
         return yargs.positional('id', {
             type: 'string',
-            description: 'Feature ID',
+            description: 'Feature review ID',
         });
     }, async (argv) => {
-        await featureDelete(argv.id);
+        warnRenamed('ranger feature delete', 'ranger delete');
+        await withTelemetry('feature delete', () => featureDelete(argv.id));
     })
-        .command('restore <id>', 'Restore a soft-deleted feature', (yargs) => {
+        .command('restore <id>', false, (yargs) => {
         return yargs.positional('id', {
             type: 'string',
-            description: 'Feature ID to restore',
+            description: 'Feature review ID to restore',
             demandOption: true,
         });
     }, async (argv) => {
-        await featureRestore(argv.id);
-    })
-        .demandCommand(1, 'You must specify a feature subcommand')
-        .epilogue(`Commands:
-      create <name>           Create a new feature with checklist
-      list                    List all features
-      show [id]               Show feature details
-      resume [id]             Resume a feature by ID
-      sessions [id]           List sessions for a feature
-      conclude-session [id]   End the current session (even with incomplete items)
-      add-checklist-item      Add a checklist item to the active feature
-      get-feedback [id]       Show reviewer feedback for action items
-      delete [id]             Soft delete a feature
-      restore <id>            Restore a soft-deleted feature
-
-    Examples:
-      ranger feature create "User auth" -c "Login works" -c "Signup works"
-      ranger feature list --current-branch
-      ranger feature list --include-deleted
-      ranger feature show
-      ranger feature resume feat_abc123
-      ranger feature add-checklist-item "User can reset password"
-      ranger feature get-feedback
-      ranger feature delete
-      ranger feature restore feat_abc123`);
-})
-    .command('verify-feature', 'Verify a checklist item in the browser (requires active feature)', (yargs) => {
-    return yargs
-        .option('env', {
-        type: 'string',
-        description: 'Environment to use (defaults to active environment)',
-    })
-        .option('task', {
-        type: 'string',
-        description: 'Task description (defaults to checklist item description)',
+        warnRenamed('ranger feature restore', 'ranger restore');
+        await withTelemetry('feature restore', () => featureRestore(argv.id));
     })
-        .option('item', {
-        type: 'number',
-        description: 'Checklist item index (1-based)',
-    })
-        .option('start-path', {
-        type: 'string',
-        description: 'Path to start on (appended to base URL, e.g., /dashboard)',
-    })
-        .option('debug-outcome', {
-        type: 'string',
-        hidden: true,
-        choices: [
-            'verified',
-            'partial',
-            'blocked',
-            'failed',
-            'incomplete',
-        ],
-    });
-}, async (argv) => {
-    const result = await verifyFeature({
-        env: argv.env,
-        task: argv.task,
-        item: argv.item,
-        startPath: argv['start-path'],
-        debugOutcome: argv['debug-outcome'],
-    });
-    console.log('\n' + '='.repeat(60));
-    console.log(result.evaluation === 'verified'
-        ? ' VERIFIED'
-        : result.evaluation === 'partial'
-            ? ' PARTIAL'
-            : result.evaluation === 'blocked'
-                ? ' BLOCKED'
-                : ' FAILED');
-    console.log('='.repeat(60));
-    console.log(`Summary: ${result.summary}`);
-    console.log(`Evaluation: ${result.evaluation}`);
-    console.log(`Reason: ${result.evaluationReason}`);
-    if (result.issues?.length) {
-        console.log('\nIssues:');
-        result.issues.forEach((issue, i) => {
-            console.log(`\n${i + 1}. [${issue.severity}] ${issue.description}`);
-        });
-    }
-    process.exit(result.evaluation === 'verified' ? 0 : 1);
+        .demandCommand(1, 'You must specify a feature review subcommand');
 })
-    // Unified hook command (hidden from help - invoked automatically by Claude Code plugin)
+    // Unified hook command (hidden from help - invoked automatically by Claude Code / OpenCode plugins)
     .command('hook', false, (yargs) => {
     return yargs
-        .command('enable', 'Enable Ranger hooks for this session', () => { }, async () => {
-        await hook('enable');
+        .command('enable', 'Enable Ranger hooks for this session', (yargs) => {
+        return yargs.option('session-id', {
+            type: 'string',
+            description: 'Session ID (for non-Claude integrations like OpenCode)',
+        });
+    }, async (argv) => {
+        await hook('enable', argv['session-id']);
     })
-        .command('disable', 'Disable Ranger hooks for this session', () => { }, async () => {
-        await hook('disable');
+        .command('disable', 'Disable Ranger hooks for this session', (yargs) => {
+        return yargs.option('session-id', {
+            type: 'string',
+            description: 'Session ID (for non-Claude integrations like OpenCode)',
+        });
+    }, async (argv) => {
+        await hook('disable', argv['session-id']);
     })
         .option('name', {
         type: 'string',
         description: 'Hook name (session-start, pre-compact, post-edit, etc.)',
+    })
+        .option('session-id', {
+        type: 'string',
+        description: 'Session ID (for non-Claude integrations like OpenCode)',
     });
 }, async (argv) => {
     if (argv.name) {
-        await hook(argv.name);
+        await hook(argv.name, argv['session-id']);
     }
 })
     .demandCommand(1, 'You must specify a command')
     .strictCommands()
-    .fail((msg, err, yargs) => {
+    .fail(async (msg, err, yargs) => {
     const rawCommand = sanitizeArgs(process.argv.slice(2));
     const errorType = getErrorType(msg, err);
-    logDesirePath({
-        rawCommand,
-        errorMessage: msg || err?.message,
-        errorType,
-    });
     if (msg && msg.includes('Unknown command')) {
         const command = process.argv[2];
         console.error(`\nUnknown command: ${command}`);
@@ -521,9 +889,21 @@ Examples:
     else if (err) {
         console.error(`\nError: ${err.message}\n`);
     }
-    // Small delay allows desire path log fetch to dispatch before exit
-    setTimeout(() => process.exit(1), 50);
+    await logDesirePath({
+        rawCommand,
+        errorMessage: msg || err?.message,
+        errorType,
+    });
+    // Report to telemetry if there's an active collector
+    const collector = getCurrentCollector();
+    if (collector) {
+        await collector.trackCommandError(err || new Error(msg || 'Unknown error'));
+    }
+    process.exit(1);
 })
+    .epilogue('Documentation:\n' +
+    '  https://docs.ranger.net\n' +
+    '  https://docs.ranger.net/llms.txt (for LLMs)')
     .help()
     .alias('help', 'h')
     .parse();