weapp-ide-cli 5.0.3 → 5.1.0

package/dist/index.d.ts

@@ -1,5 +1,151 @@
+import * as miniprogram_automator_out_MiniProgram from 'miniprogram-automator/out/MiniProgram';
+import { Buffer } from 'node:buffer';
 import * as execa from 'execa';
 
+interface AutomatorOptions {
+    projectPath: string;
+    timeout?: number;
+}
+/**
+ * @description Check if error is a DevTools HTTP port error
+ */
+declare function isDevtoolsHttpPortError(error: unknown): boolean;
+/**
+ * @description Check if error is a login required error
+ */
+declare function isAutomatorLoginError(error: unknown): boolean;
+/**
+ * @description Format login error for display
+ */
+declare function formatAutomatorLoginError(error: unknown): string;
+/**
+ * @description Launch automator with default options
+ */
+declare function launchAutomator(options: AutomatorOptions): Promise<miniprogram_automator_out_MiniProgram.default>;
+
+interface ParsedAutomatorArgs {
+    projectPath: string;
+    timeout?: number;
+    json: boolean;
+    positionals: string[];
+}
+/**
+ * @description 解析 automator 命令通用参数与位置参数。
+ */
+declare function parseAutomatorArgs(argv: readonly string[]): ParsedAutomatorArgs;
+/**
+ * @description 读取选项值，支持 --option value 与 --option=value。
+ */
+declare function readOptionValue(argv: readonly string[], optionName: string): string | undefined;
+/**
+ * @description 删除参数中的指定选项（同时支持 --opt value 与 --opt=value）。
+ */
+declare function removeOption(argv: readonly string[], optionName: string): string[];
+
+interface AutomatorSessionOptions {
+    projectPath: string;
+    timeout?: number;
+}
+interface MiniProgramElement {
+    tap: () => Promise<void>;
+    input?: (value: string) => Promise<void>;
+}
+interface MiniProgramPage {
+    path?: string;
+    query?: Record<string, unknown>;
+    data: (path?: string) => Promise<unknown>;
+    $: (selector: string) => Promise<MiniProgramElement | null>;
+}
+interface MiniProgramLike {
+    navigateTo: (url: string) => Promise<unknown>;
+    redirectTo: (url: string) => Promise<unknown>;
+    navigateBack: () => Promise<unknown>;
+    reLaunch: (url: string) => Promise<unknown>;
+    switchTab: (url: string) => Promise<unknown>;
+    pageStack: () => Promise<MiniProgramPage[]>;
+    currentPage: () => Promise<MiniProgramPage>;
+    systemInfo: () => Promise<unknown>;
+    pageScrollTo: (scrollTop: number) => Promise<unknown>;
+    stopAudits: () => Promise<unknown>;
+    screenshot: () => Promise<string | Buffer>;
+    remote: (enable?: boolean) => Promise<unknown>;
+    close: () => Promise<void>;
+}
+/**
+ * @description 统一管理 automator 会话生命周期与常见连接错误提示。
+ */
+declare function withMiniProgram<T>(options: AutomatorSessionOptions, runner: (miniProgram: MiniProgramLike) => Promise<T>): Promise<T>;
+
+declare const WECHAT_CLI_COMMAND_NAMES: readonly ["open", "login", "islogin", "preview", "auto-preview", "upload", "build-npm", "auto", "auto-replay", "reset-fileutils", "close", "quit", "cache", "engine", "open-other", "build-ipa", "build-apk", "cloud"];
+declare const MINIDEV_NAMESPACE_COMMAND_NAMES: readonly ["alipay", "ali", "minidev"];
+declare const CONFIG_COMMAND_NAME: "config";
+declare const WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES: string[];
+/**
+ * @description 判断是否为 weapp-ide-cli 支持的顶层命令。
+ */
+declare function isWeappIdeTopLevelCommand(command: string | undefined): boolean;
+
+interface AutomatorCommandOptions extends AutomatorSessionOptions {
+}
+interface NavigateOptions extends AutomatorCommandOptions {
+    url: string;
+}
+interface PageInfoOptions extends AutomatorCommandOptions {
+    json?: boolean;
+}
+interface PageDataOptions extends PageInfoOptions {
+    path?: string;
+}
+interface SelectorOptions extends AutomatorCommandOptions {
+    selector: string;
+}
+interface TapOptions extends SelectorOptions {
+}
+interface InputOptions extends SelectorOptions {
+    value: string;
+}
+interface ScrollOptions extends AutomatorCommandOptions {
+    scrollTop: number;
+}
+interface AuditOptions extends AutomatorCommandOptions {
+    outputPath?: string;
+}
+interface ScreenshotOptions extends AutomatorCommandOptions {
+    outputPath?: string;
+    page?: string;
+}
+interface ScreenshotResult {
+    base64?: string;
+    path?: string;
+}
+interface RemoteOptions extends AutomatorCommandOptions {
+    enable?: boolean;
+}
+interface PageSnapshot {
+    path: string;
+    query: Record<string, unknown> | undefined;
+}
+declare function navigateTo(options: NavigateOptions): Promise<void>;
+declare function redirectTo(options: NavigateOptions): Promise<void>;
+declare function navigateBack(options: AutomatorCommandOptions): Promise<void>;
+declare function reLaunch(options: NavigateOptions): Promise<void>;
+declare function switchTab(options: NavigateOptions): Promise<void>;
+declare function pageStack(options: PageInfoOptions): Promise<PageSnapshot[]>;
+declare function currentPage(options: PageInfoOptions): Promise<PageSnapshot>;
+declare function systemInfo(options: PageInfoOptions): Promise<unknown>;
+declare function pageData(options: PageDataOptions): Promise<unknown>;
+declare function tap(options: TapOptions): Promise<void>;
+declare function input(options: InputOptions): Promise<void>;
+declare function scrollTo(options: ScrollOptions): Promise<void>;
+declare function audit(options: AuditOptions): Promise<unknown>;
+declare function takeScreenshot(options: ScreenshotOptions): Promise<ScreenshotResult>;
+declare function remote(options: RemoteOptions): Promise<void>;
+
+/**
+ * @description 处理 config 子命令。
+ */
+declare function handleConfigCommand(argv: string[]): Promise<void>;
+
 /**
  * @description 运行支付宝小程序 CLI（minidev）
  */
