@hermit-org/cli 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,73 @@
+# `@hermit-org/cli`
+
+Bun CLI for Hermit. Manages local ACP agents, exposes them as an SSE gateway,
+and handles mobile device pairing.
+
+## Commands
+
+```bash
+# Show help
+bun packages/cli/src/index.ts --help
+
+# Generate a pairing code
+bun packages/cli/src/index.ts pair
+
+# Start the gateway
+bun packages/cli/src/index.ts start
+```
+
+## Configuration
+
+The CLI reads `hermit.config.json` from the current working directory.
+
+```json
+{
+  "agent": {
+    "command": "npx",
+    "args": ["codex", "--acp"]
+  },
+  "gateway": {
+    "port": 8787,
+    "hostname": "0.0.0.0",
+    "endpoint": "/",
+    "sendEndpoint": "/send",
+    "heartbeatInterval": 30000,
+    "cors": true,
+    "timeout": 0
+  },
+  "authorizedTokens": []
+}
+```
+
+## Gateway endpoints
+
+When running `start`, the CLI exposes:
+
+- `GET/POST /` — SSE stream of the agent stdout (requires bearer token)
+- `POST /send` — write request body to agent stdin (requires bearer token)
+- `POST /pair` — exchange a 6-digit pairing code for a bearer token
+
+## Pairing flow
+
+1. Run `bun packages/cli/src/index.ts pair`.
+2. Enter the displayed 6-digit code in the Hermit mobile app.
+3. The app calls `POST /pair` and receives a bearer token.
+4. The token is persisted in `~/.hermit/authorized-tokens.json`.
+
+## Programmatic usage
+
+```ts
+import { AcpGatewayServer } from "@hermit-org/cli/src/lib/gateway";
+
+const server = new AcpGatewayServer({
+  command: "npx",
+  args: ["codex", "--acp"],
+  port: 8787,
+  onRequest: async (req, res) => {
+    // Custom auth / routing logic
+    return false;
+  },
+});
+
+const { url, stop } = await server.start();
+```

package/README.zh-CN.md

@@ -0,0 +1,72 @@
+# `@hermit-org/cli`
+
+Hermit 的 Bun CLI。管理本地 ACP Agent，将其暴露为 SSE Gateway，并处理移动设备配对。
+
+## 命令
+
+```bash
+# 显示帮助
+bun packages/cli/src/index.ts --help
+
+# 生成配对码
+bun packages/cli/src/index.ts pair
+
+# 启动 Gateway
+bun packages/cli/src/index.ts start
+```
+
+## 配置
+
+CLI 会从当前工作目录读取 `hermit.config.json`。
+
+```json
+{
+  "agent": {
+    "command": "npx",
+    "args": ["codex", "--acp"]
+  },
+  "gateway": {
+    "port": 8787,
+    "hostname": "0.0.0.0",
+    "endpoint": "/",
+    "sendEndpoint": "/send",
+    "heartbeatInterval": 30000,
+    "cors": true,
+    "timeout": 0
+  },
+  "authorizedTokens": []
+}
+```
+
+## Gateway 端点
+
+执行 `start` 后，CLI 暴露以下端点：
+
+- `GET/POST /` —— Agent stdout 的 SSE 流（需要 Bearer token）
+- `POST /send` —— 将请求体写入 Agent stdin（需要 Bearer token）
+- `POST /pair` —— 用 6 位配对码换取 Bearer token
+
+## 配对流程
+
+1. 运行 `bun packages/cli/src/index.ts pair`。
+2. 在 Hermit 移动应用的 ServerList 页面输入显示的 6 位配对码。
+3. 应用调用 `POST /pair` 获取 Bearer token。
+4. Token 持久化到 `~/.hermit/authorized-tokens.json`。
+
+## 编程方式使用
+
+```ts
+import { AcpGatewayServer } from "@hermit-org/cli/src/lib/gateway";
+
+const server = new AcpGatewayServer({
+  command: "npx",
+  args: ["codex", "--acp"],
+  port: 8787,
+  onRequest: async (req, res) => {
+    // 自定义认证 / 路由逻辑
+    return false;
+  },
+});
+
+const { url, stop } = await server.start();
+```

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@hermit-org/cli",
+  "version": "0.0.1-alpha.0",
+  "type": "module",
+  "module": "src/index.ts",
+  "bin": {
+    "hermit": "./src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hermit-org/types": "^0.0.1-alpha.0",
+    "@hermit-org/utils": "^0.0.1-alpha.0",
+    "@hermit-org/stdio-to-sse": "^0.0.1-alpha.0",
+    "commander": "^13.0.0",
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@types/qrcode": "^1.5.5"
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,54 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { Command } from "commander";
+
+async function scanCommandsDir(dir: string): Promise<Command[]> {
+  const commands: Command[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      let parent: Command | undefined;
+
+      try {
+        const mod = await import(join(fullPath, "index.ts"));
+        if (mod.command instanceof Command) {
+          parent = mod.command;
+        }
+      } catch {
+        // no index.ts
+      }
+
+      if (!parent) {
+        parent = new Command(entry.name);
+      }
+
+      const children = await scanCommandsDir(fullPath);
+      for (const child of children) {
+        parent.addCommand(child);
+      }
+
+      commands.push(parent);
+    } else if (
+      entry.isFile() &&
+      entry.name.endsWith(".ts") &&
+      entry.name !== "index.ts"
+    ) {
+      const mod = await import(fullPath);
+      if (mod.command instanceof Command) {
+        commands.push(mod.command);
+      }
+    }
+  }
+
+  return commands;
+}
+
+export async function loadCommands(program: Command): Promise<void> {
+  const commands = await scanCommandsDir(import.meta.dir);
+  for (const cmd of commands) {
+    program.addCommand(cmd);
+  }
+}

