@perkos/perkos-a2a 0.8.35 → 0.9.0

package/scripts/hermes/install.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * install-hermes — managed-service install helper for the
+ * Hermes-flavoured PerkOS A2A bridge.
+ *
+ * Goal: parity with `openclaw plugins install @perkos/perkos-a2a`. The
+ * OpenClaw flow drops a plugin into the runtime and the runtime
+ * supervises it. Hermes has no plugin host, so the equivalent is a
+ * systemd unit (Linux) or a launchd plist (macOS) that supervises the
+ * `perkos-a2a-hermes` CLI alongside the Hermes API Server.
+ *
+ * Two modes:
+ *   --emit   Print the unit/plist to stdout. Use when you want to pipe
+ *            into your own deploy tooling.
+ *   --write  Write to the conventional system location. Requires root
+ *            on Linux; on macOS writes to ~/Library/LaunchAgents.
+ *
+ * Required:
+ *   --agent-name <name>
+ *
+ * Common:
+ *   --relay-url <wss>        Transport relay URL
+ *   --relay-key <key>        Transport relay API key
+ *   --hermes-url <url>       Hermes API base URL (default http://127.0.0.1:8642)
+ *   --port <n>               Local A2A port (default 5060)
+ *   --user <name>            systemd User= (default current $USER)
+ *
+ * Pre-flight: confirms the Hermes API responds before emitting the
+ * unit. Skip with --skip-preflight.
+ */
+
+import { writeFileSync, mkdirSync, existsSync, statSync, chmodSync } from "node:fs";
+import { homedir, platform, userInfo } from "node:os";
+import { join, resolve } from "node:path";
+
+function argValue(flag) {
+  const idx = process.argv.indexOf(flag);
+  if (idx === -1) return undefined;
+  return process.argv[idx + 1];
+}
+function hasFlag(flag) { return process.argv.includes(flag); }
+
+function fail(msg, code = 1) {
+  console.error(`install-hermes: ${msg}`);
+  process.exit(code);
+}
+
+function help() {
+  console.log(`install-hermes — managed-service install for perkos-a2a-hermes.
+
+Usage:
+  install-hermes --emit  --agent-name Apollo [...]
+  install-hermes --write --agent-name Apollo [...]
+
+Required:
+  --agent-name <name>
+
+Common:
+  --relay-url <wss>        Transport relay URL (or A2A_RELAY_URL)
+  --relay-key <key>        Transport relay API key (or A2A_RELAY_API_KEY)
+  --hermes-url <url>       Hermes API base URL (default http://127.0.0.1:8642)
+  --hermes-token <token>   Hermes API bearer token (or HERMES_API_KEY)
+  --port <n>               Local A2A port (default 5060)
+  --user <name>            systemd User= (default \$USER)
+  --skip-preflight         Skip the Hermes API reachability check
+
+Output:
+  Linux: systemd unit at /etc/systemd/system/perkos-a2a-hermes.service
+  macOS: launchd plist at ~/Library/LaunchAgents/xyz.perkos.a2a-hermes.plist
+`);
+}
+
+if (hasFlag("-h") || hasFlag("--help")) { help(); process.exit(0); }
+const mode = hasFlag("--emit") ? "emit" : hasFlag("--write") ? "write" : null;
+if (!mode) fail("specify --emit or --write (see --help)", 2);
+
+const agentName = argValue("--agent-name");
+if (!agentName) fail("--agent-name is required", 2);
+const port = Number(argValue("--port") || 5060);
+if (!Number.isFinite(port) || port <= 0) fail(`invalid --port ${argValue("--port")}`, 2);
+const relayUrl = argValue("--relay-url") || process.env.A2A_RELAY_URL;
+const relayKey = argValue("--relay-key") || process.env.A2A_RELAY_API_KEY;
+const hermesUrl = argValue("--hermes-url") || process.env.HERMES_API_URL || "http://127.0.0.1:8642";
+const hermesToken = argValue("--hermes-token") || process.env.HERMES_API_KEY;
+const user = argValue("--user") || userInfo().username;
+
+async function preflight() {
+  if (hasFlag("--skip-preflight")) return;
+  let res;
+  try {
+    res = await fetch(`${hermesUrl.replace(/\/+$/, "")}/v1/responses`, {
+      method: "OPTIONS",
+    });
+  } catch (err) {
+    fail(`Hermes API not reachable at ${hermesUrl} (${err.message}). Re-run with --skip-preflight if intentional.`);
+  }
+  // Any response — including 405 Method Not Allowed — proves something is listening.
+  if (!res) fail(`Hermes API check returned no response. Re-run with --skip-preflight if intentional.`);
+}
+
+function unitLinux() {
+  const env = [
+    `Environment=A2A_AGENT_NAME=${agentName}`,
+    `Environment=A2A_PORT=${port}`,
+    `Environment=HERMES_API_URL=${hermesUrl}`,
+  ];
+  if (relayUrl) env.push(`Environment=A2A_RELAY_URL=${relayUrl}`);
+  if (relayKey) env.push(`Environment=A2A_RELAY_API_KEY=${relayKey}`);
+  if (hermesToken) env.push(`Environment=HERMES_API_KEY=${hermesToken}`);
+
+  return `[Unit]
+Description=PerkOS A2A bridge (Hermes runtime)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${user}
+ExecStart=${process.execPath} ${resolve(process.argv[1], "..", "..", "..", "dist", "hermes-cli.js")}
+Restart=on-failure
+RestartSec=5
+${env.join("\n")}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+function plistMac() {
+  const envPairs = [
+    ["A2A_AGENT_NAME", agentName],
+    ["A2A_PORT", String(port)],
+    ["HERMES_API_URL", hermesUrl],
+  ];
+  if (relayUrl) envPairs.push(["A2A_RELAY_URL", relayUrl]);
+  if (relayKey) envPairs.push(["A2A_RELAY_API_KEY", relayKey]);
+  if (hermesToken) envPairs.push(["HERMES_API_KEY", hermesToken]);
+
+  const envXml = envPairs
+    .map(([k, v]) => `    <key>${k}</key>\n    <string>${escapeXml(v)}</string>`)
+    .join("\n");
+
+  const cliPath = resolve(process.argv[1], "..", "..", "..", "dist", "hermes-cli.js");
+
+  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>xyz.perkos.a2a-hermes</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${process.execPath}</string>
+    <string>${cliPath}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${homedir()}/Library/Logs/perkos-a2a-hermes.log</string>
+  <key>StandardErrorPath</key>
+  <string>${homedir()}/Library/Logs/perkos-a2a-hermes.err.log</string>
+</dict>
+</plist>
+`;
+}
+
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+async function main() {
+  await preflight();
+  const os = platform();
+  const content = os === "darwin" ? plistMac() : unitLinux();
+  if (mode === "emit") {
+    process.stdout.write(content);
+    return;
+  }
+  // mode === "write"
+  let target;
+  if (os === "darwin") {
+    const dir = join(homedir(), "Library", "LaunchAgents");
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    target = join(dir, "xyz.perkos.a2a-hermes.plist");
+    writeFileSync(target, content, { mode: 0o644 });
+    console.log(`wrote ${target}`);
+    console.log("activate: launchctl load -w " + target);
+  } else {
+    target = "/etc/systemd/system/perkos-a2a-hermes.service";
+    try {
+      writeFileSync(target, content, { mode: 0o644 });
+      console.log(`wrote ${target}`);
+      console.log("activate: sudo systemctl daemon-reload && sudo systemctl enable --now perkos-a2a-hermes");
+    } catch (err) {
+      fail(`cannot write ${target} (${err.message}). Re-run with sudo, or use --emit and pipe to sudo tee.`);
+    }
+  }
+}
+
+main().catch((err) => fail(err.message ?? String(err)));