auto-harness-client 0.6.0 → 0.7.0

package/src/cli/commands/doctor.js

@@ -0,0 +1,164 @@
+import { AutoHarnessClient, AutoHarnessError } from "../../index.js";
+import { loginAsAdmin } from "../admin-login.js";
+import { allowlistPrincipal } from "../allowlist.js";
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS, resolveConfig } from "../config.js";
+
+// A raw API Gateway endpoint bypasses CloudFront, which is what injects the ingress token; the
+// host daemon's own usage text says never to use one (see cli-usage.ts).
+const EXECUTE_API_HOST = /\.execute-api\.[^.]+\.amazonaws\.com$/i;
+
+// Matches `AutoHarnessClient`'s default `requestTimeoutMs`.
+const REACHABILITY_TIMEOUT_MS = 30_000;
+
+/** Runs the url/reachability/auth checks and prints one `<status> <name>: <reason>` line each.
+ * Returns 1 if any check `fail`s, else 0 — a `warn` never fails the overall run. */
+export async function runDoctor(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: GLOBAL_BOOLEAN_FLAGS,
+  });
+  if (positionals.length > 0) {
+    throw new CliUsageError(`doctor takes no arguments; received: ${positionals.join(" ")}`);
+  }
+  const config = await resolveConfig(flags, io);
+  const checks = [
+    checkUrlShape(config.baseUrl, config.allowInsecureHttp),
+    await checkReachability(config.baseUrl, io.fetch, io.timeoutSignal ?? AbortSignal.timeout),
+    await checkAuth(config, io),
+  ];
+  for (const check of checks) io.stdout.write(formatCheck(check));
+  return checks.some((check) => check.status === "fail") ? 1 : 0;
+}
+
+/** `AutoHarnessClient` strips a trailing `/api/v1` from `baseUrl` itself; `/health` lives at the
+ * site root, so this mirrors that same normalization for the raw (non-`client.request`) fetch. */
+function siteOrigin(baseUrl) {
+  return baseUrl.replace(/\/$/, "").replace(/\/api\/v1$/, "");
+}
+
+function checkUrlShape(baseUrl, allowInsecureHttp) {
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    return { name: "url", status: "fail", message: `${baseUrl} is not a valid URL` };
+  }
+  if (url.protocol === "http:" && !allowInsecureHttp) {
+    return {
+      name: "url",
+      status: "fail",
+      message: "baseUrl uses http:// (pass --allow-insecure-http only for local/loopback dev)",
+    };
+  }
+  if (EXECUTE_API_HOST.test(url.hostname)) {
+    return {
+      name: "url",
+      status: "warn",
+      message:
+        "raw API Gateway URL bypasses CloudFront, which injects the ingress token, so " +
+        "requests will be rejected; use the CloudFront WebUrl from the deploy output instead",
+    };
+  }
+  return { name: "url", status: "ok", message: `using ${baseUrl}` };
+}
+
+/** `timeoutSignal(ms)` defaults to `AbortSignal.timeout`; tests inject one they can abort,
+ * since a real 30-second timer cannot be fast-forwarded. */
+async function checkReachability(baseUrl, fetchFn, timeoutSignal) {
+  const url = `${siteOrigin(baseUrl)}/health`;
+  // Bounded like `AutoHarnessClient`'s default, and it covers the body read below as well as
+  // the connection — without it a stalled server hangs doctor forever instead of failing.
+  const signal = timeoutSignal(REACHABILITY_TIMEOUT_MS);
+  let response;
+  let body;
+  try {
+    response = await fetchFn(url, { signal });
+    if (response.status === 200) {
+      // A non-JSON body is a failed check, but a timeout mid-body must surface as the timeout
+      // rather than be swallowed here — the same rule `AutoHarnessClient#request` applies.
+      body = await response.json().catch((error) => {
+        if (signal.aborted) throw error;
+        return undefined;
+      });
+    }
+  } catch (error) {
+    return {
+      name: "reachability",
+      status: "fail",
+      message: `GET /health failed: ${error.message}`,
+    };
+  }
+  if (response.status !== 200) {
+    return {
+      name: "reachability",
+      status: "fail",
+      message: `GET /health returned HTTP ${response.status}`,
+    };
+  }
+  if (!body || body.ok !== true) {
+    return {
+      name: "reachability",
+      status: "fail",
+      message: 'GET /health did not return {"ok":true}',
+    };
+  }
+  return { name: "reachability", status: "ok", message: "control plane is reachable" };
+}
+
+/**
+ * In admin mode the login itself is attempted here, inside this check's own try/catch — not
+ * eagerly in `resolveConfig` — so a bad admin password only fails this one check and still
+ * lets the url/reachability checks above it print, the same way a rejected API key does.
+ */
+async function checkAuth(config, io) {
+  if (!config.apiKey && !config.adminMode) {
+    return {
+      name: "auth",
+      status: "warn",
+      message: "no API key configured; only unauthenticated checks ran",
+    };
+  }
+  let fetchFn = io.fetch;
+  if (config.adminMode) {
+    try {
+      fetchFn = (
+        await loginAsAdmin(io, config.baseUrl, config.adminUsername, config.allowInsecureHttp)
+      ).fetch;
+    } catch (error) {
+      return { name: "auth", status: "fail", message: error.message };
+    }
+  }
+  let client;
+  try {
+    client = new AutoHarnessClient({
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey,
+      fetch: fetchFn,
+      allowInsecureHttp: config.allowInsecureHttp,
+    });
+  } catch (error) {
+    return { name: "auth", status: "fail", message: error.message };
+  }
+  try {
+    const principal = allowlistPrincipal(await client.request("/auth/me"));
+    const role = principal.role ?? "unknown";
+    const capabilities = Array.isArray(principal.capabilities)
+      ? principal.capabilities.join(", ")
+      : "none";
+    const message = config.adminMode
+      ? `authenticated as ${principal.username} (role ${role}; capabilities: ${capabilities})`
+      : `authenticated as role ${role} (capabilities: ${capabilities})`;
+    return { name: "auth", status: "ok", message };
+  } catch (error) {
+    if (error instanceof AutoHarnessError && error.status === 401) {
+      return { name: "auth", status: "fail", message: "API key rejected" };
+    }
+    return { name: "auth", status: "fail", message: `GET /auth/me failed: ${error.message}` };
+  }
+}
+
+function formatCheck({ status, name, message }) {
+  return `${status} ${name}: ${message}\n`;
+}

