@huynle/hub 0.6.1 → 0.7.2

package/packages/cli/src/launches.ts

@@ -0,0 +1,157 @@
+// `hub launch` and `hub launches list | show | stop` (design §6.1; decision znbg8xa5): the flags as a launch spec
+// for POST /api/agent/launches, and the launch routes' answers as short text. The CLI checks only the flags' own
+// shape (enums, key=value, what needs what); the hub validates the spec and fills in its defaults.
+import path from "node:path"
+import type { LaunchSpec, LaunchStep, LaunchView } from "../../sdk/src/index.ts"
+import { CLEANUP_POLICIES, LAUNCH_END_WHEN, RUNTIME_KINDS, WORKSPACE_MODES } from "../../protocol/src/launch.ts"
+import { str, UsageError, type FlagKind, type Parsed } from "./args"
+
+export const LAUNCH_FLAGS: Readonly<Record<string, FlagKind>> = {
+  key: "string",
+  name: "string",
+  role: "multi",
+  harness: "string",
+  agent: "string",
+  model: "string",
+  repo: "string",
+  mode: "string",
+  branch: "string",
+  base: "string",
+  remote: "string",
+  runtime: "string",
+  profile: "string",
+  machine: "string",
+  prefer: "bool",
+  "node-label": "multi",
+  label: "multi",
+  prompt: "string",
+  end: "string",
+  timeout: "string",
+  cleanup: "string",
+}
+
+/** `a, b or c` */
+const choices = (options: readonly string[]) => (options.length === 2 ? options.join(" or ") : `${options.slice(0, -1).join(", ")} or ${options.at(-1)}`)
+
+function oneOf<T extends string>(flags: Parsed["flags"], flag: string, options: readonly T[]): T | undefined {
+  const value = str(flags, flag)
+  if (value === undefined) return undefined
+  if (!options.includes(value as T)) throw new UsageError(`--${flag} is ${choices(options)}`)
+  return value as T
+}
+
+/** Repeated `--flag key=value` as an object; undefined when none is given. */
+export function pairsArg(flags: Parsed["flags"], flag: string): Record<string, string> | undefined {
+  const given = flags[flag] as string[] | undefined
+  if (!given?.length) return undefined
+  const out: Record<string, string> = {}
+  for (const pair of given) {
+    const at = pair.indexOf("=")
+    if (at < 1) throw new UsageError(`--${flag} takes key=value (got ${JSON.stringify(pair)})`)
+    out[pair.slice(0, at)] = pair.slice(at + 1)
+  }
+  return out
+}
+
+/** Only the defined fields of `fields`; undefined when none is. */
+function defined<T extends Record<string, unknown>>(fields: T): Partial<T> | undefined {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(fields)) if (value !== undefined) out[key] = value
+  return Object.keys(out).length ? (out as Partial<T>) : undefined
+}
+
+export interface LaunchArgContext {
+  /** Relative --repo paths resolve against it; the default repo. */
+  readonly cwd: string
+  readonly stdin?: () => Promise<string>
+}
+
+/** The launch spec the flags describe (only the given fields). */
+export async function launchSpecArg(flags: Parsed["flags"], context: LaunchArgContext): Promise<LaunchSpec> {
+  const mode = oneOf(flags, "mode", WORKSPACE_MODES)
+  const kind = oneOf(flags, "runtime", RUNTIME_KINDS)
+  const when = oneOf(flags, "end", LAUNCH_END_WHEN)
+  const cleanup = oneOf(flags, "cleanup", CLEANUP_POLICIES)
+  const nodeLabels = pairsArg(flags, "node-label")
+  const labels = pairsArg(flags, "label")
+  const profile = str(flags, "profile")
+  const machine = str(flags, "machine")
+  if (profile !== undefined && kind === undefined) throw new UsageError("--profile needs --runtime (e.g. --runtime openshell)")
+  if (flags.prefer === true && machine === undefined && nodeLabels === undefined) throw new UsageError("--prefer needs --machine or --node-label")
+
+  let prompt = str(flags, "prompt")
+  if (prompt === "-") {
+    if (!context.stdin) throw new UsageError("cannot read the prompt from stdin here")
+    prompt = await context.stdin()
+  }
+  if (prompt !== undefined && !prompt.trim()) throw new UsageError("--prompt is empty")
+
+  const repo = path.resolve(context.cwd, str(flags, "repo") ?? ".")
+  const roles = (flags.role as string[] | undefined)?.map((r) => r.replace(/^@@/, ""))
+  const name = str(flags, "name")?.replace(/^@+/, "")
+  const workspace = { repo, ...defined({ mode, branch: str(flags, "branch"), base: str(flags, "base"), remote: str(flags, "remote") }) }
+  const runtime = kind === undefined ? undefined : { kind, ...(profile !== undefined ? { profile } : {}) }
+  const placement = defined({ labels: nodeLabels, machine, mode: flags.prefer === true ? ("prefer" as const) : undefined })
+  const end = defined({ when, timeout: str(flags, "timeout"), cleanup })
+  return {
+    ...defined({ key: str(flags, "key"), name, roles, harness: str(flags, "harness"), agent: str(flags, "agent"), model: str(flags, "model") }),
+    workspace,
+    ...defined({ runtime, placement, prompt, labels, end }),
+  }
+}
+
+// ---------- text ----------
+
+const at = (name: string) => `@${name.replace(/^@+/, "")}`
+const stateText = (l: Pick<LaunchView, "state" | "outcome">) => (l.outcome ? `${l.state} ${l.outcome}` : l.state)
+const sessionText = (l: LaunchView) => [l.name ? at(l.name) : undefined, l.sessionID].filter(Boolean).join(" ")
+const labelsText = (labels: Readonly<Record<string, string>> | undefined) =>
+  Object.entries(labels ?? {})
+    .map(([k, v]) => `${k}=${v}`)
+    .join(" ")
+
+/** `lch_1: running (session started), @api ses_1` */
+const summary = (l: LaunchView) => `${l.id}: ${stateText(l)} (${l.reason})${sessionText(l) ? `, ${sessionText(l)}` : ""}`
+
+/** What `hub launch` prints: a new launch, or the existing launch of the same key. */
+export function launchedText(launch: LaunchView, created: boolean, key: string | undefined = launch.spec.key): string {
+  if (created || key === undefined) return `launched ${summary(launch)}`
+  return `${launch.id} was already launched with key ${key}: ${summary(launch).slice(launch.id.length + 2)}`
+}
+
+export const stoppedLaunchText = (launch: LaunchView): string => `stopped ${summary(launch)}`
+
+/** `lch_1  running  @api ses_1  /repo (branch)  app=brain` */
+export function launchLine(l: LaunchView): string {
+  const where = l.directory ?? `${l.spec.workspace.repo}${l.spec.workspace.branch ? ` (${l.spec.workspace.branch})` : ""}`
+  return [l.id, stateText(l), sessionText(l) || undefined, where, labelsText(l.spec.labels) || undefined].filter(Boolean).join("  ")
+}
+
+export const launchesText = (launches: readonly LaunchView[]): string => (launches.length ? launches.map(launchLine).join("\n") : "no launches")
+
+function artifactsText(a: NonNullable<LaunchView["artifacts"]>): string {
+  const parts: string[] = []
+  if (a.branch) parts.push(`branch ${a.branch}${a.base ? ` from ${a.base}` : ""}`)
+  if (a.head) parts.push(`head ${a.head}`)
+  if (a.commits !== undefined) parts.push(`${a.commits} commit${a.commits === 1 ? "" : "s"}`)
+  if (a.dirty !== undefined) parts.push(a.dirty ? "uncommitted changes" : "clean")
+  return parts.join(", ")
+}
+
+const stepText = (s: LaunchStep) => `  ${new Date(s.at).toISOString()}  ${stateText(s)}: ${s.reason}`
+
+/** `hub launches show`: the launch, its spec, its steps. */
+export function launchText(l: LaunchView): string {
+  const ws = l.spec.workspace
+  const lines = [`${l.id}  ${stateText(l)} (${l.reason})`]
+  if (sessionText(l) || l.machineID) lines.push(`session: ${[sessionText(l) || "none yet", l.machineID ? `on ${l.machineID}` : undefined].filter(Boolean).join(" ")}`)
+  lines.push(`workspace: ${[ws.repo, ws.mode, ws.branch].filter(Boolean).join(" ")}${ws.base ? ` from ${ws.base}` : ""}${l.directory ? ` → ${l.directory}` : ""}`)
+  const run = [l.spec.harness, l.spec.agent, l.spec.model, l.spec.runtime ? `${l.spec.runtime.kind}${l.spec.runtime.profile ? `/${l.spec.runtime.profile}` : ""}` : undefined].filter(Boolean)
+  if (run.length) lines.push(`runs: ${run.join(" ")}`)
+  if (l.spec.end) lines.push(`ends: ${[l.spec.end.when, l.spec.end.timeout ? `timeout ${l.spec.end.timeout}` : undefined, l.spec.end.cleanup ? `cleanup ${l.spec.end.cleanup}` : undefined].filter(Boolean).join(", ")}`)
+  if (l.by) lines.push(`by: ${l.by}`)
+  if (labelsText(l.spec.labels)) lines.push(`labels: ${labelsText(l.spec.labels)}`)
+  if (l.artifacts && artifactsText(l.artifacts)) lines.push(`artifacts: ${artifactsText(l.artifacts)}`)
+  if (l.history?.length) lines.push("steps:", ...l.history.map(stepText))
+  return lines.join("\n")
+}

