@mearl/native-host 2.7.2 → 2.8.0

package/dist/cdp-backend/discover.d.ts

@@ -1,28 +0,0 @@
-/**
- * CDP target discovery.
- *
- * Strategy (in order):
- * 1. Read Chrome's DevToolsActivePort file — written by Chrome when remote
- *    debugging is enabled (including via chrome://inspect/#remote-debugging).
- *    Contains the actual port and browser WebSocket path.
- * 2. Fall back to HTTP /json REST API on the given port (requires Chrome
- *    launched with --remote-debugging-port).
- */
-export interface CdpTarget {
-    id: string;
-    title: string;
-    type: string;
-    url: string;
-    webSocketDebuggerUrl: string;
-    faviconUrl?: string;
-}
-/**
- * Read Chrome's DevToolsActivePort file.
- * Returns { port, browserWsPath } or null if unavailable.
- */
-export declare function readDevToolsActivePort(userDataDir?: string): {
-    port: number;
-    browserWsPath: string;
-} | null;
-export declare function discoverTargets(port?: number): Promise<CdpTarget[]>;
-export declare function isCdpAvailable(port?: number, userDataDir?: string): Promise<boolean>;

package/dist/cdp-backend/domain-manager.d.ts

@@ -1,4 +0,0 @@
-import type { CdpChildSession, CdpClient } from './client.js';
-type DomainClient = CdpClient | CdpChildSession;
-export declare function ensureCdpDomain(client: DomainClient, domain: string, params?: Record<string, unknown>): Promise<void>;
-export {};

package/dist/cdp-backend/handlers.d.ts

@@ -1,31 +0,0 @@
-/**
- * CDP backend action handlers — re-export hub.
- *
- * All handler implementations live in dedicated sub-modules.
- * Importing this file triggers side-effect registrations in the action registry.
- */
-import './request-handlers.js';
-import './mock-handlers.js';
-import './http-handlers.js';
-import './browser-handlers.js';
-import './tdbank-handlers.js';
-import './tab-handlers.js';
-import './interaction-handlers.js';
-import './timezone-handlers.js';
-import './cookie-handlers.js';
-import './snapshot-handlers.js';
-import './recording-handlers.js';
-import './composite-handlers.js';
-export { dispatchCdpAction, getRegisteredActionNames } from './action-registry.js';
-export { cdpGetRequests, cdpGetLogs, cdpGetEvents } from './request-handlers.js';
-export { cdpSetMock, cdpGetMocks } from './mock-handlers.js';
-export { cdpSendRequest, cdpSendMtopRequest, cdpGetApiSchema } from './http-handlers.js';
-export { cdpPageScreenshot, cdpPageSelectedElement, cdpGetUserInfo } from './browser-handlers.js';
-export { cdpTdbankAccount } from './tdbank-handlers.js';
-export { cdpTabOpen, cdpTabClose, cdpTabList } from './tab-handlers.js';
-export { cdpPageClick, cdpPageType, cdpPageScroll, cdpPageEval, cdpPagePress, cdpPageWait, cdpPageNavigate, cdpPageUpload, cdpSetDeviceEmulation, } from './interaction-handlers.js';
-export { cdpPageSnapshot, cdpPageFrames } from './snapshot-handlers.js';
-export { cdpRecordStart, cdpRecordStop } from './recording-handlers.js';
-export { cdpRunActions, cdpObservedPageAction } from './composite-handlers.js';
-export { cdpSetTimezone } from './timezone-handlers.js';
-export { cdpGetCookie, cdpSetCookie } from './cookie-handlers.js';

package/dist/cdp-backend/http-handlers.d.ts

@@ -1,8 +0,0 @@
-/**
- * CDP HTTP proxy / MTOP request / API schema handlers.
- */
-import { type GetApiSchemaParams, type SendMtopRequestParams, type SendRequestParams } from '@mearl/browser-core';
-import type { PageSession } from './cdp-session.js';
-export declare function cdpSendRequest(session: PageSession, data: SendRequestParams): Promise<any>;
-export declare function cdpSendMtopRequest(session: PageSession, data: SendMtopRequestParams): Promise<any>;
-export declare function cdpGetApiSchema(session: PageSession, data: GetApiSchemaParams): Promise<any>;