@@ -18,6 +164,10 @@ declare function resolveCliPath(): Promise<{
     source: ConfigSource;
 }>;
 
+interface RetryKeypressOptions {
+    timeoutMs?: number;
+}
+type RetryPromptResult = 'retry' | 'cancel' | 'timeout';
 /**
  * @description 判断是否为微信开发者工具登录失效错误。
  */
@@ -30,25 +180,67 @@ declare function extractExecutionErrorText(error: unknown): string;
  * @description 将登录失效错误格式化为更易读的摘要。
  */
 declare function formatWechatIdeLoginRequiredError(error: unknown): string;
+/**
+ * @description 创建登录失效专用错误，并携带退出码语义。
+ */
+declare function createWechatIdeLoginRequiredExitError(error: unknown, reason?: string): Error & {
+    code: number;
+    exitCode: number;
+};
 /**
  * @description 交互等待用户按键重试，按 r 重试，按 q 或 Ctrl+C 取消。
  */
-declare function waitForRetryKeypress(): Promise<boolean>;
+declare function waitForRetryKeypress(options?: RetryKeypressOptions): Promise<RetryPromptResult>;
 /**
  * @description 生成重试按键提示，并高亮关键热键。
  */
-declare function formatRetryHotkeyPrompt(): string;
+declare function formatRetryHotkeyPrompt(timeoutMs?: number): string;
 
 /**
- * @description CLI 入口解析与分发
+ * @description CLI 入口解析与分发。
  */
 declare function parse(argv: string[]): Promise<void>;
 
+declare const AUTOMATOR_COMMAND_NAMES: string[];
+/**
+ * @description 判断是否属于 automator 子命令。
+ */
+declare function isAutomatorCommand(command: string | undefined): boolean;
+/**
+ * @description 分发 automator 子命令。
+ */
+declare function runAutomatorCommand(command: string, argv: string[]): Promise<void>;
+/**
+ * @description 获取 automator 命令帮助文本。
+ */
+declare function getAutomatorCommandHelp(command: string): string | undefined;
+
+type LoginRetryMode = 'never' | 'once' | 'always';
+/**
+ * @description 运行微信开发者工具 CLI，并在登录失效时允许按键重试。
+ */
+declare function runWechatCliWithRetry(cliPath: string, argv: string[]): Promise<void>;
+
+/**
+ * @description Print help for screenshot command
+ */
+declare function printScreenshotHelp(): void;
+/**
+ * @description Parse command line arguments for screenshot command
+ */
+declare function parseScreenshotArgs(argv: string[]): ScreenshotOptions;
+
+/**
+ * @description 在调用官方微信 CLI 前做轻量参数校验。
+ */
+declare function validateWechatCliCommandArgs(argv: readonly string[]): void;
+
 /**
  * @description 基础配置
  */
 interface BaseConfig {
     cliPath: string;
+    locale?: 'zh' | 'en';
 }
 /**
  * @description 配置来源
@@ -68,10 +260,30 @@ interface AliasEntry {
     replacement: string;
 }
 
+interface CustomConfigFile {
+    cliPath?: string;
+    locale?: 'zh' | 'en';
+}
 /**
  * @description 写入自定义 CLI 路径配置
  */
 declare function createCustomConfig(params: BaseConfig): Promise<string>;
