@mearl/native-host 2.0.0

package/dist/install.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Unified Native Messaging Host installer for Mearl.
+ *
+ * Registers a Chrome Native Messaging Host manifest so that the browser
+ * extension can launch the native-host process via `chrome.runtime.connectNative()`.
+ *
+ * Both MCP and Skills integration modes share this installer. By default it
+ * installs both hosts (they run the same binary and share one Unix socket, so
+ * the two integrations can be used at the same time); pass a specific `--mode`
+ * (CLI) or `mode` option (API) to install just one.
+ *
+ * CLI:
+ *   mearl-native-host --init [--mode skills|mcp|both] [--extension-id <id>]
+ *
+ * API:
+ *   import { installNativeHost } from '@mearl/native-host';
+ *   await installNativeHost(); // installs both
+ */
+export type IntegrationMode = 'skills' | 'mcp';
+export interface InstallOptions {
+    /**
+     * Integration mode. Determines the host name. Defaults to `'both'`, which
+     * installs the manifests for both Skills and MCP so the two integrations can
+     * be used simultaneously (they share the same Unix socket and handlers).
+     */
+    mode?: IntegrationMode | 'both';
+    /** Chrome extension ID. Defaults to the published store ID. */
+    extensionId?: string;
+    /** Suppress console output when `true`. Uses stderr to avoid interfering with stdio transport. */
+    silent?: boolean;
+    /** Skip installation if the manifest file already exists. Defaults to `false`. */
+    skipIfExists?: boolean;
+}
+export declare function resolveHostDir(): string;
+export declare function installNativeHost(options?: InstallOptions): Promise<boolean>;
+export declare function runCli(argv: string[]): Promise<void>;

package/dist/install.js

