@hermit-org/cli 0.0.1-alpha.0

package/src/lib/config.ts

@@ -0,0 +1,142 @@
+import { readFile, writeFile, access, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Configuration schema for `hermit.config.json`.
+ */
+export interface HermitConfig {
+  /** Command that runs the local ACP agent. */
+  agent?: {
+    command: string;
+    args?: string[];
+  };
+  /** HTTP gateway settings. */
+  gateway?: {
+    port?: number;
+    hostname?: string;
+    endpoint?: string;
+    heartbeatInterval?: number;
+    cors?: boolean;
+    timeout?: number;
+  };
+  /** Pre-authorized bearer tokens for mobile clients. */
+  authorizedTokens?: string[];
+}
+
+export const DEFAULT_CONFIG: Required<HermitConfig> = {
+  agent: {
+    command: "npx",
+    args: ["codex", "--acp"],
+  },
+  gateway: {
+    port: 8787,
+    hostname: "0.0.0.0",
+    endpoint: "/",
+    heartbeatInterval: 30000,
+    cors: true,
+    timeout: 0,
+  },
+  authorizedTokens: [],
+};
+
+const CONFIG_FILE_NAME = "hermit.config.json";
+
+function mergeConfig(base: HermitConfig, override: HermitConfig): HermitConfig {
+  return {
+    agent:
+      override.agent
+        ? {
+            command: override.agent.command ?? base.agent!.command,
+            args: override.agent.args ?? base.agent!.args,
+          }
+        : base.agent,
+    gateway:
+      override.gateway
+        ? {
+            port: override.gateway.port ?? base.gateway!.port,
+            hostname: override.gateway.hostname ?? base.gateway!.hostname,
+            endpoint: override.gateway.endpoint ?? base.gateway!.endpoint,
+            heartbeatInterval:
+              override.gateway.heartbeatInterval ?? base.gateway!.heartbeatInterval,
+            cors: override.gateway.cors ?? base.gateway!.cors,
+            timeout: override.gateway.timeout ?? base.gateway!.timeout,
+          }
+        : base.gateway,
+    authorizedTokens: override.authorizedTokens ?? base.authorizedTokens,
+  };
+}
+
+/**
+ * Load the Hermit configuration from the current working directory, falling
+ * back to defaults when the file is absent or invalid.
+ */
+export async function loadConfig(
+  cwd: string = process.cwd(),
+): Promise<HermitConfig> {
+  const path = join(cwd, CONFIG_FILE_NAME);
+
+  try {
+    await access(path);
+    const text = await readFile(path, "utf-8");
+    const parsed = JSON.parse(text) as HermitConfig;
+    return mergeConfig(DEFAULT_CONFIG, parsed);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return DEFAULT_CONFIG;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Write the configuration back to `hermit.config.json` in the given directory.
+ */
+export async function saveConfig(
+  config: HermitConfig,
+  cwd: string = process.cwd(),
+): Promise<void> {
+  const path = join(cwd, CONFIG_FILE_NAME);
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+
+/**
+ * Path to the Hermit data directory inside the user's home folder.
+ */
+export function getHermitDataDir(): string {
+  return join(homedir(), ".hermit");
+}
+
+/**
+ * Ensure the Hermit data directory exists.
+ */
+export async function ensureHermitDataDir(): Promise<void> {
+  const dir = getHermitDataDir();
+  await mkdir(dir, { recursive: true });
+}
+
+/**
+ * Read a JSON file from the Hermit data directory, returning `null` if absent.
+ */
+export async function readHermitJson<T>(name: string): Promise<T | null> {
+  const path = join(getHermitDataDir(), name);
+  try {
+    const text = await readFile(path, "utf-8");
+    return JSON.parse(text) as T;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Write a JSON file to the Hermit data directory.
+ */
+export async function writeHermitJson<T>(name: string, data: T): Promise<void> {
+  const path = join(getHermitDataDir(), name);
+  await ensureHermitDataDir();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
+}

package/src/lib/gateway.test.ts

@@ -0,0 +1,143 @@
+import { describe, test, expect } from "bun:test";
+import { request } from "node:http";
+import { AcpGatewayServer } from "./gateway";
+
+async function getFreePort(): Promise<number> {
+  return 10000 + Math.floor(Math.random() * 30000);
+}
+
+async function post(url: string, body: string): Promise<Response> {
+  return fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "text/plain" },
+    body,
+  });
+}
+
+function readSseUntil(
+  url: string,
+  predicate: (data: string) => boolean,
+): Promise<string[]> {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const results: string[] = [];
+
+    const req = request(
+      {
+        hostname: parsed.hostname,
+        port: parsed.port,
+        path: parsed.pathname,
+        method: "POST",
+      },
+      (res) => {
+        let buffer = "";
+        res.setEncoding("utf-8");
+        res.on("data", (chunk: string) => {
+          buffer += chunk;
+          const parts = buffer.split("\n\n");
+          buffer = parts.pop() ?? "";
+          for (const part of parts) {
+            const match = part.match(/^data: (.*)$/m);
+            if (match) {
+              results.push(match[1]);
+              if (predicate(match[1])) {
+                req.destroy();
+                resolve(results);
+              }
+            }
+          }
+        });
+        res.once("error", reject);
+      },
+    );
+
+    req.once("error", reject);
+    req.end();
+  });
+}
+
+describe("AcpGatewayServer", () => {
+  test("streams agent stdout emitted immediately after spawn", async () => {
+    const port = await getFreePort();
+    const server = new AcpGatewayServer({
+      command: "node",
+      args: ["-e", "console.log('startup'); setInterval(() => {}, 1000);"],
+      port,
+    });
+
+    const { url, stop } = await server.start();
+
+    try {
+      const results = await readSseUntil(url, (data) => data === "startup");
+      expect(results).toContain("startup");
+    } finally {
+      await stop();
+    }
+  });
+
+  test("streams agent stdout over SSE and accepts stdin via /send", async () => {
+    const port = await getFreePort();
+    const server = new AcpGatewayServer({
+      command: "node",
+      args: [
+        "-e",
+        "process.stdin.on('data', d => process.stdout.write(d)); process.stdin.resume(); setInterval(() => {}, 1000);",
+      ],
+      port,
+      sendEndpoint: "/send",
+    });
+
+    const { url, stop } = await server.start();
+    const sendUrl = `${url.replace(/\/$/, "")}/send`;
+
+    try {
+      const consumePromise = readSseUntil(url, (data) => data === "hello");
+
+      // Give the SSE connection a moment to establish.
+      await new Promise((resolve) => setTimeout(resolve, 300));
+
+      const response = await post(sendUrl, "hello\n");
+      expect(response.status).toBe(200);
+
+      const results = await consumePromise;
+      expect(results).toContain("hello");
+    } finally {
+      await stop();
+    }
+  });
+
+  test("returns 404 for unmatched paths", async () => {
+    const port = await getFreePort();
+    const server = new AcpGatewayServer({
+      command: "node",
+      args: ["-e", "process.stdin.resume();"],
+      port,
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      const response = await fetch(`${url}/not-found`, { method: "POST" });
+      expect(response.status).toBe(404);
+    } finally {
+      await stop();
+    }
+  });
+
+  test("responds to CORS preflight requests", async () => {
+    const port = await getFreePort();
+    const server = new AcpGatewayServer({
+      command: "node",
+      args: ["-e", "process.stdin.resume();"],
+      port,
+    });
+    const { url, stop } = await server.start();
+
+    try {
+      const response = await fetch(url, { method: "OPTIONS" });
+      expect(response.status).toBe(204);
+      expect(response.headers.get("access-control-allow-origin")).toBe("*");
+    } finally {
+      await stop();
+    }
+  });
+});

package/src/lib/gateway.ts

@@ -0,0 +1,404 @@
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { spawn, type ChildProcess } from "node:child_process";
+import { createInterface } from "node:readline";
+import { encodeSse, encodeSseKeepAlive } from "@hermit-org/stdio-to-sse";
+
+/**
+ * Configuration for `AcpGatewayServer`.
+ *
+ * The gateway spawns a single long-lived child process and exposes two HTTP
+ * endpoints:
+ *   - `GET/POST /`  : Server-Sent Events stream of the process stdout.
+ *   - `POST /send`  : Writes the request body to the process stdin.
+ *
+ * This is protocol-agnostic at the transport level: it bridges bytes between
+ * stdio and SSE. The CLI adds ACP/MCP-specific routing, pairing, and auth.
+ */
+export interface ConnectionPayload {
+  url: string;
+  sendUrl: string;
+  token: string;
+}
+
+export interface AcpGatewayServerOptions {
+  command: string;
+  args?: string[];
+  port?: number;
+  hostname?: string;
+  endpoint?: string;
+  sendEndpoint?: string;
+  qrEndpoint?: string;
+  cors?: boolean;
+  heartbeatInterval?: number;
+  onRequest?: (
+    req: IncomingMessage,
+    res: ServerResponse,
+  ) => boolean | Promise<boolean>;
+  getQrPayload?: () => ConnectionPayload | null | Promise<ConnectionPayload | null>;
+}
+
+export interface AcpGatewayServerState {
+  url: string;
+  stop: () => Promise<void>;
+}
+
+interface ActiveConnection {
+  res: ServerResponse;
+  heartbeatId: ReturnType<typeof setInterval>;
+}
+
+/**
+ * Gateway that exposes one local stdio process as a persistent SSE endpoint.
+ *
+ * Transport-layer only: no knowledge of ACP, MCP, JSON-RPC, or any specific
+ * protocol. The consumer is expected to send/receive line-delimited messages.
+ */
+export class AcpGatewayServer {
+  private server?: Server;
+  private proc?: ChildProcess;
+  private connections: Set<ActiveConnection> = new Set();
+  private stdinWriteQueue: Array<{
+    chunk: Buffer;
+    resolve: () => void;
+    reject: (error: Error) => void;
+  }> = [];
+  private stdinWriting = false;
+  private started = false;
+
+  constructor(private readonly options: AcpGatewayServerOptions) {}
+
+  async start(): Promise<AcpGatewayServerState> {
+    if (this.started) {
+      throw new Error("AcpGatewayServer is already started");
+    }
+
+    const {
+      command,
+      args = [],
+      port = 8080,
+      hostname = "0.0.0.0",
+      endpoint = "/",
+      sendEndpoint = "/send",
+      qrEndpoint = "/qr",
+      cors = true,
+      heartbeatInterval = 30000,
+    } = this.options;
+
+    const normalizedEndpoint = endpoint === "/" ? "/" : endpoint.replace(/\/$/, "");
+    const normalizedSendEndpoint = sendEndpoint.replace(/\/$/, "");
+    const normalizedQrEndpoint = qrEndpoint.replace(/\/$/, "");
+
+    this.started = true;
+
+    return new Promise((resolve, reject) => {
+      this.server = createServer(async (req, res) => {
+        if (this.options.onRequest) {
+          try {
+            const handled = await this.options.onRequest(req, res);
+            if (handled) return;
+          } catch (error) {
+            if (!res.headersSent) {
+              res.writeHead(500);
+              res.end(error instanceof Error ? error.message : "Internal Server Error");
+            }
+            return;
+          }
+        }
+
+        try {
+          if (cors && req.method === "OPTIONS") {
+            res.writeHead(204, {
+              "Access-Control-Allow-Origin": "*",
+              "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+              "Access-Control-Allow-Headers": "Content-Type, Authorization",
+            });
+            res.end();
+            return;
+          }
+
+          if ((req.method === "GET" || req.method === "POST") && req.url === normalizedEndpoint) {
+            this.handleSseRequest(req, res, cors, heartbeatInterval);
+            return;
+          }
+
+          if (req.method === "POST" && req.url === normalizedSendEndpoint) {
+            await this.handleSendRequest(req, res, cors);
+            return;
+          }
+
+          if (req.method === "GET" && req.url === normalizedQrEndpoint) {
+            await this.handleQrRequest(req, res, cors);
+            return;
+          }
+
+          res.writeHead(404);
+          res.end("Not Found");
+        } catch (error) {
+          if (!res.headersSent) {
+            res.writeHead(500);
+            res.end(error instanceof Error ? error.message : "Internal Server Error");
+          }
+        }
+      });
+
+      this.server.once("error", reject);
+
+      this.server.listen(port, hostname, () => {
+        this.server!.removeListener("error", reject);
+        this.spawnAgent(command, args);
+
+        const displayEndpoint = normalizedEndpoint === "/" ? "" : normalizedEndpoint;
+        const host = hostname === "0.0.0.0" ? "localhost" : hostname;
+        const url = `http://${host}:${port}${displayEndpoint}`;
+
+        resolve({
+          url,
+          stop: () => this.stop(),
+        });
+      });
+    });
+  }
+
+  private spawnAgent(command: string, args: string[]): void {
+    this.proc = spawn(command, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    this.proc.once("error", (error) => {
+      this.broadcastError(error.message);
+    });
+
+    this.proc.once("exit", (code, signal) => {
+      this.broadcastError(
+        signal
+          ? `Agent process exited with signal ${signal}`
+          : `Agent process exited with code ${code ?? "unknown"}`,
+      );
+      this.closeAllConnections();
+    });
+
+    const rl = createInterface({
+      input: this.proc.stdout!,
+      crlfDelay: Infinity,
+    });
+
+    rl.on("line", (line) => {
+      this.broadcast(line);
+    });
+
+    rl.once("close", () => {
+      this.closeAllConnections();
+    });
+
+    this.proc.stderr!.on("data", (chunk: Buffer) => {
+      const text = chunk.toString("utf-8").trimEnd();
+      if (text) {
+        for (const line of text.split("\n")) {
+          if (line.trim()) {
+            this.broadcastError(line);
+          }
+        }
+      }
+    });
+  }
+
+  private handleSseRequest(
+    _req: IncomingMessage,
+    res: ServerResponse,
+    cors: boolean,
+    heartbeatInterval: number,
+  ): void {
+    const headers: Record<string, string | string[]> = {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    };
+
+    if (cors) {
+      headers["Access-Control-Allow-Origin"] = "*";
+    }
+
+    res.writeHead(200, headers);
+
+    const heartbeatId = setInterval(() => {
+      if (!res.writableEnded) {
+        res.write(encodeSseKeepAlive());
+      }
+    }, heartbeatInterval);
+
+    const connection: ActiveConnection = { res, heartbeatId };
+    this.connections.add(connection);
+
+    res.once("close", () => {
+      this.removeConnection(connection);
+    });
+  }
+
+  private async handleSendRequest(
+    req: IncomingMessage,
+    res: ServerResponse,
+    cors: boolean,
+  ): Promise<void> {
+    if (!this.proc || this.proc.killed || !this.proc.stdin || this.proc.stdin.destroyed) {
+      this.sendJson(res, 503, { ok: false, error: "Agent process is not running" }, cors);
+      return;
+    }
+
+    const body = await readRequestBody(req);
+    await this.writeToStdin(body);
+
+    this.sendJson(res, 200, { ok: true }, cors);
+  }
+
+  private async handleQrRequest(
+    _req: IncomingMessage,
+    res: ServerResponse,
+    cors: boolean,
+  ): Promise<void> {
+    if (!this.options.getQrPayload) {
+      this.sendJson(res, 404, { ok: false, error: "QR payload not configured" }, cors);
+      return;
+    }
+
+    const payload = await Promise.resolve(this.options.getQrPayload());
+    if (!payload) {
+      this.sendJson(res, 404, { ok: false, error: "QR payload not available" }, cors);
+      return;
+    }
+
+    const { generateQrBuffer } = await import("./qr");
+    const buffer = await generateQrBuffer(payload);
+
+    const headers: Record<string, string> = {
+      "Content-Type": "image/png",
+      "Content-Length": String(buffer.length),
+      "Cache-Control": "no-store",
+    };
+    if (cors) {
+      headers["Access-Control-Allow-Origin"] = "*";
+    }
+
+    res.writeHead(200, headers);
+    res.end(buffer);
+  }
+
+  private writeToStdin(chunk: Buffer): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.stdinWriteQueue.push({ chunk, resolve, reject });
+      this.flushStdinQueue().catch(reject);
+    });
+  }
+
+  private async flushStdinQueue(): Promise<void> {
+    if (this.stdinWriting || this.stdinWriteQueue.length === 0) return;
+
+    this.stdinWriting = true;
+
+    while (this.stdinWriteQueue.length > 0) {
+      const { chunk, resolve, reject } = this.stdinWriteQueue.shift()!;
+
+      try {
+        await new Promise<void>((writeResolve, writeReject) => {
+          if (!this.proc || !this.proc.stdin || this.proc.stdin.destroyed) {
+            writeReject(new Error("Agent stdin is not available"));
+            return;
+          }
+
+          const canContinue = this.proc.stdin.write(chunk, (error) => {
+            if (error) writeReject(error);
+            else writeResolve();
+          });
+
+          if (!canContinue) {
+            this.proc.stdin.once("drain", writeResolve);
+          }
+        });
+        resolve();
+      } catch (error) {
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+
+    this.stdinWriting = false;
+  }
+
+  private broadcast(payload: string): void {
+    const frame = encodeSse(payload);
+    for (const connection of this.connections) {
+      if (!connection.res.writableEnded) {
+        connection.res.write(frame);
+      }
+    }
+  }
+
+  private broadcastError(message: string): void {
+    const frame = encodeSse(message, { event: "error" });
+    for (const connection of this.connections) {
+      if (!connection.res.writableEnded) {
+        connection.res.write(frame);
+      }
+    }
+  }
+
+  private removeConnection(connection: ActiveConnection): void {
+    this.connections.delete(connection);
+    clearInterval(connection.heartbeatId);
+    if (!connection.res.writableEnded) {
+      connection.res.end();
+    }
+  }
+
+  private closeAllConnections(): void {
+    for (const connection of this.connections) {
+      this.removeConnection(connection);
+    }
+  }
+
+  private sendJson(
+    res: ServerResponse,
+    status: number,
+    payload: unknown,
+    cors: boolean,
+  ): void {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+    if (cors) {
+      headers["Access-Control-Allow-Origin"] = "*";
+    }
+    res.writeHead(status, headers);
+    res.end(JSON.stringify(payload));
+  }
+
+  private async stop(): Promise<void> {
+    this.closeAllConnections();
+
+    if (this.proc && !this.proc.killed) {
+      this.proc.kill();
+      await new Promise<void>((resolve) => {
+        const timeout = setTimeout(() => {
+          this.proc?.kill("SIGKILL");
+          resolve();
+        }, 5000);
+        this.proc?.once("exit", () => {
+          clearTimeout(timeout);
+          resolve();
+        });
+      });
+    }
+
+    return new Promise((resolve) => {
+      this.server?.close(() => resolve());
+      this.server?.closeAllConnections?.();
+    });
+  }
+}
+
+function readRequestBody(req: IncomingMessage): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}