package/dist/cdp-backend/interaction-handlers.d.ts

@@ -1,18 +0,0 @@
-/**
- * CDP page interaction handlers.
- *
- * Covers: click, type, scroll, eval, press, wait, navigate, upload, device emulation.
- */
-import { type PageClickParams, type PageDragParams, type PageDragResultData, type PageEvalParams, type PageHoverParams, type PageNavigateParams, type PagePressParams, type PageScrollParams, type PageTypeParams, type PageUploadParams, type PageWaitParams, type SetDeviceEmulationParams } from '@mearl/browser-core';
-import type { PageSession } from './cdp-session.js';
-export declare function cdpPageClick(session: PageSession, data: PageClickParams): Promise<any>;
-export declare function cdpPageDrag(session: PageSession, data: PageDragParams): Promise<PageDragResultData>;
-export declare function cdpPageType(session: PageSession, data: PageTypeParams): Promise<any>;
-export declare function cdpPageScroll(session: PageSession, data: PageScrollParams): Promise<any>;
-export declare function cdpPageEval(session: PageSession, data: PageEvalParams): Promise<any>;
-export declare function cdpPagePress(session: PageSession, data: PagePressParams): Promise<any>;
-export declare function cdpPageWait(session: PageSession, data: PageWaitParams): Promise<any>;
-export declare function cdpPageNavigate(session: PageSession, data: PageNavigateParams): Promise<any>;
-export declare function cdpPageUpload(session: PageSession, data: PageUploadParams): Promise<any>;
-export declare function cdpSetDeviceEmulation(session: PageSession, data: SetDeviceEmulationParams): Promise<any>;
-export declare function cdpPageHover(session: PageSession, data: PageHoverParams): Promise<any>;

package/dist/cdp-backend/mock-handlers.d.ts

@@ -1,9 +0,0 @@
-/**
- * CDP mock interception handlers.
- */
-import { type GetMocksParams, type SetMockParams } from '@mearl/browser-core';
-import type { PageSession } from './cdp-session.js';
-/** browser_release 使用：丢弃所有依赖当前 CDP 会话的 mock 状态。 */
-export declare function clearCdpMockState(): void;
-export declare function cdpSetMock(session: PageSession, data: SetMockParams): Promise<any>;
-export declare function cdpGetMocks(_session: PageSession, _data: GetMocksParams): any;

package/dist/cdp-backend/navigation-observer.d.ts

@@ -1,9 +0,0 @@
-import { type PageActNavigationObserver } from '@mearl/browser-core';
-import type { CdpSession, PageSession } from './cdp-session.js';
-export declare function startCdpNavigationObserver(cdpSession: CdpSession, pageSession: PageSession, urlBefore: string, options?: {
-    trackNetwork?: boolean;
-    networkIdleMs?: number;
-    contentReadyAfterMs?: number;
-    trackOpenedTabs?: boolean;
-    sourceTabId?: number;
-}): Promise<PageActNavigationObserver>;

package/dist/cdp-backend/page-observer.d.ts

@@ -1,5 +0,0 @@
-import { type PageChangeSet, type PageObservationCheckpoint, type PageObservationWaitOptions } from '@mearl/browser-core';
-import type { PageSession } from './cdp-session.js';
-export declare function startPageObservation(session: PageSession): Promise<PageObservationCheckpoint>;
-export declare function finishPageObservation(session: PageSession, checkpoint: PageObservationCheckpoint, options?: PageObservationWaitOptions): Promise<PageChangeSet>;
-export declare function disposePageObservation(session: PageSession): Promise<void>;

package/dist/cdp-backend/page-refs.d.ts

