moonbridge-ts 0.1.0

package/src/moonbridge-ipc/client/types/ipc_types.ts

@@ -0,0 +1,50 @@
+/**
+ * IPC 类型定义，对应 Flutter lib/client/types/ipc_types.dart。
+ * 仅定义类型，不包含具体实现逻辑。
+ */
+
+import { IpcError } from '../../general/error/ipc_error';
+import { Request } from '../../general/message/request';
+import { Response } from '../../general/message/response';
+import { Error } from '../../general/message/error';
+
+/** 响应回调：接收动态数组形式的响应载荷。 */
+export type IpcResponseCallback = (response: unknown[]) => void;
+
+/** 错误回调：接收 IpcError。 */
+export type IpcErrorCallback = (error: IpcError) => void;
+
+/** 服务端进程连接完成处理器。US2：统一使用 undefined 表示无错误，不再使用 | null。 */
+export type IpcConnectionCompletionHandler = (
+  isConnected: boolean,
+  error?: IpcError,
+) => void;
+
+/**
+ * IPC 消息拦截器，用于拦截和处理 IPC 消息。
+ * 对应 Flutter MessageInterceptor。
+ */
+export class MessageInterceptor {
+  constructor(
+    /** 拦截请求消息；返回 true 表示已处理，false 表示继续默认逻辑 */
+    public readonly interceptRequest?: (request: Request) => boolean,
+    /** 拦截响应消息；返回 true 表示已处理 */
+    public readonly interceptResponse?: (response: Response) => boolean,
+    /** 拦截错误消息；返回 true 表示已处理 */
+    public readonly interceptError?: (error: Error) => boolean,
+  ) { }
+}
+
+/**
+ * IPC 连接状态观察器，定义处理与服务端连接状态变化的方式。
+ * 对应 Flutter ConnectionObserver。
+ */
+export class ConnectionObserver {
+  constructor(
+    /** 当与服务端建立连接时调用 */
+    public readonly onConnected?: () => void,
+    /** 当与服务端断开连接时调用 */
+    public readonly onDisconnected?: () => void,
+  ) { }
+}
+

package/src/moonbridge-ipc/extension/bridge_extension.ts

@@ -0,0 +1,32 @@
+import { Bridge } from "../../moonbridge/kernel/bridge";
+import { BridgeModule } from "../../moonbridge/kernel/bridge_module";
+import { IpcClientBridge } from "../client/internal/bridge/ipc_client_bridge";
+import { MoonBridgeIpcClient } from "../client/moonbridge_ipc_client";
+
+/**
+ * 桥接模块工具类
+ */
+export class BridgeModuleUtils {
+    /**
+     * 获取 IPC 客户端
+     * @param object 桥接实例或桥接模块实例
+     * @returns IPC 客户端实例
+     */
+    static getIpcClient(arg?: BridgeModule | Bridge): MoonBridgeIpcClient | undefined {
+        if (!arg) {
+            return undefined;
+        }
+
+        let bridge: Bridge | undefined;
+        if (arg instanceof BridgeModule) {
+            bridge = arg.bridge;
+        } else {
+            bridge = arg;
+        }
+
+        if (bridge instanceof IpcClientBridge) {
+            return bridge.ipcClient;
+        }
+        return undefined;
+    }
+}

package/src/moonbridge-ipc/general/app_launch/app_launcher.ts

@@ -0,0 +1,21 @@
+/**
+ * 跨进程唤醒服务端应用的抽象，与 Flutter PlatformAppLauncher 行为对齐（US4）。
+ *
+ * 宿主（如 WPS 加载项）可通过 IpcClientSettings.appLauncher 注入真实实现；
+ * 例如在 wps-addin 中封装 wakeNpc 等能力后传入。未注入时 ConnectionManager 使用 StubAppLauncher。
+ *
+ * 019：launchApp 返回 AppLaunchResult，含 success 与 error，便于业务层识别失败原因。
+ */
+
+import { AppLaunchResult } from './model/app_launch_models.js';
+
+/**
+ * 应用启动器接口：用于在服务端未运行时尝试唤醒目标应用。
+ * 真实实现可由宿主（如 WPS 加载项 / wps-addin wakeNpc）提供并注入。
+ */
+export interface AppLauncher {
+  /** 尝试启动/唤醒目标应用；返回结果对象，含 success 与可选 error */
+  launchApp(): Promise<AppLaunchResult>;
+  /** 可选：检查目标应用是否已在运行 */
+  isAppRunning?(): Promise<boolean>;
+}

