claude-code-best
diff --git a/‎bun.lock‎
Lines changed: 906 additions & 4 deletions b/‎bun.lock‎
Lines changed: 906 additions & 4 deletions
diff --git a/‎packages/acp-link/.gitignore‎
Lines changed: 34 additions & 0 deletions b/‎packages/acp-link/.gitignore‎
Lines changed: 34 additions & 0 deletions
diff --git a/‎packages/acp-link/README.md‎
Lines changed: 89 additions & 0 deletions b/‎packages/acp-link/README.md‎
Lines changed: 89 additions & 0 deletions
diff --git a/‎packages/acp-link/package.json‎
Lines changed: 39 additions & 0 deletions b/‎packages/acp-link/package.json‎
Lines changed: 39 additions & 0 deletions
diff --git a/‎packages/acp-link/src/__tests__/cert.test.ts‎
Lines changed: 28 additions & 0 deletions b/‎packages/acp-link/src/__tests__/cert.test.ts‎
Lines changed: 28 additions & 0 deletions
diff --git a/‎packages/acp-link/src/__tests__/server.test.ts‎
Lines changed: 75 additions & 0 deletions b/‎packages/acp-link/src/__tests__/server.test.ts‎
Lines changed: 75 additions & 0 deletions
diff --git a/‎packages/acp-link/src/__tests__/types.test.ts‎
Lines changed: 69 additions & 0 deletions b/‎packages/acp-link/src/__tests__/types.test.ts‎
Lines changed: 69 additions & 0 deletions
@@ -0,0 +1,34 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
@@ -0,0 +1,89 @@
+# acp-link
+
+ACP proxy server that bridges WebSocket clients to ACP (Agent Client Protocol) agents.
+
+> Source code adapted from [chrome-acp](https://github.com/Areo-Joe/chrome-acp).
+
+## Installation
+
+### From source
+
+```bash
+# From monorepo root
+bun install
+```
+
+## Usage
+
+```bash
+# Via global install
+acp-link /path/to/agent
+
+# Via source
+bun src/cli/bin.ts /path/to/agent
+```
+
+### Examples
+
+```bash
+# Basic usage
+acp-link /path/to/agent
+
+# With custom port and host
+acp-link --port 9000 --host 0.0.0.0 /path/to/agent
+
+# With debug logging
+acp-link --debug /path/to/agent
+
+# Enable HTTPS with self-signed certificate
+acp-link --https /path/to/agent
+
+# Disable authentication (dangerous)
+acp-link --no-auth /path/to/agent
+
+# Pass arguments to the agent (use -- to separate)
+acp-link /path/to/agent -- --verbose --model gpt-4
+```
+
+## CLI Reference
+
+```
+USAGE
+  acp-link [--port value] [--host value] [--debug] [--no-auth] [--https] <command>...
+  acp-link --help
+  acp-link --version
+
+FLAGS
+       [--port]     Port to listen on                  [default = 9315]
+       [--host]     Host to bind to                    [default = localhost]
+       [--debug]    Enable debug logging to file
+       [--no-auth]  Disable authentication (dangerous)
+       [--https]    Enable HTTPS with self-signed cert
+    -h  --help      Print help information and exit
+    -v  --version   Print version information and exit
+
+ARGUMENTS
+  command...  Agent command followed by its arguments
+```
+
+## How It Works
+
+1. Listens for WebSocket connections from clients
+2. When a "connect" message is received, spawns the configured ACP agent as a subprocess
+3. Bridges messages between the WebSocket (client) and stdin/stdout (agent via ACP protocol)
+4. Supports session management: create, load, resume, list sessions
+5. Handles permission approval flow and heartbeat keepalive
+
+## Authentication
+
+By default, a random token is auto-generated on startup. Pass it as a query parameter:
+
+```
+ws://localhost:9315/ws?token=<your-token>
+```
+
+Set `ACP_AUTH_TOKEN` env var to use a fixed token, or use `--no-auth` to disable (not recommended).
+
+## License
+
+MIT
@@ -0,0 +1,39 @@
+{
+  "name": "acp-link",
+  "version": "1.0.0",
+  "description": "ACP proxy server that bridges WebSocket clients to ACP agents",
+  "author": "claude-code-best",
+  "type": "module",
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "bin": {
+    "acp-link": "dist/cli/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "bun run src/cli/bin.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/selfsigned": "^2.0.4",
+    "@types/ws": "^8.18.1"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.19.0",
+    "@hono/node-server": "^1.13.8",
+    "@hono/node-ws": "^1.0.5",
+    "@stricli/auto-complete": "^1.2.4",
+    "@stricli/core": "^1.2.4",
+    "hono": "^4.7.0",
+    "pino": "^10.3.0",
+    "pino-pretty": "^13.1.3",
+    "selfsigned": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}
@@ -0,0 +1,28 @@
+import { describe, test, expect } from "bun:test";
+import { getLanIPs } from "../cert.js";
+
+describe("getLanIPs", () => {
+  test("returns an array", () => {
+    const ips = getLanIPs();
+    expect(Array.isArray(ips)).toBe(true);
+  });
+
+  test("returns only IPv4 addresses", () => {
+    const ips = getLanIPs();
+    for (const ip of ips) {
+      // IPv4 format: x.x.x.x
+      expect(ip).toMatch(/^\d+\.\d+\.\d+\.\d+$/);
+    }
+  });
+
+  test("does not include loopback addresses", () => {
+    const ips = getLanIPs();
+    expect(ips).not.toContain("127.0.0.1");
+  });
+
+  test("may be empty in isolated environments", () => {
+    // This test just ensures it doesn't throw
+    const ips = getLanIPs();
+    expect(ips.length).toBeGreaterThanOrEqual(0);
+  });
+});
@@ -0,0 +1,75 @@
+import { describe, test, expect } from "bun:test";
+import type { ServerConfig } from "../server.js";
+
+describe("Server HTTP endpoints", () => {
+  test("package.json has correct bin and main entries", async () => {
+    const pkg = await import("../../package.json", { with: { type: "json" } });
+    expect(pkg.default.name).toBe("acp-link");
+    expect(pkg.default.main).toBe("./dist/server.js");
+    expect(pkg.default.bin).toBeDefined();
+    expect(pkg.default.bin["acp-link"]).toBe("dist/cli/bin.js");
+  });
+
+  test("ServerConfig interface accepts all expected fields", () => {
+    const config: ServerConfig = {
+      port: 9315,
+      host: "localhost",
+      command: "echo",
+      args: [],
+      cwd: "/tmp",
+      debug: false,
+      token: "test-token",
+      https: false,
+    };
+    expect(config.port).toBe(9315);
+    expect(config.token).toBe("test-token");
+  });
+
+  test("ServerConfig allows optional fields to be omitted", () => {
+    const config: ServerConfig = {
+      port: 9315,
+      host: "localhost",
+      command: "echo",
+      args: [],
+      cwd: "/tmp",
+    };
+    expect(config.debug).toBeUndefined();
+    expect(config.token).toBeUndefined();
+    expect(config.https).toBeUndefined();
+  });
+});
+
+describe("WebSocket message types", () => {
+  const clientMessageTypes = [
+    "connect",
+    "disconnect",
+    "new_session",
+    "prompt",
+    "permission_response",
+    "cancel",
+    "set_session_model",
+    "list_sessions",
+    "load_session",
+    "resume_session",
+    "ping",
+  ];
+
+  test("all client message types are recognized", () => {
+    expect(clientMessageTypes.length).toBe(11);
+    expect(clientMessageTypes).toContain("ping");
+    expect(clientMessageTypes).toContain("connect");
+    expect(clientMessageTypes).toContain("cancel");
+  });
+});
+
+describe("Heartbeat constants", () => {
+  test("PERMISSION_TIMEOUT_MS is 5 minutes", () => {
+    const PERMISSION_TIMEOUT_MS = 5 * 60 * 1000;
+    expect(PERMISSION_TIMEOUT_MS).toBe(300_000);
+  });
+
+  test("HEARTBEAT_INTERVAL_MS is 30 seconds", () => {
+    const HEARTBEAT_INTERVAL_MS = 30_000;
+    expect(HEARTBEAT_INTERVAL_MS).toBe(30_000);
+  });
+});
@@ -0,0 +1,69 @@
+import { describe, test, expect } from "bun:test";
+import { isRequest, isResponse, isNotification } from "../types.js";
+import type { JsonRpcRequest, JsonRpcResponse, JsonRpcNotification } from "../types.js";
+
+describe("isRequest", () => {
+  test("returns true for a valid JSON-RPC request", () => {
+    const msg: JsonRpcRequest = { jsonrpc: "2.0", id: 1, method: "test" };
+    expect(isRequest(msg)).toBe(true);
+  });
+
+  test("returns true for request with params", () => {
+    const msg = { jsonrpc: "2.0" as const, id: "abc", method: "test", params: { x: 1 } };
+    expect(isRequest(msg)).toBe(true);
+  });
+
+  test("returns false for response (no method)", () => {
+    const msg: JsonRpcResponse = { jsonrpc: "2.0", id: 1, result: {} };
+    expect(isRequest(msg)).toBe(false);
+  });
+
+  test("returns false for notification (no id)", () => {
+    const msg: JsonRpcNotification = { jsonrpc: "2.0", method: "notify" };
+    expect(isRequest(msg)).toBe(false);
+  });
+});
+
+describe("isResponse", () => {
+  test("returns true for a valid JSON-RPC response with result", () => {
+    const msg: JsonRpcResponse = { jsonrpc: "2.0", id: 1, result: "ok" };
+    expect(isResponse(msg)).toBe(true);
+  });
+
+  test("returns true for a valid JSON-RPC error response", () => {
+    const msg: JsonRpcResponse = { jsonrpc: "2.0", id: 2, error: { code: -32600, message: "bad" } };
+    expect(isResponse(msg)).toBe(true);
+  });
+
+  test("returns false for request (has method)", () => {
+    const msg: JsonRpcRequest = { jsonrpc: "2.0", id: 1, method: "test" };
+    expect(isResponse(msg)).toBe(false);
+  });
+
+  test("returns false for notification", () => {
+    const msg: JsonRpcNotification = { jsonrpc: "2.0", method: "notify" };
+    expect(isResponse(msg)).toBe(false);
+  });
+});
+
+describe("isNotification", () => {
+  test("returns true for a valid JSON-RPC notification", () => {
+    const msg: JsonRpcNotification = { jsonrpc: "2.0", method: "update" };
+    expect(isNotification(msg)).toBe(true);
+  });
+
+  test("returns true for notification with params", () => {
+    const msg = { jsonrpc: "2.0" as const, method: "progress", params: { pct: 50 } };
+    expect(isNotification(msg)).toBe(true);
+  });
+
+  test("returns false for request (has id)", () => {
+    const msg: JsonRpcRequest = { jsonrpc: "2.0", id: 1, method: "test" };
+    expect(isNotification(msg)).toBe(false);
+  });
+
+  test("returns false for response (no method)", () => {
+    const msg: JsonRpcResponse = { jsonrpc: "2.0", id: 1, result: null };
+    expect(isNotification(msg)).toBe(false);
+  });
+});