@@ -1,9 +0,0 @@
-import { BackendNodeRefRegistry, type BackendNodeSnapshotRefAllocator, type PageChangeSet, type PageEffectRefEntry } from '@mearl/browser-core';
-import type { PageSession } from './cdp-session.js';
-export type PageRefEntry = PageEffectRefEntry;
-export declare function getPageRefRegistry(session: PageSession): BackendNodeRefRegistry<PageRefEntry>;
-export declare function beginPageSnapshotRefs(session: PageSession): BackendNodeSnapshotRefAllocator<PageRefEntry>;
-export declare function resolvePageRef(session: PageSession, ref: string): PageRefEntry | undefined;
-export declare function deletePageRef(session: PageSession, ref: string): void;
-export declare function clearPageRefsForNavigation(session: PageSession): void;
-export declare function enrichCdpPageChangeSetWithRefs(session: PageSession, observation: PageChangeSet): Promise<PageChangeSet>;

package/dist/cdp-backend/recording-handlers.d.ts

@@ -1,12 +0,0 @@
-/**
- * CDP recording session handlers.
- *
- * Manages browser-side action recording via Runtime.addBinding +
- * Page.addScriptToEvaluateOnNewDocument.
- */
-import { type RecordParams } from '@mearl/browser-core';
-import type { PageSession } from './cdp-session.js';
-export declare function cdpRecordStart(session: PageSession, _data: RecordParams): Promise<any>;
-export declare function cdpRecordStop(session: PageSession, _data: RecordParams): Promise<any>;
-/** browser_release 使用：停止仍存活页面的录制，并丢弃已失效 target 的残留状态。 */
-export declare function releaseCdpRecordings(sessions: PageSession[]): Promise<void>;

package/dist/cdp-backend/release-control.d.ts

@@ -1,13 +0,0 @@
-/**
- * Browser-level CDP control release.
- *
- * Closes Mearl's browser/page WebSocket sessions while keeping Chrome and all
- * targets alive. A later browser action may create a fresh CdpSession.
- */
-import type { CdpSession } from './cdp-session.js';
-export interface CdpReleaseResult {
-    released: boolean;
-    hadActiveControl: boolean;
-    affectedTabIds: number[];
-}
-export declare function releaseCdpControl(session: CdpSession): Promise<CdpReleaseResult>;

package/dist/cdp-backend/request-handlers.d.ts

@@ -1,10 +0,0 @@
-/**
- * CDP request/log/event buffer query handlers.
- */
-import type { CaptureCheckpointParams, GetEventsParams, GetLogsParams, GetRequestsParams, PageDiagnosticsOptions } from '@mearl/browser-core';
-import type { PageSession } from './cdp-session.js';
-export declare function cdpGetRequests(session: PageSession, data: GetRequestsParams): Promise<any>;
-export declare function cdpGetLogs(session: PageSession, data: GetLogsParams): Promise<any>;
-export declare function cdpCaptureCheckpoint(session: PageSession, _data: CaptureCheckpointParams): Promise<any>;
-export declare function collectCdpPageDiagnostics(session: PageSession, after: string, diagnostics: PageDiagnosticsOptions): Promise<Record<string, any>>;
-export declare function cdpGetEvents(session: PageSession, data: GetEventsParams): Promise<any>;

package/dist/cdp-backend/send-request.d.ts

@@ -1,2 +0,0 @@
-import { type SendRequestParams } from '@mearl/browser-core';
-export declare function executeNodeSendRequest(data: SendRequestParams, cookieMap?: Map<string, string>): Promise<any>;

package/dist/cdp-backend/snapshot-handlers.d.ts

@@ -1,7 +0,0 @@
-/**
- * CDP accessibility tree snapshot and frame handlers.
- */
-import { type PageFramesParams, type PageSnapshotParams } from '@mearl/browser-core';
-import type { PageSession } from './cdp-session.js';
-export declare function cdpPageSnapshot(session: PageSession, data: PageSnapshotParams): Promise<any>;
-export declare function cdpPageFrames(session: PageSession, _data: PageFramesParams): Promise<any>;

package/dist/cdp-backend/tab-handlers.d.ts