@@ -0,0 +1,220 @@
+// src/install.ts
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+var DEFAULT_EXTENSION_ID = "aoehhjnofngknnjefamjbplchbolghkm";
+var HOST_NAME_BY_MODE = {
+  skills: "com.alibaba.mearl.skills",
+  mcp: "com.alibaba.mearl.mcp"
+};
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+var ALL_MODES = ["skills", "mcp"];
+function resolveHostDir() {
+  switch (process.platform) {
+    case "darwin":
+      return path.join(
+        os.homedir(),
+        "Library/Application Support/Google/Chrome/NativeMessagingHosts"
+      );
+    case "linux":
+      return path.join(os.homedir(), ".config/google-chrome/NativeMessagingHosts");
+    case "win32":
+      return path.join(
+        process.env.PROGRAMDATA || "C:\\ProgramData",
+        "Google\\Chrome\\NativeMessagingHosts"
+      );
+    default:
+      throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+}
+function resolveNativeHostPath() {
+  const siblingPath = path.join(__dirname, "index.js");
+  if (fs.existsSync(siblingPath)) {
+    return siblingPath;
+  }
+  try {
+    const require2 = createRequire(import.meta.url);
+    return require2.resolve("@mearl/native-host/runtime");
+  } catch {
+    throw new Error(
+      "Cannot locate native-host runtime entry point. Ensure @mearl/native-host is installed correctly."
+    );
+  }
+}
+function registerWindowsNativeHost(hostName, manifestPath) {
+  const regKey = `HKCU\\SOFTWARE\\Google\\Chrome\\NativeMessagingHosts\\${hostName}`;
+  execFileSync("reg", ["add", regKey, "/ve", "/t", "REG_SZ", "/d", manifestPath, "/f"], {
+    stdio: "pipe"
+  });
+}
+function createLauncherScript(hostDir, hostPath, hostName) {
+  const nodePath = path.resolve(process.execPath);
+  if (process.platform === "win32") {
+    const launcherPath2 = path.join(hostDir, `${hostName}-launcher.cmd`);
+    const content2 = `@echo off\r
+"${nodePath}" "${hostPath}" %*\r
+`;
+    fs.writeFileSync(launcherPath2, content2, "utf-8");
+    return launcherPath2;
+  }
+  const launcherPath = path.join(hostDir, `${hostName}-launcher.sh`);
+  const content = [
+    "#!/bin/sh",
+    `NODE_BIN=${JSON.stringify(nodePath)}`,
+    `HOST_SCRIPT=${JSON.stringify(hostPath)}`,
+    'exec "$NODE_BIN" "$HOST_SCRIPT" "$@"',
+    ""
+  ].join("\n");
+  fs.writeFileSync(launcherPath, content, "utf-8");
+  fs.chmodSync(launcherPath, 493);
+  return launcherPath;
+}
+async function installNativeHost(options = {}) {
+  const {
+    mode = "both",
+    extensionId = DEFAULT_EXTENSION_ID,
+    silent = false,
+    skipIfExists = false
+  } = options;
+  if (mode === "both") {
+    const results = await Promise.all(
+      ALL_MODES.map((m) => installNativeHost({ ...options, mode: m }))
+    );
+    return results.every(Boolean);
+  }
+  const hostName = HOST_NAME_BY_MODE[mode];
+  if (!hostName) {
+    throw new Error(`Unknown mode: ${mode}. Expected 'skills' or 'mcp'.`);
+  }
+  const log = (...args) => {
+    if (!silent) console.error(...args);
+  };
+  try {
+    const hostDir = resolveHostDir();
+    if (skipIfExists) {
+      const manifestPath2 = path.join(hostDir, `${hostName}.json`);
+      if (fs.existsSync(manifestPath2)) {
+        log(`✅ Already installed: ${manifestPath2}`);
+        return true;
+      }
+    }
+    if (!fs.existsSync(hostDir)) {
+      fs.mkdirSync(hostDir, { recursive: true });
+      log(`✅ Created directory: ${hostDir}`);
+    }
+    const resolvedHostPath = resolveNativeHostPath();
+    log(`✅ Native host path: ${resolvedHostPath}`);
+    const launcherPath = createLauncherScript(hostDir, resolvedHostPath, hostName);
+    log(`✅ Launcher script: ${launcherPath}`);
+    const manifest = {
+      name: hostName,
+      description: "Mearl Native Messaging Bridge",
+      path: launcherPath,
+      type: "stdio",
+      allowed_origins: [`chrome-extension://${extensionId}/`]
+    };
+    const manifestPath = path.join(hostDir, `${hostName}.json`);
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    if (process.platform === "win32") {
+      registerWindowsNativeHost(hostName, manifestPath);
+      log(`✅ Windows registry key created for: ${hostName}`);
+    } else {
+      fs.chmodSync(manifestPath, 420);
+    }
+    log(`✅ Manifest installed: ${manifestPath}`);
+    log(`✅ Extension ID: ${extensionId}`);
+    log(`✅ Host name: ${hostName}`);
+    return true;
+  } catch (error) {
+    log(`❌ Installation failed: ${error instanceof Error ? error.message : String(error)}`);
+    if (error instanceof Error && "code" in error && error.code === "EACCES") {
+      log("\n   Permission denied. Try running with sudo.");
+    }
+    return false;
+  }
+}
+function parseCliArgs(argv) {
+  let mode = "both";
+  let extensionId;
+  let skipIfExists = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      return { showHelp: true, mode, skipIfExists };
+    }
+    if (arg === "--mode" || arg.startsWith("--mode=")) {
+      const value = arg.includes("=") ? arg.slice("--mode=".length) : argv[++i];
+      if (value !== "skills" && value !== "mcp" && value !== "both") {
+        console.error(`❌ Invalid mode: ${value}. Expected 'skills', 'mcp', or 'both'.`);
+        process.exit(1);
+      }
+      mode = value;
+      continue;
+    }
+    if (arg === "--extension-id" || arg.startsWith("--extension-id=")) {
+      extensionId = arg.includes("=") ? arg.slice("--extension-id=".length) : argv[++i];
+      continue;
+    }
+    if (arg === "--skip-if-exists") {
+      skipIfExists = true;
+      continue;
+    }
+    if (arg === "--init") {
+      continue;
+    }
+  }
+  return { showHelp: false, mode, extensionId, skipIfExists };
+}
+function printHelp() {
+  console.error(`Usage:
+  mearl-native-host --init [options]
+
+Options:
+  --mode <skills|mcp|both> Integration mode (default: both — installs both hosts)
+  --extension-id <id>      Chrome extension ID (default: ${DEFAULT_EXTENSION_ID})
+  -h, --help               Show this help message
+
+Examples:
+  mearl-native-host --init
+  mearl-native-host --init --mode mcp
+  mearl-native-host --init --extension-id abcdefghijklmnopqrstuvwxyzabcdef`);
+}
+async function runCli(argv) {
+  const parsed = parseCliArgs(argv);
+  if (parsed.showHelp) {
+    printHelp();
+    process.exit(0);
+  }
+  if (parsed.extensionId && !/^[a-z]{32}$/.test(parsed.extensionId)) {
+    console.error(`❌ Invalid extension ID: ${parsed.extensionId}`);
+    console.error("   Must be a 32-character lowercase string (see chrome://extensions/)");
+    process.exit(1);
+  }
+  const success = await installNativeHost({
+    mode: parsed.mode,
+    extensionId: parsed.extensionId,
+    skipIfExists: parsed.skipIfExists
+  });
+  if (success) {
+    console.error(`
+✅ Installation complete!
+
+Next steps:
+1. Ensure Chrome is running (the extension auto-connects to native host)
+2. Start using CLI commands
+
+Verify:
+  mearl get_requests --payload '{"count":1}'
+`);
+  }
+  process.exit(success ? 0 : 1);
+}
+export {
+  installNativeHost,
+  resolveHostDir,
+  runCli
+};

