auto-harness-client 0.6.0 → 0.7.0

package/README.md

@@ -160,6 +160,20 @@ const resumed = await harness.resumeSession("session-1", { prompt: "Address the
 console.log(resumed.status);
 ```
 
+Pass `target` (and, only alongside it, `fallbacks`) to **rebind** the resume onto a different
+Command/Provider instead of continuing the source session's original route — the same
+`providerId`/`commandId`/`providerName`/`commandName` shapes as `createSession()`, resolved to ids
+the same way. This replaces the source session's whole target/fallback policy (a bare `fallbacks`
+override with no `target` is rejected) and always resumes on a fresh assignment: there is no native
+CLI resume onto a different Command, so it may also land on a different host.
+
+```js
+const resumed = await harness.resumeSession("session-1", {
+  prompt: "Continue with the updated Command.",
+  target: { commandName: "claude-print-auto" },
+});
+```
+
 ## List sessions
 
 Session listings are bounded pages with the same cursor shape as repository listings, plus
@@ -203,3 +217,276 @@ import { parseHarnessTarget, requiredEnvironmentValue } from "auto-harness-clien
 const target = parseHarnessTarget(process.env.HARNESS_TARGET);
 const apiKey = requiredEnvironmentValue(process.env, "HARNESS_API_KEY");
 ```
+
+## CLI: `auto-harness`
+
+This package also ships a small operator CLI, `auto-harness`, for scripting and debugging
+against a control plane from a shell:
+
+```sh
+npx auto-harness-client whoami
+# or, once installed:
+auto-harness whoami
+```
+
+### Configuration
+
+The CLI never touches your repository config or the host daemon's persisted env file — it only
+reads what you pass it:
+
+| Setting              | Flag                    | Environment variable(s)                       |
+| -------------------- | ----------------------- | --------------------------------------------- |
+| Base URL             | `--api-url <url>`       | `HARNESS_API_URL` (alias: `HARNESS_API_HTTP`) |
+| API key              | —                       | `HARNESS_API_KEY`                             |
+| API key, from a file | `--api-key-file <path>` | `HARNESS_API_KEY_FILE`                        |
+| Allow plain HTTP     | `--allow-insecure-http` | —                                             |
+
+A flag always wins over its environment variable. `HARNESS_API_URL`/`HARNESS_API_HTTP` are the
+same two variables the host daemon itself already accepts, so operators typically have one set.
+An `--api-key-file`/`HARNESS_API_KEY_FILE` value is read and trimmed of surrounding whitespace.
+
+**There is no `--api-key` flag.** A key passed on the command line lands in `ps` output and shell
+history for the life of the process and the life of the shell's history file. Use the
+`HARNESS_API_KEY` environment variable, or point `--api-key-file` / `HARNESS_API_KEY_FILE` at a
+file holding it; passing `--api-key` fails immediately with a usage error telling you so.
+
+Exit codes: `0` success, `1` an API/HTTP failure (or a failed `doctor` check), `2` a usage or
+configuration error.
+
+#### Admin bootstrap: `--admin-password-stdin`
+
+Every API key is minted by `service-account create`, which itself requires being authenticated —
+so the very first maintainer or service-account key can only come from an admin, and admin exists
+only as a username/password, not an API key. `--admin-password-stdin` (with `--admin-username
+<name>`, default `admin`) logs in as that admin instead of using an API key: it reads the password
+from stdin (one trailing newline stripped), `POST`s it once to `/auth/login`, and carries the
+returned session cookie on every later request for the rest of the invocation. The password never
+touches argv, shell history, or output, and the login response body — which carries the
+principal — is deliberately never read or printed.
+
+```sh
+aws ssm get-parameter --name /auto-harness/admin-password --with-decryption \
+  --query Parameter.Value --output text \
+  | auto-harness --admin-password-stdin service-account create --name ci --role operator --print-key
+```
+
+It cannot be combined with an API key (`--api-key-file`, `HARNESS_API_KEY`, or
+`HARNESS_API_KEY_FILE` all make the identity ambiguous) or with a command that also reads stdin
+for its own input (`api --body-file -`, `host inventory set --file -`) — both are usage errors
+(exit 2) before any request is made. A rejected password is `error: admin login failed (HTTP 401)`
+(exit 1), never anything about the password itself. `whoami` and `doctor` work in this mode too,
+reporting the admin identity instead of an API key's role.
+
+### `auto-harness api <METHOD> <path>`
+
+A generic escape hatch for any route the control plane exposes. Both `/hosts` and
+`/api/v1/hosts` are accepted (a leading `/api/v1` is stripped). `--body` takes inline JSON;
+`--body-file <path>` reads a file, and `--body-file -` reads stdin. A `204` or otherwise empty
+response prints nothing; anything else is pretty-printed JSON on stdout.
+
+```sh
+auto-harness api GET /hosts
+auto-harness api POST /repositories --body '{"name":"org/repo","url":"https://github.com/org/repo"}'
+echo '{"prompt":"Review the latest changes"}' | auto-harness api POST /sessions --body-file -
+```
+
+### `auto-harness whoami [--json]`
+
+`GET /auth/me`, printing only an allowlist of fields (`id`, `kind`, `username`, `name`, `role`,
+`capabilities`, `boundHostId`, `allowedRepositoryIds`) — never `passwordHash`, `apiKeyHash`, or
+anything else the API response happens to carry.
+
+```sh
+auto-harness whoami
+auto-harness whoami --json
+```
+
+### `auto-harness doctor`
+
+Runs a handful of independent checks and reports each as `ok`, `warn`, or `fail` with a one-line
+reason, exiting `1` if any check `fail`s:
+
+- **url** — `fail`s for a plain `http://` base URL unless `--allow-insecure-http` is set; `warn`s
+  for a raw `*.execute-api.*.amazonaws.com` URL, which bypasses CloudFront (and the ingress token
+  CloudFront injects), so requests against it will be rejected.
+- **reachability** — `GET /health` (at the site root, not under `/api/v1`) expecting HTTP 200 and
+  `{"ok":true}`.
+- **auth** — if an API key is configured, `GET /auth/me`; `warn`s instead, without making the
+  call, when no key is configured. A `401` reports "API key rejected".
+
+```sh
+auto-harness doctor
+```
+
+### `auto-harness host <subcommand>`
+
+Operator commands for the host fleet. Every call goes through `client.request()` against the
+same routes `auto-harness api` would hit — nothing here is a special path.
+
+#### `auto-harness host list [--online | --offline] [--limit N] [--cursor C] [--all] [--json]`
+
+`GET /hosts`, printing one line per host (`hostId`, `online`/`offline`, and `draining` when
+true). `--online`/`--offline` filter server-side (mutually exclusive — passing both is a usage
+error); `--limit`/`--cursor` page manually. If the page has a `nextCursor` and `--all` was not
+passed, a final line prints it so you can continue.
+
+`--all` follows `nextCursor` itself and prints every host across pages (or `{ items: [...all] }`
+with `--json`). Per this repo's [list/history invariant](../../docs/plan.md#5-invariants), it
+never collects pages without bound: it stops after 20 pages and warns on stderr if there was
+still more, rather than silently truncating or looping forever.
+
+```sh
+auto-harness host list --online
+auto-harness host list --all --json
+```
+
+#### `auto-harness host drain <hostId> [--json]`
+
+`POST /hosts/drain` with `{"hostId": "<id>"}` in the JSON body — **the host id is never in the
+path** (`POST /hosts/<id>/drain` does not exist). Prints how many sessions are still running and
+their ids. A `409 CONFLICT` means the host's connection changed mid-request; the normal error is
+printed, followed by a one-line hint that retrying is safe.
+
+#### `auto-harness host resume <hostId> [--json]`
+
+`POST /hosts/resume`, same body-param shape as `drain`. Idempotent — safe to run on a host that
+is not currently draining, which returns 200 rather than an error.
+
+#### `auto-harness host inventory get <hostId> [--json]`
+
+`GET /hosts/<hostId>/inventory`. Human output shows the record's `version`, each attached
+repository (`id`, `path`, worktree count), and the provider account count; `--json` prints the
+raw record.
+
+#### `auto-harness host inventory set <hostId> --file <path|->`
+
+`PUT /hosts/<hostId>/inventory` from a JSON file (or `-` for stdin), sent **verbatim** — this is
+an authoritative write that replaces the entire inventory record, not a merge. Two traps this
+command guards against:
+
+- **Omitting `version` silently disables optimistic concurrency**: the server falls back to
+  whatever version is currently stored, so a concurrent edit can be overwritten with no error.
+  This command refuses (exit 2) to send a document with no integer `version` field, and tells you
+  to start from `auto-harness host inventory get <hostId> --json`.
+- A version that has moved since you read it comes back as `409 CONFLICT` — re-read and reapply
+  rather than retrying the same body.
+
+Because the write replaces the whole record, omitting `providerAccounts` wipes the host's
+provider routing — always build the new document from a fresh `inventory get --json`, editing
+only what you mean to change.
+
+#### `auto-harness host repo rm <hostId> <repositoryId> [--dry-run] [--json]`
+
+Detaches one repository from a host. This exists because the only prior way to do it was to
+hand-assemble a full `PUT` of the inventory record — easy to get wrong, especially for
+`providerAccounts`, which a naive PUT can silently drop. This command does a safe
+read-modify-write instead:
+
+1. `GET` the inventory.
+2. If no repository with that id is attached, it fails (exit 1) and lists the ids that _are_
+   attached — nothing is written.
+3. Builds the new document as the record exactly as read, with only that repository removed from
+   `repositories` and the read `version` kept — every other field, including
+   `providerAccounts`, is preserved untouched. (The control plane also re-adds any repository a
+   scoped API key can't see before persisting, so this read-modify-write is safe even when the
+   caller's key is scoped to a subset of repositories.)
+4. `--dry-run` prints what would be removed — the repository's id, path, and the ids of its
+   worktrees — and exits without writing.
+5. On a `409` (someone else wrote first) it re-reads and re-applies, up to 3 attempts total, then
+   fails saying the inventory kept changing. Any other error status is not retried.
+6. On success it prints what was removed and the version transition (e.g. `version 29 → 30`).
+
+**Removing a repository from the inventory also removes its worktrees** — they are a projection
+of the repository, not independent records. Deleting the repository record itself (as opposed to
+detaching it from this host's inventory) is a separate operation.
+
+```sh
+auto-harness host repo rm host-1 repo-1 --dry-run
+auto-harness host repo rm host-1 repo-1
+```
+
+### `auto-harness repo <subcommand>`
+
+Repository CRUD, straight against the same routes `auto-harness api` would hit.
+
+#### `auto-harness repo list [--limit N] [--cursor C] [--all] [--json]`
+
+`GET /repositories`, printing one line per repository (id, name, and status/url when present).
+Paging works exactly like `host list`: `--limit`/`--cursor` page manually, and `--all` follows
+`nextCursor` itself, capped at 20 pages with a stderr warning if more remain.
+
+```sh
+auto-harness repo list --all
+```
+
+#### `auto-harness repo rm <repositoryId> [--json]`
+
+`DELETE /repositories/<id>`. The point of this command is that a refusal explains itself: a `409`
+means other records still reference the repository, and rather than dumping that as raw JSON,
+each blocking dependency gets the concrete next step to actually clear it:
+
+| Dependency kind               | Next step                                                                            |
+| ----------------------------- | ------------------------------------------------------------------------------------ |
+| `schedule`                    | `auto-harness api DELETE /schedules/<id>`                                            |
+| `session` (live)              | wait for it, or `auto-harness api POST /sessions/<id>/cancel`                        |
+| `session-drain`               | `auto-harness api POST /repositories/<repositoryId>/session-drains/<id>/release`     |
+| `host-inventory`              | `auto-harness host repo rm <hostId> <repositoryId>`                                  |
+| `worktree`                    | same as `host-inventory` — worktrees go with detaching the repository from that host |
+| `integration: github-ingress` | remove this repository's binding from the GitHub ingress configuration               |
+| `integration` (other)         | remove or retarget that integration                                                  |
+| anything else                 | printed as `<kind> <id>`, so a new server-side kind still displays                   |
+
+Exits `1` on a `409` (after printing the server's message and every hint). With `--json`, a `409`
+prints `{ "deleted": false, "dependencies": [...], "hints": [...] }`; success prints
+`{ "deleted": true, "id": "..." }`.
+
+```sh
+auto-harness repo rm repo-1
+```
+
+### `auto-harness service-account <subcommand>`
+
+Service-account lifecycle. Every account's real permissions are its `role` and grants
+(`boundHostId`/`allowedRepositoryIds`) — the CLI never invents a route for anything else.
+
+#### `auto-harness service-account list [--limit N] [--cursor C] [--all] [--json]`
+
+`GET /auth/service-accounts`, printing id, name, role, `boundHostId` (if set), and `createdAt`.
+Items are already server-sanitized, but this still filters them through the same allowlist as
+`whoami`/`doctor` as defense in depth — in **both** human and `--json` output, so a field outside
+the allowlist can never leak through either mode. Paging matches `host list`/`repo list`.
+
+#### `auto-harness service-account create --name <name> --role <role> [--bound-host <hostId>] [--repositories <id,id,...>] (--key-file <path> | --print-key) [--json]`
+
+`POST /auth/service-accounts`. The response's API key is shown **exactly once** — the server
+stores only a hash — so this command forces a deliberate choice about where that one-time value
+goes:
+
+- **`--key-file <path>`** writes the key to a new file, created with `O_CREAT | O_EXCL` and mode
+  `0600` — it never overwrites an existing file (checked before the request is even made, and
+  enforced atomically when the file is actually written). Only the account id and
+  `key written to <path>` are printed; if the write fails _after_ the account was already
+  created, the error names the account id and tells you to run `service-account rm` on it, since
+  the key itself is unrecoverable at that point.
+- **`--print-key`** writes _only_ the key to stdout, on its own line, so
+  `KEY=$(auto-harness service-account create … --print-key)` works; the human-readable account
+  summary goes to stderr instead. Combining this with `--json` is a usage error — the stdout
+  contract would be ambiguous.
+
+Exactly one of `--key-file`/`--print-key` is required; neither/both is a usage error (exit 2,
+no request made). `--repositories a,b,c` maps to `allowedRepositoryIds`. The server validates
+`--role` and any grants; an invalid one surfaces as its own `400`, unchanged.
+
+```sh
+auto-harness service-account create --name ci --role operator --key-file ./ci.key
+KEY=$(auto-harness service-account create --name ci --role operator --print-key)
+```
+
+#### `auto-harness service-account rm <id> [--json]`
+
+`DELETE /auth/service-accounts/<id>`. A `409` prints each blocking dependency generically, as
+`<kind> <id>` — unlike `repo rm`, there is no per-kind hint here.
+
+```sh
+auto-harness service-account rm svc-1
+```

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "auto-harness-client",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Dependency-free client for the Auto Harness automation API",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jonathanong/auto-harness.git",
     "directory": "modules/client"
   },
+  "bin": {
+    "auto-harness": "./src/cli/index.js"
+  },
   "files": [
     "LICENSE",
     "README.md",

package/src/cli/admin-login.js

@@ -0,0 +1,71 @@
+import { isLoopbackOrigin } from "../loopback.js";
+import { CliConfigError, CliUsageError } from "./cli-errors.js";
+import { readStdin } from "./read-stdin.js";
+
+// Matches `AutoHarnessClient`'s default `requestTimeoutMs`.
+const ADMIN_LOGIN_TIMEOUT_MS = 30_000;
+
+/**
+ * Usage-error checks for `--admin-password-stdin`, run before any request. An admin login is an
+ * alternate *identity*, not an additional one, so it is ambiguous to also have an API key
+ * configured — and it needs stdin for the password, so it conflicts with any command that also
+ * reads stdin for its own input (pass that command's own description as `stdinClaimedBy`, e.g.
+ * `"api --body-file -"`).
+ */
+export function checkAdminLoginUsage(flags, env, stdinClaimedBy) {
+  if (!flags["--admin-password-stdin"]) return;
+  // Presence, not truthiness: an empty `--api-key-file=` is still an explicit (broken) request
+  // for API-key identity, and must not slip past this ambiguity check.
+  if (Object.hasOwn(flags, "--api-key-file") || env.HARNESS_API_KEY || env.HARNESS_API_KEY_FILE) {
+    throw new CliUsageError(
+      "--admin-password-stdin cannot be combined with an API key (--api-key-file, " +
+        "HARNESS_API_KEY, or HARNESS_API_KEY_FILE); pick one identity",
+    );
+  }
+  if (stdinClaimedBy) {
+    throw new CliUsageError(
+      `--admin-password-stdin and ${stdinClaimedBy} both need stdin; pass one of them another way`,
+    );
+  }
+}
+
+/**
+ * `POST /auth/login` with the password read from stdin (one trailing newline stripped), then
+ * returns a `fetch` that carries the session cookie on every later request. The login response
+ * body carries the principal but is deliberately never read — see the CLI spec — so a non-200 is
+ * reported by status code alone, never by inspecting or printing the body.
+ */
+export async function loginAsAdmin(io, baseUrl, username, allowInsecureHttp = false) {
+  // The password is a credential, so it gets the same transport rule the client applies to an
+  // API key (`assertSecureTransport` in loopback.js): https, or plain http only to a loopback
+  // host and only with --allow-insecure-http. Admin mode sets no API key, so the client's own
+  // check never fires here. Checked before stdin is read, so a refused URL never consumes the
+  // password, and the session cookie that comes back is bound to the same transport.
+  if (!baseUrl.startsWith("https://") && !(allowInsecureHttp && isLoopbackOrigin(baseUrl))) {
+    throw new CliConfigError(
+      "--admin-password-stdin requires an https API URL (--allow-insecure-http only permits " +
+        "plain HTTP to a loopback host, e.g. http://127.0.0.1 or http://localhost)",
+    );
+  }
+  const rawPassword = await readStdin(io.stdin);
+  const password = rawPassword.endsWith("\n") ? rawPassword.slice(0, -1) : rawPassword;
+  const origin = baseUrl.replace(/\/$/, "").replace(/\/api\/v1$/, "");
+  // A raw fetch, so it needs its own bound — the same one `doctor`'s /health probe uses —
+  // or a stalled server hangs the command before `AutoHarnessClient`'s timeout ever applies.
+  const response = await io.fetch(`${origin}/api/v1/auth/login`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ username, password }),
+    signal: (io.timeoutSignal ?? AbortSignal.timeout)(ADMIN_LOGIN_TIMEOUT_MS),
+  });
+  if (response.status !== 200) throw new Error(`admin login failed (HTTP ${response.status})`);
+  const cookieHeader = response.headers
+    .getSetCookie()
+    .map((header) => header.split(";")[0].trim())
+    .join("; ");
+  return {
+    username,
+    fetch: (url, init = {}) =>
+      io.fetch(url, { ...init, headers: { ...init.headers, cookie: cookieHeader } }),
+  };
+}

package/src/cli/allowlist.js

@@ -0,0 +1,34 @@
+// Defense in depth. `GET /auth/me` spreads the server's principal object into its response.
+// That principal is sanitized today — verified live, it carries no password or API-key hash —
+// but the stored records behind it do hold `passwordHash` / `apiKeyHash`, and the client cannot
+// see a future server change that lets one through. So `whoami` and `doctor` print only these
+// named fields rather than trusting the response shape.
+const ALLOWED_PRINCIPAL_FIELDS = [
+  "id",
+  "kind",
+  "username",
+  "name",
+  "role",
+  "capabilities",
+  "boundHostId",
+  "allowedRepositoryIds",
+];
+
+export function allowlistPrincipal(principal) {
+  const allowed = {};
+  if (!principal || typeof principal !== "object") return allowed;
+  for (const field of ALLOWED_PRINCIPAL_FIELDS) {
+    if (Object.hasOwn(principal, field)) allowed[field] = principal[field];
+  }
+  return allowed;
+}
+
+export function formatWhoami(principal) {
+  const lines = [];
+  for (const field of ALLOWED_PRINCIPAL_FIELDS) {
+    if (!Object.hasOwn(principal, field)) continue;
+    const value = principal[field];
+    lines.push(`${field}: ${Array.isArray(value) ? value.join(", ") : value}`);
+  }
+  return lines.length > 0 ? `${lines.join("\n")}\n` : "(no fields returned)\n";
+}

package/src/cli/args.js

@@ -0,0 +1,41 @@
+import { CliUsageError } from "./cli-errors.js";
+
+const REJECTED_API_KEY_MESSAGE =
+  "--api-key is not accepted on the command line (it would leak into `ps` output and shell " +
+  "history); set HARNESS_API_KEY instead, or point --api-key-file / HARNESS_API_KEY_FILE at a file";
+
+/**
+ * Splits `argv` into recognized `--flag`/`--flag value`/`--flag=value` entries and positional
+ * arguments. Every `--name=value` token is split into name and value *before* any matching, so
+ * every check below — the rejected `--api-key` flag, an unknown flag, a value flag missing its
+ * value — only ever sees the flag name. This is what keeps a mistyped `--api-key=<secret>` (or
+ * any other `--unknown=<secret>`) from echoing the secret back in a "unknown flag" error.
+ */
+export function parseFlags(argv, { valueFlags = [], booleanFlags = [] } = {}) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const equals = arg.indexOf("=");
+    const name = equals === -1 ? arg : arg.slice(0, equals);
+    const inlineValue = equals === -1 ? undefined : arg.slice(equals + 1);
+    if (name === "--api-key") throw new CliUsageError(REJECTED_API_KEY_MESSAGE);
+    if (valueFlags.includes(name)) {
+      const value = inlineValue !== undefined ? inlineValue : argv[(i += 1)];
+      if (value === undefined) throw new CliUsageError(`${name} requires a value`);
+      flags[name] = value;
+      continue;
+    }
+    if (booleanFlags.includes(name)) {
+      if (inlineValue !== undefined) throw new CliUsageError(`${name} does not take a value`);
+      flags[name] = true;
+      continue;
+    }
+    throw new CliUsageError(`unknown flag: ${name}`);
+  }
+  return { flags, positionals };
+}

