@sovovs/bycli 2.0.0 → 2.1.1

package/clis/weixin/_wechat/wechat-api.js

@@ -0,0 +1,133 @@
+import { AuthRequiredError, CommandExecutionError } from '@sovovs/bycli/errors';
+import { buildSecretSet, redactText } from './redact.js';
+
+const DOMAIN = 'mp.weixin.qq.com';
+const ENDPOINT = `https://${DOMAIN}/cgi-bin/appmsgpublish`;
+
+function normalizedMessage(value) {
+  return String(value ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+function commandError(message) {
+  return new CommandExecutionError(redactText(message, []));
+}
+
+function parseNestedJson(value, label) {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw commandError(`WeChat ${label} is malformed: ${detail}`);
+  }
+}
+
+/** @param {unknown} data */
+export function parsePublishData(data) {
+  if (!data || typeof data !== 'object') {
+    throw new CommandExecutionError('WeChat article history returned an unreadable response');
+  }
+  const response = /** @type {Record<string, any>} */ (data);
+  const ret = response.base_resp?.ret;
+  const message = response.base_resp?.err_msg ?? response.base_resp?.err_msg_en ?? '';
+  if (ret === 200013 && normalizedMessage(message) === 'invalid credential') {
+    throw new AuthRequiredError(DOMAIN, 'WeChat article-history credentials have expired');
+  }
+  if (ret !== undefined && ret !== 0) {
+    throw new CommandExecutionError(`WeChat article history failed (ret=${String(ret)})`);
+  }
+  if (response.publish_page === undefined || response.publish_page === null || response.publish_page === '') {
+    return { total: 0, publishItemCount: 0, articles: [] };
+  }
+  const page = parseNestedJson(response.publish_page, 'publish_page');
+  if (!page || typeof page !== 'object' || !Array.isArray(page.publish_list)) {
+    throw new CommandExecutionError('WeChat article history returned an invalid publish page');
+  }
+  const total = page.total_count === undefined ? 0 : page.total_count;
+  if (!Number.isSafeInteger(total) || total < 0) {
+    throw new CommandExecutionError('WeChat article history returned invalid total metadata');
+  }
+  const articles = [];
+  for (const item of page.publish_list) {
+    const info = parseNestedJson(item?.publish_info ?? {}, 'publish_info');
+    if (!info || typeof info !== 'object' || !Array.isArray(info.appmsg_info)) {
+      throw new CommandExecutionError('WeChat article history returned invalid publish information');
+    }
+    const timestamp = info.sent_info?.time ?? info.publish_info?.create_time ?? 0;
+    let publishedAt = null;
+    if (timestamp !== 0) {
+      if (typeof timestamp !== 'number' || !Number.isFinite(timestamp) || timestamp <= 0) {
+        throw new CommandExecutionError('WeChat article history returned an invalid publish timestamp');
+      }
+      const date = new Date(timestamp * 1000);
+      if (!Number.isFinite(date.getTime())) {
+        throw new CommandExecutionError('WeChat article history returned an invalid publish timestamp');
+      }
+      publishedAt = date.toISOString();
+    }
+    for (const messageItem of info.appmsg_info) {
+      const article = messageItem && typeof messageItem === 'object' ? messageItem : {};
+      articles.push({
+        title: typeof article.title === 'string' ? article.title : '',
+        url: typeof article.content_url === 'string' ? article.content_url : '',
+        isDeleted: article.is_deleted === true,
+        timestamp,
+        publishedAt,
+        digest: typeof article.digest === 'string' ? article.digest : '',
+        author: typeof article.author === 'string' ? article.author : '',
+      });
+    }
+  }
+  return {
+    total,
+    publishItemCount: page.publish_list.length,
+    articles,
+  };
+}
+
+export function requestHeaders(cookie, token) {
+  return {
+    Accept: 'application/json, text/javascript, */*; q=0.01',
+    Cookie: cookie,
+    Origin: `https://${DOMAIN}`,
+    Referer: `https://${DOMAIN}/cgi-bin/appmsg?t=media/appmsg_edit_v2&action=edit&isNew=1&type=10&token=${encodeURIComponent(token)}&lang=zh_CN`,
+    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/143 Safari/537.36',
+    'X-Requested-With': 'XMLHttpRequest',
+  };
+}
+
+/**
+ * @param {{token:string,cookie:string,timeoutMs?:number,fetchImpl?:typeof fetch}} options
+ */
+export function createWechatApi({ token, cookie, timeoutMs = 30_000, fetchImpl = fetch }) {
+  const headers = requestHeaders(cookie, token);
+  const secrets = buildSecretSet({ token, cookie });
+
+  return {
+    async fetchPage({ fakeid, begin = 0, count = 10 }) {
+      const query = new URLSearchParams({
+        sub: 'list', begin: String(begin), count: String(count), fakeid, token,
+        lang: 'zh_CN', f: 'json', ajax: '1',
+      });
+      try {
+        const response = await fetchImpl(`${ENDPOINT}?${query}`, {
+          headers,
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!response.ok) {
+          throw new CommandExecutionError(`WeChat article history request failed: HTTP ${response.status} ${response.statusText ?? ''}`.trim());
+        }
+        return parsePublishData(await response.json());
+      } catch (error) {
+        if (error instanceof AuthRequiredError && error.domain === DOMAIN) throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        const hint = error && typeof error === 'object' && 'hint' in error && typeof error.hint === 'string'
+          ? error.hint : undefined;
+        throw new CommandExecutionError(
+          `WeChat article history request failed: ${redactText(message, secrets)}`,
+          hint ? redactText(hint, secrets) : undefined,
+        );
+      }
+    },
+  };
+}

package/clis/weixin/accounts.js

@@ -0,0 +1,38 @@
+import { ArgumentError, EmptyResultError } from '@sovovs/bycli/errors';
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import { readEnvironmentCredentials, resolveBrowserCredentials } from './_wechat/auth-session.js';
+import { captureSearchBizFingerprint } from './_wechat/fingerprint.js';
+import { executeSearchBiz } from './_wechat/search-biz.js';
+import { readAuthSource } from './_wechat/args.js';
+
+const DOMAIN = 'mp.weixin.qq.com';
+const browserRequired = args => readAuthSource(args) === 'browser';
+
+export const accountsCommand = cli({
+  site: 'weixin', name: 'accounts', access: 'read', domain: DOMAIN,
+  description: 'Search WeChat official accounts and return their fakeids',
+  strategy: Strategy.INTERCEPT, browser: browserRequired,
+  args: [
+    { name: 'query', positional: true, required: true, help: 'Official-account name to search for' },
+    { name: 'limit', type: 'int', default: 10, help: 'Maximum number of matching accounts to return' },
+    { name: 'auth-source', default: 'browser', choices: ['browser', 'env'], help: 'Credential source: browser session or environment variables' },
+  ],
+  columns: ['nickname', 'fakeid', 'alias'],
+  func: async (page, args) => {
+    const query = String(args.query ?? '').trim();
+    if (!query) throw new ArgumentError('query is required');
+    const limit = args.limit ?? 10;
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new ArgumentError('limit must be a positive safe integer');
+    const authSource = readAuthSource(args);
+    let credentials;
+    if (authSource === 'env') {
+      credentials = readEnvironmentCredentials(true);
+    } else {
+      credentials = await resolveBrowserCredentials(page);
+      credentials = { ...credentials, fingerprint: await captureSearchBizFingerprint(page, query) };
+    }
+    const rows = await executeSearchBiz({ page, source: authSource, credentials, query, limit });
+    if (rows.length === 0) throw new EmptyResultError('weixin accounts', `No official accounts matched "${query}".`);
+    return rows.map(row => ({ nickname: row.nickname, fakeid: row.fakeid, alias: row.alias || null }));
+  },
+});

package/clis/weixin/articles.js

@@ -0,0 +1,35 @@
+import { ArgumentError, EmptyResultError } from '@sovovs/bycli/errors';
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import { readEnvironmentCredentials, resolveBrowserCredentials } from './_wechat/auth-session.js';
+import { collectArticles } from './_wechat/article-service.js';
+import { createWechatApi } from './_wechat/wechat-api.js';
+import { readAuthSource } from './_wechat/args.js';
+
+const DOMAIN = 'mp.weixin.qq.com';
+const browserRequired = args => readAuthSource(args) === 'browser';
+
+export const articlesCommand = cli({
+  site: 'weixin', name: 'articles', access: 'read', domain: DOMAIN,
+  description: 'List published articles from a WeChat official account',
+  strategy: Strategy.COOKIE, browser: browserRequired,
+  args: [
+    { name: 'fakeid', positional: true, required: true, help: 'Official-account fakeid returned by weixin accounts' },
+    { name: 'name', help: 'Optional official-account name for display context' }, { name: 'limit', type: 'int', help: 'Maximum number of articles to return' }, { name: 'max-pages', type: 'int', help: 'Maximum number of history pages to scan' },
+    { name: 'auth-source', default: 'browser', choices: ['browser', 'env'], help: 'Credential source: browser session or environment variables' },
+  ],
+  columns: ['title', 'author', 'digest', 'publishedAt', 'url'],
+  func: async (page, args) => {
+    const fakeid = String(args.fakeid ?? '').trim();
+    if (!fakeid) throw new ArgumentError('fakeid is required');
+    const authSource = readAuthSource(args);
+    const credentials = authSource === 'env'
+      ? readEnvironmentCredentials(false) : await resolveBrowserCredentials(page);
+    const { fetchPage } = createWechatApi(credentials);
+    const { articles } = await collectArticles({ fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'] });
+    if (articles.length === 0) throw new EmptyResultError('weixin articles', `No published articles were found for ${fakeid}.`);
+    return articles.map(article => ({
+      title: article.title, author: article.author || null, digest: article.digest || null,
+      publishedAt: article.publishedAt || null, url: article.url,
+    }));
+  },
+});

package/clis/weixin/download.js

@@ -8,6 +8,8 @@
  */
 import { cli, Strategy } from '@sovovs/bycli/registry';
 import { downloadArticle } from '@sovovs/bycli/download/article-download';
+import { buildExtractWechatArticleContentJs } from './_wechat/article-content.js';
+export { extractWechatArticleContent } from './_wechat/article-content.js';
 // ============================================================
 // URL Normalization
 // ============================================================
@@ -241,53 +243,8 @@ cli({
         );
         if (result.errorHint) return result;
 
-        // Content processing
-        const contentEl = document.querySelector('#js_content');
-        if (!contentEl) return result;
-
-        // Fix lazy-loaded images: data-src -> src
-        contentEl.querySelectorAll('img').forEach(img => {
-          const dataSrc = img.getAttribute('data-src');
-          if (dataSrc) img.setAttribute('src', dataSrc);
-        });
-
-        // Extract code blocks with placeholder replacement
-        const codeBlocks = [];
-        contentEl.querySelectorAll('.code-snippet__fix').forEach(el => {
-          el.querySelectorAll('.code-snippet__line-index').forEach(li => li.remove());
-          const pre = el.querySelector('pre[data-lang]');
-          const lang = pre ? (pre.getAttribute('data-lang') || '') : '';
-          const lines = [];
-          el.querySelectorAll('code').forEach(codeTag => {
-            const text = codeTag.textContent;
-            if (/^[ce]?ounter\\(line/.test(text)) return;
-            lines.push(text);
-          });
-          if (lines.length === 0) lines.push(el.textContent);
-          const placeholder = 'CODEBLOCK-PLACEHOLDER-' + codeBlocks.length;
-          codeBlocks.push({ lang, code: lines.join('\\n') });
-          const p = document.createElement('p');
-          p.textContent = placeholder;
-          el.replaceWith(p);
-        });
-        result.codeBlocks = codeBlocks;
-
-        // Remove noise elements
-        ['script', 'style', '.qr_code_pc', '.reward_area'].forEach(sel => {
-          contentEl.querySelectorAll(sel).forEach(tag => tag.remove());
-        });
-
-        // Collect image URLs (deduplicated)
-        const seen = new Set();
-        contentEl.querySelectorAll('img[src]').forEach(img => {
-          const src = img.getAttribute('src');
-          if (src && !seen.has(src)) {
-            seen.add(src);
-            result.imageUrls.push(src);
-          }
-        });
-
-        result.contentHtml = contentEl.innerHTML;
+        const extractWechatArticleContent = ${buildExtractWechatArticleContentJs()};
+        Object.assign(result, extractWechatArticleContent(document));
         return result;
       })()
     `);
@@ -318,6 +275,7 @@ cli({
                 const m = url.match(/wx_fmt=(\w+)/) || url.match(/\.(\w{3,4})(?:\?|$)/);
                 return m ? m[1] : 'png';
             },
+            secureMarkdown: true,
         });
     },
 });

package/clis/weixin/save-articles.js

@@ -0,0 +1,175 @@
+import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
+import { MAX_WECHAT_HTML_BYTES } from '@sovovs/bycli/download/wechat-article';
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import { readEnvironmentCredentials, resolveBrowserCredentials } from './_wechat/auth-session.js';
+import { collectArticles, isTrustedWechatArticleUrl } from './_wechat/article-service.js';
+import { saveArticles } from './_wechat/save-service.js';
+import { createWechatApi } from './_wechat/wechat-api.js';
+import { readAuthSource } from './_wechat/args.js';
+
+const DOMAIN = 'mp.weixin.qq.com';
+const browserRequired = args => readAuthSource(args) === 'browser';
+
+const MAX_REDIRECTS = 5;
+
+async function readBoundedHtml(response) {
+  const lengthValue = response.headers?.get?.('content-length');
+  if (lengthValue !== null && lengthValue !== undefined && lengthValue !== '') {
+    const length = Number(lengthValue);
+    if (!Number.isSafeInteger(length) || length < 0 || length > MAX_WECHAT_HTML_BYTES) {
+      throw new CommandExecutionError('Article response exceeds the allowed size');
+    }
+  }
+  if (!response.body?.getReader) {
+    if (typeof response.text !== 'function') throw new CommandExecutionError('Article response has no readable body');
+    const text = await response.text();
+    if (new TextEncoder().encode(text).byteLength > MAX_WECHAT_HTML_BYTES) {
+      throw new CommandExecutionError('Article response exceeds the allowed size');
+    }
+    return text;
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!(value instanceof Uint8Array)) throw new CommandExecutionError('Article response returned invalid body data');
+    total += value.byteLength;
+    if (total > MAX_WECHAT_HTML_BYTES) {
+      try { await reader.cancel(); } catch { /* best-effort stream cleanup */ }
+      throw new CommandExecutionError('Article response exceeds the allowed size');
+    }
+    chunks.push(value);
+  }
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+  return new TextDecoder().decode(bytes);
+}
+
+export async function fetchArticleHtml(article, { fetchImpl = fetch, timeoutMs = 30_000 } = {}) {
+  try {
+    if (!isTrustedWechatArticleUrl(article?.url)) throw new CommandExecutionError('Article request rejected an untrusted URL');
+    let current = new URL(article.url).href;
+    const seen = new Set([current]);
+    for (let redirects = 0; ; redirects += 1) {
+      const response = await fetchImpl(current, {
+        signal: AbortSignal.timeout(timeoutMs), redirect: 'manual',
+      });
+      if (response.status >= 300 && response.status < 400) {
+        if (redirects >= MAX_REDIRECTS) throw new CommandExecutionError('Article request exceeded the redirect limit');
+        const location = response.headers?.get?.('location');
+        if (!location) throw new CommandExecutionError('Article redirect was missing a destination');
+        let next;
+        try { next = new URL(location, current).href; } catch { throw new CommandExecutionError('Article redirect was invalid'); }
+        if (!isTrustedWechatArticleUrl(next)) throw new CommandExecutionError('Article redirect was rejected');
+        if (seen.has(next)) throw new CommandExecutionError('Article redirect loop was rejected');
+        seen.add(next);
+        current = next;
+        continue;
+      }
+      if (!response.ok) throw new CommandExecutionError(`Article request failed: HTTP ${response.status}`);
+      return await readBoundedHtml(response);
+    }
+  } catch (error) {
+    if (error instanceof CommandExecutionError) throw error;
+    throw new CommandExecutionError('Article request failed');
+  }
+}
+
+export async function fetchArticleHtmlInBrowser(article, page) {
+  try {
+    if (!isTrustedWechatArticleUrl(article?.url)) {
+      throw new CommandExecutionError('Article browser request rejected an untrusted URL');
+    }
+    if (!page || typeof page.goto !== 'function' || typeof page.evaluate !== 'function') {
+      throw new CommandExecutionError('Article browser fallback is unavailable');
+    }
+    await page.goto(article.url);
+    await page.wait(5);
+    const result = await page.evaluate(({ maxBytes }) => {
+      const html = document.documentElement?.outerHTML ?? '';
+      const pageText = document.body?.innerText?.replace(/\s+/g, ' ').trim() ?? '';
+      const finalUrl = window.location.href;
+      const pathname = window.location.pathname;
+      const accessIssue = pathname.includes('/mp/wappoc_appmsgcaptcha')
+        || (/环境异常/.test(pageText) && /(完成验证后即可继续访问|去验证)/.test(pageText))
+        || /secitptpage\/verify\.html/.test(html)
+        || /id=["']js_verify["']/.test(html)
+        ? 'environment verification required' : '';
+      const byteLength = new TextEncoder().encode(html).byteLength;
+      return {
+        finalUrl,
+        accessIssue,
+        byteLength,
+        tooLarge: byteLength > maxBytes,
+        html: byteLength > maxBytes ? '' : html,
+      };
+    }, { maxBytes: MAX_WECHAT_HTML_BYTES });
+    if (result?.accessIssue) throw new CommandExecutionError('Article browser page requires environment verification');
+    if (!isTrustedWechatArticleUrl(result?.finalUrl)) {
+      throw new CommandExecutionError('Article browser navigation left the trusted article path');
+    }
+    if (result?.tooLarge || !Number.isSafeInteger(result?.byteLength)
+        || result.byteLength < 0 || result.byteLength > MAX_WECHAT_HTML_BYTES) {
+      throw new CommandExecutionError('Article response exceeds the allowed size');
+    }
+    if (typeof result?.html !== 'string' || result.html.length === 0) {
+      throw new CommandExecutionError('Article browser page returned no HTML');
+    }
+    if (new TextEncoder().encode(result.html).byteLength > MAX_WECHAT_HTML_BYTES) {
+      throw new CommandExecutionError('Article response exceeds the allowed size');
+    }
+    return result.html;
+  } catch (error) {
+    if (error instanceof CommandExecutionError) throw error;
+    throw new CommandExecutionError('Article browser request failed');
+  }
+}
+
+export function createArticleHtmlDownloader({
+  authSource,
+  page,
+  nodeFetcher = fetchArticleHtml,
+  browserFetcher = fetchArticleHtmlInBrowser,
+}) {
+  return async article => {
+    try {
+      return await nodeFetcher(article);
+    } catch (error) {
+      if (authSource !== 'browser') throw error;
+      return browserFetcher(article, page);
+    }
+  };
+}
+
+export const saveArticlesCommand = cli({
+  site: 'weixin', name: 'save-articles', access: 'write', domain: DOMAIN,
+  description: 'Download WeChat official-account articles as Markdown files',
+  strategy: Strategy.COOKIE, browser: browserRequired,
+  args: [
+    { name: 'fakeid', positional: true, required: true, help: 'Official-account fakeid returned by weixin accounts' }, { name: 'name', help: 'Official-account name used in Markdown metadata' },
+    { name: 'output', default: './weixin-articles', help: 'Directory for saved Markdown files' }, { name: 'limit', type: 'int', help: 'Maximum number of articles to save' },
+    { name: 'max-pages', type: 'int', help: 'Maximum number of history pages to scan' }, { name: 'auth-source', default: 'browser', choices: ['browser', 'env'], help: 'Credential source: browser session or environment variables' },
+  ],
+  columns: ['title', 'status', 'stage', 'path', 'error', 'url'],
+  func: async (page, args) => {
+    const fakeid = String(args.fakeid ?? '').trim();
+    if (!fakeid) throw new ArgumentError('fakeid is required');
+    const authSource = readAuthSource(args);
+    const credentials = authSource === 'env'
+      ? readEnvironmentCredentials(false) : await resolveBrowserCredentials(page);
+    const { fetchPage } = createWechatApi(credentials);
+    const { articles } = await collectArticles({ fakeid, fetchPage, limit: args.limit, maxPages: args['max-pages'] });
+    const articleHtmlDownloader = createArticleHtmlDownloader({ authSource, page });
+    const rows = await saveArticles({
+      articles, accountName: String(args.name ?? '').trim(),
+      outputDir: args.output ?? './weixin-articles', fetchArticleHtml: articleHtmlDownloader,
+    });
+    return rows.map(row => ({
+      title: row.title, status: row.status, stage: row.stage || null, path: row.saved || null,
+      error: row.error || null, url: row.url,
+    }));
+  },
+});

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;