@sovovs/bycli 1.8.0 → 2.1.0

package/dist/src/discovery.js

@@ -8,18 +8,20 @@
  * 2. FALLBACK (filesystem scan): Traditional runtime discovery for development.
  */
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { Strategy, registerCommand } from './registry.js';
 import { getErrorMessage } from './errors.js';
 import { log } from './logger.js';
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
-/** User runtime directory: ~/.bycli */
-export const USER_BYCLI_DIR = path.join(os.homedir(), '.bycli');
-/** User CLIs directory: ~/.bycli/clis */
-export const USER_CLIS_DIR = path.join(USER_BYCLI_DIR, 'clis');
-/** Plugins directory: ~/.bycli/plugins/ */
+import { getConfigDir, getUserClisDir } from './config-paths.js';
+/** User runtime directory: BYCLI_CONFIG_DIR or ~/.bycli.
+ * Resolved once at module load; the entry process fixes BYCLI_CONFIG_DIR before import. */
+export const USER_BYCLI_DIR = getConfigDir();
+/** User CLIs directory: <config>/clis */
+export const USER_CLIS_DIR = getUserClisDir();
+/** Plugins directory: <config>/plugins/ (plugins are out of scope for the clis/sites
+ * relocation; kept as a const that many plugin.ts/tests consumers rely on). */
 export const PLUGINS_DIR = path.join(USER_BYCLI_DIR, 'plugins');
 /** Matches files that register commands via cli() or lifecycle hooks */
 const PLUGIN_MODULE_PATTERN = /\b(?:cli|onStartup|onBeforeExecute|onAfterExecute)\s*\(/;
@@ -111,7 +113,7 @@ export async function discoverClis(...dirs) {
  * Fast-path: register commands from pre-compiled manifest.
  * TS modules are deferred — loaded lazily on first execution.
  */
-async function loadFromManifest(manifestPath, clisDir) {
+export async function loadFromManifest(manifestPath, clisDir) {
     try {
         const raw = await fs.promises.readFile(manifestPath, 'utf-8');
         const manifest = JSON.parse(raw);
@@ -119,7 +121,7 @@ async function loadFromManifest(manifestPath, clisDir) {
             if (!entry.modulePath)
                 continue;
             const modulePath = path.resolve(clisDir, entry.modulePath);
-            const cmd = {
+            const common = {
                 site: entry.site,
                 name: entry.name,
                 aliases: entry.aliases,
@@ -128,7 +130,6 @@ async function loadFromManifest(manifestPath, clisDir) {
                 example: entry.example,
                 domain: entry.domain,
                 strategy: parseStrategy(entry.strategy),
-                browser: entry.browser,
                 args: entry.args ?? [],
                 columns: entry.columns,
                 defaultFormat: entry.defaultFormat,
@@ -139,7 +140,16 @@ async function loadFromManifest(manifestPath, clisDir) {
                 _lazy: true,
                 _modulePath: modulePath,
             };
-            // normalizeCommand inside registerCommand handles strategy → browser/navigateBefore
+            const cmd = entry.browser === 'conditional'
+                ? {
+                    ...common,
+                    browser: 'conditional',
+                    requiresBrowser: () => {
+                        throw new Error(`Conditional manifest placeholder ${entry.site}/${entry.name} was not hydrated`);
+                    },
+                    _hydrateBeforeBrowserRouting: true,
+                }
+                : { ...common, browser: entry.browser };
             registerCommand(cmd);
         }
         return true;

package/dist/src/discovery.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/execution.d.ts

@@ -11,6 +11,9 @@
  */
 import { type CliCommand, type Arg, type CommandArgs } from './registry.js';
 import { type ObservationExportResult } from './observation/index.js';
+/** Internal test-only reset. Never use this to recover a production process. */
+export declare function _resetLazyModuleStateForTests(): void;
+export declare function _getLazyModuleFingerprintReadCountForTests(): number;
 export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs;
 export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean, opts?: {
     prepared?: boolean;
@@ -22,3 +25,5 @@ export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs,
     onTraceExport?: (trace: ObservationExportResult) => void;
 }): Promise<unknown>;
 export declare function prepareCommandArgs(cmd: CliCommand, rawKwargs: CommandArgs): CommandArgs;
+/** Prepare adapter arguments using the execution boundary's public error contract. */
+export declare function prepareCommandArgsOrThrowArgumentError(cmd: CliCommand, rawKwargs: CommandArgs): CommandArgs;

package/dist/src/execution.js

@@ -13,9 +13,10 @@ import { getRegistry, fullName, } from './registry.js';
 import { pathToFileURL } from 'node:url';
 import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
-import * as os from 'node:os';
+import * as path from 'node:path';
+import { getUserClisDir } from './config-paths.js';
 import { executePipeline } from './pipeline/index.js';
-import { adapterLoadError, ArgumentError, CommandExecutionError, attachTraceReceipt, getErrorMessage } from './errors.js';
+import { adapterLoadError, ArgumentError, CliError, CommandExecutionError, attachTraceReceipt, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 import { resolveProfileContextId } from './browser/profile.js';
@@ -25,10 +26,34 @@ import { isElectronApp } from './electron-apps.js';
 import { probeCDP, resolveElectronEndpoint } from './launcher.js';
 import { ObservationSession, exportObservationSession } from './observation/index.js';
 import { resolveAdapterSourcePath } from './adapter-source.js';
+import { canonicalizeManifestArgSchema, ManifestSchemaError } from './manifest-schema.js';
+import { capturedRegistryValues, closeRegistryTransaction, createRegistryTransaction, finalizeRegistryTransaction, resetRegistryTransactionStateForTests, rollbackRegistryTransaction, runRegistryTransaction, transactionGroupsForKey, } from './registry-transaction.js';
 const _loadedModules = new Map();
-/** Track mtime of loaded user adapter files for hot-reload in daemon mode. */
-const _moduleMtimes = new Map();
-const _userClisDir = `${os.homedir()}/.bycli/clis/`;
+/** Independent cache-busting generation; retained when an import promise is discarded. */
+const _moduleImportGenerations = new Map();
+let _registrationImportTail = Promise.resolve();
+let _registrationImportsPoisoned = false;
+let _fingerprintReadCount = 0;
+const DEFAULT_ADAPTER_IMPORT_TIMEOUT_MS = 30_000;
+function adapterImportTimeoutMs() {
+    const configured = Number(process.env.BYCLI_ADAPTER_IMPORT_TIMEOUT_MS);
+    return Number.isFinite(configured) && configured > 0 ? configured : DEFAULT_ADAPTER_IMPORT_TIMEOUT_MS;
+}
+function poisonedImportError() {
+    return adapterLoadError('Adapter registration imports are unavailable because a previous import timed out.', 'Restart byCLI before retrying; the timed-out module may still complete and register stale commands in this process.');
+}
+/** Internal test-only reset. Never use this to recover a production process. */
+export function _resetLazyModuleStateForTests() {
+    _loadedModules.clear();
+    _moduleImportGenerations.clear();
+    _registrationImportTail = Promise.resolve();
+    _registrationImportsPoisoned = false;
+    _fingerprintReadCount = 0;
+    resetRegistryTransactionStateForTests();
+}
+export function _getLazyModuleFingerprintReadCountForTests() {
+    return _fingerprintReadCount;
+}
 function normalizeTraceMode(raw) {
     if (raw === undefined || raw === null || raw === '' || raw === 'off')
         return 'off';
@@ -81,41 +106,19 @@ export function coerceAndValidateArgs(cmdArgs, kwargs) {
 async function runCommand(cmd, page, kwargs, debug) {
     const internal = cmd;
     if (internal._lazy && internal._modulePath) {
-        const modulePath = internal._modulePath;
-        // Hot-reload: if a user adapter's file has changed on disk, invalidate cache
-        const isUserAdapter = modulePath.startsWith(_userClisDir);
-        if (isUserAdapter && _loadedModules.has(modulePath)) {
-            try {
-                const stat = fs.statSync(modulePath);
-                const prevMtime = _moduleMtimes.get(modulePath);
-                if (prevMtime !== undefined && stat.mtimeMs !== prevMtime) {
-                    _loadedModules.delete(modulePath);
-                    _moduleMtimes.delete(modulePath);
-                }
-            }
-            catch { /* file may have been deleted; let import below handle it */ }
-        }
-        if (!_loadedModules.has(modulePath)) {
-            const url = pathToFileURL(modulePath).href;
-            const importUrl = _moduleMtimes.has(modulePath) ? `${url}?t=${Date.now()}` : url;
-            const loadPromise = import(importUrl).then(() => {
-                try {
-                    _moduleMtimes.set(modulePath, fs.statSync(modulePath).mtimeMs);
-                }
-                catch { }
-            }, (err) => {
-                _loadedModules.delete(modulePath);
-                throw adapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`, 'Check that the adapter file exists and has no syntax errors.');
-            });
-            _loadedModules.set(modulePath, loadPromise);
-        }
-        await _loadedModules.get(modulePath);
-        const updated = getRegistry().get(fullName(cmd));
-        if (updated?.func) {
+        const loadedEntry = await loadLazyModule(internal);
+        // Use the command registered by this import generation. A newer file
+        // generation may already be queued/current, but an execution that began
+        // on the older generation is allowed to finish with its own command.
+        const updated = loadedEntry?.registeredCommands.get(fullName(cmd));
+        if (loadedEntry && updated?.func) {
+            finalizeCommandRegistration(loadedEntry, fullName(cmd));
             return runCommandFunc(updated, page, kwargs, debug);
         }
-        if (updated?.pipeline)
+        if (loadedEntry && updated?.pipeline) {
+            finalizeCommandRegistration(loadedEntry, fullName(cmd));
             return executePipeline(page, updated.pipeline, { args: kwargs, debug });
+        }
     }
     if (cmd.func)
         return runCommandFunc(cmd, page, kwargs, debug);
@@ -123,14 +126,212 @@ async function runCommand(cmd, page, kwargs, debug) {
         return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
     throw new CommandExecutionError(`Command ${fullName(cmd)} has no func or pipeline`, 'This is likely a bug in the adapter definition. Please report this issue.');
 }
+function moduleFingerprint(modulePath) {
+    try {
+        _fingerprintReadCount += 1;
+        return crypto.createHash('sha256').update(fs.readFileSync(modulePath)).digest('hex');
+    }
+    catch {
+        return undefined;
+    }
+}
+function isHotReloadableModule(modulePath) {
+    const prefix = getUserClisDir() + path.sep;
+    return modulePath.startsWith(prefix);
+}
+function refreshCapturedCommands(entry) {
+    entry.registeredCommands = capturedRegistryValues(entry.transaction);
+}
+function rollbackImport(entry) {
+    rollbackRegistryTransaction(entry.transaction, getRegistry());
+}
+function rollbackCommandRegistration(entry, key) {
+    const groups = transactionGroupsForKey(entry.transaction, key);
+    rollbackRegistryTransaction(entry.transaction, getRegistry(), groups);
+}
+function finalizeCommandRegistration(entry, key) {
+    const groups = transactionGroupsForKey(entry.transaction, key);
+    finalizeRegistryTransaction(entry.transaction, getRegistry(), groups);
+}
+async function performRegistrationImport(entry, importUrl, modulePath) {
+    if (_registrationImportsPoisoned)
+        throw poisonedImportError();
+    const settlement = runRegistryTransaction(entry.transaction, () => import(importUrl)).then(() => ({ ok: true }), (error) => ({ ok: false, error }));
+    let timeoutId;
+    const timeout = new Promise((resolve) => {
+        timeoutId = setTimeout(() => resolve({ timeout: true }), adapterImportTimeoutMs());
+    });
+    const outcome = await Promise.race([settlement, timeout]);
+    if ('timeout' in outcome) {
+        _registrationImportsPoisoned = true;
+        closeRegistryTransaction(entry.transaction);
+        rollbackImport(entry);
+        void settlement.then(() => {
+            refreshCapturedCommands(entry);
+            rollbackImport(entry);
+        });
+        throw adapterLoadError(`Adapter module ${modulePath} registration timed out after ${adapterImportTimeoutMs()}ms.`, 'Restart byCLI before retrying; ESM evaluation cannot be cancelled safely.');
+    }
+    if (timeoutId)
+        clearTimeout(timeoutId);
+    refreshCapturedCommands(entry);
+    if (!outcome.ok) {
+        rollbackImport(entry);
+        throw adapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(outcome.error)}`, 'Check that the adapter file exists and has no syntax errors.');
+    }
+}
+function scheduleRegistrationImport(entry, importUrl, modulePath) {
+    const scheduled = _registrationImportTail.then(() => performRegistrationImport(entry, importUrl, modulePath), () => performRegistrationImport(entry, importUrl, modulePath));
+    _registrationImportTail = scheduled.then(() => undefined, () => undefined);
+    return scheduled;
+}
+async function loadLazyModule(internal) {
+    const modulePath = internal._modulePath;
+    if (!internal._lazy || !modulePath)
+        return;
+    let entry = _loadedModules.get(modulePath);
+    if (entry) {
+        if (!entry.hotReloadable) {
+            await entry.promise;
+            return entry;
+        }
+        const currentFingerprint = moduleFingerprint(modulePath);
+        if (entry.fingerprint === currentFingerprint) {
+            await entry.promise;
+            return entry;
+        }
+        if (_registrationImportsPoisoned)
+            throw poisonedImportError();
+        invalidateLazyModule(modulePath, entry);
+        entry = undefined;
+    }
+    if (_registrationImportsPoisoned)
+        throw poisonedImportError();
+    if (!entry) {
+        const hotReloadable = isHotReloadableModule(modulePath);
+        const fingerprint = hotReloadable ? moduleFingerprint(modulePath) : undefined;
+        const url = pathToFileURL(modulePath).href;
+        const generation = _moduleImportGenerations.get(modulePath) ?? 0;
+        const importUrl = generation === 0 ? url : `${url}?v=${generation}`;
+        const createdEntry = {
+            promise: Promise.resolve(),
+            fingerprint,
+            generation,
+            registeredCommands: new Map(),
+            transaction: createRegistryTransaction(),
+            hotReloadable,
+        };
+        createdEntry.promise = scheduleRegistrationImport(createdEntry, importUrl, modulePath).catch((error) => {
+            invalidateLazyModule(modulePath, createdEntry);
+            throw error;
+        });
+        _loadedModules.set(modulePath, createdEntry);
+        entry = createdEntry;
+    }
+    await entry.promise;
+    return entry;
+}
+function invalidateLazyModule(modulePath, expectedEntry) {
+    if (!modulePath)
+        return;
+    const currentEntry = _loadedModules.get(modulePath);
+    if (!currentEntry || (expectedEntry && currentEntry !== expectedEntry))
+        return;
+    if (currentEntry.transaction.active) {
+        void currentEntry.promise.then(() => finalizeRegistryTransaction(currentEntry.transaction, getRegistry()), () => finalizeRegistryTransaction(currentEntry.transaction, getRegistry()));
+    }
+    else {
+        finalizeRegistryTransaction(currentEntry.transaction, getRegistry());
+    }
+    _loadedModules.delete(modulePath);
+    _moduleImportGenerations.set(modulePath, Math.max(_moduleImportGenerations.get(modulePath) ?? 0, currentEntry.generation) + 1);
+}
+function assertMatchingArgSchema(placeholder, hydrated, loadedEntry) {
+    const key = fullName(placeholder);
+    try {
+        const manifestSchema = canonicalizeManifestArgSchema(placeholder.args, `Manifest command ${key}`);
+        const moduleSchema = canonicalizeManifestArgSchema(hydrated.args, `Hydrated command ${key}`);
+        if (manifestSchema === moduleSchema)
+            return;
+    }
+    catch (error) {
+        if (loadedEntry)
+            rollbackCommandRegistration(loadedEntry, key);
+        invalidateLazyModule(placeholder._modulePath, loadedEntry);
+        if (!(error instanceof ManifestSchemaError))
+            throw error;
+        throw new CommandExecutionError(`Conditional adapter ${key} has an unsafe argument schema: ${error.message}`, 'Use only JSON-safe defaults and string choices, then rebuild the CLI manifest.');
+    }
+    if (loadedEntry)
+        rollbackCommandRegistration(loadedEntry, key);
+    invalidateLazyModule(placeholder._modulePath, loadedEntry);
+    throw new CommandExecutionError(`Conditional adapter ${key} argument schema does not match its manifest`, 'Rebuild the CLI manifest so defaults, coercion, and validation use the adapter module schema.');
+}
+async function hydrateConditionalCommand(cmd) {
+    const internal = cmd;
+    const key = fullName(cmd);
+    if (cmd.browser !== 'conditional') {
+        throw new CommandExecutionError(`Conditional adapter placeholder ${key} has invalid browser metadata`, 'Rebuild the CLI manifest with the current byCLI version.');
+    }
+    const placeholderResolver = cmd.requiresBrowser;
+    let loadedEntry;
+    try {
+        loadedEntry = await loadLazyModule(internal);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CommandExecutionError(`Failed to hydrate conditional adapter ${key}: ${getErrorMessage(error)}`, 'Rebuild or reinstall the adapter so its manifest and module are both available.');
+    }
+    const hydrated = loadedEntry?.registeredCommands.get(key);
+    const invalidReplacement = !hydrated
+        || hydrated === cmd
+        || fullName(hydrated) !== key
+        || hydrated.browser !== 'conditional';
+    if (invalidReplacement) {
+        if (loadedEntry)
+            rollbackCommandRegistration(loadedEntry, key);
+        invalidateLazyModule(internal._modulePath, loadedEntry);
+        throw new CommandExecutionError(`Conditional adapter ${key} did not register a valid hydrated conditional command`, 'Ensure the module registers the same site/name with a browser predicate and is rebuilt with the current byCLI version.');
+    }
+    const hydratedInternal = hydrated;
+    if (typeof hydrated.requiresBrowser !== 'function'
+        || hydrated.requiresBrowser === placeholderResolver
+        || hydratedInternal._hydrateBeforeBrowserRouting === true
+        || hydratedInternal._lazy === true
+        || hydratedInternal._modulePath !== undefined) {
+        if (loadedEntry)
+            rollbackCommandRegistration(loadedEntry, key);
+        invalidateLazyModule(internal._modulePath, loadedEntry);
+        throw new CommandExecutionError(`Conditional adapter ${key} did not register a valid hydrated conditional command`, 'Ensure the module registers the same site/name with a browser predicate and is rebuilt with the current byCLI version.');
+    }
+    assertMatchingArgSchema(cmd, hydrated, loadedEntry);
+    if (loadedEntry)
+        finalizeCommandRegistration(loadedEntry, key);
+    return hydrated;
+}
 function runCommandFunc(cmd, page, kwargs, debug) {
     if (cmd.browser === false)
         return cmd.func(kwargs, debug);
+    if (cmd.browser === 'conditional')
+        return cmd.func(page, kwargs, debug);
     if (!page) {
         throw new CommandExecutionError(`Command ${fullName(cmd)} requires a browser session but none was provided`);
     }
     return cmd.func(page, kwargs, debug);
 }
+function resolveBrowserRequirement(cmd, kwargs) {
+    if (cmd.browser !== 'conditional')
+        return cmd.browser;
+    try {
+        return Boolean(cmd.requiresBrowser(kwargs));
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CommandExecutionError(`Browser requirement evaluation failed for ${fullName(cmd)}: ${getErrorMessage(error)}`);
+    }
+}
 function resolvePreNav(cmd) {
     if (cmd.navigateBefore === false)
         return null;
@@ -172,16 +373,24 @@ async function shouldRunPreNav(cmd, page, siteSession, preNavUrl) {
     return !urlMatchesDomain(currentUrl, cmd.domain);
 }
 export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
-    let kwargs;
-    try {
-        kwargs = opts.prepared ? rawKwargs : prepareCommandArgs(cmd, rawKwargs);
-    }
-    catch (err) {
-        if (err instanceof ArgumentError)
-            throw err;
-        throw new ArgumentError(getErrorMessage(err));
+    const initialTraceCommand = cmd;
+    let kwargs = opts.prepared
+        ? rawKwargs
+        : prepareCommandArgsOrThrowArgumentError(cmd, rawKwargs);
+    if (cmd._hydrateBeforeBrowserRouting) {
+        cmd = await hydrateConditionalCommand(cmd);
+        // Manifest placeholders cannot serialize adapter validators. The matching
+        // schema above guarantees coercion/defaults stay valid; run only the real
+        // module validator here so custom validation has exactly one side effect.
+        try {
+            cmd.validateArgs?.(kwargs);
+        }
+        catch (error) {
+            if (error instanceof ArgumentError)
+                throw error;
+            throw new ArgumentError(getErrorMessage(error));
+        }
     }
-    const userTimeoutSec = readUserTimeoutSeconds(cmd, kwargs);
     const traceMode = normalizeTraceMode(opts.trace);
     const hookCtx = {
         command: fullName(cmd),
@@ -189,9 +398,12 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
         startedAt: Date.now(),
     };
     await emitHook('onBeforeExecute', hookCtx);
+    kwargs = hookCtx.args;
     let result;
     try {
-        if (shouldUseBrowserSession(cmd)) {
+        const resolvedBrowser = resolveBrowserRequirement(cmd, kwargs);
+        const userTimeoutSec = readUserTimeoutSeconds(cmd, kwargs);
+        if (shouldUseBrowserSession(cmd, resolvedBrowser)) {
             const electron = isElectronApp(cmd.site);
             let cdpEndpoint;
             if (electron) {
@@ -225,7 +437,8 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                             target: page.getActivePage?.(),
                             site: cmd.site,
                             command: fullName(cmd),
-                            adapterSourcePath: resolveAdapterSourcePath(internal),
+                            adapterSourcePath: resolveAdapterSourcePath(internal)
+                                ?? resolveAdapterSourcePath(initialTraceCommand),
                         },
                     });
                 if (observation) {
@@ -433,6 +646,17 @@ export function prepareCommandArgs(cmd, rawKwargs) {
     cmd.validateArgs?.(kwargs);
     return kwargs;
 }
+/** Prepare adapter arguments using the execution boundary's public error contract. */
+export function prepareCommandArgsOrThrowArgumentError(cmd, rawKwargs) {
+    try {
+        return prepareCommandArgs(cmd, rawKwargs);
+    }
+    catch (err) {
+        if (err instanceof ArgumentError)
+            throw err;
+        throw new ArgumentError(getErrorMessage(err));
+    }
+}
 /**
  * Runtime ceiling padding (seconds) added on top of the user's `--timeout`.
  * The adapter's polling loop typically uses the full user value; the padding

package/dist/src/help.js

@@ -1,5 +1,5 @@
 import yaml from 'js-yaml';
-import { fullName } from './registry.js';
+import { browserRequirementLabel, fullName, hasBrowserCapability } from './registry.js';
 import { formatCommandExample } from './serialization.js';
 const COMMON_OPTIONS = [
     {
@@ -363,12 +363,12 @@ function compactCommand(cmd) {
         usage: formatUsage(cmd),
         access: cmd.access,
         description: cmd.description,
-        browser: !!cmd.browser,
+        browser: cmd.browser,
         ...(cmd.domain ? { domain: cmd.domain } : {}),
         ...(cmd.aliases?.length ? { aliases: cmd.aliases } : {}),
         positionals: positionals(cmd).map(compactArg),
         command_options: commandOptions(cmd).map(compactArg),
-        ...(cmd.browser ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
+        ...(hasBrowserCapability(cmd) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
         example: formatCommandExample(cmd),
         ...(cmd.siteSession ? { siteSession: cmd.siteSession } : {}),
         ...(cmd.defaultFormat ? { defaultFormat: cmd.defaultFormat } : {}),
@@ -416,7 +416,7 @@ export function siteHelpData(site, commands) {
         command_count: unique.length,
         commands: unique.map(cmd => compactCommand(cmd)),
         common_options: COMMON_OPTIONS.map(compactCommonOption),
-        ...(unique.some(cmd => cmd.browser) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
+        ...(unique.some(hasBrowserCapability) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
         next: [
             `bycli ${site} <command> --help -f yaml`,
             `bycli ${site} <command> -f yaml`,
@@ -428,7 +428,7 @@ export function commandHelpData(cmd) {
         site: cmd.site,
         ...compactCommand(cmd),
         common_options: COMMON_OPTIONS.map(compactCommonOption),
-        ...(cmd.browser ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
+        ...(hasBrowserCapability(cmd) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
         output_formats: ['table', 'plain', 'yaml', 'json', 'md', 'csv'],
     };
 }
@@ -480,7 +480,7 @@ export function formatSiteHelpText(site, commands) {
         ...formatRows(unique.map(cmd => [formatCommandListTerm(cmd), formatSiteCommandDescription(cmd)])),
         '',
         formatCommonOptionsHelpText(),
-        ...(unique.some(cmd => cmd.browser) ? ['', formatBrowserCommonOptionsHelpText()] : []),
+        ...(unique.some(hasBrowserCapability) ? ['', formatBrowserCommonOptionsHelpText()] : []),
         '',
         `Agent tip: use 'bycli ${site} --help -f yaml' to get all command args/options in one structured response.`,
         '',
@@ -509,11 +509,11 @@ export function formatCommandHelpText(cmd) {
         lines.push('Command options:', ...formatRows(optionRows), '');
     }
     lines.push(formatCommonOptionsHelpText(), '');
-    if (cmd.browser)
+    if (hasBrowserCapability(cmd))
         lines.push(formatBrowserCommonOptionsHelpText(), '');
     const meta = [];
     meta.push(`Access: ${cmd.access}`);
-    meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
+    meta.push(`Browser: ${browserRequirementLabel(cmd)}`);
     if (cmd.domain)
         meta.push(`Domain: ${cmd.domain}`);
     if (cmd.defaultFormat)

package/dist/src/main.js

@@ -13,8 +13,8 @@ if (process.platform !== 'win32') {
     process.env.PATH = [...cur].join(':');
 }
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
+import { getUserClisDir } from './config-paths.js';
 import { fileURLToPath } from 'node:url';
 import { getCompletionsFromManifest, hasAllManifests, printCompletionScriptFast } from './completion-fast.js';
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
@@ -26,7 +26,7 @@ const __dirname = path.dirname(__filename);
 // Adapters are JS-first and live at <package-root>/clis/.
 // Use findPackageRoot so the path works both in dev (src/main.ts) and prod (dist/src/main.js).
 const BUILTIN_CLIS = path.join(findPackageRoot(__filename), 'clis');
-const USER_CLIS = path.join(os.homedir(), '.bycli', 'clis');
+const USER_CLIS = getUserClisDir();
 // ── Ultra-fast path: lightweight commands bypass full discovery ──────────
 // These are high-frequency or trivial paths that must not pay the startup tax.
 const argv = process.argv.slice(2);
@@ -52,6 +52,22 @@ if (argv[0] === 'completion' && argv.length >= 2) {
     }
     // Unknown shell — fall through to full path for proper error handling
 }
+// Fast path: internal verify-runner — the child process spawned by the verify RunnerPort
+// (08). It loads ONLY the target adapter (by path, from input.json) and emits JSONL; it must
+// never run full adapter discovery, and its stdout must stay pure JSONL.
+if (argv[0] === 'internal' && argv[1] === 'verify-runner') {
+    const { runVerifyRunnerCli } = await import('./recorder/runner/verify-runner-main.js');
+    await runVerifyRunnerCli(argv.slice(2));
+    process.exit(process.exitCode ?? EXIT_CODES.SUCCESS);
+}
+// Fast path: internal highlevel-http — the OPTIONAL standalone High-Level HTTP wrapper (M9,
+// 07 · Optional HTTP Wrapper). Default off; opt-in only via this command. Binds 127.0.0.1 and
+// keeps running, so it must skip full adapter discovery. Distinct from the daemon /v1/* family.
+if (argv[0] === 'internal' && argv[1] === 'highlevel-http') {
+    const { runWrapperCli } = await import('./recorder/http/wrapper-server.js');
+    await runWrapperCli(); // blocks while the server is alive; resolves on close (SIGTERM/SIGINT)
+    process.exit(process.exitCode ?? EXIT_CODES.SUCCESS); // never fall through to CLI discovery
+}
 // Fast path: --get-completions — read from manifest, skip discovery
 const getCompIdx = process.argv.indexOf('--get-completions');
 if (getCompIdx !== -1) {

package/dist/src/manifest-schema.d.ts

@@ -0,0 +1,9 @@
+import type { Arg } from './registry.js';
+export declare class ManifestSchemaError extends Error {
+    constructor(message: string);
+}
+/**
+ * Canonical execution-relevant argument schema used by both manifest build and
+ * runtime hydration. Objects are key-order independent; arrays remain ordered.
+ */
+export declare function canonicalizeManifestArgSchema(args: readonly Arg[], context: string): string;