+/**
+ * @description 写入语言配置（zh / en）。
+ */
+declare function createLocaleConfig(locale: 'zh' | 'en'): Promise<"zh" | "en">;
+/**
+ * @description 删除指定配置项。
+ */
+declare function removeCustomConfigKey(key: keyof CustomConfigFile): Promise<void>;
+/**
+ * @description 覆盖写入配置内容（会替换原内容）。
+ */
+declare function overwriteCustomConfig(config: CustomConfigFile): Promise<void>;
+/**
+ * @description 读取原始自定义配置。
+ */
+declare function readCustomConfig(): Promise<CustomConfigFile>;
 
 /**
  * @description 默认自定义配置目录
@@ -86,6 +298,10 @@ declare const defaultCustomConfigFilePath: string;
  * @description 读取并解析 CLI 配置（自定义优先）
  */
 declare function getConfig(): Promise<ResolvedConfig>;
+/**
+ * @description 获取用户配置的语言偏好。
+ */
+declare function getConfiguredLocale(): Promise<"zh" | "en" | undefined>;
 
 /**
  * @description 官方微信开发者工具只支持 Windows、macOS，Linux 只有社区版
@@ -144,4 +360,4 @@ declare function execute(cliPath: string, argv: string[], options?: ExecuteOptio
  */
 declare function resolvePath(filePath: string): string;
 
-export { type ArgvTransform, type BaseConfig, type ConfigSource, type ResolvedConfig, type SupportedPlatform, SupportedPlatformsMap, createAlias, createCustomConfig, createPathCompat, defaultCustomConfigDirPath, defaultCustomConfigFilePath, execute, extractExecutionErrorText, formatRetryHotkeyPrompt, formatWechatIdeLoginRequiredError, getConfig, getDefaultCliPath, isOperatingSystemSupported, isWechatIdeLoginRequiredError, operatingSystemName, parse, promptForCliPath, resolveCliPath, resolvePath, runMinidev, transformArgv, waitForRetryKeypress };
+export { AUTOMATOR_COMMAND_NAMES, type ArgvTransform, type AuditOptions, type AutomatorCommandOptions, type AutomatorOptions, type AutomatorSessionOptions, type BaseConfig, CONFIG_COMMAND_NAME, type ConfigSource, type InputOptions, type LoginRetryMode, MINIDEV_NAMESPACE_COMMAND_NAMES, type MiniProgramElement, type MiniProgramLike, type MiniProgramPage, type NavigateOptions, type PageDataOptions, type PageInfoOptions, type ParsedAutomatorArgs, type RemoteOptions, type ResolvedConfig, type RetryKeypressOptions, type RetryPromptResult, type ScreenshotOptions, type ScreenshotResult, type ScrollOptions, type SelectorOptions, type SupportedPlatform, SupportedPlatformsMap, type TapOptions, WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES, WECHAT_CLI_COMMAND_NAMES, audit, createAlias, createCustomConfig, createLocaleConfig, createPathCompat, createWechatIdeLoginRequiredExitError, currentPage, defaultCustomConfigDirPath, defaultCustomConfigFilePath, execute, extractExecutionErrorText, formatAutomatorLoginError, formatRetryHotkeyPrompt, formatWechatIdeLoginRequiredError, getAutomatorCommandHelp, getConfig, getConfiguredLocale, getDefaultCliPath, handleConfigCommand, input, isAutomatorCommand, isAutomatorLoginError, isDevtoolsHttpPortError, isOperatingSystemSupported, isWeappIdeTopLevelCommand, isWechatIdeLoginRequiredError, launchAutomator, navigateBack, navigateTo, operatingSystemName, overwriteCustomConfig, pageData, pageStack, parse, parseAutomatorArgs, parseScreenshotArgs, printScreenshotHelp, promptForCliPath, reLaunch, readCustomConfig, readOptionValue, redirectTo, remote, removeCustomConfigKey, removeOption, resolveCliPath, resolvePath, runAutomatorCommand, runMinidev, runWechatCliWithRetry, scrollTo, switchTab, systemInfo, takeScreenshot, tap, transformArgv, validateWechatCliCommandArgs, waitForRetryKeypress, withMiniProgram };

package/dist/index.js

