@huynle/hub 0.6.1 → 0.7.1

package/packages/claude-code/src/tools.ts

@@ -0,0 +1,66 @@
+// Claude Code tools in the hub's vocabulary (decision fx04e42c point 4). A permission request names the hub action
+// (Bash → shell, Edit/Write/MultiEdit/NotebookEdit → edit, Read → read, mcp__<server>__<tool> → <server>_<tool>,
+// any other tool its lower-case name), what it applies to (the command, the file path, the URL: short resources,
+// never the whole tool input) and the rules an "always" reply would save (Claude's permission_suggestions).
+import { HARNESS_ACTION_MAX, HARNESS_RESOURCE_MAX, HARNESS_RESOURCES_MAX, HARNESS_SUMMARY_MAX, summarizeToolInput } from "../../protocol/src/index.ts"
+
+export interface PermissionRequestInfo {
+  readonly action: string
+  readonly resources: string[]
+  /** Rules an "always" reply saves, as Claude Code writes them (`Bash(npm test:*)`). */
+  readonly save?: string[]
+}
+
+const EDIT_TOOLS: ReadonlySet<string> = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"])
+const MCP = /^mcp__(.+?)__(.+)$/
+
+const cut = (text: string, max: number) => (text.length > max ? `${text.slice(0, max - 1)}…` : text)
+const record = (v: unknown): Record<string, unknown> => (typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : {})
+const str = (v: unknown): string | undefined => (typeof v === "string" && v.trim() ? v : undefined)
+
+/** The hub action for a Claude Code tool name. */
+export function permissionAction(tool: string): string {
+  if (tool === "Bash") return "shell"
+  if (EDIT_TOOLS.has(tool)) return "edit"
+  if (tool === "Read") return "read"
+  const mcp = MCP.exec(tool)
+  const name = mcp ? `${mcp[1]}_${mcp[2]}` : tool.toLowerCase()
+  const clean = name.replace(/[^A-Za-z0-9_.-]/g, "_")
+  return clean ? cut(clean, HARNESS_ACTION_MAX) : "unknown"
+}
+
+/** What a tool call applies to: its command, file, path, URL or pattern (one short text), else nothing. */
+function resourceOf(tool: string, input: unknown): string | undefined {
+  const r = record(input)
+  const value = tool === "Bash" ? str(r.command) : (str(r.file_path) ?? str(r.notebook_path) ?? str(r.path) ?? str(r.url) ?? str(r.pattern))
+  return value === undefined ? undefined : cut(value, HARNESS_RESOURCE_MAX)
+}
+
+/** permission_suggestions' addRules entries as rule texts (`Tool(content)`, or `Tool` alone). */
+function savedRules(suggestions: unknown): string[] {
+  const out: string[] = []
+  for (const s of Array.isArray(suggestions) ? suggestions : []) {
+    const suggestion = record(s)
+    if (suggestion.type !== "addRules" || (suggestion.behavior !== undefined && suggestion.behavior !== "allow")) continue
+    for (const rule of Array.isArray(suggestion.rules) ? suggestion.rules : []) {
+      const { toolName, ruleContent } = record(rule)
+      if (typeof toolName !== "string" || !toolName) continue
+      const text = typeof ruleContent === "string" && ruleContent ? `${toolName}(${ruleContent})` : toolName
+      if (!out.includes(text) && out.length < HARNESS_RESOURCES_MAX) out.push(cut(text, HARNESS_RESOURCE_MAX))
+    }
+  }
+  return out
+}
+
+/** A PermissionRequest hook input as the hub's permission.asked fields. */
+export function permissionRequest(tool: string, input: unknown, suggestions: unknown): PermissionRequestInfo {
+  const resource = resourceOf(tool, input)
+  const save = savedRules(suggestions)
+  return { action: permissionAction(tool), resources: resource === undefined ? [] : [resource], ...(save.length ? { save } : {}) }
+}
+
+/** A short summary of a tool call (its command or path's first line), or undefined when it has none. */
+export function toolSummary(tool: string, input: unknown): string | undefined {
+  const line = (resourceOf(tool, input) ?? summarizeToolInput(input)).trim().split("\n")[0]!
+  return line ? cut(line, HARNESS_SUMMARY_MAX) : undefined
+}