package/src/commands/pair.ts

@@ -0,0 +1,95 @@
+import { Command } from "commander";
+import { networkInterfaces } from "node:os";
+import { createPendingPair } from "../lib/pairing";
+import { loadConfig } from "../lib/config";
+import { generateQrTerminal, encodeConnectionPayload } from "../lib/qr";
+import type { ConnectionPayload } from "../lib/gateway";
+
+const VIRTUAL_IFACE_PATTERNS = [
+  /^docker/i,
+  /^veth/i,
+  /^br-/i,
+  /^tun/i,
+  /^tap/i,
+  /^vmnet/i,
+  /^vboxnet/i,
+  /^hyper-v/i,
+  /^lo$/i,
+];
+
+const PREFERRED_IFACE_PATTERNS = [
+  /^wlan/i,
+  /^en[0-9]/i,
+  /^eth[0-9]/i,
+  /^Wi-?Fi/i,
+  /^Ethernet/i,
+];
+
+function isVirtualInterface(name: string): boolean {
+  return VIRTUAL_IFACE_PATTERNS.some((pattern) => pattern.test(name));
+}
+
+function getInterfacePriority(name: string): number {
+  for (let i = 0; i < PREFERRED_IFACE_PATTERNS.length; i++) {
+    if (PREFERRED_IFACE_PATTERNS[i].test(name)) {
+      return i;
+    }
+  }
+  return PREFERRED_IFACE_PATTERNS.length;
+}
+
+function getLanAddress(port: number): string {
+  const interfaces = networkInterfaces();
+  const candidates: { name: string; address: string }[] = [];
+
+  for (const [name, entries] of Object.entries(interfaces)) {
+    if (isVirtualInterface(name)) continue;
+    for (const iface of entries ?? []) {
+      if (iface.family === "IPv4" && !iface.internal) {
+        candidates.push({ name, address: iface.address });
+      }
+    }
+  }
+
+  if (candidates.length === 0) {
+    return `http://localhost:${port}`;
+  }
+
+  candidates.sort((a, b) => getInterfacePriority(a.name) - getInterfacePriority(b.name));
+
+  return `http://${candidates[0].address}:${port}`;
+}
+
+async function pairAction(): Promise<void> {
+  const { code, token } = await createPendingPair();
+  const config = await loadConfig();
+
+  const sseEndpoint = config.gateway?.endpoint || "/";
+  const sendEndpoint = sseEndpoint === "/" ? "/send" : `${sseEndpoint}/send`;
+  const port = config.gateway?.port ?? 8787;
+
+  const qrPayload: ConnectionPayload = {
+    url: getLanAddress(port) + sseEndpoint,
+    sendUrl: getLanAddress(port) + sendEndpoint,
+    token,
+  };
+
+  console.log("Hermit pairing initiated.");
+  console.log("");
+  console.log(`Pairing code : ${code}`);
+  console.log(`Bearer token : ${token}`);
+  console.log("");
+  console.log("Scan the QR code with Hermit mobile app to connect:");
+  console.log(await generateQrTerminal(qrPayload));
+  console.log("\nOr paste this connection string:");
+  console.log(encodeConnectionPayload(qrPayload));
+  console.log("");
+  console.log(
+    "Enter the pairing code in the Hermit mobile app to authorize this gateway.",
+  );
+  console.log("This code expires in 5 minutes.");
+}
+
+export const command = new Command("pair")
+  .description("Generate a pairing code for a mobile client")
+  .action(pairAction);

