@sovovs/bycli 2.0.0 → 2.1.1

package/dist/src/registry.d.ts

@@ -20,7 +20,11 @@ export interface Arg {
     choices?: string[];
 }
 export type CommandArgs = Record<string, any>;
+export type BrowserRequirementResolver = (args: CommandArgs) => boolean;
+export type BrowserDeclaration = boolean | BrowserRequirementResolver;
+export type NormalizedBrowserRequirement = boolean | 'conditional';
 export type BrowserCommandFunc = (page: IPage, kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
+export type ConditionalBrowserCommandFunc = (page: IPage | null, kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
 export type NonBrowserCommandFunc = (kwargs: CommandArgs, debug?: boolean) => Promise<unknown>;
 export type CommandAccess = 'read' | 'write';
 export type SiteSessionMode = 'ephemeral' | 'persistent';
@@ -28,8 +32,9 @@ export type SiteSessionMode = 'ephemeral' | 'persistent';
  * 所有已注册 adapter command 的共享元数据和运行选项。
  *
  * 这里故意不包含 `browser` 和 `func` 这类执行形态字段，因为浏览器命令和
- * 非浏览器命令的执行签名不同。`BrowserCliCommand` 和 `NonBrowserCliCommand`
- * 会在 normalize 之后扩展这个共同底座，形成最终可执行的命令类型。
+ * 非浏览器命令、条件浏览器命令的执行签名不同。`BrowserCliCommand`、
+ * `NonBrowserCliCommand` 和 `ConditionalBrowserCliCommand` 会在 normalize 之后
+ * 扩展这个共同底座，形成最终可执行的命令类型。
  */
 interface BaseCliCommand {
     /** 站点或命名空间名称，对应命令中的 `<site>`，例如 `devto`、`brave`。 */
@@ -81,8 +86,8 @@ interface BaseCliCommand {
     defaultFormat?: 'table' | 'plain' | 'json' | 'yaml' | 'yml' | 'md' | 'markdown' | 'csv';
 }
 export interface BrowserCliCommand extends BaseCliCommand {
-    /** Browser commands receive an IPage. Omitted means true after normalization. */
-    browser?: true;
+    /** Browser commands receive an IPage. */
+    browser: true;
     func?: BrowserCommandFunc;
 }
 export interface NonBrowserCliCommand extends BaseCliCommand {
@@ -90,25 +95,50 @@ export interface NonBrowserCliCommand extends BaseCliCommand {
     browser: false;
     func?: NonBrowserCommandFunc;
 }
-export type CliCommand = BrowserCliCommand | NonBrowserCliCommand;
+export interface ConditionalBrowserCliCommand extends BaseCliCommand {
+    /** Browser use is resolved from the final command arguments at execution time. */
+    browser: 'conditional';
+    requiresBrowser: BrowserRequirementResolver;
+    func?: ConditionalBrowserCommandFunc;
+}
+export type CliCommand = BrowserCliCommand | NonBrowserCliCommand | ConditionalBrowserCliCommand;
 /**
  * `cli()` 注册 adapter 时使用的内部预归一化命令形态。
  *
  * adapter 作者传入的是 `CliOptions`，它的 TypeScript union 会保证公开调用点足够精确。
- * registry 内部会先把这些选项复制成这个更宽松的形态，再交给 `normalizeCommand()`
- * 根据 `strategy` 推导 `browser`、`navigateBefore` 等运行时意图，最后存成具体的
- * `CliCommand`。
+ * registry 内部会先把这些选项复制成对应的预归一化分支，再交给
+ * `normalizeCommand()` 根据 `strategy` 推导 `browser`、`navigateBefore` 等运行时意图，
+ * 最后存成具体的 `CliCommand`。
  */
-type RawCliCommand = BaseCliCommand & {
-    /** 预归一化阶段的浏览器需求标记；可省略，之后会由 strategy 推导。 */
-    browser?: boolean;
-    /** 预归一化阶段的执行函数；可能是浏览器签名，也可能是非浏览器签名。 */
-    func?: BrowserCommandFunc | NonBrowserCommandFunc;
+type RawCliCommandBase = Omit<BaseCliCommand, 'strategy'>;
+type RawBrowserCliCommand = RawCliCommandBase & {
+    func?: BrowserCommandFunc;
+} & ({
+    browser: true;
+    strategy?: Strategy;
+} | {
+    browser?: true;
+    strategy?: BrowserStrategy;
+});
+type RawNonBrowserCliCommand = RawCliCommandBase & {
+    func?: NonBrowserCommandFunc;
+} & ({
+    browser: false;
+    strategy?: Strategy;
+} | {
+    browser?: false;
+    strategy: Strategy.PUBLIC | Strategy.LOCAL;
+});
+type RawConditionalBrowserCliCommand = RawCliCommandBase & {
+    browser: BrowserRequirementResolver;
+    strategy?: Strategy;
+    func?: ConditionalBrowserCommandFunc;
 };
 /** Internal extension for lazy-loaded TS modules (not exposed in public API) */
 export type InternalCliCommand = CliCommand & {
     _lazy?: boolean;
     _modulePath?: string;
+    _hydrateBeforeBrowserRouting?: boolean;
 };
 type RequiredCliOptions = {
     site: string;
@@ -131,13 +161,25 @@ type NonBrowserCliOptions = Partial<Omit<NonBrowserCliCommand, 'args' | 'descrip
     strategy: Strategy.PUBLIC | Strategy.LOCAL;
     browser?: false;
 });
-export type CliOptions = BrowserCliOptions | NonBrowserCliOptions;
+type ConditionalBrowserCliOptions = Partial<Omit<ConditionalBrowserCliCommand, 'args' | 'description' | 'browser' | 'requiresBrowser'>> & RequiredCliOptions & {
+    browser: BrowserRequirementResolver;
+};
+export type CliOptions = BrowserCliOptions | NonBrowserCliOptions | ConditionalBrowserCliOptions;
 declare global {
     var __bycli_registry__: Map<string, CliCommand> | undefined;
 }
-export declare function cli(opts: CliOptions): CliCommand;
+export declare function cli(opts: ConditionalBrowserCliOptions): ConditionalBrowserCliCommand;
+export declare function cli(opts: NonBrowserCliOptions): NonBrowserCliCommand;
+export declare function cli(opts: BrowserCliOptions): BrowserCliCommand;
 export declare function getRegistry(): Map<string, CliCommand>;
 export declare function fullName(cmd: Pick<BaseCliCommand, 'site' | 'name'>): string;
 export declare function strategyLabel(cmd: CliCommand): string;
-export declare function registerCommand(cmd: RawCliCommand): void;
+/** Whether a command may use browser-backed execution for some invocation. */
+export declare function hasBrowserCapability(cmd: CliCommand): boolean;
+/** Stable human-readable label for the normalized browser requirement. */
+export declare function browserRequirementLabel(cmd: CliCommand): 'yes' | 'no' | 'conditional';
+export declare function registerCommand(cmd: RawConditionalBrowserCliCommand): void;
+export declare function registerCommand(cmd: RawNonBrowserCliCommand): void;
+export declare function registerCommand(cmd: RawBrowserCliCommand): void;
+export declare function registerCommand(cmd: CliCommand): void;
 export {};

package/dist/src/registry.js

@@ -1,6 +1,7 @@
 /**
  * Core registry: Strategy enum, Arg/CliCommand interfaces, cli() registration.
  */
+import { pruneRegistryMutationKey, recordRegistryMutation, registryMutationKeys, withRegistryMutationGroup, } from './registry-transaction.js';
 export var Strategy;
 (function (Strategy) {
     Strategy["PUBLIC"] = "public";
@@ -9,9 +10,77 @@ export var Strategy;
     Strategy["INTERCEPT"] = "intercept";
     Strategy["UI"] = "ui";
 })(Strategy || (Strategy = {}));
-const _registry = globalThis.__bycli_registry__ ??= new Map();
+const TRACKED_REGISTRY_MARKER = Symbol.for('@sovovs/bycli/tracked-registry');
+function isTrackedRegistry(registry) {
+    return registry !== undefined
+        && registry[TRACKED_REGISTRY_MARKER] === true;
+}
+function instrumentRegistry(registry) {
+    if (isTrackedRegistry(registry))
+        return registry;
+    Object.defineProperties(registry, {
+        set: {
+            value(key, value) {
+                const before = { present: this.has(key), value: this.get(key) };
+                recordRegistryMutation(key, before, { present: true, value });
+                return Map.prototype.set.call(this, key, value);
+            },
+        },
+        delete: {
+            value(key) {
+                const before = { present: this.has(key), value: this.get(key) };
+                recordRegistryMutation(key, before, { present: false, value: undefined });
+                const deleted = Map.prototype.delete.call(this, key);
+                pruneRegistryMutationKey(key, this);
+                return deleted;
+            },
+        },
+        clear: {
+            value() {
+                const keys = new Set([...this.keys(), ...registryMutationKeys()]);
+                if (keys.size === 0)
+                    return;
+                withRegistryMutationGroup(() => {
+                    for (const key of keys) {
+                        const present = this.has(key);
+                        recordRegistryMutation(key, { present, value: present ? this.get(key) : undefined }, { present: false, value: undefined });
+                    }
+                    Map.prototype.clear.call(this);
+                    for (const key of keys)
+                        pruneRegistryMutationKey(key, this);
+                });
+            },
+        },
+        [TRACKED_REGISTRY_MARKER]: { value: true },
+    });
+    return registry;
+}
+const existingRegistry = globalThis.__bycli_registry__ ?? new Map();
+const _registry = instrumentRegistry(existingRegistry);
+globalThis.__bycli_registry__ = _registry;
 export function cli(opts) {
-    const cmd = {
+    const base = rawCommandBase(opts);
+    let cmd;
+    if (typeof opts.browser === 'function') {
+        cmd = { ...base, strategy: opts.strategy, browser: opts.browser, func: opts.func };
+    }
+    else if (opts.browser === false) {
+        cmd = { ...base, strategy: opts.strategy, browser: false, func: opts.func };
+    }
+    else if (opts.browser === true) {
+        cmd = { ...base, strategy: opts.strategy, browser: true, func: opts.func };
+    }
+    else if (isImplicitNonBrowserOptions(opts)) {
+        cmd = { ...base, strategy: opts.strategy, browser: opts.browser, func: opts.func };
+    }
+    else {
+        cmd = { ...base, strategy: opts.strategy, browser: opts.browser, func: opts.func };
+    }
+    registerCommandInput(cmd);
+    return _registry.get(fullName(cmd));
+}
+function rawCommandBase(opts) {
+    return {
         site: opts.site,
         name: opts.name,
         aliases: opts.aliases,
@@ -19,11 +88,8 @@ export function cli(opts) {
         access: opts.access,
         example: opts.example,
         domain: opts.domain,
-        strategy: opts.strategy,
-        browser: opts.browser,
         args: opts.args ?? [],
         columns: opts.columns,
-        func: opts.func,
         pipeline: opts.pipeline,
         footerExtra: opts.footerExtra,
         validateArgs: opts.validateArgs,
@@ -31,8 +97,10 @@ export function cli(opts) {
         siteSession: opts.siteSession,
         defaultFormat: opts.defaultFormat,
     };
-    registerCommand(cmd);
-    return _registry.get(fullName(cmd));
+}
+function isImplicitNonBrowserOptions(opts) {
+    return opts.browser === undefined
+        && (opts.strategy === Strategy.PUBLIC || opts.strategy === Strategy.LOCAL);
 }
 export function getRegistry() {
     return _registry;
@@ -43,6 +111,14 @@ export function fullName(cmd) {
 export function strategyLabel(cmd) {
     return cmd.strategy ?? Strategy.PUBLIC;
 }
+/** Whether a command may use browser-backed execution for some invocation. */
+export function hasBrowserCapability(cmd) {
+    return cmd.browser !== false;
+}
+/** Stable human-readable label for the normalized browser requirement. */
+export function browserRequirementLabel(cmd) {
+    return cmd.browser === 'conditional' ? 'conditional' : cmd.browser ? 'yes' : 'no';
+}
 /**
  * Normalize a command's runtime fields. This is the single place where
  * `strategy` is decoded into the concrete fields that the execution path
@@ -57,10 +133,8 @@ export function strategyLabel(cmd) {
  *   2. Derived from strategy + domain (the defaults below)
  */
 function normalizeCommand(cmd) {
-    assertCommandAccess(cmd);
-    assertSiteSession(cmd);
-    const strategy = cmd.strategy ?? (cmd.browser === false ? Strategy.PUBLIC : Strategy.COOKIE);
-    const browser = cmd.browser ?? (strategy !== Strategy.PUBLIC && strategy !== Strategy.LOCAL);
+    const declaredBrowser = cmd.browser;
+    const strategy = cmd.strategy ?? (declaredBrowser === false ? Strategy.PUBLIC : Strategy.COOKIE);
     let navigateBefore = cmd.navigateBefore;
     if (navigateBefore === undefined) {
         if (strategy === Strategy.COOKIE && cmd.domain) {
@@ -73,9 +147,34 @@ function normalizeCommand(cmd) {
             navigateBefore = true;
         }
     }
-    return browser
-        ? { ...cmd, strategy, browser: true, navigateBefore }
-        : { ...cmd, strategy, browser: false, navigateBefore };
+    if (typeof cmd.browser === 'function') {
+        const normalized = {
+            ...cmd,
+            strategy,
+            browser: 'conditional',
+            requiresBrowser: cmd.browser,
+            navigateBefore,
+        };
+        return normalized;
+    }
+    if (cmd.browser === false) {
+        const normalized = { ...cmd, strategy, browser: false, navigateBefore };
+        return normalized;
+    }
+    if (cmd.browser === true) {
+        const normalized = { ...cmd, strategy, browser: true, navigateBefore };
+        return normalized;
+    }
+    if (isImplicitNonBrowserCommand(cmd)) {
+        const normalized = { ...cmd, strategy, browser: false, navigateBefore };
+        return normalized;
+    }
+    const normalized = { ...cmd, strategy, browser: true, navigateBefore };
+    return normalized;
+}
+function isImplicitNonBrowserCommand(cmd) {
+    return cmd.browser === undefined
+        && (cmd.strategy === Strategy.PUBLIC || cmd.strategy === Strategy.LOCAL);
 }
 function assertCommandAccess(cmd) {
     if (cmd.access === 'read' || cmd.access === 'write')
@@ -92,7 +191,24 @@ function assertSiteSession(cmd) {
     }
 }
 export function registerCommand(cmd) {
-    const normalized = normalizeCommand(cmd);
+    registerCommandInput(cmd);
+}
+function registerCommandInput(cmd) {
+    withRegistryMutationGroup(() => {
+        assertCommandAccess(cmd);
+        assertSiteSession(cmd);
+        if (cmd.browser === 'conditional') {
+            if (typeof cmd.requiresBrowser !== 'function') {
+                const key = `${cmd.site}/${cmd.name}`;
+                throw new Error(`Command ${key} requiresBrowser must be a function`);
+            }
+            insertNormalizedCommand(cmd);
+            return;
+        }
+        insertNormalizedCommand(normalizeCommand(cmd));
+    });
+}
+function insertNormalizedCommand(normalized) {
     const canonicalKey = fullName(normalized);
     const existing = _registry.get(canonicalKey);
     if (existing?.aliases) {

package/dist/src/serialization.d.ts

@@ -26,7 +26,7 @@ export declare function serializeCommand(cmd: CliCommand): {
     description: string;
     access: import("./registry.js").CommandAccess;
     strategy: string;
-    browser: boolean;
+    browser: boolean | "conditional";
     args: SerializedArg[];
     columns: string[];
     domain: string | null;

package/dist/src/serialization.js

@@ -4,7 +4,7 @@
  * Used by the `list` command, Commander --help, and build-manifest.
  * Separated from registry.ts to keep the registry focused on types + registration.
  */
-import { fullName, strategyLabel } from './registry.js';
+import { browserRequirementLabel, fullName, strategyLabel } from './registry.js';
 /** Stable arg schema — every field is always present (no sparse objects). */
 export function serializeArg(a) {
     return {
@@ -28,7 +28,7 @@ export function serializeCommand(cmd) {
         description: cmd.description,
         access: cmd.access,
         strategy: strategyLabel(cmd),
-        browser: !!cmd.browser,
+        browser: cmd.browser,
         args: cmd.args.map(serializeArg),
         columns: cmd.columns ?? [],
         domain: cmd.domain ?? null,
@@ -87,7 +87,7 @@ export function formatRegistryHelpText(cmd) {
     }
     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/types.d.ts

@@ -207,6 +207,8 @@ export interface IPage {
      * Useful for rich editors that ignore synthetic DOM value/text mutations.
      */
     insertText?(text: string): Promise<void>;
+    /** Focus the browser window containing the active page for interactive login. */
+    focusWindow?(): Promise<void>;
     closeWindow?(): Promise<void>;
     /** Returns the current page URL, or null if unavailable. */
     getCurrentUrl?(): Promise<string | null>;

package/dist/src/weixin-built-in-docs.test.d.ts

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

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@sovovs/bycli",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "publishConfig": {
     "access": "public"
   },
   "description": "Make any website or Electron App your CLI. AI-powered.",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.6.0"
   },
   "type": "module",
   "workspaces": [
@@ -32,6 +32,7 @@
     "./download/article-download": "./dist/src/download/article-download.js",
     "./download/media-download": "./dist/src/download/media-download.js",
     "./download/progress": "./dist/src/download/progress.js",
+    "./download/wechat-article": "./dist/src/download/wechat-article.js",
     "./pipeline": "./dist/src/pipeline/index.js"
   },
   "files": [
@@ -66,6 +67,7 @@
     "advise:listing-id-pairing": "node scripts/check-listing-id-pairing.mjs",
     "check:silent-column-drop": "node scripts/check-silent-column-drop.mjs",
     "check:typed-error-lint": "node scripts/check-typed-error-lint.mjs",
+    "check:package-install": "node scripts/check-package-install.mjs",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs"
@@ -87,17 +89,19 @@
   },
   "dependencies": {
     "@mozilla/readability": "^0.6.0",
+    "@sovovs/bycli-recorder-core": "^0.1.0",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",
     "js-yaml": "^4.1.0",
+    "parse5": "^7.3.0",
     "turndown": "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2",
     "undici": "^6.25.0",
     "ws": "^8.18.0"
   },
   "devDependencies": {
-    "@types/jsdom": "^27.0.0",
     "@types/js-yaml": "^4.0.9",
+    "@types/jsdom": "^27.0.0",
     "@types/node": "^25.5.2",
     "@types/turndown": "^5.0.6",
     "@types/ws": "^8.5.13",

package/scripts/check-package-install.mjs

@@ -0,0 +1,71 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const temp = mkdtempSync(join(tmpdir(), 'bycli-package-install-'));
+const artifacts = join(temp, 'artifacts');
+const project = join(temp, 'project');
+const mainStage = join(temp, 'main-package');
+
+function run(command, args, cwd = root) {
+  return execFileSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function pack(cwd) {
+  const result = JSON.parse(run('npm', [
+    'pack', '--json', '--ignore-scripts', '--pack-destination', artifacts,
+  ], cwd));
+  assert.equal(result.length, 1);
+  return {
+    tarball: join(artifacts, result[0].filename),
+    files: new Set(result[0].files.map(({ path }) => path)),
+  };
+}
+
+try {
+  mkdirSync(artifacts, { recursive: true });
+  mkdirSync(project, { recursive: true });
+  mkdirSync(mainStage, { recursive: true });
+  for (const path of [
+    'package.json', 'dist', 'clis', 'cli-manifest.json', 'scripts',
+    'README.md', 'README.zh-CN.md', 'LICENSE', 'NOTICE',
+  ]) {
+    cpSync(join(root, path), join(mainStage, path), { recursive: true });
+  }
+
+  const core = pack(join(root, 'packages/recorder-core'));
+  const main = pack(mainStage);
+
+  for (const file of ['dist/index.js', 'dist/index.d.ts', 'README.md', 'LICENSE']) {
+    assert(core.files.has(file), `recorder-core tarball is missing ${file}`);
+  }
+  assert(![...core.files].some((file) => file.startsWith('src/')), 'recorder-core tarball includes src/');
+
+  writeFileSync(join(project, 'package.json'), JSON.stringify({ private: true, type: 'module' }));
+  run('npm', [
+    'install', '--ignore-scripts', '--no-audit', '--no-fund', core.tarball, main.tarball,
+  ], project);
+
+  const mainManifest = JSON.parse(readFileSync(join(
+    project, 'node_modules/@sovovs/bycli/package.json',
+  ), 'utf8'));
+  assert.equal(mainManifest.dependencies?.['@sovovs/bycli-recorder-core'], '^0.1.0');
+
+  const coreDirectory = join(project, 'node_modules/@sovovs/bycli-recorder-core');
+  const recorderEntry = join(
+    project, 'node_modules/@sovovs/bycli/dist/src/browser/analyze.js',
+  );
+  await import(pathToFileURL(recorderEntry).href);
+  await import(pathToFileURL(join(coreDirectory, 'dist/index.js')).href);
+  console.log('package install smoke test passed');
+} finally {
+  rmSync(temp, { recursive: true, force: true });
+}