package/src/cli/cli-errors.js

@@ -0,0 +1,16 @@
+/** A malformed invocation: a bad flag, a missing/invalid argument, invalid JSON input. Exit 2. */
+export class CliUsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliUsageError";
+  }
+}
+
+/** Configuration could not be resolved: no base URL, an unreadable key file, an invalid
+ * baseUrl/apiKey combination rejected by `AutoHarnessClient` itself. Exit 2. */
+export class CliConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliConfigError";
+  }
+}

package/src/cli/commands/api.js

@@ -0,0 +1,91 @@
+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 { readStdin } from "../read-stdin.js";
+
+const USAGE = "usage: auto-harness api <METHOD> <path> [--body <json> | --body-file <path|->]";
+
+// Methods the control-plane API uses. An explicit list rather than HTTP's token grammar: Fetch
+// also rejects valid tokens (CONNECT, TRACE, TRACK), and a typo should be a usage error (exit 2)
+// before anything is sent, not a Fetch TypeError surfacing as an API failure (exit 1).
+const METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]);
+
+// Segments the WHATWG URL parser resolves as "." and "..", percent-encoded forms included
+// (compared case-insensitively). Letting one through would resolve the request outside
+// `/api/v1` — e.g. `/../../health` becomes `/health` — with the bearer token still attached.
+const DOT_SEGMENTS = new Set([".", "..", "%2e", "%2e%2e", ".%2e", "%2e."]);
+
+/**
+ * Generic escape hatch for any route. Prints the response's parsed JSON, pretty-printed, on
+ * success; prints nothing for a 204 or otherwise empty body. Deliberately does not filter the
+ * response the way `whoami`/`doctor` do — an operator asking for `GET /auth/me` through this
+ * command gets the raw body, hashes included, because filtering an explicit raw-response request
+ * would defeat the point of having an escape hatch at all.
+ */
+export async function runApi(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--body", "--body-file"],
+    booleanFlags: GLOBAL_BOOLEAN_FLAGS,
+  });
+  const [method, path] = positionals;
+  if (!method || !path || positionals.length > 2) throw new CliUsageError(USAGE);
+  if (flags["--body"] !== undefined && flags["--body-file"] !== undefined) {
+    throw new CliUsageError("--body and --body-file are mutually exclusive");
+  }
+  const httpMethod = method.toUpperCase();
+  if (!METHODS.has(httpMethod)) {
+    throw new CliUsageError(
+      `unsupported HTTP method ${method}; use one of ${[...METHODS].join(", ")}`,
+    );
+  }
+  const apiPath = normalizeApiPath(path);
+  // Both this command's own `--body-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["--body-file"] === "-" ? "api --body-file -" : undefined;
+  checkAdminLoginUsage(flags, io.env, stdinClaimedBy);
+  const body = await resolveBody(flags, io);
+  const client = await createClient(flags, io);
+  const result = await client.request(apiPath, {
+    method: httpMethod,
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+  if (result !== undefined) io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}
+
+async function resolveBody(flags, io) {
+  let text;
+  if (flags["--body"] !== undefined) text = flags["--body"];
+  else if (flags["--body-file"] === "-") text = await readStdin(io.stdin);
+  else if (flags["--body-file"] !== undefined) {
+    text = await readBodyFile(flags["--body-file"], io.readFile);
+  } else return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CliUsageError("--body/--body-file must contain valid JSON");
+  }
+}
+
+async function readBodyFile(path, readFile) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    throw new CliUsageError(`could not read --body-file ${path}: ${error.message}`);
+  }
+}
+
+/** The client already prefixes every path with `/api/v1`, so accept both `/hosts` and
+ * `/api/v1/hosts` by stripping a leading `/api/v1` segment before handing the path along.
+ * Rejects any dot segment in the path part (the query string is not a path), splitting on `\`
+ * as well as `/` because an https URL treats a backslash as a segment separator. */
+function normalizeApiPath(path) {
+  const withLeadingSlash = path.startsWith("/") ? path : `/${path}`;
+  const stripped = withLeadingSlash.replace(/^\/api\/v1(?=\/|$)/, "");
+  const pathPart = stripped.split(/[?#]/, 1)[0];
+  if (pathPart.split(/[/\\]/).some((segment) => DOT_SEGMENTS.has(segment.toLowerCase()))) {
+    throw new CliUsageError(`path must not contain "." or ".." segments: ${path}`);
+  }
+  return stripped === "" ? "/" : stripped;
+}

package/src/cli/commands/dependency-conflict.js

@@ -0,0 +1,15 @@
+import { AutoHarnessError } from "../../index.js";
+
+/** True for a refused delete: a 409 CONFLICT whose body carries `dependencies` (see
+ * `AutoHarnessClient#request`, which puts the whole `error` body on `AutoHarnessError#details`).
+ * Shared by `repo rm` and `service-account rm`, which both handle this status themselves rather
+ * than letting the generic `reportError` print it as an opaque JSON blob. */
+export function isDependencyConflict(error) {
+  return error instanceof AutoHarnessError && error.status === 409;
+}
+
+/** The dependency array from a conflict's error body, or `[]` if absent/malformed. */
+export function conflictDependencies(error) {
+  const dependencies = error.details?.dependencies;
+  return Array.isArray(dependencies) ? dependencies : [];
+}