package/src/cli/commands/host-drain.js

@@ -0,0 +1,22 @@
+import { runHostIdPostAction } from "./host-post-action.js";
+
+/** `POST /hosts/drain` with `{ hostId }` in the body. */
+export async function runHostDrain(argv, io) {
+  return runHostIdPostAction(argv, io, {
+    commandName: "drain",
+    path: "/hosts/drain",
+    onSuccess: (result, hostId, flags) => {
+      if (flags["--json"]) {
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+      }
+      const runningSessionIds = result?.runningSessionIds ?? [];
+      io.stdout.write(
+        `host ${hostId} is draining (${runningSessionIds.length} session(s) still running)\n`,
+      );
+      if (runningSessionIds.length > 0) {
+        io.stdout.write(`${runningSessionIds.map((id) => `  ${id}`).join("\n")}\n`);
+      }
+    },
+  });
+}

package/src/cli/commands/host-inventory-get.js

@@ -0,0 +1,40 @@
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+import { pathSegment } from "../path-segment.js";
+
+const USAGE = "usage: auto-harness host inventory get <hostId> [--json]";
+
+/** `GET /hosts/<hostId>/inventory`. */
+export async function runHostInventoryGet(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  const [hostId] = positionals;
+  if (!hostId || positionals.length > 1) throw new CliUsageError(USAGE);
+  const hostSegment = pathSegment(hostId, "hostId");
+  const client = await createClient(flags, io);
+  const record = await client.request(`/hosts/${hostSegment}/inventory`);
+  io.stdout.write(
+    flags["--json"] ? `${JSON.stringify(record, null, 2)}\n` : formatInventory(record),
+  );
+  return 0;
+}
+
+function formatInventory(record) {
+  const lines = [`version: ${record.version ?? 0}`];
+  const repositories = record.repositories ?? [];
+  if (repositories.length === 0) {
+    lines.push("repositories: (none)");
+  } else {
+    lines.push("repositories:");
+    for (const repository of repositories) {
+      const worktreeCount = (repository.worktrees ?? []).length;
+      const label = worktreeCount === 1 ? "worktree" : "worktrees";
+      lines.push(`  ${repository.id}  ${repository.path}  (${worktreeCount} ${label})`);
+    }
+  }
+  lines.push(`provider accounts: ${(record.providerAccounts ?? []).length}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/cli/commands/host-inventory-set.js

@@ -0,0 +1,66 @@
+import { checkAdminLoginUsage } from "../admin-login.js";
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+import { pathSegment } from "../path-segment.js";
+import { readStdin } from "../read-stdin.js";
+
+const USAGE = "usage: auto-harness host inventory set <hostId> --file <path|->";
+
+const MISSING_VERSION_MESSAGE =
+  "the document has no integer `version` field: omitting it silently disables optimistic " +
+  "concurrency on the server, so a concurrent change could be overwritten with no error; " +
+  "start from `auto-harness host inventory get <hostId> --json` and edit that";
+
+/**
+ * `PUT /hosts/<hostId>/inventory`. The PUT is authoritative — it replaces the whole record —
+ * so this sends the file/stdin text verbatim as the request body rather than re-serializing a
+ * parsed copy; it only parses to validate that the document is a JSON object carrying the
+ * integer `version` the server needs for optimistic concurrency.
+ */
+export async function runHostInventorySet(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--file"],
+    booleanFlags: GLOBAL_BOOLEAN_FLAGS,
+  });
+  const [hostId] = positionals;
+  if (!hostId || positionals.length > 1 || !flags["--file"]) throw new CliUsageError(USAGE);
+  const hostSegment = pathSegment(hostId, "hostId");
+  // Both this command's own `--file -` and `--admin-password-stdin` need stdin; catch the
+  // conflict before reading either, rather than letting one silently drain the other's input.
+  const stdinClaimedBy = flags["--file"] === "-" ? "host inventory set --file -" : undefined;
+  checkAdminLoginUsage(flags, io.env, stdinClaimedBy);
+  const text = await readDocument(flags["--file"], io);
+  validateDocument(text);
+  const client = await createClient(flags, io);
+  const result = await client.request(`/hosts/${hostSegment}/inventory`, {
+    method: "PUT",
+    body: text,
+  });
+  io.stdout.write(`inventory for host ${hostId} set to version ${result?.version}\n`);
+  return 0;
+}
+
+async function readDocument(path, io) {
+  if (path === "-") return readStdin(io.stdin);
+  try {
+    return await io.readFile(path, "utf8");
+  } catch (error) {
+    throw new CliUsageError(`could not read --file ${path}: ${error.message}`);
+  }
+}
+
+function validateDocument(text) {
+  let document;
+  try {
+    document = JSON.parse(text);
+  } catch {
+    throw new CliUsageError("--file must contain valid JSON");
+  }
+  if (!document || typeof document !== "object" || Array.isArray(document)) {
+    throw new CliUsageError("--file must contain a JSON object");
+  }
+  if (!Number.isInteger(document.version)) {
+    throw new CliUsageError(MISSING_VERSION_MESSAGE);
+  }
+}

package/src/cli/commands/host-inventory.js

@@ -0,0 +1,15 @@
+import { CliUsageError } from "../cli-errors.js";
+import { runHostInventoryGet } from "./host-inventory-get.js";
+import { runHostInventorySet } from "./host-inventory-set.js";
+
+const USAGE = `usage: auto-harness host inventory <get|set> ...
+  auto-harness host inventory get <hostId> [--json]
+  auto-harness host inventory set <hostId> --file <path|->`;
+
+/** Dispatches `host inventory <get|set>`. */
+export async function runHostInventory(argv, io) {
+  const [action, ...rest] = argv;
+  if (action === "get") return runHostInventoryGet(rest, io);
+  if (action === "set") return runHostInventorySet(rest, io);
+  throw new CliUsageError(USAGE);
+}

package/src/cli/commands/host-list.js

@@ -0,0 +1,87 @@
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+
+// This repo's list/history invariant forbids unbounded collection of pages at storage, so
+// `--all` stops here and warns rather than following `nextCursor` forever.
+const MAX_ALL_PAGES = 20;
+
+/** `GET /hosts`, optionally filtered by `online`/`offline` and paged with `limit`/`cursor`.
+ * `--all` follows `nextCursor` itself, capped at `MAX_ALL_PAGES` pages. */
+export async function runHostList(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--limit", "--cursor"],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--online", "--offline", "--all", "--json"],
+  });
+  if (positionals.length > 0) {
+    throw new CliUsageError(`host list takes no arguments; received: ${positionals.join(" ")}`);
+  }
+  if (flags["--online"] && flags["--offline"]) {
+    throw new CliUsageError("--online and --offline are mutually exclusive");
+  }
+  const client = await createClient(flags, io);
+  return flags["--all"] ? runListAll(client, flags, io) : runListOnePage(client, flags, io);
+}
+
+function buildQuery(flags, cursor) {
+  const query = new URLSearchParams();
+  if (flags["--online"]) query.set("online", "online");
+  if (flags["--offline"]) query.set("online", "offline");
+  if (flags["--limit"] !== undefined) query.set("limit", flags["--limit"]);
+  if (cursor !== undefined) query.set("cursor", cursor);
+  const suffix = query.toString();
+  return suffix ? `/hosts?${suffix}` : "/hosts";
+}
+
+async function runListOnePage(client, flags, io) {
+  const page = await client.request(buildQuery(flags, flags["--cursor"]));
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify(page, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatHostLines(page.items ?? []));
+  if (page.nextCursor) {
+    io.stdout.write(
+      `more hosts available; pass --cursor ${page.nextCursor} to continue (or --all)\n`,
+    );
+  }
+  return 0;
+}
+
+async function runListAll(client, flags, io) {
+  const items = [];
+  const seenCursors = new Set();
+  let cursor = flags["--cursor"];
+  for (let pageCount = 0; pageCount < MAX_ALL_PAGES; pageCount += 1) {
+    const page = await client.request(buildQuery(flags, cursor));
+    items.push(...(page.items ?? []));
+    cursor = page.nextCursor || undefined;
+    if (!cursor) break;
+    // Mirrors the same guard in AutoHarnessClient#listCatalog: a server repeating a cursor is a
+    // bug worth failing loudly on, not something to paper over as "more pages than the cap".
+    if (seenCursors.has(cursor)) throw new Error("repeated pagination cursor for /hosts");
+    seenCursors.add(cursor);
+  }
+  if (cursor) {
+    io.stderr.write(
+      `warning: --all stopped after ${MAX_ALL_PAGES} pages; more hosts remain ` +
+        `(nextCursor: ${cursor})\n`,
+    );
+  }
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ items }, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatHostLines(items));
+  return 0;
+}
+
+function formatHostLines(items) {
+  if (items.length === 0) return "(no hosts)\n";
+  return `${items
+    .map(
+      (host) =>
+        `${host.hostId}  ${host.online ? "online" : "offline"}${host.draining ? "  draining" : ""}`,
+    )
+    .join("\n")}\n`;
+}

package/src/cli/commands/host-post-action.js

@@ -0,0 +1,38 @@
+import { AutoHarnessError } from "../../index.js";
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+import { reportError } from "../report-error.js";
+
+/**
+ * Shared shape for `host drain` and `host resume`: both POST `{ hostId }` in the body — never
+ * the path, see `local-routes-host-drain.ts` — and both can 409 on a host connection race. A
+ * 409 is reported here, inside the command, rather than left to `main.js`'s catch: once that
+ * catch runs there is no way back into this function to add the trailing retry hint, so this
+ * prints the normal error line itself (via `reportError`) and then the hint, in that order.
+ * `onSuccess(result, hostId, flags)` writes the success output — it closes over its own `io`
+ * rather than taking one here, so it does not shadow this function's `io` parameter.
+ */
+export async function runHostIdPostAction(argv, io, { commandName, path, onSuccess }) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  const [hostId] = positionals;
+  if (!hostId || positionals.length > 1) {
+    throw new CliUsageError(`usage: auto-harness host ${commandName} <hostId> [--json]`);
+  }
+  const client = await createClient(flags, io);
+  let result;
+  try {
+    result = await client.request(path, { method: "POST", body: JSON.stringify({ hostId }) });
+  } catch (error) {
+    const exitCode = reportError(error, io);
+    if (error instanceof AutoHarnessError && error.status === 409) {
+      io.stderr.write("hint: the host's connection changed mid-request; retrying is safe\n");
+    }
+    return exitCode;
+  }
+  onSuccess(result, hostId, flags);
+  return 0;
+}

package/src/cli/commands/host-repo-rm.js

@@ -0,0 +1,128 @@
+import { AutoHarnessError } from "../../index.js";
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+import { pathSegment } from "../path-segment.js";
+
+const USAGE = "usage: auto-harness host repo rm <hostId> <repositoryId> [--dry-run] [--json]";
+const MAX_ATTEMPTS = 3;
+
+/**
+ * Detaches one repository from a host's inventory as a safe read-modify-write: GET the full
+ * record, remove only the target repository (its worktrees go with it — that is a projection
+ * of the repository, not a separate thing to delete), and PUT back everything else — including
+ * `providerAccounts` — exactly as read, with the read `version` kept. On a 409 (someone else
+ * wrote first) it re-reads and re-applies, up to `MAX_ATTEMPTS` PUTs total; any other status is
+ * not retried.
+ */
+export async function runHostRepoRm(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--dry-run", "--json"],
+  });
+  const [hostId, repositoryId] = positionals;
+  if (!hostId || !repositoryId || positionals.length > 2) throw new CliUsageError(USAGE);
+  pathSegment(hostId, "hostId"); // validate before createClient, which may log in
+  const client = await createClient(flags, io);
+  const record = await getInventory(client, hostId);
+  const removal = extractRepository(record, hostId, repositoryId);
+  if (flags["--dry-run"]) {
+    printResult(io, flags, { dryRun: true, hostId, ...removal });
+    return 0;
+  }
+  return removeWithRetry(client, io, flags, hostId, repositoryId, record, removal);
+}
+
+function getInventory(client, hostId) {
+  return client.request(`/hosts/${pathSegment(hostId, "hostId")}/inventory`);
+}
+
+/** Finds the repository by id. By default throws (exit 1) listing what is actually attached;
+ * pass `required: false` to get `null` instead — used on a retry's re-read, where the
+ * repository being gone already means someone else's write reached the same goal. */
+function extractRepository(record, hostId, repositoryId, { required = true } = {}) {
+  const repositories = record.repositories ?? [];
+  const repository = repositories.find((repo) => repo.id === repositoryId);
+  if (!repository) {
+    if (!required) return null;
+    const attached = repositories.map((repo) => repo.id);
+    throw new Error(
+      `repository ${repositoryId} is not attached to host ${hostId}; attached repositories: ` +
+        (attached.length > 0 ? attached.join(", ") : "(none)"),
+    );
+  }
+  const worktreeIds = (repository.worktrees ?? []).map((worktree) => worktree.id);
+  const remaining = repositories.filter((repo) => repo.id !== repositoryId);
+  return { repository, worktreeIds, remaining };
+}
+
+async function removeWithRetry(client, io, flags, hostId, repositoryId, record, removal) {
+  let currentRecord = record;
+  let current = removal;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    const fromVersion = currentRecord.version ?? 0;
+    const document = { ...currentRecord, repositories: current.remaining, version: fromVersion };
+    try {
+      const result = await client.request(`/hosts/${pathSegment(hostId, "hostId")}/inventory`, {
+        method: "PUT",
+        body: JSON.stringify(document),
+      });
+      printResult(io, flags, {
+        dryRun: false,
+        hostId,
+        repository: current.repository,
+        worktreeIds: current.worktreeIds,
+        fromVersion,
+        toVersion: result?.version,
+      });
+      return 0;
+    } catch (error) {
+      const conflict = error instanceof AutoHarnessError && error.status === 409;
+      if (!conflict) throw error;
+      if (attempt === MAX_ATTEMPTS) {
+        throw new Error(
+          `inventory for host ${hostId} kept changing; gave up after ${MAX_ATTEMPTS} attempts`,
+          { cause: error },
+        );
+      }
+      currentRecord = await getInventory(client, hostId);
+      const next = extractRepository(currentRecord, hostId, repositoryId, { required: false });
+      if (!next) {
+        printResult(io, flags, {
+          convergedElsewhere: true,
+          hostId,
+          repository: current.repository,
+          worktreeIds: current.worktreeIds,
+          toVersion: currentRecord.version,
+        });
+        return 0;
+      }
+      current = next;
+    }
+  }
+  /* v8 ignore next 2 -- the loop above always returns or throws before falling out */
+  return 1;
+}
+
+function printResult(io, flags, info) {
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify(info, null, 2)}\n`);
+    return;
+  }
+  if (info.convergedElsewhere) {
+    io.stdout.write(
+      `repository ${info.repository.id} was already removed from host ${info.hostId} by ` +
+        `another writer (now at version ${info.toVersion})\n`,
+    );
+    return;
+  }
+  const verb = info.dryRun ? "would remove" : "removed";
+  const lines = [
+    `${verb} repository ${info.repository.id} (${info.repository.path}) from host ${info.hostId}`,
+  ];
+  if (info.worktreeIds.length > 0) {
+    lines.push(`  worktrees removed with it: ${info.worktreeIds.join(", ")}`);
+  }
+  if (!info.dryRun) lines.push(`version ${info.fromVersion} → ${info.toVersion}`);
+  io.stdout.write(`${lines.join("\n")}\n`);
+}