@@ -1,8 +0,0 @@
-/**
- * CDP tab management handlers.
- */
-import { type ControlSource, type TabCloseParams, type TabOpenParams } from '@mearl/browser-core';
-import type { CdpSession } from './cdp-session.js';
-export declare function cdpTabOpen(session: CdpSession, data: TabOpenParams, controlSource?: ControlSource): Promise<any>;
-export declare function cdpTabClose(session: CdpSession, data: TabCloseParams): Promise<any>;
-export declare function cdpTabList(session: CdpSession, _data: any): Promise<any>;

package/dist/cdp-backend/tdbank-handlers.d.ts

@@ -1,14 +0,0 @@
-/**
- * CDP TDBank account handlers.
- *
- * Manages TDBank account listing, switching, borrowing via CDP cookie-based auth.
- */
-import { type TdbankAccountParams } from '@mearl/browser-core';
-import type { CdpSession } from './cdp-session.js';
-/** Prepare a TDBank SSO ticket without changing the controller browser account. */
-export declare function cdpPrepareTdbankSso(cdpSession: CdpSession, data: TdbankAccountParams): Promise<any>;
-/** Consume a TDBank SSO ticket inside an isolated managed browser. */
-export declare function cdpConsumeTdbankSso(cdpSession: CdpSession, ssoUrl: string, expectedLoginId?: string): Promise<{
-    nickname: string;
-}>;
-export declare function cdpTdbankAccount(cdpSession: CdpSession, data: TdbankAccountParams): Promise<any>;

package/dist/cdp-backend/timezone-handlers.d.ts

@@ -1,4 +0,0 @@
-/** CDP timezone override handler. */
-import type { SetTimezoneParams } from '@mearl/browser-core';
-import type { PageSession } from './cdp-session.js';
-export declare function cdpSetTimezone(session: PageSession, data: SetTimezoneParams): Promise<any>;

package/dist/cloud-connector.d.ts

@@ -1,61 +0,0 @@
-/**
- * Cloud connector process management — start/stop/list cloud-connector
- * child processes that bridge the local native-host to remote cloud servers.
- *
- * Lifecycle design
- * ----------------
- * cloud-connector processes are spawned `detached` and intentionally OUTLIVE
- * the native-host that started them. The native-host is an ephemeral broker:
- * Chrome kills it whenever the extension reloads / updates (stdin EOF). If a
- * connector were a normal child it would die with that broker, tearing down the
- * cloud bridge on every extension reload.
- *
- * Shared registry & ownership
- * ---------------------------
- * Connectors are also self-manageable from the terminal (`cloud-connector start
- * <url>`), so the host-managed and self-managed modes must not fight over the
- * same connector. They interoperate through a single shared registry under
- * ~/.mearl/connectors/ (one JSON record per serverUrl), with paths
- * derived via @mearl/daemon-core so both sides agree on locations.
- *
- * The CONNECTOR PROCESS is the sole writer of its own record (it writes on
- * connect, removes on graceful exit). This native-host only READS the registry
- * to adopt/list connectors, and best-effort removes a record when it stops or
- * reaps one. A freshly started native-host reads the registry, verifies the
- * recorded pids are still alive, and ADOPTS them instead of spawning duplicates.
- * Starting a connector is therefore idempotent: if a healthy one already exists
- * for the serverUrl (started by us, a previous host, or the daemon CLI) we reuse
- * it. Connectors die only when explicitly stopped, when they exit on their own,
- * or when the machine reboots — never merely because the broker restarted.
- */
-export interface CloudConnectorListItem {
-    serverUrl: string;
-    pid: number;
-    connectorId?: string;
-    name?: string;
-}
-export interface CloudConnectorListResult {
-    connectors: CloudConnectorListItem[];
-}
-/**
- * Initialise module-level dependencies. Must be called before any other export.
- */
-export declare function initCloudConnector(deps: {
-    log: (...args: any[]) => void;
-    isDaemonMode: boolean;
-    sendToExtension: (message: Record<string, any>) => void;
-    version: string;
-}): void;
-export declare function startCloudConnector(serverUrl: string): Promise<{
-    success: boolean;
-    pid?: number;
-    connectorId?: string;
-    name?: string;
-    reused?: boolean;
-    error?: string;
-}>;
-export declare function stopCloudConnector(serverUrl: string): {
-    success: boolean;
-    error?: string;
-};
-export declare function listCloudConnectors(): CloudConnectorListResult;

