@mearl/native-host 2.22.0 → 3.0.0-beta.0

package/dist/cloud-connector.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 daemon manager reserves a record while a connector starts; the connector
+ * process then owns its runtime state updates. This native-host reads the
+ * registry to adopt/list connectors and removes a record only while its pid still
+ * matches the process being stopped or reaped. A freshly started native-host
+ * verifies recorded pids and ADOPTS live connectors 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/config.d.ts

@@ -0,0 +1,7 @@
+export interface MearlConfig {
+    clientId?: string;
+    [key: string]: unknown;
+}
+export declare const MEARL_CONFIG_FILE: string;
+export declare function readMearlConfig(configFile?: string): MearlConfig;
+export declare function writeMearlConfig(config: MearlConfig, configFile?: string): void;

package/dist/control-session-manager.d.ts

@@ -0,0 +1,30 @@
+import { type ControlSessionInfo, type PageDownloadParams } from '@mearl/browser-core';
+import { ControlSessionRegistry } from './control-session.js';
+import { BrowserArtifactStore } from './browser-artifacts.js';
+interface Dependencies {
+    browserId: () => string;
+    transport: () => ControlSessionInfo['transport'];
+    invoke: (action: string, data: any, transport: ControlSessionInfo['transport']) => Promise<any>;
+    deactivate?: (tabs: number[], transport: ControlSessionInfo['transport']) => Promise<void>;
+    cleanup: (tabs: number[], transport: ControlSessionInfo['transport'], preserveEnvironment: boolean) => Promise<void>;
+    download: (data: PageDownloadParams, transport: ControlSessionInfo['transport'], origin: string) => Promise<{
+        filename: string;
+        filePath: string;
+        action: unknown;
+        owned?: boolean;
+        directory?: string;
+    }>;
+    notify: () => void;
+}
+export declare class ControlSessionManager {
+    private dependencies;
+    readonly registry: ControlSessionRegistry;
+    readonly artifacts: BrowserArtifactStore;
+    private activityQueues;
+    private withActivity;
+    constructor(dependencies: Dependencies);
+    private closeTabs;
+    userControl(id: string, operation: 'handoff' | 'resume' | 'release', reason?: string): Promise<ControlSessionInfo>;
+    invoke(action: string, data: any, sessionId?: string, requestedTransport?: 'cdp', origin?: string): Promise<any>;
+}
+export {};

package/dist/control-session.d.ts

@@ -0,0 +1,31 @@
+import { type ControlSessionInfo, type BrowserReleaseParams } from '@mearl/browser-core';
+/** Resource ownership survives individual CLI connections; queues serialize shared pages. */
+export declare class ControlSessionRegistry {
+    private browserId;
+    private sessions;
+    private owners;
+    private queues;
+    private pending;
+    private browserReleasing;
+    private resuming;
+    constructor(browserId: () => string);
+    private createSessionId;
+    create(transport: ControlSessionInfo['transport']): ControlSessionInfo;
+    info(id: string): ControlSessionInfo;
+    state(id: string): Omit<ControlSessionInfo, 'tabs'>;
+    find(id: string): ControlSessionInfo | undefined;
+    list(): ControlSessionInfo[];
+    private require;
+    private assertActive;
+    claim(id: string, tabId: number, source: 'created' | 'attached'): void;
+    blockedTabs(id?: string): number[];
+    assertBrowserRelease(): void;
+    releaseBrowser<T>(operation: () => Promise<T>): Promise<T>;
+    run<T>(id: string | undefined, action: string, data: any, operation: () => Promise<T>, transport?: ControlSessionInfo['transport']): Promise<T>;
+    waitForIdle(id: string): Promise<void>;
+    assertStep(id: string, generation: number): void;
+    recordResult(id: string, action: string, result: any, data?: any): void;
+    handoff(id: string, reason?: string): ControlSessionInfo;
+    resume(id: string, cleanup?: () => Promise<void>): Promise<ControlSessionInfo>;
+    release(id: string, params: BrowserReleaseParams, cleanup: (tabs: number[], close: number[]) => Promise<void>): Promise<ControlSessionInfo>;
+}

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

@@ -0,0 +1,7 @@
+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/extension-updater.d.ts

@@ -0,0 +1,18 @@
+import { updateSetupManagedBrowserExtensionFiles, type BrowserExtensionRelease } from '@mearl/setup/browser-extension';
+export interface SetupExtensionUpdateRequest {
+    currentVersion: string;
+    setupManagedPath: string;
+}
+export interface SetupExtensionUpdateResult {
+    changelogUrl: string;
+    updated: boolean;
+    version: string;
+}
+export interface SetupExtensionUpdaterDependencies {
+    fetchRelease?: () => Promise<BrowserExtensionRelease>;
+    isProcessAlive?: (pid: number) => boolean;
+    lockPath?: string;
+    now?: () => number;
+    updateFiles?: typeof updateSetupManagedBrowserExtensionFiles;
+}
+export declare function updateSetupManagedExtension(request: SetupExtensionUpdateRequest, dependencies?: SetupExtensionUpdaterDependencies): Promise<SetupExtensionUpdateResult>;

package/dist/host-updater.d.ts

@@ -0,0 +1,39 @@
+import { type CommandRunner } from '@mearl/daemon-core';
+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

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