@weapp-vite/miniprogram-automator 1.2.23 → 1.3.0

package/README.md

@@ -141,6 +141,22 @@ await miniProgram.flushConsole()
 
 先用 `addListener` 被动注册，再显式等待 `enableLog`，可以记录初始化期间的日志。`flushConsole()` 等待调用时已收到的错误属性检查完成；每次查询最多等待 1 秒，失败会在原参数上保留 `inspectionError`。断开连接时尚未完成的日志也会携带该诊断发布。只有宿主明确返回 CDP 命令不支持时才回退 SDK 格式；其他初始化错误仍然抛出。重复调用 `enableLog` 会刷新 Runtime 订阅，并保留已选择的格式。
 
+### 4.7 AppService 堆内存探测
+
+`getAppServiceHeapUsage({ timeout })` 通过现有 `App.CDPCommand` 调用 `Runtime.getHeapUsage`，默认超时 2500ms。支持时返回 `{ status: 'available', source: 'appservice-cdp-runtime', usedSize, totalSize }`，两个值均为字节。仅当宿主明确不支持该协议或方法时，返回 `status: 'unsupported'` 及 `protocol-unimplemented` / `method-not-found` 原因。
+
+```ts
+const heap = await miniProgram.getAppServiceHeapUsage({ timeout: 2_500 })
+if (heap.status === 'available') {
+  console.log({ usedBytes: heap.usedSize, allocatedBytes: heap.totalSize })
+}
+else {
+  console.log({ unsupported: heap.reason })
+}
+```
+
+空结果、缺失字段、字符串、负数、非有限数值或已用量超过分配量都会报错；连接超时与其他协议错误原样传播，不会转换为不支持或零内存。每次调用重新探测，不缓存旧会话的能力结果，也不主动触发 GC。该指标仅覆盖 AppService JS 堆，不是 renderer/native 内存、进程 RSS、峰值或可归因的组件独占内存。实际可用性取决于连接的 DevTools/基础库，仍须在目标宿主确认；headless 不提供真实 IDE 堆证据。
+
 ## 5. 主要导出
 
 | 导出                      | 说明                                     |
@@ -164,3 +180,9 @@ pnpm --filter @weapp-vite/miniprogram-automator typecheck
 
 - 仓库：https://github.com/weapp-vite/weapp-vite
 - `weapp-ide-cli`：[../weapp-ide-cli/README.md](../weapp-ide-cli/README.md)
+
+## 启动预算与取消
+
+微信 DevTools 的 `launch` / `connect` 使用一次总 `timeout`（默认 30 秒）。路径准备、端口租约、HTTP 适配、WebSocket、版本与 App ready 均消耗剩余预算，自动重试不重置 deadline。可传 `signal` 取消；成功后连接归调用方管理。
+
+失败保留 `cause`，`error.operation` 包含阶段、最后成功阶段、耗时、剩余预算、尝试次数、未退出操作数量及本次资源清理状态。清理 `pending` 表示在预算内未确认退出，不能当作资源已释放。迟到连接只断开自身 WebSocket；启动器只终止持有句柄的 CLI 子进程，不据此认领 IDE 宿主或清理其他项目。无需在 App ready 后再固定等待五秒。

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { OPERATION_TIMEOUT_CODE, OperationDiagnostics, OperationErrorCategory, OperationLifecycle, OperationStepOptions, classifyOperationError, isRecoverableOperationError, readWechatLoginState } from "./operation.mjs";
 import { EventEmitter } from "node:events";
 import WebSocket from "ws";
 import { Buffer } from "node:buffer";
@@ -31,6 +32,22 @@ declare function get(label?: string): SmartappLogger;
 declare function currentTimestamp(): number;
 declare function delay(ms: number): Promise<void>;
 //#endregion
