@chrome-in-harness/launcher 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# @chrome-in-harness/launcher
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文](#中文) | [English](#english)
+
+`chrome-in-harness` CLI：一条命令完成「启动本地 server + 写 MCP 客户端配置」，并提供可选的常驻服务注册。
+
+> npm 包名是 `@chrome-in-harness/launcher`，bin 名是 `chrome-in-harness`，因此用法是 `npx @chrome-in-harness/launcher <command>`。
+
+## 中文
+
+### 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `start` | 前台启动本地 server（Ctrl-C 退出）；已运行则复用；同时向 OpenCode 全局配置写入 MCP 条目 |
+| `doctor` | 环境自检：server 是否运行、扩展是否连通（真发一次 `ping`）、检测常见 MCP 客户端配置文件 |
+| `service install` | 注册常驻服务：macOS launchd / Linux systemd --user（登录自启 + 崩溃自动拉起） |
+| `service status` | 查看服务安装状态与 server 运行状态 |
+| `service uninstall` | 停止并移除常驻服务 |
+| （无参数） | 帮助信息 |
+
+### 实现要点
+
+- **server 入口解析**：`import.meta.resolve('@chrome-in-harness/server')` 经 npm 依赖解析拿到入口文件，不硬编码路径
+- **MCP 配置写入**（`writeOpencodeConfig`）：
+  - 已有同名 `chrome-in-harness` 条目 → 原样保留（逐字节不动）
+  - 配置文件不存在 → 创建配置目录并写入（文件权限 0600）
+  - 配置文件非法（坏 JSON / 非对象 / `mcp` 段非对象）→ **报错退出，不覆盖原文件**
+- **常驻服务**（`src/service.ts`，文件生成是纯函数、系统命令可注入，全程单测覆盖）：
+  - macOS：`~/Library/LaunchAgents/com.chrome-in-harness.server.plist`（`RunAtLoad` + `KeepAlive`），日志 `~/Library/Logs/chrome-in-harness-server.log`
+  - Linux：`~/.config/systemd/user/chrome-in-harness.service`（`Restart=always`），日志走 journalctl
+  - 已安装时再次 `install` 拒绝覆盖；`launchctl load` 失败会回滚已写的 plist，不留半安装状态
+  - Windows 不支持，明确报错并建议 `start` + 进程守护
+- **CLI 入口拆分**：执行逻辑在 `src/cli.ts`（可被测试 import 且不自动执行），`src/bin.ts` 只做入口引导——通过 symlink 安装、路径含空格也能正确判定入口
+
+### 与其他包的关系
+
+launcher 只负责生命周期与配置：server 进程来自 `@chrome-in-harness/server`，浏览器操作全部在扩展内完成。launcher 不是源码 watcher，迭代开发请用仓库根的 `npm run dev:server`。
+
+---
+
+## English
+
+The `chrome-in-harness` CLI: one command to start the local server and register the MCP client config, plus an opt-in persistent-service installer.
+
+> The npm package is `@chrome-in-harness/launcher` while the bin is `chrome-in-harness`, so usage is `npx @chrome-in-harness/launcher <command>`.
+
+### Commands
+
+| Command | What it does |
+| --- | --- |
+| `start` | Start the local server in the foreground (Ctrl-C to stop); reuses an already-running server; also writes the MCP entry into the OpenCode global config |
+| `doctor` | Environment check: is the server running, is the extension connected (performs a real `ping`), and detects common MCP client config files |
+| `service install` | Install a persistent user service: launchd on macOS / systemd --user on Linux (start at login + auto-restart on crash) |
+| `service status` | Show service installation and server running state |
+| `service uninstall` | Stop and remove the persistent service |
+| (no args) | Help |
+
+### Implementation notes
+
+- **Server entry resolution**: `import.meta.resolve('@chrome-in-harness/server')` resolves the entry via npm dependency resolution — no hardcoded paths
+- **MCP config write** (`writeOpencodeConfig`):
+  - An existing `chrome-in-harness` entry is preserved byte for byte
+  - Missing config → the directory is created and the file written (mode 0600)
+  - Invalid config (broken JSON / non-object / non-object `mcp` section) → **errors out without touching the original file**
+- **Persistent service** (`src/service.ts`; file generation is a pure function and system commands are injectable, fully unit-tested):
+  - macOS: `~/Library/LaunchAgents/com.chrome-in-harness.server.plist` (`RunAtLoad` + `KeepAlive`), logs at `~/Library/Logs/chrome-in-harness-server.log`
+  - Linux: `~/.config/systemd/user/chrome-in-harness.service` (`Restart=always`), logs via journalctl
+  - Re-running `install` while installed refuses to overwrite; a failed `launchctl load` rolls back the written plist, leaving no half-installed state
+  - Windows is unsupported and fails with an explicit message suggesting `start` plus a process supervisor
+- **CLI entry split**: the logic lives in `src/cli.ts` (importable by tests without side effects) while `src/bin.ts` is only the bootstrap — installs via symlinks and paths containing spaces are handled correctly
+
+### Relation to other packages
+
+The launcher only manages lifecycle and configuration: the server process comes from `@chrome-in-harness/server`, and all browser work happens inside the extension. The launcher is not a source watcher — use `npm run dev:server` from the repo root for development.

package/dist/bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { runCli } from './cli.js';
+runCli().catch((error) => {
+    console.error(`launcher failed: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+});

package/dist/cli.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * chrome-in-harness launcher：一条命令完成「检查/引导装扩展 + 起 server + 写 MCP 配置」。
+ *
+ * 用法：
+ *   npx @chrome-in-harness/launcher           检查环境并给出下一步
+ *   npx @chrome-in-harness/launcher start     启动本地 server（前台，Ctrl-C 退出）
+ *   npx @chrome-in-harness/launcher doctor    完整环境自检
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import net from 'node:net';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { installService, launchdPlistPath, systemdUnitPath, uninstallService } from './service.js';
+const SERVER_URL = 'http://127.0.0.1:12306/mcp';
+const WS_PORT = 8765;
+const HTTP_PORT = 12306;
+export function parseArgs(argv) {
+    const cmd = argv[2] ?? 'help';
+    if (cmd === 'start' || cmd === 'doctor')
+        return cmd;
+    if (cmd === 'service') {
+        const action = argv[3];
+        if (action === 'install' || action === 'uninstall' || action === 'status') {
+            return { service: action };
+        }
+    }
+    return 'help';
+}
+function log(msg) {
+    console.log(msg);
+}
+/** 探测 MCP 端口是否已有 server 监听（TCP 握手比 MCP 协议探测更可靠）。 */
+function isServerRunning() {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(1000);
+        socket.once('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once('timeout', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.once('error', () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.connect(HTTP_PORT, '127.0.0.1');
+    });
+}
+async function detectClients() {
+    const home = process.env['HOME'] ?? '';
+    const cwd = process.cwd();
+    const opencodeGlobal = path.join(home, '.config', 'opencode', 'opencode.json');
+    const opencodeJson = path.join(cwd, 'opencode.json');
+    const opencodeJsonc = path.join(cwd, 'opencode.jsonc');
+    const mcpJson = path.join(cwd, '.mcp.json');
+    const claudeConfig = path.join(home, '.claude.json');
+    const found = [];
+    for (const p of [opencodeGlobal, opencodeJson, opencodeJsonc, mcpJson, claudeConfig]) {
+        if (existsSync(p))
+            found.push(p);
+    }
+    if (found.length === 0) {
+        log('  未发现现有 MCP 客户端配置文件（opencode / .mcp.json / claude）。');
+    }
+    else {
+        log(`  发现配置文件：${found.join(', ')}`);
+    }
+}
+/** 检测扩展是否已装：通过 MCP tools/call ping 验证全链路（server+扩展）。 */
+async function pingExtension() {
+    try {
+        const res = await fetch(SERVER_URL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json, text/event-stream',
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 2,
+                method: 'tools/call',
+                params: { name: 'ping', arguments: {} },
+            }),
+            signal: AbortSignal.timeout(3000),
+        });
+        if (!res.ok)
+            return false;
+        const body = (await res.json());
+        const text = body.result?.content?.[0]?.text ?? '';
+        // ping 成功返回 {version, userAgent}
+        return text.includes('version') || text.includes('userAgent');
+    }
+    catch {
+        return false;
+    }
+}
+/** 合并 opencode 配置：插入 chrome-in-harness MCP 条目（不覆盖已有同名）。返回新配置对象（纯逻辑）。 */
+export function mergeOpencodeConfig(existing, url) {
+    const base = existing === undefined ? {} : { ...existing };
+    const currentMcp = base['mcp'];
+    if (currentMcp !== undefined && !isConfigObject(currentMcp)) {
+        throw new Error('OpenCode configuration mcp must be an object; the original file was not changed.');
+    }
+    const mcp = currentMcp ?? {};
+    if (mcp['chrome-in-harness'] !== undefined)
+        return { config: base, added: false };
+    return {
+        config: { ...base, mcp: { ...mcp, 'chrome-in-harness': { type: 'remote', url, enabled: true } } },
+        added: true,
+    };
+}
+function isConfigObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function readOpencodeConfig(configPath) {
+    let raw;
+    try {
+        raw = await readFile(configPath, 'utf8');
+    }
+    catch (error) {
+        if (isConfigObject(error) && error['code'] === 'ENOENT')
+            return {};
+        throw new Error(`Cannot read OpenCode configuration at ${configPath}; the original file was not changed.`, { cause: error });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON in OpenCode configuration at ${configPath}; the original file was not changed.`, { cause: error });
+    }
+    if (!isConfigObject(parsed)) {
+        throw new Error(`OpenCode configuration at ${configPath} must be an object; the original file was not changed.`);
+    }
+    return parsed;
+}
+/** 往 opencode 全局配置写入 MCP 条目（不覆盖已有同名条目）。 */
+export async function writeOpencodeConfig(configPath = path.join(homedir(), '.config', 'opencode', 'opencode.json')) {
+    const config = await readOpencodeConfig(configPath);
+    const { config: merged, added } = mergeOpencodeConfig(config, SERVER_URL);
+    if (!added) {
+        log('  opencode 配置已包含 chrome-in-harness，跳过。');
+        return;
+    }
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await writeFile(configPath, `${JSON.stringify(merged, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    log(`  已写入 opencode 全局配置: ${configPath}`);
+}
+async function doctor() {
+    log('chrome-in-harness doctor');
+    log('=======================');
+    const running = await isServerRunning();
+    log(running ? `[✓] server 已在运行 (${SERVER_URL})` : '[✗] server 未运行');
+    if (running) {
+        const ok = await pingExtension();
+        log(ok ? '[✓] 扩展已连接（ping 通过）' : '[✗] 扩展未连接（请确认已加载 Chrome 扩展）');
+    }
+    await detectClients();
+    log('\n下一步：');
+    log('  1. npx @chrome-in-harness/launcher start    # 启动 server');
+    log('  2. 在 Chrome 加载扩展（chrome://extensions → 开发者模式 → 加载已解压）');
+    log('  3. npx @chrome-in-harness/launcher doctor   # 复检全链路');
+}
+async function start() {
+    if (await isServerRunning()) {
+        log(`server 已在运行：${SERVER_URL}`);
+        await writeOpencodeConfig();
+        log('如扩展已加载，直接在客户端里调 ping 即可。');
+        return;
+    }
+    log('启动 chrome-in-harness server …');
+    // 解析 @chrome-in-harness/server 的入口文件（npm 依赖解析，无需硬编码路径）
+    let bin;
+    try {
+        bin = fileURLToPath(import.meta.resolve('@chrome-in-harness/server'));
+    }
+    catch {
+        log('未找到 @chrome-in-harness/server，请先安装依赖：npm i @chrome-in-harness/server');
+        process.exit(1);
+    }
+    log(`使用入口: ${bin}`);
+    await writeOpencodeConfig();
+    const child = spawn(process.execPath, [bin], {
+        stdio: 'inherit',
+        env: { ...process.env, WS_PORT: String(WS_PORT), HTTP_PORT: String(HTTP_PORT) },
+    });
+    child.on('exit', (code) => {
+        log(`\nserver 已退出 (code ${code ?? '?'})`);
+        process.exit(code ?? 0);
+    });
+    log('server 启动中。Ctrl-C 停止。');
+}
+/** service install 的 node / server 入口解析：node 用当前解释器，server 走 npm 依赖解析。 */
+function resolveServiceEntry() {
+    const serverEntry = fileURLToPath(import.meta.resolve('@chrome-in-harness/server'));
+    return { nodeBin: process.execPath, serverEntry };
+}
+async function service(action) {
+    if (action === 'status') {
+        const running = await isServerRunning();
+        const installed = existsSync(launchdPlistPath()) || existsSync(systemdUnitPath());
+        log(`service: ${installed ? '已安装（开机自启）' : '未安装'}`);
+        log(`server: ${running ? `运行中 (${SERVER_URL})` : '未运行'}`);
+        if (!installed) {
+            log('  提示：npx @chrome-in-harness/launcher service install 可注册常驻服务。');
+        }
+        return;
+    }
+    if (action === 'uninstall') {
+        await uninstallService();
+        log('service 已卸载（文件已删除，服务已停止）。');
+        return;
+    }
+    const { nodeBin, serverEntry } = resolveServiceEntry();
+    await installService({ nodeBin, serverEntry, wsPort: WS_PORT, httpPort: HTTP_PORT });
+    await writeOpencodeConfig();
+    const logHint = process.platform === 'darwin'
+        ? `日志: ${path.join(homedir(), 'Library', 'Logs', 'chrome-in-harness-server.log')}`
+        : '日志: journalctl --user -u chrome-in-harness.service';
+    log('service 已安装并启动：登录自启 + 崩溃自动拉起。');
+    log(`  ${logHint}`);
+}
+export async function runCli() {
+    const cmd = parseArgs(process.argv);
+    if (cmd === 'start')
+        await start();
+    else if (cmd === 'doctor')
+        await doctor();
+    else if (typeof cmd === 'object')
+        await service(cmd.service);
+    else {
+        log('chrome-in-harness — 通过 Chrome 扩展控制真实 Chrome profile 的浏览器 MCP');
+        log('');
+        log('用法：');
+        log('  npx @chrome-in-harness/launcher doctor           # 环境自检');
+        log('  npx @chrome-in-harness/launcher start            # 前台启动 server（Ctrl-C 退出）');
+        log('  npx @chrome-in-harness/launcher service install   # 注册常驻服务（launchd / systemd --user）');
+        log('  npx @chrome-in-harness/launcher service status    # 查看服务与运行状态');
+        log('  npx @chrome-in-harness/launcher service uninstall # 移除常驻服务');
+        log('');
+        log('扩展安装：chrome://extensions → 开发者模式 → 加载已解压的扩展程序');
+        log('  （从 GitHub Releases 下载 chrome-in-harness-extension.zip，或本仓库 packages/extension/.output/chrome-mv3）');
+    }
+}

package/dist/service.js

@@ -0,0 +1,153 @@
+/**
+ * 常驻服务安装：把本地 server 注册为登录自启 + 崩溃自动拉起的用户级服务。
+ * - macOS：launchd 用户代理（~/Library/LaunchAgents，RunAtLoad + KeepAlive）
+ * - Linux：systemd 用户单元（~/.config/systemd/user，Restart=always）
+ * 文件生成是纯函数（可单测）；install/uninstall 只做「写文件 + 调系统命令」的薄封装，
+ * 系统命令通过 run 注入，测试不打真 launchctl/systemctl。
+ */
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export const LAUNCHD_LABEL = 'com.chrome-in-harness.server';
+export const SYSTEMD_NAME = 'chrome-in-harness.service';
+export const defaultRunner = async (file, args) => {
+    try {
+        const { stdout, stderr } = await execFileAsync(file, args);
+        return { code: 0, stdout, stderr };
+    }
+    catch (error) {
+        const e = error;
+        return { code: e.code ?? 1, stdout: e.stdout ?? '', stderr: e.stderr ?? e.message };
+    }
+};
+export function launchdPlistPath(home = homedir()) {
+    return path.join(home, 'Library', 'LaunchAgents', `${LAUNCHD_LABEL}.plist`);
+}
+export function launchdLogPath(home = homedir()) {
+    return path.join(home, 'Library', 'Logs', 'chrome-in-harness-server.log');
+}
+export function systemdUnitPath(home = homedir()) {
+    return path.join(home, '.config', 'systemd', 'user', SYSTEMD_NAME);
+}
+export function buildLaunchdPlist(input) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${input.nodeBin}</string>
+    <string>${input.serverEntry}</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>WS_PORT</key><integer>${input.wsPort}</integer>
+    <key>HTTP_PORT</key><integer>${input.httpPort}</integer>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${input.logFile}</string>
+  <key>StandardErrorPath</key><string>${input.logFile}</string>
+</dict>
+</plist>
+`;
+}
+export function buildSystemdUnit(input) {
+    return `[Unit]
+Description=chrome-in-harness local MCP server
+After=network.target
+
+[Service]
+ExecStart=${input.nodeBin} ${input.serverEntry}
+Environment=WS_PORT=${input.wsPort}
+Environment=HTTP_PORT=${input.httpPort}
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}
+function normalizePlatform(platform) {
+    if (platform === 'darwin')
+        return 'darwin';
+    if (platform === 'linux')
+        return 'linux';
+    return 'unsupported';
+}
+export async function installService(options) {
+    const platform = normalizePlatform(options.platform ?? process.platform);
+    const run = options.run ?? defaultRunner;
+    if (platform === 'unsupported') {
+        throw new Error(`service install is not supported on ${String(options.platform ?? process.platform)}; ` +
+            'run "chrome-in-harness start" in a long-lived terminal instead.');
+    }
+    if (platform === 'darwin') {
+        const home = options.home ?? homedir();
+        const plist = launchdPlistPath(home);
+        if (existsSync(plist)) {
+            throw new Error(`service is already installed at ${plist}; run "service uninstall" first.`);
+        }
+        await mkdir(path.dirname(plist), { recursive: true });
+        await writeFile(plist, buildLaunchdPlist({
+            nodeBin: options.nodeBin,
+            serverEntry: options.serverEntry,
+            wsPort: options.wsPort,
+            httpPort: options.httpPort,
+            logFile: launchdLogPath(home),
+        }));
+        const result = await run('launchctl', ['load', plist]);
+        if (result.code !== 0) {
+            // 安装半途失败：清掉 plist，回到未安装状态，不留双态。
+            await rm(plist, { force: true });
+            throw new Error(`launchctl load failed: ${result.stderr.trim()}`);
+        }
+        return;
+    }
+    const home = options.home ?? homedir();
+    const unit = systemdUnitPath(home);
+    if (existsSync(unit)) {
+        throw new Error(`service is already installed at ${unit}; run "service uninstall" first.`);
+    }
+    await mkdir(path.dirname(unit), { recursive: true });
+    await writeFile(unit, buildSystemdUnit({
+        nodeBin: options.nodeBin,
+        serverEntry: options.serverEntry,
+        wsPort: options.wsPort,
+        httpPort: options.httpPort,
+    }));
+    const reload = await run('systemctl', ['--user', 'daemon-reload']);
+    const enable = await run('systemctl', ['--user', 'enable', '--now', SYSTEMD_NAME]);
+    if (reload.code !== 0 || enable.code !== 0) {
+        await rm(unit, { force: true });
+        await run('systemctl', ['--user', 'daemon-reload']).catch(() => undefined);
+        throw new Error(`systemctl enable failed: ${(enable.stderr || reload.stderr).trim()}`);
+    }
+}
+export async function uninstallService(options = {}) {
+    const platform = normalizePlatform(options.platform ?? process.platform);
+    const run = options.run ?? defaultRunner;
+    if (platform === 'unsupported') {
+        throw new Error(`service uninstall is not supported on ${String(options.platform ?? process.platform)}.`);
+    }
+    if (platform === 'darwin') {
+        const plist = launchdPlistPath(options.home ?? homedir());
+        if (!existsSync(plist))
+            return;
+        // unload 尽力而为：服务本来没加载也算卸载成功。
+        await run('launchctl', ['unload', plist]);
+        await rm(plist, { force: true });
+        return;
+    }
+    const unit = systemdUnitPath(options.home ?? homedir());
+    if (!existsSync(unit))
+        return;
+    await run('systemctl', ['--user', 'disable', '--now', SYSTEMD_NAME]);
+    await rm(unit, { force: true });
+    await run('systemctl', ['--user', 'daemon-reload']);
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@chrome-in-harness/launcher",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "bin": {
+    "chrome-in-harness": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "pretest": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@chrome-in-harness/server": "^0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^5.0.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hcfw007/chrome-in-harness.git"
+  }
+}