@@ -1,48 +1,136 @@
 import {
+  AUTOMATOR_COMMAND_NAMES,
+  CONFIG_COMMAND_NAME,
+  MINIDEV_NAMESPACE_COMMAND_NAMES,
   SupportedPlatformsMap,
+  WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES,
+  WECHAT_CLI_COMMAND_NAMES,
   createAlias,
   createCustomConfig,
+  createLocaleConfig,
   createPathCompat,
+  createWechatIdeLoginRequiredExitError,
   defaultCustomConfigDirPath,
   defaultCustomConfigFilePath,
   execute,
   extractExecutionErrorText,
   formatRetryHotkeyPrompt,
   formatWechatIdeLoginRequiredError,
+  getAutomatorCommandHelp,
   getConfig,
+  getConfiguredLocale,
   getDefaultCliPath,
+  handleConfigCommand,
+  isAutomatorCommand,
   isOperatingSystemSupported,
+  isWeappIdeTopLevelCommand,
   isWechatIdeLoginRequiredError,
   operatingSystemName,
+  overwriteCustomConfig,
   parse,
+  parseAutomatorArgs,
+  parseScreenshotArgs,
+  printScreenshotHelp,
   promptForCliPath,
+  readCustomConfig,
+  readOptionValue,
+  removeCustomConfigKey,
+  removeOption,
   resolveCliPath,
   resolvePath,
+  runAutomatorCommand,
   runMinidev,
+  runWechatCliWithRetry,
   transformArgv,
+  validateWechatCliCommandArgs,
   waitForRetryKeypress
-} from "./chunk-A26E3I4U.js";
+} from "./chunk-C2MXNGAM.js";
+import {
+  audit,
+  currentPage,
+  formatAutomatorLoginError,
+  input,
+  isAutomatorLoginError,
+  isDevtoolsHttpPortError,
+  launchAutomator,
+  navigateBack,
+  navigateTo,
+  pageData,
+  pageStack,
+  reLaunch,
+  redirectTo,
+  remote,
+  scrollTo,
+  switchTab,
+  systemInfo,
+  takeScreenshot,
+  tap,
+  withMiniProgram
+} from "./chunk-NSYCXXXT.js";
 export {
+  AUTOMATOR_COMMAND_NAMES,
+  CONFIG_COMMAND_NAME,
+  MINIDEV_NAMESPACE_COMMAND_NAMES,
   SupportedPlatformsMap,
+  WEAPP_IDE_TOP_LEVEL_COMMAND_NAMES,
+  WECHAT_CLI_COMMAND_NAMES,
+  audit,
   createAlias,
   createCustomConfig,
+  createLocaleConfig,
   createPathCompat,
+  createWechatIdeLoginRequiredExitError,
+  currentPage,
   defaultCustomConfigDirPath,
   defaultCustomConfigFilePath,
   execute,
   extractExecutionErrorText,
+  formatAutomatorLoginError,
   formatRetryHotkeyPrompt,
   formatWechatIdeLoginRequiredError,
+  getAutomatorCommandHelp,
   getConfig,
+  getConfiguredLocale,
   getDefaultCliPath,
+  handleConfigCommand,
+  input,
+  isAutomatorCommand,
+  isAutomatorLoginError,
+  isDevtoolsHttpPortError,
   isOperatingSystemSupported,
+  isWeappIdeTopLevelCommand,
   isWechatIdeLoginRequiredError,
+  launchAutomator,
+  navigateBack,
+  navigateTo,
   operatingSystemName,
+  overwriteCustomConfig,
+  pageData,
+  pageStack,
   parse,
+  parseAutomatorArgs,
+  parseScreenshotArgs,
+  printScreenshotHelp,
   promptForCliPath,
+  reLaunch,
+  readCustomConfig,
+  readOptionValue,
+  redirectTo,
+  remote,
+  removeCustomConfigKey,
+  removeOption,
   resolveCliPath,
   resolvePath,
+  runAutomatorCommand,
   runMinidev,
+  runWechatCliWithRetry,
+  scrollTo,
+  switchTab,
+  systemInfo,
+  takeScreenshot,
+  tap,
   transformArgv,
-  waitForRetryKeypress
+  validateWechatCliCommandArgs,
+  waitForRetryKeypress,
+  withMiniProgram
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weapp-ide-cli",
   "type": "module",
-  "version": "5.0.3",
+  "version": "5.1.0",
   "description": "让微信开发者工具，用起来更加方便！",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -64,6 +64,7 @@
   "dependencies": {
     "execa": "9.6.1",
     "fs-extra": "^11.3.3",
+    "miniprogram-automator": "^0.12.1",
     "pathe": "^2.0.3",
     "@weapp-core/logger": "^3.1.0"
   },