@jackwener/opencli 1.7.0 → 1.7.2

package/dist/src/pipeline/template.js

@@ -188,14 +188,34 @@ const FORBIDDEN_EXPR_PATTERNS = /\b(constructor|__proto__|prototype|globalThis|p
 /**
  * Deep-copy plain data to sever prototype chains, preventing sandbox escape
  * via `args.constructor.constructor('return process')()` etc.
+ *
+ * Uses a WeakMap cache keyed by object reference: when the same object
+ * (e.g. `args` or `data`) is passed repeatedly across loop iterations,
+ * the expensive JSON round-trip is performed only once. The WeakMap
+ * lets entries be GC'd when the source object is no longer referenced.
+ */
+/**
+ * Cache serialized JSON strings (not parsed objects) by source reference.
+ * Caching the parsed object would be unsafe: the VM sandbox could mutate it,
+ * and the polluted version would leak to subsequent calls. By caching the
+ * string and returning a fresh JSON.parse() each time, every evaluation gets
+ * its own clean deep-copy while still avoiding redundant JSON.stringify()
+ * for the same unchanged source object across loop iterations.
  */
+const _sanitizeCache = new WeakMap();
 function sanitizeContext(obj) {
     if (obj === null || obj === undefined)
         return obj;
     if (typeof obj !== 'object' && typeof obj !== 'function')
         return obj;
+    const objRef = obj;
+    const cached = _sanitizeCache.get(objRef);
+    if (cached !== undefined)
+        return JSON.parse(cached);
     try {
-        return JSON.parse(JSON.stringify(obj));
+        const jsonStr = JSON.stringify(obj);
+        _sanitizeCache.set(objRef, jsonStr);
+        return JSON.parse(jsonStr);
     }
     catch {
         return {};
@@ -218,6 +238,51 @@ function getOrCompileScript(expr) {
     _vmCache.set(expr, script);
     return script;
 }
+/**
+ * Reusable VM sandbox context.
+ *
+ * vm.createContext() is expensive (~0.3ms per call) because it creates a new
+ * V8 context with its own global object. In pipeline loops (map/filter over
+ * hundreds of items), this adds up to significant overhead.
+ *
+ * Instead, we create the context once and mutate the sandbox properties
+ * before each evaluation. This is safe because:
+ *   1. Sandbox properties are sanitized (deep-copied) before assignment
+ *   2. Scripts run with a 50ms timeout
+ *   3. codeGeneration is disabled (no eval/Function inside the sandbox)
+ */
+let _reusableSandbox = null;
+let _reusableContext = null;
+function getReusableContext() {
+    if (_reusableSandbox && _reusableContext) {
+        return { sandbox: _reusableSandbox, context: _reusableContext };
+    }
+    _reusableSandbox = {
+        args: {},
+        item: {},
+        data: null,
+        index: 0,
+        encodeURIComponent,
+        decodeURIComponent,
+        JSON,
+        Math,
+        Number,
+        String,
+        Boolean,
+        Array,
+        Date,
+    };
+    _reusableContext = vm.createContext(_reusableSandbox, {
+        codeGeneration: { strings: false, wasm: false },
+    });
+    return { sandbox: _reusableSandbox, context: _reusableContext };
+}
+/** Properties that are part of the sandbox's initial shape and safe to keep. */
+const SANDBOX_WHITELIST = new Set([
+    'args', 'item', 'data', 'index',
+    'encodeURIComponent', 'decodeURIComponent',
+    'JSON', 'Math', 'Number', 'String', 'Boolean', 'Array', 'Date',
+]);
 function evalJsExpr(expr, ctx) {
     // Guard against absurdly long expressions that could indicate injection.
     if (expr.length > 2000)
@@ -225,33 +290,22 @@ function evalJsExpr(expr, ctx) {
     // Block obvious sandbox escape attempts.
     if (FORBIDDEN_EXPR_PATTERNS.test(expr))
         return undefined;
-    const args = sanitizeContext(ctx.args ?? {});
-    const item = sanitizeContext(ctx.item ?? {});
-    const data = sanitizeContext(ctx.data);
-    const index = ctx.index ?? 0;
     try {
         const script = getOrCompileScript(expr);
-        const sandbox = vm.createContext({
-            args,
-            item,
-            data,
-            index,
-            encodeURIComponent,
-            decodeURIComponent,
-            JSON,
-            Math,
-            Number,
-            String,
-            Boolean,
-            Array,
-            Date,
-        }, {
-            codeGeneration: {
-                strings: false,
-                wasm: false,
-            },
-        });
-        return script.runInContext(sandbox, { timeout: 50 });
+        const { sandbox, context } = getReusableContext();
+        // Clean non-whitelisted properties that a previous script may have added.
+        // Without this, `${{ x = 42 }}` would leak `x` into subsequent evaluations.
+        for (const key of Object.keys(sandbox)) {
+            if (!SANDBOX_WHITELIST.has(key)) {
+                delete sandbox[key];
+            }
+        }
+        // Update mutable sandbox properties — sanitizeContext severs prototype chains.
+        sandbox.args = sanitizeContext(ctx.args ?? {});
+        sandbox.item = sanitizeContext(ctx.item ?? {});
+        sandbox.data = sanitizeContext(ctx.data);
+        sandbox.index = ctx.index ?? 0;
+        return script.runInContext(context, { timeout: 50 });
     }
     catch {
         return undefined;

package/dist/src/plugin.js

@@ -12,8 +12,9 @@ import * as path from 'node:path';
 import { execSync, execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { PLUGINS_DIR } from './discovery.js';
-import { getErrorMessage } from './errors.js';
+import { getErrorMessage, PluginError } from './errors.js';
 import { log } from './logger.js';
+import { isRecord } from './utils.js';
 import { readPluginManifest, isMonorepo, getEnabledPlugins, checkCompatibility, } from './plugin-manifest.js';
 const isWindows = process.platform === 'win32';
 const LOCAL_PLUGIN_SOURCE_PREFIX = 'local:';
@@ -52,9 +53,7 @@ function toStoredPluginSource(source) {
 function toLocalPluginSource(pluginDir) {
     return toStoredPluginSource({ kind: 'local', path: pluginDir });
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
+// isRecord is imported from './utils.js'
 function normalizeLegacyMonorepo(value) {
     if (!isRecord(value))
         return undefined;
@@ -166,7 +165,7 @@ function createSiblingTempPath(dest, kind) {
  */
 function promoteDir(stagingDir, dest, fsOps = fs) {
     if (fsOps.existsSync(dest)) {
-        throw new Error(`Destination already exists: ${dest}`);
+        throw new PluginError(`Destination already exists: ${dest}`);
     }
     fsOps.mkdirSync(path.dirname(dest), { recursive: true });
     const tempDest = createSiblingTempPath(dest, 'tmp');
@@ -195,7 +194,7 @@ function cloneRepoToTemp(cloneUrl) {
         });
     }
     catch (err) {
-        throw new Error(`Failed to clone plugin: ${getErrorMessage(err)}`);
+        throw new PluginError(`Failed to clone plugin: ${getErrorMessage(err)}`, 'Check the repository URL and your network connection.');
     }
     return tmpCloneDir;
 }
@@ -227,6 +226,13 @@ function pathExistsSync(p) {
         return false;
     }
 }
+function resolveRepoContainedPath(repoRoot, subPath) {
+    const resolved = path.resolve(repoRoot, subPath);
+    if (!resolved.startsWith(repoRoot + path.sep) && resolved !== repoRoot) {
+        throw new PluginError(`Plugin path "${subPath}" escapes repo root.`);
+    }
+    return resolved;
+}
 function removePathSync(p) {
     try {
         const stat = fs.lstatSync(p);
@@ -499,7 +505,7 @@ function installDependencies(dir) {
         });
     }
     catch (err) {
-        throw new Error(`npm install failed in ${dir}: ${getErrorMessage(err)}`);
+        throw new PluginError(`npm install failed in ${dir}: ${getErrorMessage(err)}`, 'Check your network connection and npm configuration.');
     }
 }
 function finalizePluginRuntime(pluginDir) {
@@ -528,7 +534,7 @@ function postInstallMonorepoLifecycle(repoDir, pluginDirs) {
 function ensureStandalonePluginReady(pluginDir) {
     const validation = validatePluginStructure(pluginDir);
     if (!validation.valid) {
-        throw new Error(`Invalid plugin structure:\n- ${validation.errors.join('\n- ')}`);
+        throw new PluginError(`Invalid plugin structure:\n- ${validation.errors.join('\n- ')}`);
     }
     postInstallLifecycle(pluginDir);
 }
@@ -553,7 +559,7 @@ function publishMonorepoPlugins(repoDir, pluginsDir, plugins, publishRepo, write
         const commitHash = getCommitHash(repoDir);
         for (const plugin of plugins) {
             const linkPath = path.join(pluginsDir, plugin.name);
-            const subDir = path.join(repoDir, plugin.subPath);
+            const subDir = resolveRepoContainedPath(repoDir, plugin.subPath);
             tx.track(beginReplaceSymlink(subDir, linkPath));
         }
         writeLock?.(commitHash);
@@ -606,7 +612,7 @@ function installSinglePlugin(cloneDir, cloneUrl, name, manifest) {
     const pluginName = manifest?.name ?? name;
     const targetDir = path.join(PLUGINS_DIR, pluginName);
     if (fs.existsSync(targetDir)) {
-        throw new Error(`Plugin "${pluginName}" is already installed at ${targetDir}`);
+        throw new PluginError(`Plugin "${pluginName}" is already installed at ${targetDir}`, 'Use "opencli plugin uninstall" first, or pick a different name.');
     }
     ensureStandalonePluginReady(cloneDir);
     publishStandalonePlugin(cloneDir, targetDir, (commitHash) => {
@@ -628,24 +634,24 @@ function installSinglePlugin(cloneDir, cloneUrl, name, manifest) {
  */
 function installLocalPlugin(localPath, name) {
     if (!fs.existsSync(localPath)) {
-        throw new Error(`Local plugin path does not exist: ${localPath}`);
+        throw new PluginError(`Local plugin path does not exist: ${localPath}`);
     }
     const stat = fs.statSync(localPath);
     if (!stat.isDirectory()) {
-        throw new Error(`Local plugin path is not a directory: ${localPath}`);
+        throw new PluginError(`Local plugin path is not a directory: ${localPath}`);
     }
     const manifest = readPluginManifest(localPath);
     if (manifest?.opencli && !checkCompatibility(manifest.opencli)) {
-        throw new Error(`Plugin requires opencli ${manifest.opencli}, but current version is incompatible.`);
+        throw new PluginError(`Plugin requires opencli ${manifest.opencli}, but current version is incompatible.`, 'Upgrade opencli to a compatible version.');
     }
     const pluginName = manifest?.name ?? name;
     const targetDir = path.join(PLUGINS_DIR, pluginName);
     if (fs.existsSync(targetDir)) {
-        throw new Error(`Plugin "${pluginName}" is already installed at ${targetDir}`);
+        throw new PluginError(`Plugin "${pluginName}" is already installed at ${targetDir}`, 'Use "opencli plugin uninstall" first, or pick a different name.');
     }
     const validation = validatePluginStructure(localPath);
     if (!validation.valid) {
-        throw new Error(`Invalid plugin structure:\n- ${validation.errors.join('\n- ')}`);
+        throw new PluginError(`Invalid plugin structure:\n- ${validation.errors.join('\n- ')}`);
     }
     fs.mkdirSync(PLUGINS_DIR, { recursive: true });
     const resolvedPath = path.resolve(localPath);
@@ -685,7 +691,7 @@ function installMonorepo(cloneDir, cloneUrl, repoName, manifest, subPlugin) {
     const repoRoot = repoAlreadyInstalled ? repoDir : cloneDir;
     const effectiveManifest = repoAlreadyInstalled ? readPluginManifest(repoDir) : manifest;
     if (!effectiveManifest || !isMonorepo(effectiveManifest)) {
-        throw new Error(`Monorepo manifest missing or invalid at ${repoRoot}`);
+        throw new PluginError(`Monorepo manifest missing or invalid at ${repoRoot}`);
     }
     let pluginsToInstall = getEnabledPlugins(effectiveManifest);
     // If a specific sub-plugin was requested, filter to just that one
@@ -695,9 +701,9 @@ function installMonorepo(cloneDir, cloneUrl, repoName, manifest, subPlugin) {
             // Check if it exists but is disabled
             const disabled = effectiveManifest.plugins?.[subPlugin];
             if (disabled) {
-                throw new Error(`Sub-plugin "${subPlugin}" is disabled in the manifest.`);
+                throw new PluginError(`Sub-plugin "${subPlugin}" is disabled in the manifest.`);
             }
-            throw new Error(`Sub-plugin "${subPlugin}" not found in monorepo. Available: ${Object.keys(effectiveManifest.plugins ?? {}).join(', ')}`);
+            throw new PluginError(`Sub-plugin "${subPlugin}" not found in monorepo. Available: ${Object.keys(effectiveManifest.plugins ?? {}).join(', ')}`);
         }
     }
     const installedNames = [];
@@ -710,7 +716,14 @@ function installMonorepo(cloneDir, cloneUrl, repoName, manifest, subPlugin) {
             log.warn(`Skipping "${name}": requires opencli ${entry.opencli}`);
             continue;
         }
-        const subDir = path.join(repoRoot, entry.path);
+        let subDir;
+        try {
+            subDir = resolveRepoContainedPath(repoRoot, entry.path);
+        }
+        catch {
+            log.warn(`Skipping "${name}": path "${entry.path}" escapes repo root.`);
+            continue;
+        }
         if (!fs.existsSync(subDir)) {
             log.warn(`Skipping "${name}": path "${entry.path}" not found in repo.`);
             continue;
@@ -732,10 +745,10 @@ function installMonorepo(cloneDir, cloneUrl, repoName, manifest, subPlugin) {
     }
     const publishPlugins = eligiblePlugins.map(({ name, entry }) => ({ name, subPath: entry.path }));
     if (repoAlreadyInstalled) {
-        postInstallMonorepoLifecycle(repoDir, eligiblePlugins.map((p) => path.join(repoDir, p.entry.path)));
+        postInstallMonorepoLifecycle(repoDir, eligiblePlugins.map((p) => resolveRepoContainedPath(repoDir, p.entry.path)));
     }
     else {
-        postInstallMonorepoLifecycle(cloneDir, eligiblePlugins.map((p) => path.join(cloneDir, p.entry.path)));
+        postInstallMonorepoLifecycle(cloneDir, eligiblePlugins.map((p) => resolveRepoContainedPath(cloneDir, p.entry.path)));
     }
     publishMonorepoPlugins(repoDir, PLUGINS_DIR, publishPlugins, repoAlreadyInstalled ? undefined : { stagingDir: cloneDir, parentDir: monoreposDir }, (commitHash) => {
         for (const { name, entry } of eligiblePlugins) {
@@ -768,7 +781,7 @@ function collectUpdatedMonorepoPlugins(monoName, lock, manifest, cloneUrl, tmpCl
         if (manifestEntry.opencli && !checkCompatibility(manifestEntry.opencli)) {
             throw new Error(`Sub-plugin "${pluginName}" requires opencli ${manifestEntry.opencli}`);
         }
-        const subDir = path.join(tmpCloneDir, manifestEntry.path);
+        const subDir = resolveRepoContainedPath(tmpCloneDir, manifestEntry.path);
         const validation = validatePluginStructure(subDir);
         if (!validation.valid) {
             throw new Error(`Updated sub-plugin "${pluginName}" is invalid:\n- ${validation.errors.join('\n- ')}`);
@@ -883,7 +896,7 @@ export function updatePlugin(name) {
             }
             const updatedPlugins = collectUpdatedMonorepoPlugins(monoName, lock, manifest, cloneUrl, tmpCloneDir);
             if (updatedPlugins.length > 0) {
-                postInstallMonorepoLifecycle(tmpCloneDir, updatedPlugins.map((plugin) => path.join(tmpCloneDir, plugin.manifestEntry.path)));
+                postInstallMonorepoLifecycle(tmpCloneDir, updatedPlugins.map((plugin) => resolveRepoContainedPath(tmpCloneDir, plugin.manifestEntry.path)));
             }
             publishMonorepoPlugins(monoDir, PLUGINS_DIR, updatedPlugins.map((plugin) => ({ name: plugin.name, subPath: plugin.manifestEntry.path })), { stagingDir: tmpCloneDir, parentDir: path.dirname(monoDir) }, (commitHash) => {
                 updateMonorepoLockEntries(lock, updatedPlugins, cloneUrl, monoName, commitHash);

package/dist/src/plugin.test.js

@@ -1279,6 +1279,47 @@ describe('updatePlugin transactional staging', () => {
             subPath: 'packages/moved-alpha',
         });
     });
+    it('rejects monorepo updates whose manifest path escapes the repo root', () => {
+        const oldSubDir = path.join(monorepoRepoDir, 'packages', 'old-alpha');
+        fs.mkdirSync(oldSubDir, { recursive: true });
+        fs.writeFileSync(path.join(oldSubDir, 'old.js'), 'cli({ site: "old", name: "old" })');
+        fs.mkdirSync(PLUGINS_DIR, { recursive: true });
+        fs.symlinkSync(oldSubDir, monorepoLink, 'dir');
+        const lock = _readLockFile();
+        lock[monorepoPluginName] = {
+            source: {
+                kind: 'monorepo',
+                url: 'https://github.com/user/opencli-plugins-__test-transactional-mono-update__.git',
+                repoName: monorepoName,
+                subPath: 'packages/old-alpha',
+            },
+            commitHash: 'oldmonooldmonooldmonooldmonooldmonoold',
+            installedAt: '2025-01-01T00:00:00.000Z',
+        };
+        _writeLockFile(lock);
+        mockExecFileSync.mockImplementation((cmd, args) => {
+            if (cmd === 'git' && Array.isArray(args) && args[0] === 'clone') {
+                const cloneDir = String(args[4]);
+                fs.mkdirSync(cloneDir, { recursive: true });
+                fs.writeFileSync(path.join(cloneDir, 'opencli-plugin.json'), JSON.stringify({
+                    plugins: {
+                        [monorepoPluginName]: { path: '../outside-alpha' },
+                    },
+                }));
+                return '';
+            }
+            if (cmd === 'git' && Array.isArray(args) && args[0] === 'rev-parse' && args[1] === 'HEAD') {
+                return '1234567890abcdef1234567890abcdef12345678\n';
+            }
+            return '';
+        });
+        expect(() => updatePlugin(monorepoPluginName)).toThrow('escapes repo root');
+        expect(fs.realpathSync(monorepoLink)).toBe(fs.realpathSync(oldSubDir));
+        expect(_readLockFile()[monorepoPluginName]?.source).toMatchObject({
+            kind: 'monorepo',
+            subPath: 'packages/old-alpha',
+        });
+    });
     it('rolls back the monorepo repo swap when relinking fails', () => {
         const oldSubDir = path.join(monorepoRepoDir, 'packages', 'old-alpha');
         fs.mkdirSync(oldSubDir, { recursive: true });

package/dist/src/record.js

@@ -14,7 +14,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as readline from 'node:readline';
-import chalk from 'chalk';
+import { styleText } from 'node:util';
 import { sendCommand } from './browser/daemon-client.js';
 import { SEARCH_PARAMS, PAGINATION_PARAMS, FIELD_ROLES } from './constants.js';
 import { urlToPattern, findArrayPath, inferCapabilityName, inferStrategy, detectAuthFromContent, classifyQueryParams, isNoiseUrl, } from './analysis.js';
@@ -466,10 +466,10 @@ export async function recordSession(opts) {
         }
     })();
     const workspace = `record:${site}`;
-    console.log(chalk.bold.cyan('\n  opencli record'));
-    console.log(chalk.dim(`  Site: ${site}  URL: ${opts.url}`));
-    console.log(chalk.dim(`  Timeout: ${timeoutMs / 1000}s  Poll: ${pollMs}ms`));
-    console.log(chalk.dim('  Navigating…'));
+    console.log(styleText(['bold', 'cyan'], '\n  opencli record'));
+    console.log(styleText('dim', `  Site: ${site}  URL: ${opts.url}`));
+    console.log(styleText('dim', `  Timeout: ${timeoutMs / 1000}s  Poll: ${pollMs}ms`));
+    console.log(styleText('dim', '  Navigating…'));
     const factory = new opts.BrowserFactory();
     const page = await factory.connect({ timeout: 30, workspace });
     try {
@@ -481,8 +481,8 @@ export async function recordSession(opts) {
             if (tab.page)
                 await injectIntoPage(workspace, tab.page, injectedPages);
         }
-        console.log(chalk.bold('\n  Recording. Use the page in the browser automation window.'));
-        console.log(chalk.dim(`  Will auto-stop after ${timeoutMs / 1000}s, or press Enter to stop now.\n`));
+        console.log(styleText('bold', '\n  Recording. Use the page in the browser automation window.'));
+        console.log(styleText('dim', `  Will auto-stop after ${timeoutMs / 1000}s, or press Enter to stop now.\n`));
         // Race: Enter key vs timeout
         let stopped = false;
         const stop = () => { stopped = true; };
@@ -509,7 +509,7 @@ export async function recordSession(opts) {
                     if (Array.isArray(batch) && batch.length > 0) {
                         for (const r of batch)
                             allRequests.push(r);
-                        console.log(chalk.dim(`  [page:${page.slice(0, 8)}] +${batch.length} captured — total: ${allRequests.length}`));
+                        console.log(styleText('dim', `  [page:${page.slice(0, 8)}] +${batch.length} captured — total: ${allRequests.length}`));
                     }
                 }
             }
@@ -531,7 +531,7 @@ export async function recordSession(opts) {
             }
             catch { }
         }
-        console.log(chalk.dim(`\n  Stopped. Analyzing ${allRequests.length} captured requests…`));
+        console.log(styleText('dim', `\n  Stopped. Analyzing ${allRequests.length} captured requests…`));
         const result = analyzeAndWrite(site, opts.url, allRequests, opts.outDir);
         await factory.close().catch(() => { });
         return result;
@@ -558,7 +558,7 @@ async function injectIntoPage(workspace, page, injectedPages) {
         await execOnPage(workspace, page, generateFullCaptureInterceptorJs());
         if (!injectedPages.has(page)) {
             injectedPages.add(page);
-            console.log(chalk.green(`  ✓  Interceptor injected into page:${page.slice(0, 8)}`));
+            console.log(styleText('green', `  ✓  Interceptor injected into page:${page.slice(0, 8)}`));
         }
     }
     catch {
@@ -588,7 +588,7 @@ function analyzeAndWrite(site, pageUrl, requests, outDir) {
     const targetDir = outDir ?? path.join('.opencli', 'record', site);
     fs.mkdirSync(targetDir, { recursive: true });
     if (requests.length === 0) {
-        console.log(chalk.yellow('  No API requests captured.'));
+        console.log(styleText('yellow', '  No API requests captured.'));
         return { site, url: pageUrl, requests: [], outDir: targetDir, candidateCount: 0, candidates: [] };
     }
     // Score and rank deduplicated requests for console output and candidate generation.
@@ -599,18 +599,18 @@ function analyzeAndWrite(site, pageUrl, requests, outDir) {
     // Generate candidate YAMLs (top 5)
     const candidates = [];
     const usedNames = new Set();
-    console.log(chalk.bold('\n  Captured endpoints:\n'));
+    console.log(styleText('bold', '\n  Captured endpoints:\n'));
     for (const entry of analysis.candidates.sort((a, b) => (b.arrayResult?.items.length ?? 0) - (a.arrayResult?.items.length ?? 0)).slice(0, 8)) {
         const itemCount = entry.arrayResult?.items.length ?? 0;
         const strategy = entry.kind === 'write'
             ? 'cookie'
             : inferStrategy(detectAuthFromContent(entry.req.url, entry.req.responseBody));
-        const marker = entry.kind === 'write' ? chalk.magenta('✎') : itemCount > 5 ? chalk.green('★') : chalk.dim('·');
-        console.log(`  ${marker} ${chalk.white(urlToPattern(entry.req.url))}` +
-            chalk.dim(` [${strategy}]`) +
+        const marker = entry.kind === 'write' ? styleText('magenta', '✎') : itemCount > 5 ? styleText('green', '★') : styleText('dim', '·');
+        console.log(`  ${marker} ${styleText('white', urlToPattern(entry.req.url))}` +
+            styleText('dim', ` [${strategy}]`) +
             (entry.kind === 'write'
-                ? chalk.magenta(' ← write')
-                : itemCount ? chalk.cyan(` ← ${itemCount} items`) : ''));
+                ? styleText('magenta', ' ← write')
+                : itemCount ? styleText('cyan', ` ← ${itemCount} items`) : ''));
     }
     console.log();
     const topCandidates = generateRecordedCandidates(site, pageUrl, analysisRequests);
@@ -623,12 +623,12 @@ function analyzeAndWrite(site, pageUrl, requests, outDir) {
         const filePath = path.join(candidatesDir, `${entry.name}.json`);
         fs.writeFileSync(filePath, JSON.stringify(entry.yaml, null, 2));
         candidates.push({ name: entry.name, path: filePath, strategy: entry.strategy });
-        console.log(chalk.green(`  ✓ Generated: ${chalk.bold(entry.name)}.json  [${entry.strategy}]`));
-        console.log(chalk.dim(`    → ${filePath}`));
+        console.log(styleText('green', `  ✓ Generated: ${styleText('bold', entry.name)}.json  [${entry.strategy}]`));
+        console.log(styleText('dim', `    → ${filePath}`));
     }
     if (candidates.length === 0) {
-        console.log(chalk.yellow('  No candidates found.'));
-        console.log(chalk.dim('  Tip: make sure you triggered JSON API calls (open lists, search, scroll).'));
+        console.log(styleText('yellow', '  No candidates found.'));
+        console.log(styleText('dim', '  Tip: make sure you triggered JSON API calls (open lists, search, scroll).'));
     }
     return {
         site,
@@ -641,7 +641,7 @@ function analyzeAndWrite(site, pageUrl, requests, outDir) {
 }
 export function renderRecordSummary(result) {
     const lines = [
-        `\n  opencli record: ${result.candidateCount > 0 ? chalk.green('OK') : chalk.yellow('no candidates')}`,
+        `\n  opencli record: ${result.candidateCount > 0 ? styleText('green', 'OK') : styleText('yellow', 'no candidates')}`,
         `  Site: ${result.site}`,
         `  Captured: ${result.requests.length} requests`,
         `  Candidates: ${result.candidateCount}`,
@@ -651,7 +651,7 @@ export function renderRecordSummary(result) {
     }
     if (result.candidateCount > 0) {
         lines.push('');
-        lines.push(chalk.dim(`  Copy a candidate to clis/${result.site}/ and run: npm run build`));
+        lines.push(styleText('dim', `  Copy a candidate to clis/${result.site}/ and run: npm run build`));
     }
     return lines.join('\n');
 }

package/dist/src/registry.d.ts

@@ -47,14 +47,19 @@ export interface CliCommand {
     /** Preferred replacement command, if any. */
     replacedBy?: string;
     /**
-     * Control pre-navigation for cookie/header context before command execution.
+     * Control pre-navigation and browser-session requirement.
      *
-     * Browser adapters using COOKIE/HEADER strategy need the page to be on the
-     * target domain so that `fetch(url, { credentials: 'include' })` carries cookies.
+     * After normalizeCommand() expands strategy, this field carries the
+     * resolved runtime intent:
      *
-     * - `undefined` / `true`: navigate to `https://${domain}` (default)
-     * - `false`: skip — adapter handles its own navigation (e.g. boss common.ts)
-     * - `string`: navigate to this specific URL instead of the domain root
+     * - `undefined`: no pre-navigation, browser session decided by pipeline steps
+     * - `false`: explicitly skip pre-navigation (adapter handles its own navigation)
+     * - `true`: needs authenticated browser context but no specific pre-nav URL
+     *   (e.g. INTERCEPT/UI adapters, or COOKIE without domain)
+     * - `string`: pre-navigate to this URL before running the adapter
+     *   (e.g. `'https://x.com'` for COOKIE strategy with domain)
+     *
+     * Adapter authors can set this explicitly to override the strategy-based default.
      */
     navigateBefore?: boolean | string;
     /** Override the default CLI output format when the user does not pass -f/--format. */

package/dist/src/registry.js

@@ -11,17 +11,14 @@ export var Strategy;
 })(Strategy || (Strategy = {}));
 const _registry = globalThis.__opencli_registry__ ??= new Map();
 export function cli(opts) {
-    const strategy = opts.strategy ?? (opts.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
-    const browser = opts.browser ?? (strategy !== Strategy.PUBLIC);
-    const aliases = normalizeAliases(opts.aliases, opts.name);
     const cmd = {
         site: opts.site,
         name: opts.name,
-        aliases,
+        aliases: opts.aliases,
         description: opts.description ?? '',
         domain: opts.domain,
-        strategy,
-        browser,
+        strategy: opts.strategy,
+        browser: opts.browser,
         args: opts.args ?? [],
         columns: opts.columns,
         func: opts.func,
@@ -35,7 +32,7 @@ export function cli(opts) {
         defaultFormat: opts.defaultFormat,
     };
     registerCommand(cmd);
-    return cmd;
+    return _registry.get(fullName(cmd));
 }
 export function getRegistry() {
     return _registry;
@@ -46,8 +43,39 @@ export function fullName(cmd) {
 export function strategyLabel(cmd) {
     return cmd.strategy ?? Strategy.PUBLIC;
 }
+/**
+ * Normalize a command's runtime fields. This is the single place where
+ * `strategy` is decoded into the concrete fields that the execution path
+ * reads (`browser`, `navigateBefore`). After normalization, execution code
+ * (resolvePreNav, shouldUseBrowserSession) never reads `cmd.strategy`.
+ *
+ * `strategy` itself is preserved as metadata for `opencli list`, cascade
+ * probe, adapter generation, and human documentation.
+ *
+ * Override priority (highest wins):
+ *   1. Explicit field on the command (`browser: false`, `navigateBefore: false`)
+ *   2. Derived from strategy + domain (the defaults below)
+ */
+function normalizeCommand(cmd) {
+    const strategy = cmd.strategy ?? (cmd.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
+    const browser = cmd.browser ?? (strategy !== Strategy.PUBLIC);
+    let navigateBefore = cmd.navigateBefore;
+    if (navigateBefore === undefined) {
+        if ((strategy === Strategy.COOKIE || strategy === Strategy.HEADER) && cmd.domain) {
+            navigateBefore = `https://${cmd.domain}`;
+        }
+        else if (strategy !== Strategy.PUBLIC) {
+            // Non-PUBLIC without domain: needs authenticated browser context
+            // but no specific pre-navigation URL. `true` signals this to
+            // shouldUseBrowserSession without triggering resolvePreNav.
+            navigateBefore = true;
+        }
+    }
+    return { ...cmd, strategy, browser, navigateBefore };
+}
 export function registerCommand(cmd) {
-    const canonicalKey = fullName(cmd);
+    const normalized = normalizeCommand(cmd);
+    const canonicalKey = fullName(normalized);
     const existing = _registry.get(canonicalKey);
     if (existing) {
         for (const [key, value] of _registry.entries()) {
@@ -55,11 +83,11 @@ export function registerCommand(cmd) {
                 _registry.delete(key);
         }
     }
-    const aliases = normalizeAliases(cmd.aliases, cmd.name);
-    cmd.aliases = aliases.length > 0 ? aliases : undefined;
-    _registry.set(canonicalKey, cmd);
+    const aliases = normalizeAliases(normalized.aliases, normalized.name);
+    normalized.aliases = aliases.length > 0 ? aliases : undefined;
+    _registry.set(canonicalKey, normalized);
     for (const alias of aliases) {
-        _registry.set(`${cmd.site}/${alias}`, cmd);
+        _registry.set(`${normalized.site}/${alias}`, normalized);
     }
 }
 function normalizeAliases(aliases, commandName) {