package/src/moonbridge-ipc/general/app_launch/internal/real_platform_app_launcher.ts

@@ -0,0 +1,97 @@
+/**
+ * 各平台启动器实现：Stub / Browser / Node。
+ * Stub 用于未支持环境；Browser/Node 由 US1/US2 扩展。
+ * __BROWSER_BUILD__ 由浏览器构建（如 wps-addin）通过 define 注入，用于切换 node_launcher 与 node_launcher.browser。
+ */
+declare const __BROWSER_BUILD__: string | undefined;
+
+import { AppInstallationPath, AppLaunchIdentifier } from '../model/app_info.js';
+import { AppLaunchResult } from '../model/app_launch_models.js';
+import { AppLaunchModelsExtension } from '../model/app_launch_models_extension.js';
+import { LaunchAppOptions } from '../platform_app_launcher.js';
+import { PlatformAppLauncher } from '../platform_app_launcher.js';
+import { UrlSchemeLauncher } from '../launcher/url_scheme_launcher.js';
+
+/**
+ * Stub 实现：当前环境未实现唤醒时使用；launchApp 返回失败，isAppRunning 返回 false。
+ */
+export class StubPlatformAppLauncher implements PlatformAppLauncher {
+  async launchApp(): Promise<AppLaunchResult> {
+    return new AppLaunchResult(false);
+  }
+
+  async isAppRunning(): Promise<boolean> {
+    return false;
+  }
+}
+
+const defaultStatusCheckInterval = 0.3;
+const defaultOperationTimeout = 3.0;
+
+/**
+ * 浏览器用启动器：通过 URL Scheme（从 AppLaunchIdentifier 取 iOSScheme）唤起；
+ * isAppRunning 在浏览器端不可知，返回 false。
+ */
+export class BrowserPlatformAppLauncher implements PlatformAppLauncher {
+  constructor(private readonly appIdentifier: AppLaunchIdentifier) { }
+
+  async launchApp(options?: LaunchAppOptions): Promise<AppLaunchResult> {
+    const scheme = this.appIdentifier.iOSScheme;
+    if (!scheme) {
+      return new AppLaunchResult(false, 'No URL scheme (iOSScheme) in identifier');
+    }
+
+    const args = options?.argumentsForIdentifier;
+    const interval = options?.statusCheckInterval ?? defaultStatusCheckInterval;
+    const timeout = options?.operationTimeout ?? defaultOperationTimeout;
+    const platformArgs = args ? AppLaunchModelsExtension.getCurrentPlatformArguments(args) : [];
+    const query = platformArgs.length ? platformArgs.join('&') : '';
+
+    return UrlSchemeLauncher.launch({
+      scheme,
+      path: '',
+      query,
+      statusCheckInterval: interval,
+      operationTimeout: timeout,
+    });
+  }
+
+  async isAppRunning(): Promise<boolean> {
+    return false;
+  }
+}
+
+/**
+ * Node 端启动器：按 AppInstallationPath 启动并轮询 isProcessRunning；
+ * 桌面优先路径，无路径时不适用（应由工厂返回 Stub）。
+ * 使用动态 import 加载 node_launcher，避免浏览器环境加载 child_process 等 Node 内置模块。
+ */
+export class NodePlatformAppLauncher implements PlatformAppLauncher {
+  constructor(private readonly appInstallationPath: AppInstallationPath) { }
+
+  async launchApp(options?: LaunchAppOptions): Promise<AppLaunchResult> {
+    const nodeLauncherPath =
+      typeof __BROWSER_BUILD__ !== 'undefined'
+        ? '../launcher/node_launcher.browser.js'
+        : '../launcher/node_launcher.js';
+    const { NodeProcessLauncher } = await import(nodeLauncherPath);
+    const args = options?.argumentsForInstallationPath
+      ? AppLaunchModelsExtension.getCurrentPlatformArguments(options.argumentsForInstallationPath)
+      : undefined;
+
+    return NodeProcessLauncher.launchByPath(this.appInstallationPath, {
+      args,
+      statusCheckInterval: options?.statusCheckInterval ?? defaultStatusCheckInterval,
+      operationTimeout: options?.operationTimeout ?? defaultOperationTimeout,
+    });
+  }
+
+  async isAppRunning(): Promise<boolean> {
+    const nodeLauncherPath =
+      typeof __BROWSER_BUILD__ !== 'undefined'
+        ? '../launcher/node_launcher.browser.js'
+        : '../launcher/node_launcher.js';
+    const { NodeProcessLauncher } = await import(nodeLauncherPath);
+    return NodeProcessLauncher.isProcessRunning(this.appInstallationPath);
+  }
+}