package/packages/claude-code/src/wire.ts

@@ -0,0 +1,71 @@
+// The local protocol between the hook bridge (and the wrapper and the MCP pipe) and the per-user daemon: one JSON
+// object per line over the daemon's Unix socket (in a 0700 directory, the socket itself 0600; no TCP, no HTTP).
+// A client sends one request line; the daemon answers one reply line and closes, except for "mcp", after which both
+// sides exchange JSON-RPC lines until either closes.
+import { Socket } from "node:net"
+
+export const WIRE_VERSION = 1
+/** Longest line either side accepts (hook stdin can carry large tool inputs). */
+export const MAX_LINE = 4 * 1024 * 1024
+
+export type BridgeRequest =
+  /** A hook: its stdin JSON, the `hub claude` run it belongs to, and how the hook was registered. */
+  | { readonly v: 1; readonly kind: "hook"; readonly input: unknown; readonly launch?: string; readonly rewake?: true; readonly waitMs?: number }
+  /** Is the daemon there? → {ok: true, pid, state}. */
+  | { readonly v: 1; readonly kind: "ping" }
+  /** A `hub claude` run started (its pid, checked for liveness) or ended. */
+  | { readonly v: 1; readonly kind: "launch"; readonly launch: string; readonly pid: number }
+  | { readonly v: 1; readonly kind: "exit"; readonly launch: string }
+  /** The MCP pipe of a `hub claude` run: JSON-RPC lines follow in both directions. */
+  | { readonly v: 1; readonly kind: "mcp"; readonly launch?: string }
+
+/** Splits a stream into lines; a line longer than MAX_LINE ends the connection. */
+export function onLines(socket: Socket, line: (text: string) => void, max = MAX_LINE): void {
+  let buffer = ""
+  socket.setEncoding("utf8")
+  socket.on("data", (chunk: string) => {
+    buffer += chunk
+    let end: number
+    while ((end = buffer.indexOf("\n")) >= 0) {
+      const text = buffer.slice(0, end)
+      buffer = buffer.slice(end + 1)
+      if (text.trim()) line(text)
+    }
+    if (buffer.length > max) socket.destroy()
+  })
+}
+
+/**
+ * Sends one request and resolves with the daemon's reply (parsed JSON), or undefined when there is no daemon, it
+ * closed without a reply, answered something that is not JSON, or took longer than `timeoutMs`. Never rejects.
+ */
+export function ask(socketPath: string, req: BridgeRequest, options: { readonly timeoutMs?: number } = {}): Promise<unknown> {
+  return new Promise((resolve) => {
+    let done = false
+    // Listeners first: Bun reports a missing socket synchronously, inside connect().
+    const socket = new Socket()
+    const finish = (value: unknown) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      socket.destroy()
+      resolve(value)
+    }
+    const timer = options.timeoutMs === undefined ? undefined : setTimeout(() => finish(undefined), options.timeoutMs)
+    socket.on("error", () => finish(undefined))
+    socket.on("close", () => finish(undefined))
+    socket.on("connect", () => socket.write(`${JSON.stringify(req)}\n`))
+    onLines(socket, (text) => {
+      try {
+        finish(JSON.parse(text))
+      } catch {
+        finish(undefined)
+      }
+    })
+    try {
+      socket.connect(socketPath)
+    } catch {
+      finish(undefined)
+    }
+  })
+}

package/packages/claude-code/src/wrapper.ts