package/dist/extension-file-transfer.d.ts

@@ -1,7 +0,0 @@
-import { type RunActionsParams, type SendRequestParams } from '@mearl/browser-core';
-type SendExtensionTransferAction = (action: string, data: any, timeoutMs: number) => Promise<any>;
-export declare function hasSendRequestFiles(data: unknown): boolean;
-export declare function hasRunActionsSendRequestFiles(data: unknown): boolean;
-export declare function sendRequestWithTransferredFiles(data: SendRequestParams, send: SendExtensionTransferAction): Promise<any>;
-export declare function sendRunActionsWithTransferredFiles(data: RunActionsParams, send: SendExtensionTransferAction, resolveTimeoutMs: (data: RunActionsParams) => number): Promise<any>;
-export {};

package/dist/host-updater.d.ts

@@ -1,39 +0,0 @@
-import { type CommandRunner } from '@mearl/setup/process';
-export declare const NATIVE_HOST_UPDATE_TIMEOUT_MS: number;
-export type NativeHostUpdateError = 'lock-timeout' | 'network' | 'package-unavailable' | 'setup-failed' | 'timeout' | 'verification-failed' | 'unknown';
-export interface NativeHostUpdateCommand {
-    args: string[];
-}
-type UpdateLockRunner = <T>(targetVersion: string, operation: () => Promise<T>) => Promise<T>;
-export interface RunNativeHostUpdateOptions {
-    areTargetsInstalled?: (targetReleaseLine: string, environment: NodeJS.ProcessEnv) => Promise<boolean>;
-    environment?: NodeJS.ProcessEnv;
-    nodePath?: string;
-    packageBinDirectory?: string | null;
-    packageManagerCommand?: string | null;
-    packageRunner?: string;
-    platform?: NodeJS.Platform;
-    runner?: CommandRunner;
-    timeoutMs?: number;
-    updateLockPath?: string;
-    withUpdateLock?: UpdateLockRunner;
-}
-export interface NativeHostUpdateCoordinatorOptions {
-    hostVersion: string;
-    log: (...args: unknown[]) => void;
-    requestRestart: () => void | Promise<void>;
-    runUpdate: (targetVersion: string) => Promise<void>;
-}
-export declare class NativeHostUpdateFailure extends Error {
-    readonly updateError: NativeHostUpdateError;
-    constructor(updateError: NativeHostUpdateError, message: string);
-}
-export declare function nativeHostUpdateCommand(targetVersion: string): NativeHostUpdateCommand;
-export declare function runNativeHostUpdate(targetVersion: string, options?: RunNativeHostUpdateOptions): Promise<void>;
-export declare class NativeHostUpdateCoordinator {
-    #private;
-    private readonly options;
-    constructor(options: NativeHostUpdateCoordinatorOptions);
-    evaluate(extensionVersion: unknown, checkForUpdates: unknown): void;
-}
-export {};

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/internal-extension-actions.d.ts

@@ -1,9 +0,0 @@
-import { type ControlSource, type ControlSourceWireValue } from '@mearl/browser-core';
-export declare function isInternalExtensionAction(action: unknown): boolean;
-export declare function createExtensionRequestMessage(id: string, action: string, data: any, trustedInternal?: boolean, controlSource?: ControlSource): {
-    id: string;
-    action: string;
-    data: any;
-    controlSource: ControlSourceWireValue;
-    trustedInternal?: true;
-};

package/dist/managed-browser.d.ts