package/src/moonbridge-ipc/general/app_launch/launcher/node_launcher.browser.ts

@@ -0,0 +1,23 @@
+/**
+ * node_launcher 的浏览器 stub：避免在浏览器中加载 child_process 等 Node 内置模块。
+ * 当 __BROWSER_BUILD__ 被 define 时，real_platform_app_launcher 会导入此文件而非 node_launcher.ts。
+ */
+import type { AppInstallationPath } from '../model/app_info.js';
+import { AppLaunchResult } from '../model/app_launch_models.js';
+
+export class NodeProcessLauncher {
+  static isAppInstalled(_appInstallationPath: AppInstallationPath): boolean {
+    return false;
+  }
+
+  static async launchByPath(
+    _appInstallationPath: AppInstallationPath,
+    _options?: { args?: string[]; statusCheckInterval?: number; operationTimeout?: number },
+  ): Promise<AppLaunchResult> {
+    return new AppLaunchResult(false, 'NodeProcessLauncher is not available in browser');
+  }
+
+  static async isProcessRunning(_appInstallationPath: AppInstallationPath): Promise<boolean> {
+    return false;
+  }
+}

package/src/moonbridge-ipc/general/app_launch/launcher/node_launcher.ts

@@ -0,0 +1,138 @@
+/**
+ * Node 端按安装路径启动与进程检测，与 research 第 3 节一致。
+ * 使用 child_process.spawn（detached）、tasklist/ps 等，无额外依赖。
+ * 019：启动前增加 isAppInstalled 检测，未安装时返回 APP_NOT_INSTALLED。
+ */
+
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { platform } from 'process';
+import { AppInstallationPath } from '../model/app_info.js';
+import { AppLaunchResult } from '../model/app_launch_models.js';
+import { APP_NOT_INSTALLED } from '../model/app_launch_error_codes.js';
+import { AppLaunchModelsExtension } from '../model/app_launch_models_extension.js';
+
+const defaultStatusCheckInterval = 0.3;
+const defaultOperationTimeout = 3.0;
+
+export interface NodeLaunchOptions {
+  args?: string[];
+  statusCheckInterval?: number;
+  operationTimeout?: number;
+}
+
+/**
+ * Node 端按路径启动与进程检测（013：一级函数收敛为类静态方法）。
+ */
+export class NodeProcessLauncher {
+  /**
+   * 检查目标应用是否已安装（路径对应的文件/目录是否存在）。
+   * macOS .app 为目录；Windows 为 exe 文件；Linux 为可执行文件。
+   */
+  static isAppInstalled(appInstallationPath: AppInstallationPath): boolean {
+    const pathStr = AppLaunchModelsExtension.getCurrentPlatformPath(appInstallationPath);
+    if (!pathStr) return false;
+    try {
+      return existsSync(pathStr);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 按当前平台路径启动进程；Windows 直接 spawn 路径，macOS 使用 open -a 或 spawn。
+   * 启动前检查 isAppInstalled，未安装时返回 APP_NOT_INSTALLED。
+   * 启动后按 statusCheckInterval 轮询 isProcessRunning，在 operationTimeout 内有一次为 true 即返回成功。
+   */
+  static async launchByPath(
+    appInstallationPath: AppInstallationPath,
+    options: NodeLaunchOptions = {},
+  ): Promise<AppLaunchResult> {
+    const pathStr = AppLaunchModelsExtension.getCurrentPlatformPath(appInstallationPath);
+    if (!pathStr) {
+      return new AppLaunchResult(false, 'No installation path for current platform');
+    }
+    if (!NodeProcessLauncher.isAppInstalled(appInstallationPath)) {
+      return new AppLaunchResult(false, APP_NOT_INSTALLED);
+    }
+    const interval = (options.statusCheckInterval ?? defaultStatusCheckInterval) * 1000;
+    const timeout = (options.operationTimeout ?? defaultOperationTimeout) * 1000;
+    const args = options.args ?? [];
+
+    try {
+      if (platform === 'win32') {
+        spawn(pathStr, args, {
+          detached: true,
+          stdio: 'ignore',
+          shell: false,
+        }).unref();
+      } else if (platform === 'darwin') {
+        if (pathStr.endsWith('.app')) {
+          spawn('open', ['-a', pathStr, ...args], {
+            detached: true,
+            stdio: 'ignore',
+          }).unref();
+        } else {
+          spawn(pathStr, args, {
+            detached: true,
+            stdio: 'ignore',
+          }).unref();
+        }
+      } else {
+        spawn(pathStr, args, {
+          detached: true,
+          stdio: 'ignore',
+        }).unref();
+      }
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return new AppLaunchResult(false, message);
+    }
+
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const running = await NodeProcessLauncher.isProcessRunning(appInstallationPath);
+      if (running) return new AppLaunchResult(true);
+      await new Promise((r) => setTimeout(r, interval));
+    }
+    return new AppLaunchResult(false, 'Process did not appear within timeout');
+  }
+
+  /**
+   * 当前平台下该安装路径对应进程是否在运行。
+   * Windows: tasklist 匹配 exe 名；macOS: ps 匹配路径；Linux: ps 匹配路径。
+   */
+  static async isProcessRunning(
+    appInstallationPath: AppInstallationPath,
+  ): Promise<boolean> {
+    const pathStr = AppLaunchModelsExtension.getCurrentPlatformPath(appInstallationPath);
+    if (!pathStr) return false;
+
+    if (platform === 'win32') {
+      const exeName = pathStr.split(/[/\\]/).pop() ?? '';
+      if (!exeName) return false;
+      try {
+        const { execSync } = await import('child_process');
+        const out = execSync('tasklist /FO CSV /NH', { encoding: 'utf-8', windowsHide: true });
+        return out.toLowerCase().includes(exeName.toLowerCase());
+      } catch {
+        return false;
+      }
+    }
+
+    if (platform === 'darwin' || platform === 'linux') {
+      try {
+        const { execSync } = await import('child_process');
+        const out = execSync(`ps -eo args= 2>/dev/null || ps -e -o args= 2>/dev/null`, {
+          encoding: 'utf-8',
+        });
+        return out.includes(pathStr);
+      } catch {
+        return false;
+      }
+    }
+
+    return false;
+  }
+}
+

package/src/moonbridge-ipc/general/app_launch/launcher/url_scheme_launcher.ts

@@ -0,0 +1,83 @@
+/**
+ * 浏览器端通过隐藏 iframe 触发 URL Scheme 唤起，与 research 中「浏览器端唤起方式」一致。
+ * 无法检测目标进程，故超时后返回失败或依赖宿主回调。
+ */
+
+import { AppLaunchResult } from '../model/app_launch_models.js';
+
+export interface UrlSchemeLaunchOptions {
+  /** URL Scheme（如 'npc'） */
+  scheme: string;
+  /** 可选 path（如 '/open'） */
+  path?: string;
+  /** 可选 query 字符串（不含 ?） */
+  query?: string;
+  /** 状态检查间隔（秒），默认 0.3 */
+  statusCheckInterval?: number;
+  /** 操作超时（秒），超时后返回失败；默认 3.0 */
+  operationTimeout?: number;
+}
+
+const defaultTimeout = 3.0;
+
+/**
+ * 浏览器端 URL Scheme 启动（013：一级函数收敛为类静态方法）。
+ * 使用隐藏 iframe 触发 scheme://[path][?query]，避免整页跳转。
+ */
+export class UrlSchemeLauncher {
+  /**
+   * 使用隐藏 iframe 触发 scheme://[path][?query]。
+   * 浏览器无法检测目标应用是否真正启动，故在 operationTimeout 后统一返回失败。
+   */
+  static launch(options: UrlSchemeLaunchOptions): Promise<AppLaunchResult> {
+    const {
+      scheme,
+      path = '',
+      query = '',
+      operationTimeout = defaultTimeout,
+    } = options;
+
+    const pathPart = path ? `/${path.replace(/^\//, '')}` : '';
+    const queryPart = query ? (query.startsWith('?') ? query : `?${query}`) : '';
+    const url = `${scheme}://${pathPart}${queryPart}`.replace(/\/\/$/, '://');
+
+    if (typeof document === 'undefined' || !document.createElement) {
+      return Promise.resolve(new AppLaunchResult(false, 'Not in browser environment'));
+    }
+
+    try {
+      const iframe = document.createElement('iframe');
+      iframe.style.display = 'none';
+      iframe.style.position = 'absolute';
+      iframe.style.width = '0';
+      iframe.style.height = '0';
+      iframe.setAttribute('aria-hidden', 'true');
+      iframe.src = url;
+      document.body.appendChild(iframe);
+      const remove = () => {
+        try {
+          if (iframe.parentNode) iframe.parentNode.removeChild(iframe);
+        } catch {
+          // ignore
+        }
+      };
+      setTimeout(remove, 100);
+
+      return new Promise<AppLaunchResult>((resolve) => {
+        setTimeout(() => {
+          remove();
+          resolve(
+            new AppLaunchResult(
+              false,
+              'Browser cannot confirm app launch; timeout reached.',
+            ),
+          );
+        }, operationTimeout * 1000);
+      });
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      return Promise.resolve(new AppLaunchResult(false, message));
+    }
+  }
+}
+

package/src/moonbridge-ipc/general/app_launch/model/app_info.ts

@@ -0,0 +1,57 @@
+/**
+ * 应用启动标识
+ */
+export class AppLaunchIdentifier {
+  readonly windowsExecutable?: string;
+  readonly macOSBundleId?: string;
+  readonly iOSScheme?: string;
+  readonly androidPackageName?: string;
+
+  /**
+   * 构造函数
+   * @param windowsExecutable Windows 可执行文件名
+   * @param macOSBundleId macOS Bundle ID
+   * @param iOSScheme iOS URL Scheme
+   * @param androidPackageName Android 包名
+   */
+  constructor({
+    windowsExecutable,
+    macOSBundleId,
+    iOSScheme,
+    androidPackageName,
+  }: {
+    windowsExecutable?: string;
+    macOSBundleId?: string;
+    iOSScheme?: string;
+    androidPackageName?: string;
+  }) {
+    this.windowsExecutable = windowsExecutable;
+    this.macOSBundleId = macOSBundleId;
+    this.iOSScheme = iOSScheme;
+    this.androidPackageName = androidPackageName;
+  }
+}
+
+/**
+ * 应用安装路径
+ */
+export class AppInstallationPath {
+  readonly macOS?: string;
+  readonly windows?: string;
+
+  /**
+   * 构造函数
+   * @param macOS macOS 应用路径
+   * @param windows Windows 可执行文件路径
+   */
+  constructor({
+    macOS,
+    windows,
+  }: {
+    macOS?: string;
+    windows?: string;
+  }) {
+    this.macOS = macOS;
+    this.windows = windows;
+  }
+}

package/src/moonbridge-ipc/general/app_launch/model/app_launch_error_codes.ts

@@ -0,0 +1,16 @@
+/**
+ * 应用启动失败原因常量，供 AppLaunchResult.error 与业务层使用。
+ * 019-server-wake-fix: 便于业务层识别失败原因并展示对应提示。
+ */
+
+/** 应用未安装或路径无效 */
+export const APP_NOT_INSTALLED = 'APP_NOT_INSTALLED';
+
+/** 启动超时 */
+export const LAUNCH_TIMEOUT = 'LAUNCH_TIMEOUT';
+
+/** 权限拒绝 */
+export const PERMISSION_DENIED = 'PERMISSION_DENIED';
+
+/** 未知原因 */
+export const UNKNOWN = 'UNKNOWN';

package/src/moonbridge-ipc/general/app_launch/model/app_launch_models.ts

@@ -0,0 +1,35 @@
+/**
+ * 应用启动结果与启动参数，与 Flutter wake_app model/app_launch_models.dart 对齐。
+ */
+
+/**
+ * 应用启动结果，对应 Flutter AppLaunchResult。
+ */
+export class AppLaunchResult {
+  constructor(
+    public readonly success: boolean,
+    public readonly error?: string,
+  ) {}
+
+  get isSuccess(): boolean {
+    return this.success;
+  }
+}
+
+/**
+ * 各平台启动参数，对应 Flutter AppLaunchArguments。
+ * macOS/Windows 为命令行参数列表；iOS/Android 为键值对形式（如 name=value）。
+ */
+export class AppLaunchArguments {
+  constructor(
+    public readonly macOS: string[] = [],
+    public readonly windows: string[] = [],
+    public readonly iOS: string[] = [],
+    public readonly android: string[] = [],
+  ) {}
+}
+
+/** 空启动参数，与 Flutter emptyAppLaunchArguments 等价 */
+export const emptyAppLaunchArguments: AppLaunchArguments = Object.freeze(
+  new AppLaunchArguments([], [], [], []),
+);

package/src/moonbridge-ipc/general/app_launch/model/app_launch_models_extension.ts

@@ -0,0 +1,65 @@
+/**
+ * 基于当前运行环境（typeof window / process.platform）从 AppLaunchIdentifier、AppInstallationPath、AppLaunchArguments 取当前平台对应值。
+ * 与 Flutter 平台扩展语义一致。
+ */
+
+import { AppLaunchArguments } from './app_launch_models.js';
+import { AppInstallationPath, AppLaunchIdentifier } from './app_info.js';
+
+const isBrowser =
+  typeof window !== 'undefined' && typeof window.document !== 'undefined';
+
+/**
+ * 基于当前运行环境的模型扩展（013：一级函数收敛为类静态方法）。
+ */
+export class AppLaunchModelsExtension {
+  /**
+   * 当前平台下应用标识（可执行名/Bundle ID/Scheme/包名）。
+   * 浏览器视为 Web，返回 iOSScheme；Node 按 process.platform 返回对应字段。
+   */
+  static getCurrentPlatformIdentifier(
+    id: AppLaunchIdentifier,
+  ): string | undefined {
+    if (isBrowser) return id.iOSScheme;
+    if (typeof process !== 'undefined' && process.platform === 'win32') {
+      return id.windowsExecutable;
+    }
+    if (typeof process !== 'undefined' && process.platform === 'darwin') {
+      return id.macOSBundleId;
+    }
+    return undefined;
+  }
+
+  /**
+   * 当前平台下安装路径。仅 Node 桌面端有效；浏览器返回 undefined。
+   */
+  static getCurrentPlatformPath(
+    path: AppInstallationPath,
+  ): string | undefined {
+    if (isBrowser) return undefined;
+    if (typeof process !== 'undefined' && process.platform === 'win32') {
+      return path.windows;
+    }
+    if (typeof process !== 'undefined' && process.platform === 'darwin') {
+      return path.macOS;
+    }
+    return undefined;
+  }
+
+  /**
+   * 当前平台下启动参数数组。浏览器返回 iOS；Node 返回 windows/macOS 命令行参数。
+   */
+  static getCurrentPlatformArguments(
+    args: AppLaunchArguments,
+  ): string[] {
+    if (isBrowser) return args.iOS;
+    if (typeof process !== 'undefined' && process.platform === 'win32') {
+      return args.windows;
+    }
+    if (typeof process !== 'undefined' && process.platform === 'darwin') {
+      return args.macOS;
+    }
+    return [];
+  }
+}
+