@@ -0,0 +1,155 @@
+// `hub claude [claude args…]` (decision fx04e42c point 4): runs Claude Code with the hub plugin loaded through
+// --plugin-dir, never by editing the user's ~/.claude files. It makes sure the per-user daemon answers on its socket
+// (starting `hub claude-code daemon` in the background when none does), writes the plugin directory for the
+// current settings, registers the run with the daemon (a launch: its pid, so the daemon ends the run's sessions if it
+// dies) and runs `claude` with the user's arguments, its exit code passed through. Claude Code and its hooks get
+// HUB_CLAUDE_LAUNCH and HUB_CLAUDE_SOCKET (and HUB_CLAUDE_REWAKE=off for a -p run without streaming input, where the
+// asyncRewake Stop hook would hold the run until its timeout). On a machine that is not enrolled (no machine token) or when the daemon
+// cannot be started, Claude Code runs without the hub, and the command says why.
+//
+// Settings (environment): HUB_CLAUDE_BIN (default `claude` on PATH), HUB_CLAUDE_PERMISSION_WAIT (seconds a
+// permission request waits for the hub, default 120; 0: report only), HUB_CLAUDE_REWAKE_TIMEOUT (seconds the
+// asyncRewake Stop hook may wait for a message, default 3600).
+import { spawn } from "node:child_process"
+import { randomBytes } from "node:crypto"
+import { closeSync, openSync } from "node:fs"
+import path from "node:path"
+import { configPath } from "../../../src/config.ts"
+import { readSpokeCredentials } from "../../node/src/config.ts"
+import pkg from "../package.json" with { type: "json" }
+import { writePlugin } from "./plugin.ts"
+import { claudeStateDir, ensurePrivateDir, socketPath } from "./paths.ts"
+import { ask, WIRE_VERSION } from "./wire.ts"
+
+export const VERSION: string = pkg.version
+export const DEFAULT_PERMISSION_WAIT_S = 120
+export const DEFAULT_REWAKE_TIMEOUT_S = 3600
+const DAEMON_START_MS = 8000
+const ASK_MS = 2000
+
+type Env = Readonly<Record<string, string | undefined>>
+
+export interface Program {
+  readonly execPath: string
+  readonly entry: string
+}
+
+export interface ClaudeIo {
+  readonly env: Env
+  readonly home: string
+  stderr(s: string): void
+  /** What runs the hub CLI (the daemon and the hooks run it too). */
+  readonly program: Program
+}
+
+/** A non-negative number of seconds from the environment, else the default. */
+export function seconds(value: string | undefined, fallback: number): number {
+  const n = value === undefined || value.trim() === "" ? NaN : Number(value)
+  return Number.isFinite(n) && n >= 0 ? n : fallback
+}
+
+const pingOk = async (socket: string) => ((await ask(socket, { v: WIRE_VERSION, kind: "ping" }, { timeoutMs: ASK_MS })) as { ok?: unknown } | undefined)?.ok === true
+
+/** Starts `hub claude-code daemon` detached, logging to daemon.log in the spoke's state directory. */
+function spawnDaemon(io: ClaudeIo): void {
+  const dir = claudeStateDir(io.env, io.home)
+  ensurePrivateDir(dir)
+  const log = openSync(path.join(dir, "daemon.log"), "a", 0o600)
+  try {
+    const child = spawn(io.program.execPath, [io.program.entry, "claude-code", "daemon"], { detached: true, stdio: ["ignore", log, log], env: { ...io.env, BUN_BE_BUN: "1" } })
+    child.on("error", () => {})
+    child.unref()
+  } finally {
+    closeSync(log)
+  }
+}
+
+/** Writes (once) the hub plugin for these settings and returns its directory (`hub claude` and hub launches load it). */
+export function hubPlugin(env: Env, home: string, program: Program): string {
+  return writePlugin(path.join(claudeStateDir(env, home), "plugins"), {
+    program,
+    permissionWaitS: seconds(env.HUB_CLAUDE_PERMISSION_WAIT, DEFAULT_PERMISSION_WAIT_S),
+    rewakeTimeoutS: seconds(env.HUB_CLAUDE_REWAKE_TIMEOUT, DEFAULT_REWAKE_TIMEOUT_S) || DEFAULT_REWAKE_TIMEOUT_S,
+    version: VERSION,
+  })
+}
+
+/** The plugin directory when the hub can be used, else undefined (with the reason on stderr). */
+async function prepare(io: ClaudeIo, socket: string): Promise<string | undefined> {
+  if (!readSpokeCredentials(io.env, io.home)) {
+    io.stderr(`hub claude: this machine is not enrolled with a hub (no machine token in ${configPath(io.env, io.home)}); running Claude Code without the hub\n`)
+    return undefined
+  }
+  if (!(await pingOk(socket))) {
+    spawnDaemon(io)
+    const deadline = Date.now() + DAEMON_START_MS
+    let up = false
+    while (!up && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 100))
+      up = await pingOk(socket)
+    }
+    if (!up) {
+      io.stderr(`hub claude: the Claude Code spoke daemon did not start (see ${path.join(claudeStateDir(io.env, io.home), "daemon.log")}); running Claude Code without the hub\n`)
+      return undefined
+    }
+  }
+  return hubPlugin(io.env, io.home, io.program)
+}
+
+/** Runs `bin` with the terminal; resolves with its exit code (128 + signal number when a signal ended it). */
+function spawnClaude(bin: string, args: readonly string[], env: Env, stderr: (s: string) => void): Promise<number> {
+  return new Promise((resolve) => {
+    const child = spawn(bin, args, { stdio: "inherit", env: env as NodeJS.ProcessEnv })
+    // The terminal sends Ctrl-C to Claude Code too: it decides what that means; this process keeps waiting.
+    const ignore = () => {}
+    const forward = () => child.kill("SIGTERM")
+    process.on("SIGINT", ignore)
+    process.on("SIGTERM", forward)
+    const done = (code: number) => {
+      process.off("SIGINT", ignore)
+      process.off("SIGTERM", forward)
+      resolve(code)
+    }
+    child.on("error", (cause) => {
+      stderr(`hub claude: cannot run ${bin}: ${cause.message}\n`)
+      done(127)
+    })
+    child.on("exit", (code, signal) => done(code ?? (signal ? 128 + (signalNumber(signal) ?? 0) : 1)))
+  })
+}
+
+const SIGNALS: Record<string, number> = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 }
+const signalNumber = (signal: string) => SIGNALS[signal]
+
+/**
+ * A print run (-p/--print) without streaming input: Claude Code runs the asyncRewake Stop hook in the foreground
+ * there and exits only when it does (live check P7-T11), so `hub claude -p` would wait out HUB_CLAUDE_REWAKE_TIMEOUT.
+ */
+export function printWithoutStreamingInput(args: readonly string[]): boolean {
+  if (!args.includes("-p") && !args.includes("--print")) return false
+  const at = args.indexOf("--input-format")
+  return !(args.includes("--input-format=stream-json") || (at >= 0 && args[at + 1] === "stream-json"))
+}
+
+export async function runClaude(args: readonly string[], io: ClaudeIo): Promise<number> {
+  const socket = socketPath(io.env, io.home)
+  let plugin: string | undefined
+  try {
+    plugin = await prepare(io, socket)
+  } catch (cause) {
+    io.stderr(`hub claude: ${cause instanceof Error ? cause.message : String(cause)}; running Claude Code without the hub\n`)
+  }
+  if (args.includes("--bare") && plugin) io.stderr("hub claude: --bare turns off Claude Code's hooks and plugins: this session will not reach the hub\n")
+  const env: Record<string, string | undefined> = { ...io.env }
+  delete env.BUN_BE_BUN
+  const launch = `cl_${randomBytes(8).toString("hex")}`
+  if (plugin) {
+    env.HUB_CLAUDE_LAUNCH = launch
+    env.HUB_CLAUDE_SOCKET = socket
+    if (printWithoutStreamingInput(args)) env.HUB_CLAUDE_REWAKE = "off"
+    await ask(socket, { v: WIRE_VERSION, kind: "launch", launch, pid: process.pid }, { timeoutMs: ASK_MS })
+  }
+  const code = await spawnClaude(io.env.HUB_CLAUDE_BIN || "claude", plugin ? ["--plugin-dir", plugin, ...args] : [...args], env, io.stderr)
+  if (plugin) await ask(socket, { v: WIRE_VERSION, kind: "exit", launch }, { timeoutMs: ASK_MS })
+  return code
+}