+//#region src/appServiceHeap.d.ts
+interface AppServiceHeapUsageOptions {
+  /** 单次协议请求的超时预算，单位毫秒。 */
+  timeout?: number;
+}
+type AppServiceHeapUsage = {
+  status: 'available';
+  source: 'appservice-cdp-runtime';
+  usedSize: number;
+  totalSize: number;
+} | {
+  status: 'unsupported';
+  source: 'appservice-cdp-runtime';
+  reason: 'protocol-unimplemented' | 'method-not-found';
+};
+//#endregion
 //#region src/Transport.d.ts
 /** Transport 的实现。 */
 declare class Transport extends EventEmitter {
@@ -50,6 +67,7 @@ interface ToolInfo {
 /** Connection 的实现。 */
 declare class Connection extends EventEmitter {
   private transport;
+  private disposed;
   private callbacks;
   private useAppServicePageProtocol;
   private useAppServicePageMethod;
@@ -63,7 +81,7 @@ declare class Connection extends EventEmitter {
   get prefersAppServicePageMethod(): boolean;
   private onMessage;
   private onClose;
-  static create(url: string, timeout?: number): Promise<Connection>;
+  static create(url: string, timeout?: number, signal?: AbortSignal): Promise<Connection>;
 }
 //#endregion
 //#region src/structuredConsole.d.ts
@@ -381,6 +399,8 @@ declare class MiniProgram extends EventEmitter {
   restorePluginWxMethod(pluginId: string, method: string): Promise<void>;
   evaluate(appFunction: AutomatorCallable | string, ...args: any[]): Promise<any>;
   evaluateWithOptions(appFunction: AutomatorCallable | string, options?: EvaluateOptions, ...args: any[]): Promise<any>;
+  /** 探测并读取 AppService JS 堆；明确不支持时返回原因，连接故障与无效响应继续抛出。 */
+  getAppServiceHeapUsage(options?: AppServiceHeapUsageOptions): Promise<AppServiceHeapUsage>;
   pageScrollTo(scrollTop: number): Promise<void>;
   close(): Promise<void>;
   remote(auto?: boolean): Promise<void>;
@@ -392,7 +412,7 @@ declare class MiniProgram extends EventEmitter {
   exposeFunction(name: string, bindingFunction: AutomatorCallable): Promise<void>;
   checkVersion(timeout?: number): Promise<void>;
   /**
-   * @description 等待小程序 App 域协议可用，避免返回半就绪自动化会话。
+   * @description 等待原生协议返回真实页面标识和路径，避免返回半就绪自动化会话。
    */
   waitForAppReady(timeout?: number): Promise<void>;
   screenshot(options?: IScreenshotOptions): Promise<string | undefined>;
@@ -605,11 +625,13 @@ export declare function normalizePlatform(platform?: MiniprogramAutomatorPlatfor
 //#region src/Launcher.d.ts
 export interface IConnectOptions {
   wsEndpoint: string;
+  signal?: AbortSignal;
   timeout?: number;
   platform?: MiniprogramAutomatorPlatform;
 }
 /** ILaunchOptions 的类型定义。 */
 export interface ILaunchOptions {
+  signal?: AbortSignal;
   platform?: MiniprogramAutomatorPlatform;
   cliPath?: string;
   connectType?: string;
@@ -669,6 +691,17 @@ declare class Automator {
   launch(options: ILaunchOptions): Promise<any>;
 }
 //#endregion
+//#region src/launcher/portLease.d.ts
+interface AutomatorPortLease {
+  path?: string;
+  port: number;
+  release: () => Promise<void>;
+}
+/**
+ * @description 选择并短暂租约一个自动化端口，避免并发启动选择到同一端口。
+ */
+export declare function acquireAutomatorPortLease(preferredPort?: number): Promise<AutomatorPortLease>;
+//#endregion
 //#region src/util.d.ts
 /** decodeQrCode 的方法封装。 */
 export declare function decodeQrCode(qrCode: string): Promise<string>;
@@ -705,4 +738,4 @@ export declare const SmartappAutomator: {
   };
 };
 //#endregion
-export { Automator, Connection, type ConsoleLogOptions, type ConsoleRemoteObject, Element, Launcher, MiniProgram, Native, Page, type StructuredConsoleEntry, Transport };
+export { type AppServiceHeapUsage, type AppServiceHeapUsageOptions, Automator, type AutomatorPortLease, Connection, type ConsoleLogOptions, type ConsoleRemoteObject, Element, Launcher, MiniProgram, Native, OPERATION_TIMEOUT_CODE, OperationDiagnostics, OperationErrorCategory, OperationLifecycle, OperationStepOptions, Page, type StructuredConsoleEntry, Transport, classifyOperationError, isRecoverableOperationError, readWechatLoginState };