@@ -1,78 +0,0 @@
-/** Managed Chrome lifecycle for isolated, optionally headless browser instances. */
-import { type DaemonRecord } from '@mearl/daemon-core';
-import { type TransferableCookie } from './cdp-backend/cookie-transfer.js';
-import type { BrowserLaunchParams } from '@mearl/browser-core';
-export type ManagedBrowserUserAgentMode = NonNullable<BrowserLaunchParams['userAgentMode']>;
-export interface TdbankSsoTicket {
-    ssoUrl: string;
-    account: {
-        accountId?: string;
-        havanaId: string;
-        site: string;
-        loginId?: string;
-    };
-}
-interface ManagedBrowserRecord extends DaemonRecord {
-    pid: number;
-    hostPid: number;
-    browserId: string;
-    name: string;
-    headless: boolean;
-    persistent: boolean;
-    userDataDir: string;
-    executablePath: string;
-    cdpPort: number;
-    createdAt: string;
-    account?: {
-        accountId?: string;
-        loginId?: string;
-        nickname: string;
-    };
-    copiedCookies?: {
-        domains: string[];
-        count: number;
-    };
-}
-export interface ManagedBrowserSummary {
-    browserId: string;
-    name: string;
-    provider: 'local';
-    headless: boolean;
-    persistent: boolean;
-    cdpPort: number;
-    createdAt: string;
-    account?: ManagedBrowserRecord['account'];
-    copiedCookies?: ManagedBrowserRecord['copiedCookies'];
-    running: boolean;
-}
-export interface ManagedBrowserManagerDeps {
-    nativeHostScript: string;
-    prepareTdbankSso: (data: BrowserLaunchParams) => Promise<TdbankSsoTicket>;
-    exportCookies: (domains: string[]) => Promise<TransferableCookie[]>;
-    log: (...args: any[]) => void;
-}
-export declare function validateName(value: unknown): string;
-/** Use one case-insensitive identity for registry, locking, and persistent profile paths. */
-export declare function managedBrowserId(name: string): string;
-export declare function chromeExecutableCandidates(platform?: NodeJS.Platform): string[];
-export declare function resolveChromeExecutable(explicitPath?: string): string;
-export declare function desktopChromeUserAgent(version: string, platform?: NodeJS.Platform): string;
-export declare function resolveChromeVersion(executablePath: string): string;
-export declare function resolveUserAgentMode(value: unknown): ManagedBrowserUserAgentMode;
-export declare function buildManagedChromeArgs(options: {
-    userDataDir: string;
-    headless: boolean;
-    userAgent?: string;
-}): string[];
-/** Verify both PID liveness and the instance-specific command line before managing a process. */
-export declare function isManagedProcess(pid: number, commandMarker: string, platform?: NodeJS.Platform): boolean;
-export declare function listManagedBrowsers(): ManagedBrowserSummary[];
-export declare function hasManagedBrowser(selector: string): boolean;
-export declare function waitForBrowserRegistration(browserId: string, expectedPid: number): Promise<void>;
-export declare function stopProcess(pid: number, commandMarker: string): Promise<void>;
-export declare function acquireLaunchLock(browserId: string): () => void;
-export declare function launchManagedBrowser(input: BrowserLaunchParams, deps: ManagedBrowserManagerDeps): Promise<Record<string, any>>;
-export declare function closeManagedBrowser(selector: string, options?: {
-    deleteProfile?: boolean;
-}): Promise<Record<string, any>>;
-export {};

package/dist/send-request-file-utils.d.ts

@@ -1,14 +0,0 @@
-import { type SendRequestFile } from '@mearl/browser-core';
-interface SendRequestFileDescriptor {
-    fieldName: string;
-    filename: string;
-    contentType: string;
-    byteLength: number;
-}
-export interface ResolvedSendRequestFile {
-    descriptor: SendRequestFileDescriptor;
-    filePath?: string;
-    content?: Buffer;
-}
-export declare function resolveSendRequestFiles(files: SendRequestFile[]): Promise<ResolvedSendRequestFile[]>;
-export {};

package/dist/version.d.ts

@@ -1 +0,0 @@
-export declare const NATIVE_HOST_VERSION: string;