@bulolo/hermes-link 0.1.0

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.js

@@ -0,0 +1,525 @@
+#!/usr/bin/env node
+import {
+  DAEMON_LOG_FILE,
+  LINK_COMMAND,
+  LINK_VERSION,
+  bootstrapWithRelay,
+  createRotatingTextLogWriter,
+  currentCliScriptPath,
+  detectRuntimeEnvironment,
+  disableAutostart,
+  enableAutostart,
+  ensureIdentity,
+  generateAppConnectToken,
+  getAutostartStatus,
+  loadConfig,
+  loadIdentity,
+  normalizeLanHost,
+  readRecentGatewayLogEntries,
+  readRecentLogEntries,
+  resolveRuntimePaths,
+  saveAssignedLinkId,
+  saveConfig,
+  startLinkService
+} from "../chunk-C24HF73Y.js";
+
+// src/cli/index.ts
+import { mkdir as mkdir2 } from "fs/promises";
+
+// src/daemon/process.ts
+import { execFile, spawn } from "child_process";
+import { mkdir, readFile, writeFile, rm } from "fs/promises";
+import { setTimeout as sleep } from "timers/promises";
+import path from "path";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function pidFilePath(paths) {
+  return path.join(paths.homeDir, "daemon.pid");
+}
+async function readPid(paths) {
+  try {
+    const raw = await readFile(pidFilePath(paths), "utf8");
+    const pid = Number.parseInt(raw.trim(), 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+}
+async function writePid(paths, pid) {
+  await mkdir(paths.homeDir, { recursive: true, mode: 448 });
+  await writeFile(pidFilePath(paths), String(pid), { mode: 384 });
+}
+async function clearPid(paths) {
+  await rm(pidFilePath(paths), { force: true }).catch(() => void 0);
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function wait(ms) {
+  return sleep(ms);
+}
+async function getDaemonStatus(paths) {
+  const runtimePaths = paths ?? resolveRuntimePaths();
+  const pid = await readPid(runtimePaths);
+  if (pid === null) {
+    return { state: "stopped", pid: null };
+  }
+  if (isProcessAlive(pid)) {
+    return { state: "running", pid };
+  }
+  await clearPid(runtimePaths);
+  return { state: "stopped", pid: null };
+}
+async function probeLocalLinkService(options) {
+  const fetcher = options.fetchImpl ?? fetch;
+  try {
+    const response = await fetcher(`http://127.0.0.1:${options.port}/api/v1/system/status`, {
+      signal: AbortSignal.timeout(3e3)
+    });
+    return { reachable: true, statusCode: response.status };
+  } catch {
+    return { reachable: false };
+  }
+}
+async function startDaemonProcess(options) {
+  const paths = options.paths ?? resolveRuntimePaths();
+  const status = await getDaemonStatus(paths);
+  if (status.state === "running") return;
+  const child = spawn(
+    process.execPath,
+    [currentCliScriptPath(), "daemon-supervisor"],
+    {
+      detached: true,
+      stdio: "ignore"
+    }
+  );
+  child.unref();
+  for (let i = 0; i < 6; i++) {
+    await wait(500);
+    const newStatus = await getDaemonStatus(paths);
+    if (newStatus.state === "running") return;
+  }
+}
+async function stopDaemonProcess(options) {
+  const paths = options.paths ?? resolveRuntimePaths();
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  const status = await getDaemonStatus(paths);
+  if (status.state !== "running" || status.pid === null) return;
+  try {
+    process.kill(status.pid, "SIGTERM");
+  } catch {
+    await clearPid(paths);
+    return;
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await wait(200);
+    if (!isProcessAlive(status.pid)) {
+      await clearPid(paths);
+      return;
+    }
+  }
+  try {
+    process.kill(status.pid, "SIGKILL");
+  } catch {
+  }
+  await clearPid(paths);
+}
+async function runDaemonSupervisor(options) {
+  const paths = options.paths ?? resolveRuntimePaths();
+  await mkdir(paths.homeDir, { recursive: true, mode: 448 });
+  await writePid(paths, process.pid);
+  const logWriter = createRotatingTextLogWriter({ paths, fileName: DAEMON_LOG_FILE });
+  const cleanup = async () => {
+    await clearPid(paths).catch(() => void 0);
+    await logWriter.flush().catch(() => void 0);
+  };
+  process.once("SIGTERM", () => {
+    cleanup().then(() => process.exit(0)).catch(() => process.exit(1));
+  });
+  process.once("SIGINT", () => {
+    cleanup().then(() => process.exit(0)).catch(() => process.exit(1));
+  });
+  const runDaemon = () => new Promise((resolve) => {
+    const args2 = [currentCliScriptPath(), "daemon", "--foreground"];
+    if (options.port) {
+      args2.push("--port", String(options.port));
+    }
+    const child = spawn(process.execPath, args2, {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    child.stdout?.on("data", (chunk) => {
+      logWriter.write(chunk).catch(() => void 0);
+    });
+    child.stderr?.on("data", (chunk) => {
+      logWriter.write(chunk).catch(() => void 0);
+    });
+    child.once("exit", (code) => {
+      resolve(code ?? 1);
+    });
+    child.once("error", () => {
+      resolve(1);
+    });
+  });
+  let consecutiveFastExits = 0;
+  while (true) {
+    const startTime = Date.now();
+    const code = await runDaemon();
+    const elapsed = Date.now() - startTime;
+    if (code === 0) {
+      break;
+    }
+    if (elapsed < 2e3) {
+      consecutiveFastExits++;
+    } else {
+      consecutiveFastExits = 0;
+    }
+    if (consecutiveFastExits >= 5) {
+      break;
+    }
+    const backoffMs = Math.min(1e3 * consecutiveFastExits, 5e3);
+    await wait(backoffMs);
+  }
+  await cleanup();
+}
+
+// src/runtime/browser.ts
+import { spawn as spawn2 } from "child_process";
+async function openSystemBrowser(url) {
+  const platform = process.platform;
+  if (platform === "win32") {
+    return spawnDetached("cmd", ["/c", "start", "", url]);
+  }
+  if (platform === "darwin") {
+    return spawnDetached("open", [url]);
+  }
+  return spawnDetached("xdg-open", [url]);
+}
+async function spawnDetached(command2, args2) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (ok) => {
+      if (settled) return;
+      settled = true;
+      resolve(ok);
+    };
+    try {
+      const child = spawn2(command2, args2, { detached: true, stdio: "ignore" });
+      child.once("error", () => settle(false));
+      child.once("spawn", () => {
+        child.unref();
+        settle(true);
+      });
+    } catch {
+      settle(false);
+    }
+  });
+}
+
+// src/pairing/preflight.ts
+async function runPairingPreflight(options) {
+  const token = await generateAppConnectToken(options.paths);
+  const baseUrl = (options.serverBaseUrl ?? options.config.serverBaseUrl).replace(/\/+$/u, "");
+  const pairingUrl = buildPairingUrl(baseUrl, {
+    linkId: options.identity.link_id ?? "",
+    installId: options.identity.install_id,
+    connectToken: token.token,
+    port: options.config.port
+  });
+  if (options.openBrowser !== false) {
+    await openSystemBrowser(pairingUrl).catch(() => void 0);
+  }
+  return { pairingUrl, connectToken: token.token };
+}
+function buildPairingUrl(serverBaseUrl, params) {
+  const qs = new URLSearchParams({
+    link_id: params.linkId,
+    install_id: params.installId,
+    connect_token: params.connectToken,
+    port: String(params.port)
+  });
+  return `${serverBaseUrl}/link/pair?${qs.toString()}`;
+}
+
+// src/cli/index.ts
+var args = process.argv.slice(2);
+var command = args[0];
+function hasFlag(...flags) {
+  return args.some((a) => flags.includes(a));
+}
+function getFlagValue(...flags) {
+  for (let i = 0; i < args.length - 1; i++) {
+    if (flags.includes(args[i])) return args[i + 1];
+  }
+  return null;
+}
+async function main() {
+  if (hasFlag("--version", "-v")) {
+    process.stdout.write(`${LINK_VERSION}
+`);
+    return;
+  }
+  if (!command || hasFlag("--help", "-h")) {
+    printHelp();
+    return;
+  }
+  const paths = resolveRuntimePaths();
+  await mkdir2(paths.homeDir, { recursive: true, mode: 448 });
+  switch (command) {
+    case "start":
+      await cmdStart(paths);
+      break;
+    case "stop":
+      await cmdStop(paths);
+      break;
+    case "status":
+      await cmdStatus(paths);
+      break;
+    case "restart":
+      await cmdStop(paths);
+      await cmdStart(paths);
+      break;
+    case "daemon":
+      await cmdDaemon(paths);
+      break;
+    case "daemon-supervisor":
+      await cmdDaemonSupervisor(paths);
+      break;
+    case "pair":
+      await cmdPair(paths);
+      break;
+    case "config":
+      await cmdConfig(paths);
+      break;
+    case "logs":
+      await cmdLogs(paths);
+      break;
+    case "autostart":
+      await cmdAutostart(paths);
+      break;
+    case "version":
+      process.stdout.write(`${LINK_VERSION}
+`);
+      break;
+    default:
+      process.stderr.write(`Unknown command: ${command}
+`);
+      printHelp();
+      process.exitCode = 1;
+  }
+}
+async function cmdStart(paths) {
+  const status = await getDaemonStatus(paths);
+  if (status.state === "running") {
+    process.stdout.write(`Hermes Link is already running (PID ${status.pid}).
+`);
+    return;
+  }
+  await startDaemonProcess({ paths });
+  process.stdout.write("Hermes Link started.\n");
+}
+async function cmdStop(paths) {
+  const status = await getDaemonStatus(paths);
+  if (status.state !== "running") {
+    process.stdout.write("Hermes Link is not running.\n");
+    return;
+  }
+  await stopDaemonProcess({ paths });
+  process.stdout.write("Hermes Link stopped.\n");
+}
+async function cmdStatus(paths) {
+  const config = await loadConfig(paths);
+  const daemonStatus = await getDaemonStatus(paths);
+  const probe = await probeLocalLinkService({ port: config.port });
+  const identity = await loadIdentity(paths).catch(() => null);
+  const autostartStatus = await getAutostartStatus();
+  const env = detectRuntimeEnvironment();
+  process.stdout.write(`Hermes Link ${LINK_VERSION}
+`);
+  process.stdout.write(`Daemon:    ${daemonStatus.state}${daemonStatus.pid ? ` (PID ${daemonStatus.pid})` : ""}
+`);
+  process.stdout.write(`HTTP:      ${probe.reachable ? `reachable on port ${config.port}` : `not reachable`}
+`);
+  process.stdout.write(`Link ID:   ${identity?.link_id ?? "unassigned"}
+`);
+  process.stdout.write(`Autostart: ${autostartStatus.enabled ? "enabled" : "disabled"} (${autostartStatus.method})
+`);
+  process.stdout.write(`Env:       ${env.kind}
+`);
+  if (env.warning) process.stdout.write(`Warning:   ${env.warning}
+`);
+}
+async function cmdDaemon(paths) {
+  if (!hasFlag("--foreground")) {
+    process.stderr.write("Use 'hermeslink start' or 'hermeslink daemon-supervisor'\n");
+    process.exitCode = 1;
+    return;
+  }
+  const config = await loadConfig(paths);
+  const identity = await ensureIdentity(paths);
+  let relayToken = "";
+  try {
+    const bootstrapResult = await bootstrapWithRelay({
+      relayBaseUrl: config.relayBaseUrl,
+      identity,
+      port: config.port
+    });
+    if (!identity.link_id) {
+      await saveAssignedLinkId(bootstrapResult.linkId, paths);
+    }
+    relayToken = bootstrapResult.token;
+  } catch (err) {
+    process.stderr.write(`Warning: Relay bootstrap failed: ${err.message}
+`);
+  }
+  const service = await startLinkService({ config, identity, paths, relayToken });
+  process.stdout.write(`Hermes Link running on port ${config.port}
+`);
+  const shutdown = async () => {
+    await service.stop();
+    process.exit(0);
+  };
+  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", shutdown);
+}
+async function cmdDaemonSupervisor(paths) {
+  const config = await loadConfig(paths);
+  await runDaemonSupervisor({ paths, port: config.port });
+}
+async function cmdPair(paths) {
+  const config = await loadConfig(paths);
+  const identity = await ensureIdentity(paths);
+  if (!identity.link_id) {
+    process.stderr.write("Error: Hermes Link is not connected to relay. Run 'hermeslink start' first.\n");
+    process.exitCode = 1;
+    return;
+  }
+  const result = await runPairingPreflight({ identity, config, paths });
+  process.stdout.write(`Pairing URL: ${result.pairingUrl}
+`);
+  process.stdout.write(`Connect token: ${result.connectToken}
+`);
+}
+async function cmdConfig(paths) {
+  const subcommand = args[1];
+  if (subcommand === "get") {
+    const config = await loadConfig(paths);
+    process.stdout.write(JSON.stringify(config, null, 2) + "\n");
+    return;
+  }
+  if (subcommand === "set") {
+    const key = args[2];
+    const value = args[3];
+    if (!key || value === void 0) {
+      process.stderr.write("Usage: hermeslink config set <key> <value>\n");
+      process.exitCode = 1;
+      return;
+    }
+    await applyConfigSet(key, value, paths);
+    return;
+  }
+  process.stderr.write("Usage: hermeslink config [get|set]\n");
+  process.exitCode = 1;
+}
+async function applyConfigSet(key, value, paths) {
+  switch (key) {
+    case "port": {
+      const port = Number.parseInt(value, 10);
+      if (!Number.isFinite(port) || port < 1 || port > 65535) {
+        process.stderr.write("Invalid port number\n");
+        process.exitCode = 1;
+        return;
+      }
+      await saveConfig({ port }, paths);
+      process.stdout.write(`Port set to ${port}
+`);
+      break;
+    }
+    case "lan-host": {
+      const lanHost = normalizeLanHost(value) ?? null;
+      await saveConfig({ lanHost }, paths);
+      process.stdout.write(`LAN host set to ${lanHost ?? "(auto)"}
+`);
+      break;
+    }
+    case "language": {
+      const lang = value;
+      await saveConfig({ language: lang }, paths);
+      process.stdout.write(`Language set to ${lang}
+`);
+      break;
+    }
+    case "log-level": {
+      const level = value;
+      await saveConfig({ logLevel: level }, paths);
+      process.stdout.write(`Log level set to ${level}
+`);
+      break;
+    }
+    default:
+      process.stderr.write(`Unknown config key: ${key}
+`);
+      process.exitCode = 1;
+  }
+}
+async function cmdLogs(paths) {
+  const isGateway = hasFlag("--gateway");
+  const limit = getFlagValue("--limit", "-n");
+  const limitNum = limit ? Number.parseInt(limit, 10) : 50;
+  const entries = isGateway ? await readRecentGatewayLogEntries({ paths, limit: limitNum }) : await readRecentLogEntries({ paths, limit: limitNum });
+  for (const entry of entries) {
+    const ts = entry.ts ? new Date(entry.ts).toLocaleString() : "??";
+    process.stdout.write(`[${ts}] ${entry.level.toUpperCase()} ${entry.message}
+`);
+  }
+}
+async function cmdAutostart(paths) {
+  const subcommand = args[1];
+  if (subcommand === "enable") {
+    const status2 = await enableAutostart();
+    process.stdout.write(`Autostart ${status2.enabled ? "enabled" : "could not be enabled"} (${status2.method})
+`);
+    return;
+  }
+  if (subcommand === "disable") {
+    const status2 = await disableAutostart();
+    process.stdout.write(`Autostart ${status2.enabled ? "still enabled" : "disabled"} (${status2.method})
+`);
+    return;
+  }
+  const status = await getAutostartStatus();
+  process.stdout.write(`Autostart: ${status.enabled ? "enabled" : "disabled"} (${status.method})
+`);
+}
+function printHelp() {
+  process.stdout.write(`Hermes Link ${LINK_VERSION} \u2014 Local service for Hermes Agent
+
+Usage: ${LINK_COMMAND} <command> [options]
+
+Commands:
+  start              Start the Hermes Link daemon
+  stop               Stop the Hermes Link daemon
+  restart            Restart the daemon
+  status             Show daemon and service status
+  pair               Generate a pairing URL for your device
+  config get         Show current configuration
+  config set         Set a configuration value
+  autostart          Show/enable/disable autostart
+  logs               Show recent log entries (--gateway for gateway logs)
+  version            Print version
+
+Options:
+  --version, -v      Print version
+  --help, -h         Show this help
+`);
+}
+main().catch((err) => {
+  process.stderr.write(`${err.message}
+`);
+  process.exitCode = 1;
+});

package/dist/http/app.d.ts

@@ -0,0 +1,111 @@
+import Koa from 'koa';
+import { Server } from 'http';
+import { z } from 'zod';
+import { EventEmitter } from 'events';
+
+interface RuntimePaths {
+    homeDir: string;
+    identityFile: string;
+    configFile: string;
+    stateFile: string;
+    credentialsFile: string;
+    databaseFile: string;
+    conversationsDir: string;
+    blobsDir: string;
+    indexesDir: string;
+    logsDir: string;
+    runDir: string;
+    pairingDir: string;
+}
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+type Language = "auto" | "en" | "zh-CN";
+interface LinkConfig {
+    port: number;
+    lanHost: string | null;
+    serverBaseUrl: string;
+    relayBaseUrl: string;
+    appConnectTokenIssuer: string;
+    appConnectTokenAudience: string;
+    language: Language;
+    logLevel: LogLevel;
+}
+
+declare const linkIdentitySchema: z.ZodObject<{
+    install_id: z.ZodString;
+    link_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    public_key_pem: z.ZodString;
+    private_key_pem: z.ZodString;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    install_id: string;
+    public_key_pem: string;
+    private_key_pem: string;
+    created_at: string;
+    updated_at: string;
+    link_id?: string | null | undefined;
+}, {
+    install_id: string;
+    public_key_pem: string;
+    private_key_pem: string;
+    created_at: string;
+    updated_at: string;
+    link_id?: string | null | undefined;
+}>;
+type LinkIdentity = z.infer<typeof linkIdentitySchema>;
+
+type RelayClientState = "disconnected" | "connecting" | "connected" | "closing";
+interface RelayClientOptions {
+    relayBaseUrl: string;
+    identity: LinkIdentity;
+    token: string;
+    paths?: RuntimePaths;
+    fetchImpl?: typeof fetch;
+    reconnectDelayMs?: number;
+    maxReconnectDelayMs?: number;
+    pingIntervalMs?: number;
+}
+interface RelayMessage {
+    type: string;
+    [key: string]: unknown;
+}
+declare class RelayClient extends EventEmitter {
+    private options;
+    private ws;
+    private state;
+    private token;
+    private logger;
+    private reconnectTimer;
+    private pingTimer;
+    private reconnectDelay;
+    private closed;
+    constructor(options: RelayClientOptions);
+    get currentState(): RelayClientState;
+    start(): void;
+    stop(): void;
+    send(message: RelayMessage): void;
+    private connect;
+    private buildWsUrl;
+    private scheduleReconnect;
+    private maybeRefreshTokenAndReconnect;
+    private startPing;
+    private stopPing;
+    private clearTimers;
+}
+
+interface LinkServiceOptions {
+    config: LinkConfig;
+    identity: LinkIdentity;
+    paths: RuntimePaths;
+    relayToken: string;
+}
+interface LinkService {
+    app: Koa;
+    server: Server;
+    relayClient: RelayClient;
+    stop(): Promise<void>;
+}
+declare function startLinkService(options: LinkServiceOptions): Promise<LinkService>;
+
+export { type LinkService, type LinkServiceOptions, startLinkService };

package/dist/http/app.js

@@ -0,0 +1,6 @@
+import {
+  startLinkService
+} from "../chunk-C24HF73Y.js";
+export {
+  startLinkService
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@bulolo/hermes-link",
+  "version": "0.1.0",
+  "description": "Hermes Link companion service and CLI for connecting hermes-agent through zhiji",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "hermeslink": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "scripts/check-node-version.mjs",
+    "scripts/postinstall.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "hermes",
+    "hermes-agent",
+    "relay",
+    "link",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/cli/index.ts src/http/app.ts --format esm --target node20 --dts --clean",
+    "check": "tsc --noEmit",
+    "dev": "tsx src/cli/index.ts",
+    "preinstall": "node ./scripts/check-node-version.mjs",
+    "postinstall": "node ./scripts/postinstall.mjs",
+    "prepack": "npm run build",
+    "start": "node ./dist/cli/index.js",
+    "test": "vitest",
+    "publish:npm": "npm publish --access public"
+  },
+  "dependencies": {
+    "@koa/cors": "^5.0.0",
+    "@koa/router": "^15.4.0",
+    "better-sqlite3": "^12.9.0",
+    "koa": "^2.15.3",
+    "koa-bodyparser": "^4.4.1",
+    "pino": "^9.0.0",
+    "qrcode": "^1.5.4",
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.18.0",
+    "yaml": "^2.6.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/koa": "^2.15.0",
+    "@types/koa__cors": "^5.0.1",
+    "@types/koa-bodyparser": "^4.3.12",
+    "@types/node": "^20.19.39",
+    "@types/qrcode": "^1.5.6",
+    "@types/qrcode-terminal": "^0.12.2",
+    "@types/ws": "^8.5.13",
+    "pino-pretty": "^13.0.0",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}