package/src/cli/commands/host-repo.js

@@ -0,0 +1,11 @@
+import { CliUsageError } from "../cli-errors.js";
+import { runHostRepoRm } from "./host-repo-rm.js";
+
+const USAGE = "usage: auto-harness host repo rm <hostId> <repositoryId> [--dry-run] [--json]";
+
+/** Dispatches `host repo <rm>`. */
+export async function runHostRepo(argv, io) {
+  const [action, ...rest] = argv;
+  if (action === "rm") return runHostRepoRm(rest, io);
+  throw new CliUsageError(USAGE);
+}

package/src/cli/commands/host-resume.js

@@ -0,0 +1,17 @@
+import { runHostIdPostAction } from "./host-post-action.js";
+
+/** `POST /hosts/resume` with `{ hostId }` in the body. Idempotent: safe on a host that is not
+ * currently draining. */
+export async function runHostResume(argv, io) {
+  return runHostIdPostAction(argv, io, {
+    commandName: "resume",
+    path: "/hosts/resume",
+    onSuccess: (result, hostId, flags) => {
+      if (flags["--json"]) {
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+      }
+      io.stdout.write(`host ${hostId} resumed (safe to run even if it was not draining)\n`);
+    },
+  });
+}

package/src/cli/commands/host.js

@@ -0,0 +1,25 @@
+import { CliUsageError } from "../cli-errors.js";
+import { runHostDrain } from "./host-drain.js";
+import { runHostInventory } from "./host-inventory.js";
+import { runHostList } from "./host-list.js";
+import { runHostRepo } from "./host-repo.js";
+import { runHostResume } from "./host-resume.js";
+
+const USAGE = `usage: auto-harness host <subcommand> ...
+  auto-harness host list [--online | --offline] [--limit N] [--cursor C] [--all] [--json]
+  auto-harness host drain <hostId> [--json]
+  auto-harness host resume <hostId> [--json]
+  auto-harness host inventory get <hostId> [--json]
+  auto-harness host inventory set <hostId> --file <path|->
+  auto-harness host repo rm <hostId> <repositoryId> [--dry-run] [--json]`;
+
+/** Dispatches `host <subcommand>` to its own module — mirrors `main.js`'s own dispatch. */
+export async function runHost(argv, io) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "list") return runHostList(rest, io);
+  if (subcommand === "drain") return runHostDrain(rest, io);
+  if (subcommand === "resume") return runHostResume(rest, io);
+  if (subcommand === "inventory") return runHostInventory(rest, io);
+  if (subcommand === "repo") return runHostRepo(rest, io);
+  throw new CliUsageError(USAGE);
+}