package/src/commands/start/index.ts

@@ -0,0 +1,247 @@
+import { Command } from "commander";
+import { AcpGatewayServer, type ConnectionPayload } from "../../lib/gateway";
+import { loadConfig, type HermitConfig } from "../../lib/config";
+import {
+  validatePairingCode,
+  isTokenAuthorized,
+  generateToken,
+  authorizeToken,
+} from "../../lib/pairing";
+import { generateQrTerminal, encodeConnectionPayload } from "../../lib/qr";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { networkInterfaces } from "node:os";
+
+function extractBearer(req: IncomingMessage): string | undefined {
+  const auth = req.headers.authorization ?? "";
+  if (auth.startsWith("Bearer ")) {
+    return auth.slice(7);
+  }
+  return undefined;
+}
+
+async function readBody(req: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  return new Promise((resolve, reject) => {
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    req.on("error", reject);
+  });
+}
+
+function sendJson(
+  res: ServerResponse,
+  status: number,
+  payload: unknown,
+  cors = true,
+): void {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+  if (cors) {
+    headers["Access-Control-Allow-Origin"] = "*";
+    headers["Access-Control-Allow-Methods"] = "GET, POST, OPTIONS";
+    headers["Access-Control-Allow-Headers"] = "Content-Type, Authorization";
+  }
+  res.writeHead(status, headers);
+  res.end(JSON.stringify(payload));
+}
+
+// Virtual/Docker interfaces that should not be advertised to mobile clients.
+const VIRTUAL_IFACE_PATTERNS = [
+  /^docker/i,
+  /^veth/i,
+  /^br-/i,
+  /^tun/i,
+  /^tap/i,
+  /^vmnet/i,
+  /^vboxnet/i,
+  /^hyper-v/i,
+  /^lo$/i,
+];
+
+// Interfaces commonly used for Wi-Fi / Ethernet, ordered by preference.
+const PREFERRED_IFACE_PATTERNS = [
+  /^wlan/i,
+  /^en[0-9]/i,
+  /^eth[0-9]/i,
+  /^Wi-?Fi/i,
+  /^Ethernet/i,
+];
+
+function isVirtualInterface(name: string): boolean {
+  return VIRTUAL_IFACE_PATTERNS.some((pattern) => pattern.test(name));
+}
+
+function getInterfacePriority(name: string): number {
+  for (let i = 0; i < PREFERRED_IFACE_PATTERNS.length; i++) {
+    if (PREFERRED_IFACE_PATTERNS[i].test(name)) {
+      return i;
+    }
+  }
+  return PREFERRED_IFACE_PATTERNS.length;
+}
+
+function getLanAddress(port: number): string {
+  const interfaces = networkInterfaces();
+  const candidates: { name: string; address: string }[] = [];
+
+  for (const [name, entries] of Object.entries(interfaces)) {
+    if (isVirtualInterface(name)) continue;
+    for (const iface of entries ?? []) {
+      if (iface.family === "IPv4" && !iface.internal) {
+        candidates.push({ name, address: iface.address });
+      }
+    }
+  }
+
+  if (candidates.length === 0) {
+    return `http://localhost:${port}`;
+  }
+
+  // Sort by preferred interface names (lower priority number = better).
+  candidates.sort((a, b) => getInterfacePriority(a.name) - getInterfacePriority(b.name));
+
+  return `http://${candidates[0].address}:${port}`;
+}
+
+async function startServer(config: HermitConfig, webClientUrl?: string): Promise<void> {
+  const { agent, gateway } = config;
+
+  const sseEndpoint = gateway!.endpoint || "/";
+  const sendEndpoint = sseEndpoint === "/" ? "/send" : `${sseEndpoint}/send`;
+  const port = gateway!.port ?? 8787;
+
+  // Create a persistent bearer token for QR/auto-connect.
+  const token = generateToken();
+  await authorizeToken(token);
+
+  const server = new AcpGatewayServer({
+    command: agent!.command,
+    args: agent!.args,
+    port,
+    hostname: gateway!.hostname,
+    endpoint: sseEndpoint,
+    sendEndpoint,
+    cors: gateway!.cors,
+    heartbeatInterval: gateway!.heartbeatInterval,
+    getQrPayload: (): ConnectionPayload => {
+      const url = getLanAddress(port) + sseEndpoint;
+      const sendUrl = getLanAddress(port) + sendEndpoint;
+      return { url, sendUrl, token };
+    },
+    onRequest: async (req, res) => {
+      // Read-only connection info endpoint. The web client uses this to
+      // pre-fill its connection form from `hermit.config.json` when the page
+      // is opened without URL params. No token is exposed here.
+      if (gateway!.cors && req.method === "OPTIONS" && req.url === "/api/config") {
+        res.writeHead(204, {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "GET, OPTIONS",
+          "Access-Control-Allow-Headers": "Content-Type",
+        });
+        res.end();
+        return true;
+      }
+
+      if (req.method === "GET" && req.url === "/api/config") {
+        sendJson(res, 200, {
+          agent: { command: agent!.command, args: agent!.args ?? [] },
+          gateway: {
+            url: getLanAddress(port) + sseEndpoint,
+            sendUrl: getLanAddress(port) + sendEndpoint,
+            endpoint: sseEndpoint,
+            port,
+          },
+        });
+        return true;
+      }
+
+      // CORS preflight for the pairing endpoint.
+      if (gateway!.cors && req.method === "OPTIONS" && req.url === "/pair") {
+        res.writeHead(204, {
+          "Access-Control-Allow-Origin": "*",
+          "Access-Control-Allow-Methods": "POST, OPTIONS",
+          "Access-Control-Allow-Headers": "Content-Type, Authorization",
+        });
+        res.end();
+        return true;
+      }
+
+      if (req.method === "POST" && req.url === "/pair") {
+        const body = await readBody(req);
+        const { code } = JSON.parse(body || "{}") as { code?: string };
+        const token = code ? await validatePairingCode(code) : null;
+
+        if (!token) {
+          sendJson(res, 401, { ok: false, error: "Invalid or expired pairing code" });
+          return true;
+        }
+
+        sendJson(res, 200, { ok: true, token });
+        return true;
+      }
+
+      // Require a valid bearer token for the SSE and send endpoints.
+      const protectedPaths = [sseEndpoint, sendEndpoint];
+      if (protectedPaths.includes(req.url ?? "") && (req.method === "GET" || req.method === "POST")) {
+        const token = extractBearer(req);
+        if (!token || !(await isTokenAuthorized(token))) {
+          sendJson(res, 401, { ok: false, error: "Unauthorized" });
+          return true;
+        }
+        return false;
+      }
+
+      return false;
+    },
+  });
+
+  const { url, stop } = await server.start();
+  const qrPayload: ConnectionPayload = {
+    url: getLanAddress(port) + sseEndpoint,
+    sendUrl: getLanAddress(port) + sendEndpoint,
+    token,
+  };
+
+  console.log(`Hermit gateway listening at ${url}`);
+  console.log(`Send endpoint: ${sendEndpoint}`);
+  console.log(`Agent: ${agent!.command} ${(agent!.args ?? []).join(" ")}`);
+  console.log("\nScan the QR code with Hermit mobile app to connect:");
+  console.log(await generateQrTerminal(qrPayload));
+  console.log("\nOr paste this connection string:");
+  console.log(encodeConnectionPayload(qrPayload));
+
+  if (webClientUrl) {
+    const params = new URLSearchParams({
+      name: "Hermit Gateway",
+      url: qrPayload.url,
+      sendUrl: qrPayload.sendUrl,
+      token: qrPayload.token,
+    });
+    const base = webClientUrl.replace(/[?#].*$/, "");
+    console.log(`\nOpen the web client (connection pre-configured):`);
+    console.log(`${base}?${params.toString()}`);
+  }
+
+  console.log("\nPress Ctrl+C to stop");
+
+  process.once("SIGINT", async () => {
+    console.log("\nShutting down...");
+    await stop();
+    process.exit(0);
+  });
+}
+
+async function startAction(options: { web?: string }): Promise<void> {
+  const config = await loadConfig();
+  await startServer(config, options.web);
+}
+
+export const command = new Command("start")
+  .description("Start the Hermit gateway (ACP agent -> SSE)")
+  .option(
+    "--web <url>",
+    "web client base URL; prints a pre-configured link when set",
+    "http://localhost:5180",
+  )
+  .action(startAction);

package/src/index.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import pkg from "../package.json";
+import { loadCommands } from "./commands";
+
+const { version } = pkg;
+
+const program = new Command();
+
+program
+  .name("hermit")
+  .description("Hermit CLI")
+  .version(version);
+
+await loadCommands(program);
+
+program.parse();