@jackwener/opencli 1.7.14 → 1.7.15

package/dist/src/help.d.ts

@@ -1,6 +1,24 @@
 import { Command } from 'commander';
 import type { CliCommand } from './registry.js';
 export type StructuredHelpFormat = 'yaml' | 'json';
+export interface ArgSpec {
+    name: string;
+    required?: true;
+    variadic?: true;
+    help?: string;
+    default?: unknown;
+    choices?: string[];
+}
+export interface OptionSpec {
+    name: string;
+    flags: string;
+    help?: string;
+    takes_value?: 'required' | 'optional';
+    required?: true;
+    default?: unknown;
+    choices?: string[];
+    negate?: true;
+}
 export declare function getRequestedHelpFormat(argv?: readonly string[]): StructuredHelpFormat | undefined;
 export declare function renderStructuredHelp(data: unknown, format: StructuredHelpFormat): string;
 export declare function wrapCommaList(items: readonly string[], opts?: {
@@ -29,6 +47,20 @@ export interface RootAdapterGroups {
     sites: readonly string[];
 }
 export declare function formatRootAdapterHelpText(groups: RootAdapterGroups): string;
+export declare function commanderNamespaceHelpData(namespaceRoot: Command, opts?: {
+    globalCommand?: Command;
+    description?: string;
+}): Record<string, unknown>;
+export declare function commanderCommandHelpData(namespaceRoot: Command, command: Command, opts?: {
+    globalCommand?: Command;
+}): Record<string, unknown>;
+export declare function commanderGroupHelpData(namespaceRoot: Command, groupCommand: Command, opts?: {
+    globalCommand?: Command;
+}): Record<string, unknown>;
+export declare function installCommanderNamespaceStructuredHelp(namespaceRoot: Command, opts?: {
+    globalCommand?: Command;
+    description?: string;
+}): void;
 export declare function formatCommandListTerm(cmd: CliCommand): string;
 export declare function rootHelpData(program: Command, groups: RootAdapterGroups): Record<string, unknown>;
 export declare function siteHelpData(site: string, commands: readonly CliCommand[]): Record<string, unknown>;

package/dist/src/help.js

@@ -125,6 +125,151 @@ function compactCommonOption(option) {
         ...('choices' in option ? { choices: option.choices } : {}),
     };
 }
+function compactCommanderArgument(arg) {
+    return {
+        name: arg.name(),
+        ...(arg.required ? { required: true } : {}),
+        ...(arg.variadic ? { variadic: true } : {}),
+        ...(arg.description ? { help: arg.description } : {}),
+        ...(arg.defaultValue !== undefined ? { default: arg.defaultValue } : {}),
+        ...(arg.argChoices?.length ? { choices: [...arg.argChoices] } : {}),
+    };
+}
+function compactCommanderOption(option) {
+    if (option.hidden)
+        return null;
+    return {
+        name: option.attributeName(),
+        flags: option.flags,
+        ...(option.description ? { help: option.description } : {}),
+        ...(option.required ? { takes_value: 'required' } : {}),
+        ...(option.optional ? { takes_value: 'optional' } : {}),
+        ...(option.mandatory ? { required: true } : {}),
+        ...(option.defaultValue !== undefined ? { default: option.defaultValue } : {}),
+        ...(option.argChoices?.length ? { choices: [...option.argChoices] } : {}),
+        ...(option.negate ? { negate: true } : {}),
+    };
+}
+function compactCommanderOptions(options) {
+    return options
+        .map(compactCommanderOption)
+        .filter((option) => option !== null);
+}
+function commanderPath(command) {
+    const parts = [];
+    let current = command;
+    while (current) {
+        const name = current.name();
+        if (name)
+            parts.push(name);
+        current = current.parent;
+    }
+    return parts.reverse();
+}
+function commandPathFromRoot(namespaceRoot, command) {
+    const rootPath = commanderPath(namespaceRoot);
+    const commandPath = commanderPath(command);
+    return commandPath.slice(rootPath.length);
+}
+function collectLeafCommands(command) {
+    if (command.commands.length === 0)
+        return [command];
+    return command.commands.flatMap(child => collectLeafCommands(child));
+}
+function collectDescendantCommands(command) {
+    return command.commands.flatMap(child => [child, ...collectDescendantCommands(child)]);
+}
+function formatCommanderPositionals(args) {
+    return args
+        .map(arg => {
+        const name = `${arg.name()}${arg.variadic ? '...' : ''}`;
+        return arg.required ? `<${name}>` : `[${name}]`;
+    })
+        .join(' ');
+}
+function formatCommanderUsage(command, opts = {}) {
+    const path = commanderPath(command).join(' ');
+    const positionalText = formatCommanderPositionals(command.registeredArguments);
+    const hasOptions = compactCommanderOptions(command.options).length > 0
+        || (opts.namespaceRoot ? compactCommanderOptions(opts.namespaceRoot.options).length > 0 : false)
+        || (opts.globalCommand ? compactCommanderOptions(opts.globalCommand.options).length > 0 : false);
+    const optionText = hasOptions ? ' [options]' : '';
+    return `${path}${positionalText ? ` ${positionalText}` : ''}${optionText}`;
+}
+function compactCommanderCommand(namespaceRoot, command, opts = {}) {
+    const relativePath = commandPathFromRoot(namespaceRoot, command);
+    return {
+        name: relativePath.join(' '),
+        command: commanderPath(command).join(' '),
+        usage: formatCommanderUsage(command, { namespaceRoot, globalCommand: opts.globalCommand }),
+        description: command.description(),
+        ...(command.aliases().length ? { aliases: command.aliases() } : {}),
+        positionals: command.registeredArguments.map(compactCommanderArgument),
+        command_options: compactCommanderOptions(command.options),
+    };
+}
+export function commanderNamespaceHelpData(namespaceRoot, opts = {}) {
+    const leaves = collectLeafCommands(namespaceRoot)
+        .filter(command => command !== namespaceRoot)
+        .sort((a, b) => commandPathFromRoot(namespaceRoot, a).join(' ').localeCompare(commandPathFromRoot(namespaceRoot, b).join(' ')));
+    return {
+        namespace: namespaceRoot.name(),
+        command: commanderPath(namespaceRoot).join(' '),
+        usage: `${commanderPath(namespaceRoot).join(' ')} <command> [args] [options]`,
+        description: opts.description ?? namespaceRoot.description(),
+        command_count: leaves.length,
+        commands: leaves.map(command => compactCommanderCommand(namespaceRoot, command, opts)),
+        namespace_options: compactCommanderOptions(namespaceRoot.options),
+        ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
+        structured_help: {
+            formats: ['yaml', 'json'],
+            usage: `${commanderPath(namespaceRoot).join(' ')} --help -f yaml`,
+        },
+    };
+}
+export function commanderCommandHelpData(namespaceRoot, command, opts = {}) {
+    return {
+        namespace: namespaceRoot.name(),
+        ...compactCommanderCommand(namespaceRoot, command, opts),
+        namespace_options: compactCommanderOptions(namespaceRoot.options),
+        ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
+        structured_help: {
+            formats: ['yaml', 'json'],
+            usage: `${commanderPath(command).join(' ')} --help -f yaml`,
+        },
+    };
+}
+export function commanderGroupHelpData(namespaceRoot, groupCommand, opts = {}) {
+    const leaves = collectLeafCommands(groupCommand)
+        .filter(command => command !== groupCommand)
+        .sort((a, b) => commandPathFromRoot(namespaceRoot, a).join(' ').localeCompare(commandPathFromRoot(namespaceRoot, b).join(' ')));
+    return {
+        namespace: namespaceRoot.name(),
+        group: commandPathFromRoot(namespaceRoot, groupCommand).join(' '),
+        command: commanderPath(groupCommand).join(' '),
+        usage: `${commanderPath(groupCommand).join(' ')} <command> [args] [options]`,
+        description: groupCommand.description(),
+        command_count: leaves.length,
+        commands: leaves.map(command => compactCommanderCommand(namespaceRoot, command, opts)),
+        namespace_options: compactCommanderOptions(namespaceRoot.options),
+        ...(opts.globalCommand ? { global_options: compactCommanderOptions(opts.globalCommand.options) } : {}),
+        structured_help: {
+            formats: ['yaml', 'json'],
+            usage: `${commanderPath(groupCommand).join(' ')} --help -f yaml`,
+        },
+    };
+}
+export function installCommanderNamespaceStructuredHelp(namespaceRoot, opts = {}) {
+    installStructuredHelp(namespaceRoot, () => commanderNamespaceHelpData(namespaceRoot, opts));
+    for (const command of collectDescendantCommands(namespaceRoot)) {
+        if (command.commands.length > 0) {
+            installStructuredHelp(command, () => commanderGroupHelpData(namespaceRoot, command, opts));
+        }
+        else {
+            installStructuredHelp(command, () => commanderCommandHelpData(namespaceRoot, command, opts));
+        }
+    }
+}
 function positionals(cmd) {
     return cmd.args.filter(arg => arg.positional);
 }

package/dist/src/types.d.ts

@@ -20,6 +20,8 @@ export interface SnapshotOptions {
     raw?: boolean;
     viewportExpand?: number;
     maxTextLength?: number;
+    /** Observation backend. `dom` is the stable default; `ax` is an opt-in prototype. */
+    source?: 'dom' | 'ax';
 }
 export interface WaitOptions {
     text?: string;
@@ -27,10 +29,25 @@ export interface WaitOptions {
     time?: number;
     timeout?: number;
 }
+export interface BrowserDownloadWaitResult {
+    downloaded: boolean;
+    id?: number;
+    filename?: string;
+    url?: string;
+    finalUrl?: string;
+    mime?: string;
+    totalBytes?: number;
+    state?: string;
+    danger?: string;
+    error?: string;
+    elapsedMs: number;
+}
 export interface ScreenshotOptions {
     format?: 'png' | 'jpeg';
     quality?: number;
     fullPage?: boolean;
+    /** Overlay current browser-state refs on visible interactive elements. */
+    annotate?: boolean;
     /** Override viewport width in CSS pixels for the screenshot only (cleared after). */
     width?: number;
     /** Override viewport height in CSS pixels for the screenshot only (ignored when fullPage). */
@@ -84,6 +101,69 @@ export interface IPage {
         matches_n: number;
         match_level: 'exact' | 'stable' | 'reidentified';
     }>;
+    dblClick?(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    hover?(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    focus?(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        focused: boolean;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    setChecked?(ref: string, checked: boolean, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        checked: boolean;
+        changed: boolean;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+        kind?: string;
+    }>;
+    uploadFiles?(ref: string, files: string[], opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        uploaded: boolean;
+        files: number;
+        file_names: string[];
+        target: string;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+        multiple?: boolean;
+        accept?: string;
+    }>;
+    drag?(source: string, target: string, opts?: {
+        from?: {
+            nth?: number;
+            firstOnMulti?: boolean;
+        };
+        to?: {
+            nth?: number;
+            firstOnMulti?: boolean;
+        };
+    }): Promise<{
+        dragged: boolean;
+        source: string;
+        target: string;
+        source_matches_n: number;
+        target_matches_n: number;
+        source_match_level: 'exact' | 'stable' | 'reidentified';
+        target_match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
     typeText(ref: string, text: string, opts?: {
         nth?: number;
         firstOnMulti?: boolean;
@@ -111,6 +191,7 @@ export interface IPage {
     }): Promise<any>;
     getFormState(): Promise<any>;
     wait(options: number | WaitOptions): Promise<void>;
+    waitForDownload?(pattern?: string, timeoutMs?: number): Promise<BrowserDownloadWaitResult>;
     tabs(): Promise<any>;
     closeTab?(target?: number | string): Promise<void>;
     newTab?(url?: string): Promise<string | undefined>;
@@ -126,6 +207,7 @@ export interface IPage {
     getInterceptedRequests(): Promise<any[]>;
     waitForCapture(timeout?: number): Promise<void>;
     screenshot(options?: ScreenshotOptions): Promise<string>;
+    annotatedScreenshot?(options?: ScreenshotOptions): Promise<string>;
     startNetworkCapture?(pattern?: string): Promise<boolean>;
     readNetworkCapture?(): Promise<unknown[]>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.7.14",
+  "version": "1.7.15",
   "publishConfig": {
     "access": "public"
   },

package/scripts/typed-error-lint-baseline.json

@@ -615,11 +615,19 @@
     "text": "rn_need: String(Math.min(Math.max(limit + 10, 10), 30)),",
     "occurrence": 0
   },
+  {
+    "rule": "silent-clamp",
+    "command": "twitter/bookmark-folder",
+    "file": "clis/twitter/bookmark-folder.js",
+    "line": 161,
+    "text": "const fetchCount = Math.min(100, limit - allTweets.length + 10);",
+    "occurrence": 0
+  },
   {
     "rule": "silent-clamp",
     "command": "twitter/bookmarks",
     "file": "clis/twitter/bookmarks.js",
-    "line": 155,
+    "line": 156,
     "text": "const fetchCount = Math.min(100, limit - allTweets.length + 10);",
     "occurrence": 0
   },
@@ -627,7 +635,7 @@
     "rule": "silent-clamp",
     "command": "twitter/following",
     "file": "clis/twitter/following.js",
-    "line": 209,
+    "line": 215,
     "text": "const fetchCount = Math.min(50, limit - allUsers.length + 10);",
     "occurrence": 0
   },
@@ -635,7 +643,7 @@
     "rule": "silent-clamp",
     "command": "twitter/likes",
     "file": "clis/twitter/likes.js",
-    "line": 194,
+    "line": 195,
     "text": "const fetchCount = Math.min(100, limit - allTweets.length + 10);",
     "occurrence": 0
   },
@@ -643,7 +651,7 @@
     "rule": "silent-clamp",
     "command": "twitter/list-tweets",
     "file": "clis/twitter/list-tweets.js",
-    "line": 167,
+    "line": 168,
     "text": "const fetchCount = Math.min(100, limit - allTweets.length + 10);",
     "occurrence": 0
   },
@@ -651,7 +659,7 @@
     "rule": "silent-clamp",
     "command": "twitter/timeline",
     "file": "clis/twitter/timeline.js",
-    "line": 181,
+    "line": 182,
     "text": "const fetchCount = Math.min(40, limit - allTweets.length + 5); // over-fetch slightly for promoted filtering",
     "occurrence": 0
   },
@@ -659,7 +667,7 @@
     "rule": "silent-clamp",
     "command": "twitter/tweets",
     "file": "clis/twitter/tweets.js",
-    "line": 193,
+    "line": 194,
     "text": "const fetchCount = Math.min(100, limit - all.length + 10);",
     "occurrence": 0
   },
@@ -667,7 +675,7 @@
     "rule": "silent-clamp",
     "command": "twitter/tweets",
     "file": "clis/twitter/tweets.js",
-    "line": 158,
+    "line": 159,
     "text": "const limit = Math.max(1, Math.min(200, kwargs.limit || 20));",
     "occurrence": 0
   },
@@ -1203,7 +1211,7 @@
     "rule": "silent-sentinel",
     "command": "twitter/article",
     "file": "clis/twitter/article.js",
-    "line": 104,
+    "line": 105,
     "text": "const screenName = user?.legacy?.screen_name || user?.core?.screen_name || 'unknown';",
     "occurrence": 0
   },
@@ -1279,19 +1287,11 @@
     "text": "const user = lines[0] || 'Unknown';",
     "occurrence": 0
   },
-  {
-    "rule": "silent-sentinel",
-    "command": "twitter/reply",
-    "file": "clis/twitter/reply.js",
-    "line": 68,
-    "text": "throw new Error(`Unsupported remote image format \"${normalizedContentType || 'unknown'}\". ` +",
-    "occurrence": 0
-  },
   {
     "rule": "silent-sentinel",
     "command": "twitter/search",
     "file": "clis/twitter/search.js",
-    "line": 156,
+    "line": 296,
     "text": "author: tweetUser?.core?.screen_name || tweetUser?.legacy?.screen_name || 'unknown',",
     "occurrence": 0
   },
@@ -1411,7 +1411,7 @@
     "rule": "silent-sentinel",
     "command": "xiaohongshu/publish",
     "file": "clis/xiaohongshu/publish.js",
-    "line": 516,
+    "line": 529,
     "text": "throw new Error(`Image injection failed: ${upload.error ?? 'unknown'}. ` +",
     "occurrence": 0
   },