package/dist/managed-browser.d.ts

@@ -0,0 +1,85 @@
+/** 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';
+export type ManagedBrowserUserAgentMode = 'default' | 'desktop';
+export interface ManagedBrowserLaunchParams {
+    name: string;
+    headless?: boolean;
+    userAgentMode?: ManagedBrowserUserAgentMode;
+    persistent?: boolean;
+    executablePath?: string;
+    url?: string;
+    accountId?: string | number;
+    havanaId?: string | number;
+    site?: string | number;
+    query?: string;
+    tabId?: number;
+    copyCookieDomains?: string[];
+}
+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;
+    headless: boolean;
+    persistent: boolean;
+    cdpPort: number;
+    createdAt: string;
+    account?: ManagedBrowserRecord['account'];
+    copiedCookies?: ManagedBrowserRecord['copiedCookies'];
+    running: boolean;
+}
+export interface ManagedBrowserManagerDeps {
+    nativeHostScript: string;
+    prepareTdbankSso: (data: ManagedBrowserLaunchParams) => Promise<TdbankSsoTicket>;
+    exportCookies: (domains: string[]) => Promise<TransferableCookie[]>;
+    log: (...args: any[]) => void;
+}
+/** 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 launchManagedBrowser(input: ManagedBrowserLaunchParams, deps: ManagedBrowserManagerDeps): Promise<Record<string, any>>;
+export declare function closeManagedBrowser(selector: string, options?: {
+    deleteProfile?: boolean;
+}): Promise<Record<string, any>>;
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mearl/native-host",
+  "version": "2.0.0",
+  "description": "Native Messaging Host for Mearl — bridges Chrome Extension and local socket server",
+  "type": "module",
+  "main": "dist/install.js",
+  "types": "dist/install.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/install.d.ts",
+      "default": "./dist/install.js"
+    },
+    "./runtime": "./dist/index.js"
+  },
+  "bin": {
+    "mearl-native-host": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mearl",
+    "chrome-extension",
+    "native-messaging"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@agentclientprotocol/sdk": "^1.2.1",
+    "@types/node": "^24.9.1",
+    "esbuild": "^0.25.2",
+    "typescript": "^5.8.3",
+    "@mearl/daemon-core": "2.0.0",
+    "@mearl/browser-core": "2.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist/ && node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "postinstall": "node dist/index.js --init || true"
+  }
+}