@sovovs/bycli 2.0.0 → 2.1.0

package/clis/twitter/search.js

@@ -268,10 +268,10 @@ cli({
     args: [
         { name: 'query', type: 'string', required: true, positional: true, help: 'Search query. Raw X operators (e.g. "exact phrase", #tag, OR, lang:en, since:YYYY-MM-DD, from:, since:) are passed through unchanged.' },
         { name: 'filter', type: 'string', default: 'top', choices: ['top', 'live'], help: 'Legacy alias for --product. Kept for backwards compatibility; if --product is set it wins.' },
-        { name: 'product', type: 'string', choices: PRODUCT_CHOICES, help: 'Which X search tab to read: top (default), live (Latest), photos, videos. Maps to the f= URL param.' },
+        { name: 'product', type: 'string', choices: [...PRODUCT_CHOICES], help: 'Which X search tab to read: top (default), live (Latest), photos, videos. Maps to the f= URL param.' },
         { name: 'from', type: 'string', help: 'Restrict to tweets authored by <user>. Leading @ is stripped. Equivalent to appending `from:<user>` to the query.' },
-        { name: 'has', type: 'string', choices: HAS_CHOICES, help: 'Restrict to tweets that have media|images|videos|links|replies. Maps to X\'s `filter:<has>` operator.' },
-        { name: 'exclude', type: 'string', choices: EXCLUDE_CHOICES, help: 'Exclude tweets matching <type>: replies|retweets|media|links. Maps to X\'s `-filter:<x>` operator (retweets → -filter:nativeretweets).' },
+        { name: 'has', type: 'string', choices: [...HAS_CHOICES], help: 'Restrict to tweets that have media|images|videos|links|replies. Maps to X\'s `filter:<has>` operator.' },
+        { name: 'exclude', type: 'string', choices: [...EXCLUDE_CHOICES], help: 'Exclude tweets matching <type>: replies|retweets|media|links. Maps to X\'s `-filter:<x>` operator (retweets → -filter:nativeretweets).' },
         { name: 'limit', type: 'int', default: 15, help: 'Maximum number of tweets to return (default 15). Result count after server-side filtering.' },
         { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank the results by weighted engagement (likes×1 + retweets×3 + replies×2 + bookmarks×5 + log10(views+1)×0.5) and return the top N. Default 0 keeps X\'s native ordering.' },
     ],

package/dist/src/browser/cdp.js

@@ -258,6 +258,9 @@ class CDPPage extends BasePage {
             ? cookies.filter((cookie) => isCookie(cookie) && matchesCookieDomain(cookie.domain, domain))
             : cookies;
     }
+    async focusWindow() {
+        await this.bridge.send('Page.bringToFront');
+    }
     async screenshot(options = {}) {
         const fullPage = options.fullPage === true;
         const overrideWidth = options.width && options.width > 0 ? Math.ceil(options.width) : undefined;

package/dist/src/browser/daemon-client.d.ts

@@ -68,6 +68,7 @@ export interface DaemonStatus {
     extensionConnected: boolean;
     extensionVersion?: string;
     extensionCompatRange?: string;
+    extensionCapabilities?: string[];
     contextId?: string;
     profileRequired?: boolean;
     profileDisconnected?: boolean;
@@ -82,6 +83,7 @@ export interface BrowserProfileStatus {
     extensionConnected: boolean;
     extensionVersion?: string;
     extensionCompatRange?: string;
+    extensionCapabilities?: string[];
     pending: number;
     lastSeenAt?: number;
 }

package/dist/src/browser/daemon-client.js

@@ -109,7 +109,7 @@ async function sendCommandRaw(action, params) {
                     throw new BrowserCommandError(result.error ?? 'Browser command result is unknown', result.errorCode, result.errorHint);
                 }
                 const isDuplicateCommandId = res.status === 409
-                    || (result.error ?? '').includes('Duplicate command id');
+                    && (result.error ?? '').includes('Duplicate command id');
                 if (isDuplicateCommandId && attempt < maxRetries) {
                     continue;
                 }

package/dist/src/browser/extension-capabilities.d.ts

@@ -0,0 +1,13 @@
+export declare const FOCUS_WINDOW_CAPABILITY = "focus-window-v1";
+export declare const EXTENSION_CAPABILITY_MISSING_ERROR_CODE = "extension_capability_missing";
+export declare const EXTENSION_CAPABILITY_MISSING_HTTP_STATUS = 412;
+export declare function normalizeExtensionCapabilities(value: unknown): string[];
+export declare function requiredExtensionCapability(command: {
+    action?: unknown;
+    op?: unknown;
+}): string | undefined;
+export declare function missingRequiredExtensionCapability(command: {
+    action?: unknown;
+    op?: unknown;
+}, capabilities: readonly string[]): string | undefined;
+export declare function extensionCapabilityHint(capability: string): string;

package/dist/src/browser/extension-capabilities.js

@@ -0,0 +1,22 @@
+export const FOCUS_WINDOW_CAPABILITY = 'focus-window-v1';
+export const EXTENSION_CAPABILITY_MISSING_ERROR_CODE = 'extension_capability_missing';
+export const EXTENSION_CAPABILITY_MISSING_HTTP_STATUS = 412;
+export function normalizeExtensionCapabilities(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.filter((entry) => typeof entry === 'string' && entry.length > 0))];
+}
+export function requiredExtensionCapability(command) {
+    return command.action === 'tabs' && command.op === 'focus'
+        ? FOCUS_WINDOW_CAPABILITY
+        : undefined;
+}
+export function missingRequiredExtensionCapability(command, capabilities) {
+    const required = requiredExtensionCapability(command);
+    return required && !capabilities.includes(required) ? required : undefined;
+}
+export function extensionCapabilityHint(capability) {
+    return capability === FOCUS_WINDOW_CAPABILITY
+        ? 'Update and reload the byCLI Browser Bridge extension, then retry the login flow.'
+        : 'Update and reload the byCLI Browser Bridge extension, then retry.';
+}

package/dist/src/browser/extension-capabilities.test.d.ts

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

package/dist/src/browser/extension-version-metadata.test.d.ts

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

package/dist/src/browser/page.d.ts

@@ -44,6 +44,7 @@ export declare class Page extends BasePage {
         domain?: string;
         url?: string;
     }): Promise<BrowserCookie[]>;
+    focusWindow(): Promise<void>;
     /** Release the current browser session lease in the extension */
     closeWindow(): Promise<void>;
     tabs(): Promise<unknown[]>;

package/dist/src/browser/page.js

@@ -8,7 +8,8 @@
  * by the navigate action and pass it to all subsequent commands. This ensures
  * page-scoped operations target the correct page without guessing.
  */
-import { sendCommand, sendCommandFull } from './daemon-client.js';
+import { fetchDaemonStatus, sendCommand, sendCommandFull } from './daemon-client.js';
+import { extensionCapabilityHint, FOCUS_WINDOW_CAPABILITY } from './extension-capabilities.js';
 import { buildEvaluateExpression } from './utils.js';
 import { saveBase64ToFile } from '../utils.js';
 import { generateStealthJs } from './stealth.js';
@@ -180,6 +181,24 @@ export class Page extends BasePage {
         const result = await sendCommand('cookies', { ...this._sessionOpts(), ...opts });
         return Array.isArray(result) ? result : [];
     }
+    async focusWindow() {
+        const status = await fetchDaemonStatus(this.contextId ? { contextId: this.contextId } : undefined);
+        const selectedExtensionIsConnected = status?.extensionConnected === true
+            && status.profileRequired !== true
+            && status.profileDisconnected !== true;
+        const capabilities = status?.extensionCapabilities;
+        const capabilityListIsDefinitive = Array.isArray(capabilities);
+        if (selectedExtensionIsConnected
+            && capabilityListIsDefinitive
+            && !capabilities.includes(FOCUS_WINDOW_CAPABILITY)) {
+            throw new Error(`Connected Browser Bridge does not advertise ${FOCUS_WINDOW_CAPABILITY}. ${extensionCapabilityHint(FOCUS_WINDOW_CAPABILITY)}`);
+        }
+        await sendCommandFull('tabs', {
+            op: 'focus',
+            ...this._cmdOpts(),
+            ...this._sessionOpts(),
+        });
+    }
     /** Release the current browser session lease in the extension */
     async closeWindow() {
         try {

package/dist/src/build-manifest.js

@@ -28,6 +28,7 @@ import { getErrorMessage } from './errors.js';
 import { fullName, getRegistry } from './registry.js';
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
 import { isRecord } from './utils.js';
+import { canonicalizeManifestArgSchema } from './manifest-schema.js';
 const PACKAGE_ROOT = findPackageRoot(fileURLToPath(import.meta.url));
 const CLIS_DIR = path.join(PACKAGE_ROOT, 'clis');
 // Write manifest next to clis/ so both dev and installed runtime can find it.
@@ -58,7 +59,7 @@ function toManifestArgs(args) {
     return args.map(arg => ({
         name: arg.name,
         type: arg.type ?? 'str',
-        default: arg.default,
+        ...(Object.prototype.hasOwnProperty.call(arg, 'default') ? { default: arg.default } : {}),
         required: !!arg.required,
         valueRequired: !!arg.valueRequired || undefined,
         positional: arg.positional || undefined,
@@ -85,6 +86,7 @@ function isCliCommandValue(value, site) {
         && Array.isArray(value.args);
 }
 function toManifestEntry(cmd, modulePath, sourceFile) {
+    canonicalizeManifestArgSchema(cmd.args, `Command ${fullName(cmd)}`);
     return {
         site: cmd.site,
         name: cmd.name,
@@ -94,7 +96,7 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         example: cmd.example,
         domain: cmd.domain,
         strategy: (cmd.strategy ?? 'public').toString().toLowerCase(),
-        browser: cmd.browser ?? true,
+        browser: cmd.browser,
         args: toManifestArgs(cmd.args),
         columns: cmd.columns,
         defaultFormat: cmd.defaultFormat,

package/dist/src/capabilityRouting.d.ts

@@ -1,4 +1,4 @@
-import type { CliCommand } from './registry.js';
+import type { BrowserCliCommand, CliCommand, NonBrowserCliCommand } from './registry.js';
 /**
  * Pipeline steps that require a live browser session.
  *
@@ -16,4 +16,5 @@ export declare const BROWSER_ONLY_STEPS: Set<string>;
 export declare function _validateBrowserOnlyStepsAgainstRegistry(): {
     extras: string[];
 };
-export declare function shouldUseBrowserSession(cmd: CliCommand): boolean;
+export declare function shouldUseBrowserSession(cmd: BrowserCliCommand | NonBrowserCliCommand): boolean;
+export declare function shouldUseBrowserSession(cmd: CliCommand, resolvedBrowser: boolean): boolean;

package/dist/src/capabilityRouting.js

@@ -1,3 +1,4 @@
+import { CommandExecutionError } from './errors.js';
 import { getRegisteredStepNames } from './pipeline/registry.js';
 /**
  * Pipeline steps that require a live browser session.
@@ -40,8 +41,15 @@ function pipelineNeedsBrowserSession(pipeline) {
         return Object.keys(step).some((op) => BROWSER_ONLY_STEPS.has(op));
     });
 }
-export function shouldUseBrowserSession(cmd) {
-    if (!cmd.browser)
+export function shouldUseBrowserSession(cmd, resolvedBrowser) {
+    let browserRequired = resolvedBrowser;
+    if (browserRequired === undefined) {
+        if (cmd.browser === 'conditional') {
+            throw new CommandExecutionError(`Conditional browser requirement for ${cmd.site}/${cmd.name} must be resolved before capability routing`);
+        }
+        browserRequired = cmd.browser;
+    }
+    if (!browserRequired)
         return false;
     if (cmd.func)
         return true;

package/dist/src/cli.js

@@ -506,7 +506,7 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
                     description: c.description,
                     access: c.access,
                     strategy: strategyLabel(c),
-                    browser: !!c.browser,
+                    browser: c.browser,
                     args: formatArgSummary(c.args),
                 }));
             renderOutput(rows, {

package/dist/src/commanderAdapter.js

@@ -11,7 +11,7 @@
  */
 import { log } from './logger.js';
 import yaml from 'js-yaml';
-import { fullName, getRegistry } from './registry.js';
+import { fullName, getRegistry, hasBrowserCapability } from './registry.js';
 import { render as renderOutput } from './output.js';
 import { executeCommand, prepareCommandArgs } from './execution.js';
 import { commandHelpData, formatCommandHelpText, formatCommandListTerm, formatSiteCommandDescription, formatSiteHelpText, getRequestedHelpFormat, renderStructuredHelp, siteHelpData, } from './help.js';
@@ -48,7 +48,7 @@ export function registerCommandToProgram(siteCmd, cmd) {
         .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
         .option('--trace <mode>', 'Trace capture: off, on, retain-on-failure', 'off')
         .option('-v, --verbose', 'Debug output', false);
-    if (cmd.browser) {
+    if (hasBrowserCapability(cmd)) {
         subCmd
             .option('--window <mode>', 'Browser window mode: foreground or background')
             .option('--site-session <mode>', 'Adapter site session lifecycle: ephemeral or persistent')
@@ -108,9 +108,9 @@ export function registerCommandToProgram(siteCmd, cmd) {
                 prepared: true,
                 ...(typeof globals.profile === 'string' && globals.profile.trim() ? { profile: globals.profile.trim() } : {}),
                 ...(typeof optionsRecord.trace === 'string' && optionsRecord.trace !== 'off' ? { trace: optionsRecord.trace } : {}),
-                ...(cmd.browser && typeof optionsRecord.window === 'string' ? { windowMode: optionsRecord.window } : {}),
-                ...(cmd.browser && typeof optionsRecord.siteSession === 'string' ? { siteSession: optionsRecord.siteSession } : {}),
-                ...(cmd.browser && typeof optionsRecord.keepTab === 'string' ? { keepTab: optionsRecord.keepTab } : {}),
+                ...(hasBrowserCapability(cmd) && typeof optionsRecord.window === 'string' ? { windowMode: optionsRecord.window } : {}),
+                ...(hasBrowserCapability(cmd) && typeof optionsRecord.siteSession === 'string' ? { siteSession: optionsRecord.siteSession } : {}),
+                ...(hasBrowserCapability(cmd) && typeof optionsRecord.keepTab === 'string' ? { keepTab: optionsRecord.keepTab } : {}),
             });
             if (result === null || result === undefined) {
                 return;

package/dist/src/daemon.js

@@ -35,6 +35,7 @@ import { reapOrphanedVerifyRuns } from './recorder/runner/reap.js';
 import { resolveTempPolicy, resolveRunnerConfig, resolveTempCapacity } from './recorder/runner/config.js';
 import { defaultSessionKeyRegistry } from './recorder/runner/session-keys.js';
 import { recordExtensionVersion } from './update-check.js';
+import { EXTENSION_CAPABILITY_MISSING_ERROR_CODE, EXTENSION_CAPABILITY_MISSING_HTTP_STATUS, extensionCapabilityHint, missingRequiredExtensionCapability, normalizeExtensionCapabilities, } from './browser/extension-capabilities.js';
 import { buildCommandDispatchFailure, buildExtensionDisconnectFailure, getResponseCorsHeaders, } from './daemon-utils.js';
 const PORT = parseInt(process.env.BYCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 // The verify runner (M6b) spawns child processes that connect back to THIS daemon for a
@@ -123,6 +124,7 @@ function registerExtensionConnection(ws, rawContextId) {
         ws,
         extensionVersion: current?.ws === ws ? current.extensionVersion : null,
         extensionCompatRange: current?.ws === ws ? current.extensionCompatRange : null,
+        extensionCapabilities: current?.ws === ws ? current.extensionCapabilities : [],
         lastSeenAt: Date.now(),
     };
     extensionProfiles.set(contextId, connection);
@@ -357,6 +359,7 @@ async function handleRequest(req, res) {
             extensionConnected: true,
             extensionVersion: profile.extensionVersion ?? undefined,
             extensionCompatRange: profile.extensionCompatRange ?? undefined,
+            extensionCapabilities: profile.extensionCapabilities,
             pending: [...pending.values()].filter((entry) => entry.contextId === profile.contextId).length,
             lastSeenAt: profile.lastSeenAt,
         }));
@@ -368,6 +371,7 @@ async function handleRequest(req, res) {
             extensionConnected: !!route.connection,
             extensionVersion: route.connection?.extensionVersion ?? undefined,
             extensionCompatRange: route.connection?.extensionCompatRange ?? undefined,
+            extensionCapabilities: route.connection?.extensionCapabilities,
             contextId: route.connection?.contextId ?? requestedContextId,
             profileRequired: route.errorCode === 'profile_required',
             profileDisconnected: route.errorCode === 'profile_disconnected',
@@ -423,6 +427,17 @@ async function handleRequest(req, res) {
                 });
                 return;
             }
+            const requiredCapability = missingRequiredExtensionCapability(body, route.connection.extensionCapabilities);
+            if (requiredCapability) {
+                jsonResponse(res, EXTENSION_CAPABILITY_MISSING_HTTP_STATUS, {
+                    id: body.id,
+                    ok: false,
+                    errorCode: EXTENSION_CAPABILITY_MISSING_ERROR_CODE,
+                    error: `Connected Browser Bridge does not advertise ${requiredCapability}.`,
+                    errorHint: extensionCapabilityHint(requiredCapability),
+                });
+                return;
+            }
             const timeoutMs = typeof body.timeout === 'number' && body.timeout > 0
                 ? body.timeout * 1000
                 : 120000;
@@ -529,6 +544,7 @@ wss.on('connection', (ws) => {
                 const connection = registerExtensionConnection(ws, msg.contextId);
                 connection.extensionVersion = typeof msg.version === 'string' ? msg.version : null;
                 connection.extensionCompatRange = typeof msg.compatRange === 'string' ? msg.compatRange : null;
+                connection.extensionCapabilities = normalizeExtensionCapabilities(msg.capabilities);
                 connection.lastSeenAt = Date.now();
                 if (connection.extensionVersion)
                     recordExtensionVersion(connection.extensionVersion);

package/dist/src/discovery.d.ts

@@ -37,6 +37,11 @@ export declare function ensureUserAdapters(): Promise<void>;
  * Uses pre-compiled manifest when available for instant startup.
  */
 export declare function discoverClis(...dirs: string[]): Promise<void>;
+/**
+ * Fast-path: register commands from pre-compiled manifest.
+ * TS modules are deferred — loaded lazily on first execution.
+ */
+export declare function loadFromManifest(manifestPath: string, clisDir: string): Promise<boolean>;
 /**
  * Discover and register plugins from ~/.bycli/plugins/.
  * Each subdirectory is treated as a plugin (site = directory name).

package/dist/src/discovery.js

@@ -113,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);
@@ -121,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,
@@ -130,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,
@@ -141,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;