package/packages/cli/src/login.ts

@@ -0,0 +1,160 @@
+// `hub login` without --token: the CLI login device code (src/central/http.ts, POST /cli/login and /cli/login/poll).
+// The terminal asks with its name and the scopes it wants; a signed-in user approves it in the console as
+// themselves, choosing the scopes (launch only when they tick it or the terminal asked for it); the next poll hands
+// out an app token of that user, once.
+//
+// Policy (the machine enrollment's, packages/cli/src/bootstrap/enrollment/policy.ts):
+// - The hub URL is https (plain http only for a loopback hub); redirects are refused, never followed.
+// - The approval link shown is on the hub's own origin (approvalURL).
+// - The wait is bounded by the hub's expiry and by maxWaitMs; `signal` cancels it.
+// - The token is returned to the caller only, never printed. A poll that fails in transit is retried until the
+//   deadline (a reply lost after the hub handed the token out cannot be fetched again: the user revokes that token).
+import { approvalURL, checkServerURL, isUserCode } from "./bootstrap/enrollment/policy.ts"
+import { UsageError } from "./args"
+import { CliError, EXIT } from "./http"
+
+/** The longest a login waits for approval, whatever the hub says (the hub's own expiry is 10 minutes). */
+export const LOGIN_MAX_WAIT_MS = 15 * 60_000
+const MIN_INTERVAL_MS = 500
+const MAX_INTERVAL_MS = 30_000
+
+/** What to show the user while waiting. Never a credential. */
+export interface LoginPrompt {
+  readonly userCode: string
+  readonly approveURL: string
+  readonly expiresAt: number
+  /** The scopes the approval page offers ticked. */
+  readonly scopes: readonly string[]
+  readonly warning?: string
+}
+
+export interface DeviceLoginOptions {
+  readonly server: string
+  /** Names this terminal on the approval page (and in the token's label). */
+  readonly clientName: string
+  /** Asked for beyond the hub's defaults (sessions:read, messages:send, messages:read). */
+  readonly scopes?: readonly string[]
+  readonly fetch?: typeof fetch
+  readonly signal?: AbortSignal
+  readonly now?: () => number
+  /** The poll interval (default: the hub's, at least 500 ms). */
+  readonly intervalMs?: number
+  readonly maxWaitMs?: number
+  readonly onPrompt?: (prompt: LoginPrompt) => void
+}
+
+export interface DeviceLogin {
+  readonly token: string
+  readonly tokenID: string
+  readonly scopes: readonly string[]
+}
+
+const cancelled = () => new CliError(EXIT.needsUser, "login cancelled; nothing was stored", "Run `hub login` again")
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve()
+    const timer = setTimeout(done, ms)
+    function done() {
+      clearTimeout(timer)
+      signal?.removeEventListener("abort", done)
+      resolve()
+    }
+    signal?.addEventListener("abort", done, { once: true })
+  })
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value)
+const stringList = (value: unknown): string[] | undefined => (Array.isArray(value) && value.every((s) => typeof s === "string") ? (value as string[]) : undefined)
+
+/** POSTs JSON without following redirects; the parsed reply, or a CliError. */
+async function post(fetcher: typeof fetch, server: string, pathname: string, body: unknown, signal?: AbortSignal): Promise<{ status: number; body: unknown }> {
+  let response: Response
+  try {
+    response = await fetcher(`${server}${pathname}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), redirect: "manual", ...(signal ? { signal } : {}) })
+  } catch (cause) {
+    if (signal?.aborted) throw cancelled()
+    throw new CliError(EXIT.unavailable, `could not reach ${server}`, "Check the URL given to `hub login`")
+  }
+  if (response.status >= 300 && response.status < 400) throw new CliError(EXIT.other, `${server} redirected the login request; login does not follow redirects`, "Use the hub's final https URL")
+  let parsed: unknown
+  try {
+    parsed = await response.json()
+  } catch {
+    parsed = undefined
+  }
+  return { status: response.status, body: parsed }
+}
+
+const hubMessage = (body: unknown): string | undefined => (isRecord(body) && isRecord(body.error) && typeof body.error.message === "string" ? body.error.message.slice(0, 200) : undefined)
+
+/** Runs the device-code login: the approved app token, or a CliError (nothing to store). */
+export async function deviceLogin(options: DeviceLoginOptions): Promise<DeviceLogin> {
+  const server = checkServerURL(options.server)
+  if (!server) throw new UsageError(`the hub URL must be https (plain http only for a loopback hub), without user info, query or fragment: ${String(options.server).slice(0, 200)}`)
+  const fetcher = options.fetch ?? fetch
+  const now = options.now ?? Date.now
+  const { signal } = options
+  if (signal?.aborted) throw cancelled()
+
+  const started = await post(fetcher, server, "/cli/login", { clientName: options.clientName, ...(options.scopes?.length ? { scopes: options.scopes } : {}) }, signal)
+  if (started.status === 404) throw new CliError(EXIT.unavailable, `${server} has no CLI login (an older hub)`, "Create an app token in the console (Settings → Agents) and run `hub login --token <token>`")
+  if (started.status !== 200) throw new CliError(started.status === 429 ? EXIT.rateLimited : started.status === 400 ? EXIT.usage : EXIT.other, `${server} refused the login: ${hubMessage(started.body) ?? `HTTP ${started.status}`}`)
+  const start = started.body
+  if (!isRecord(start) || !isUserCode(start.userCode) || typeof start.deviceCode !== "string" || !start.deviceCode || !Number.isFinite(start.expiresAt) || !Number.isFinite(start.intervalMs)) {
+    throw new CliError(EXIT.other, `${server} sent an invalid login reply`)
+  }
+  const link = approvalURL(server, start.approveURL, start.userCode)
+  const expiresAt = Math.min(start.expiresAt as number, now() + (options.maxWaitMs ?? LOGIN_MAX_WAIT_MS))
+  options.onPrompt?.({ userCode: start.userCode, approveURL: link.url, expiresAt, scopes: stringList(start.scopes) ?? [], ...(link.warning ? { warning: link.warning } : {}) })
+
+  const interval = options.intervalMs ?? Math.min(Math.max(start.intervalMs as number, MIN_INTERVAL_MS), MAX_INTERVAL_MS)
+  for (;;) {
+    if (signal?.aborted) throw cancelled()
+    if (now() > expiresAt) break
+    let poll: { status: number; body: unknown } | undefined
+    try {
+      poll = await post(fetcher, server, "/cli/login/poll", { deviceCode: start.deviceCode }, signal)
+    } catch (cause) {
+      if (signal?.aborted) throw cancelled()
+      if (!(cause instanceof CliError) || cause.exit !== EXIT.unavailable) throw cause
+      poll = undefined // in transit: try again
+    }
+    if (poll?.status === 429) throw new CliError(EXIT.rateLimited, `the login was approved, but ${hubMessage(poll.body) ?? "the hub could not issue a token"}`, "Revoke unused app tokens in the console (Settings → Agents) and run `hub login` again")
+    const status = poll && isRecord(poll.body) ? poll.body.status : undefined
+    if (status === "approved") {
+      const body = poll!.body as Record<string, unknown>
+      const scopes = stringList(body.scopes)
+      if (typeof body.token !== "string" || !body.token || typeof body.tokenID !== "string" || !scopes) throw new CliError(EXIT.other, `${server} sent an invalid login reply`)
+      return { token: body.token, tokenID: body.tokenID, scopes }
+    }
+    if (status === "denied") throw new CliError(EXIT.forbidden, "the login was denied on the hub; nothing was stored")
+    if (status === "expired") break
+    await sleep(interval, signal)
+  }
+  if (signal?.aborted) throw cancelled()
+  throw new CliError(EXIT.needsUser, "the login code expired before it was approved; nothing was stored", "Run `hub login` again and approve the code in the console")
+}
+
+/** The lines printed while waiting (stderr). */
+export function promptText(prompt: LoginPrompt): string {
+  const minutes = Math.max(1, Math.round((prompt.expiresAt - Date.now()) / 60_000))
+  return [
+    ...(prompt.warning ? [`hub: warning: ${prompt.warning}`] : []),
+    `To log in, open ${prompt.approveURL}`,
+    `and approve code ${prompt.userCode} as yourself (expires in ${minutes} min; Ctrl-C cancels).`,
+    ...(prompt.scopes.length ? [`Requested scopes: ${prompt.scopes.join(", ")} (you choose on the page).`] : []),
+    "Waiting for approval…",
+  ].join("\n")
+}
+
+/** What the new login may not do yet, and how to get it (stdout, after the login). */
+export function scopeNotes(scopes: readonly string[], tokenID: string): string[] {
+  if (!scopes.includes("sessions:launch")) return ["note: this login cannot launch sessions; to launch from this terminal run `hub login --scope sessions:launch` (or tick \"Launch sessions\" on the approval page)"]
+  return [
+    `note: launching also needs a grant with verb launch for this token (holder app:${tokenID}) covering the repository:`,
+    scopes.includes("messages:send")
+      ? `  create it in the console, or ask for it: hub grant request --project <repo path> --allow launch --why "launch from my terminal"`
+      : "  create it in the console (Settings → Agents)",
+  ]
+}

package/packages/cli/src/main.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env bun
+// Entry of the hub CLI (`hub` / `hubctl`, one command surface): the npm bundle the spoke's launchers run as
+// `BUN_BE_BUN=1 <opencode binary> hub-cli.js …` (or node), and the standalone hubctl (`bun build --compile` of this
+// file; scripts/build-hubctl.sh). See cli.ts for the program.
+import { homedir } from "node:os"
+import { createInterface } from "node:readline"
+import { run } from "./cli"
+
+// The launcher sets BUN_BE_BUN so the OpenCode binary acts as bun; nothing this process starts may inherit it.
+delete process.env.BUN_BE_BUN
+
+const argv = process.argv.slice(2)
+
+/** All of stdin when piped; a prompted line on a terminal (`hub login` without --token). */
+async function stdin(): Promise<string> {
+  if (!process.stdin.isTTY) {
+    const chunks: Buffer[] = []
+    for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk))
+    return Buffer.concat(chunks).toString("utf8")
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true })
+  try {
+    return await new Promise<string>((resolve) => rl.question("App token: ", resolve))
+  } finally {
+    rl.close()
+  }
+}
+
+// Only `watch`, `mcp` and `node run` run until interrupted: SIGINT/SIGTERM end them cleanly (exit 0; the service
+// units stop the node with SIGTERM); other commands keep the default.
+const nodeRun = argv[0] === "node" && argv[1] === "run"
+// `hub claude-code daemon` and `hub claude-code mcp` (the Claude Code spoke) run until interrupted too.
+const claudeDaemon = argv[0] === "claude-code" && argv[1] === "daemon"
+const claudeMcp = argv[0] === "claude-code" && argv[1] === "mcp"
+// `hub codex-spoke serve` (the Codex spoke service) and `hub preset run` (until its pane ends) too.
+const codexServe = argv[0] === "codex-spoke" && argv[1] === "serve"
+const presetRun = argv[0] === "preset" && argv[1] === "run"
+// `hubctl machine enroll` and `hub login` (device code) poll until the code is approved: Ctrl-C cancels them (exit 4,
+// nothing stored). `hubctl setup apply` / `recover` pass the signal to their probes and the verification launch, so
+// Ctrl-C fails the running step and the transaction rolls back, instead of the process dying between a write and its
+// journal entry.
+const enroll = (argv[0] === "machine" && argv[1] === "enroll") || argv[0] === "login"
+const applying = argv[0] === "setup" && (argv[1] === "apply" || argv[1] === "recover")
+const controller = new AbortController()
+if (argv[0] === "watch" || argv[0] === "mcp" || nodeRun || claudeDaemon || claudeMcp || codexServe || presetRun || enroll || applying)
+  for (const signal of ["SIGINT", "SIGTERM"] as const) process.once(signal, () => controller.abort())
+
+process.exitCode = await run(argv, {
+  env: process.env,
+  home: homedir(),
+  stdout: (s) => process.stdout.write(s),
+  stderr: (s) => process.stderr.write(s),
+  stdin,
+  stdinIsTerminal: process.stdin.isTTY === true,
+  signal: controller.signal,
+  input: process.stdin,
+  cwd: process.cwd(),
+})
+// A signal ends `hub mcp` with its stdin still open; let go of it so the process can exit.
+if (argv[0] === "mcp" || claudeMcp) process.stdin.destroy()
+// Nothing else (sockets, timers) may keep a stopped node, Claude Code daemon or Codex spoke alive, nor `hub claude` /
+// `hub codex` once the harness exited, nor a stopped `hub preset run`.
+if (nodeRun || claudeDaemon || codexServe || argv[0] === "claude" || argv[0] === "codex" || presetRun) process.exit()