auto-harness-client 0.6.0 → 0.7.0

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

@@ -0,0 +1,84 @@
+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. Mirrors `host list`.
+const MAX_ALL_PAGES = 20;
+
+/** `GET /repositories`, paged with `limit`/`cursor`. `--all` follows `nextCursor` itself,
+ * capped at `MAX_ALL_PAGES` pages. */
+export async function runRepoList(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--limit", "--cursor"],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--all", "--json"],
+  });
+  if (positionals.length > 0) {
+    throw new CliUsageError(`repo list takes no arguments; received: ${positionals.join(" ")}`);
+  }
+  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["--limit"] !== undefined) query.set("limit", flags["--limit"]);
+  if (cursor !== undefined) query.set("cursor", cursor);
+  const suffix = query.toString();
+  return suffix ? `/repositories?${suffix}` : "/repositories";
+}
+
+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(formatRepoLines(page.items ?? []));
+  if (page.nextCursor) {
+    io.stdout.write(
+      `more repositories 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 /repositories");
+    seenCursors.add(cursor);
+  }
+  if (cursor) {
+    io.stderr.write(
+      `warning: --all stopped after ${MAX_ALL_PAGES} pages; more repositories remain ` +
+        `(nextCursor: ${cursor})\n`,
+    );
+  }
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ items }, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatRepoLines(items));
+  return 0;
+}
+
+function formatRepoLines(items) {
+  if (items.length === 0) return "(no repositories)\n";
+  return `${items.map(formatRepoLine).join("\n")}\n`;
+}
+
+function formatRepoLine(repo) {
+  const parts = [repo.id, repo.name];
+  if (repo.status) parts.push(repo.status);
+  if (repo.url) parts.push(repo.url);
+  return parts.join("  ");
+}

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

@@ -0,0 +1,83 @@
+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 { conflictDependencies, isDependencyConflict } from "./dependency-conflict.js";
+
+const USAGE = "usage: auto-harness repo rm <repositoryId> [--json]";
+
+/**
+ * `DELETE /repositories/<id>`. A 409 is handled here rather than by the generic `reportError`
+ * pipeline: the whole point of this command is that the refusal explains itself, one concrete
+ * next step per blocking dependency, rather than a `dependencies` array dumped as raw JSON.
+ */
+export async function runRepoRm(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  const [repositoryId] = positionals;
+  if (!repositoryId || positionals.length > 1) throw new CliUsageError(USAGE);
+  const repositorySegment = pathSegment(repositoryId, "repositoryId");
+  const client = await createClient(flags, io);
+  try {
+    await client.request(`/repositories/${repositorySegment}`, {
+      method: "DELETE",
+    });
+  } catch (error) {
+    if (!isDependencyConflict(error)) throw error;
+    return printConflict(io, flags, error, repositoryId);
+  }
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ deleted: true, id: repositoryId }, null, 2)}\n`);
+  } else {
+    io.stdout.write(`repository ${repositoryId} deleted\n`);
+  }
+  return 0;
+}
+
+function printConflict(io, flags, error, repositoryId) {
+  const dependencies = conflictDependencies(error);
+  const hints = dependencies.map((dependency) => hintFor(dependency, dependencies, repositoryId));
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ deleted: false, dependencies, hints }, null, 2)}\n`);
+    return 1;
+  }
+  io.stderr.write(`error: ${error.message} (HTTP ${error.status}, ${error.code})\n`);
+  for (const hint of hints) io.stderr.write(`  ${hint}\n`);
+  return 1;
+}
+
+/** One concrete next step per dependency `kind`. `worktree` is special-cased: worktrees are
+ * removed by detaching the repository from its host, so the hint names that host — taken from a
+ * sibling `host-inventory` dependency in the same response when present, else the literal
+ * placeholder `<hostId>`. */
+function hintFor(dependency, dependencies, repositoryId) {
+  const { kind, id, status } = dependency;
+  if (kind === "schedule") return `${kind} ${id}: auto-harness api DELETE /schedules/${id}`;
+  if (kind === "session") {
+    return (
+      `${kind} ${id} is still running (status: ${status}); wait for it, or ` +
+      `auto-harness api POST /sessions/${id}/cancel`
+    );
+  }
+  if (kind === "session-drain") {
+    return (
+      `${kind} ${id} (status: ${status}): auto-harness api POST ` +
+      `/repositories/${repositoryId}/session-drains/${id}/release`
+    );
+  }
+  if (kind === "host-inventory") {
+    return `${kind} ${id}: auto-harness host repo rm ${id} ${repositoryId}`;
+  }
+  if (kind === "worktree") {
+    const host = dependencies.find((candidate) => candidate.kind === "host-inventory");
+    const hostId = host ? host.id : "<hostId>";
+    return `${kind} ${id}: auto-harness host repo rm ${hostId} ${repositoryId}`;
+  }
+  if (kind === "integration" && id === "github-ingress") {
+    return `${kind} ${id}: remove this repository's binding from the GitHub ingress configuration`;
+  }
+  if (kind === "integration") return `${kind} ${id}: remove or retarget integration ${id}`;
+  return `${kind} ${id}`;
+}

package/src/cli/commands/repo.js

@@ -0,0 +1,15 @@
+import { CliUsageError } from "../cli-errors.js";
+import { runRepoList } from "./repo-list.js";
+import { runRepoRm } from "./repo-rm.js";
+
+const USAGE = `usage: auto-harness repo <subcommand> ...
+  auto-harness repo list [--limit N] [--cursor C] [--all] [--json]
+  auto-harness repo rm <repositoryId> [--json]`;
+
+/** Dispatches `repo <subcommand>` to its own module — mirrors `host.js`'s own dispatch. */
+export async function runRepo(argv, io) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "list") return runRepoList(rest, io);
+  if (subcommand === "rm") return runRepoRm(rest, io);
+  throw new CliUsageError(USAGE);
+}

package/src/cli/commands/service-account-create.js

@@ -0,0 +1,114 @@
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+import { allowlistAccount, formatAccountLine } from "../service-account-format.js";
+
+const USAGE =
+  "usage: 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 `apiKey` is shown exactly once — the server only
+ * stores a hash — so `--key-file`/`--print-key` is a required, mutually-exclusive choice about
+ * where that one-time value goes, validated (along with `--repositories`) before any request.
+ */
+export async function runServiceAccountCreate(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [
+      ...GLOBAL_VALUE_FLAGS,
+      "--name",
+      "--role",
+      "--bound-host",
+      "--repositories",
+      "--key-file",
+    ],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--print-key", "--json"],
+  });
+  if (positionals.length > 0 || !flags["--name"] || !flags["--role"]) {
+    throw new CliUsageError(USAGE);
+  }
+  // An empty value (`--key-file "$UNSET"`) is a mistake, not an absent flag, and both must be
+  // caught before the request: an empty --key-file creates the account and only then fails to
+  // write its one-time key, orphaning it; an empty --bound-host sends `boundHostId: ""`, which
+  // risks minting an unbound key where a host-bound one was meant.
+  for (const name of ["--key-file", "--bound-host"]) {
+    if (flags[name] !== undefined && flags[name].trim() === "") {
+      throw new CliUsageError(`${name} was given an empty value`);
+    }
+  }
+  const hasKeyFile = flags["--key-file"] !== undefined;
+  const hasPrintKey = Boolean(flags["--print-key"]);
+  if (hasKeyFile === hasPrintKey) {
+    throw new CliUsageError("exactly one of --key-file or --print-key is required");
+  }
+  if (hasPrintKey && flags["--json"]) {
+    throw new CliUsageError("--json and --print-key cannot be combined");
+  }
+  const allowedRepositoryIds = parseRepositories(flags["--repositories"]);
+  if (hasKeyFile) await assertKeyFileAbsent(flags["--key-file"], io);
+  const client = await createClient(flags, io);
+  const result = await client.request("/auth/service-accounts", {
+    method: "POST",
+    body: JSON.stringify(buildBody(flags, allowedRepositoryIds)),
+  });
+  const account = allowlistAccount(result.account);
+  return hasKeyFile
+    ? finishKeyFile(io, flags["--key-file"], flags["--json"], account, result.apiKey)
+    : finishPrintKey(io, account, result.apiKey);
+}
+
+function buildBody(flags, allowedRepositoryIds) {
+  return {
+    name: flags["--name"],
+    role: flags["--role"],
+    ...(flags["--bound-host"] !== undefined ? { boundHostId: flags["--bound-host"] } : {}),
+    ...(allowedRepositoryIds !== undefined ? { allowedRepositoryIds } : {}),
+  };
+}
+
+function parseRepositories(value) {
+  if (value === undefined) return undefined;
+  const ids = value.split(",");
+  if (ids.some((id) => id === "")) {
+    throw new CliUsageError("--repositories must be a comma-separated list with no empty entries");
+  }
+  return ids;
+}
+
+/** Best-effort pre-check so an obviously doomed request never fires; the atomic `wx` write in
+ * `finishKeyFile` is the real guarantee against overwriting an existing file. */
+async function assertKeyFileAbsent(path, io) {
+  let exists = true;
+  try {
+    await io.readFile(path, "utf8");
+  } catch {
+    exists = false;
+  }
+  if (exists)
+    throw new CliUsageError(`--key-file ${path} already exists; refusing to overwrite it`);
+}
+
+async function finishKeyFile(io, path, json, account, apiKey) {
+  try {
+    await io.writeFileExclusive(path, `${apiKey}\n`, { mode: 0o600 });
+  } catch (error) {
+    throw new Error(
+      `service account ${account.id} was created but its key could not be written to ${path} ` +
+        `(${error.message}); the key is now lost — remove it with ` +
+        `\`auto-harness service-account rm ${account.id}\` and create a new one`,
+      { cause: error },
+    );
+  }
+  if (json) {
+    io.stdout.write(`${JSON.stringify(account, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(`service account ${account.id} created\nkey written to ${path}\n`);
+  return 0;
+}
+
+function finishPrintKey(io, account, apiKey) {
+  io.stderr.write(`${formatAccountLine(account)}\n`);
+  io.stdout.write(`${apiKey}\n`);
+  return 0;
+}

package/src/cli/commands/service-account-list.js

@@ -0,0 +1,84 @@
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+import { allowlistAccount, formatAccountLine } from "../service-account-format.js";
+
+// Mirrors `host list`'s and `repo list`'s own cap and guard.
+const MAX_ALL_PAGES = 20;
+
+/**
+ * `GET /auth/service-accounts`, paged with `limit`/`cursor`. Unlike `host list`/`repo list`,
+ * `--json` does *not* print the raw page: items are already server-sanitized, but this allowlists
+ * them anyway as defense in depth (see `service-account-format.js`) — including in JSON, so a
+ * field outside the allowlist can never leak through either output mode.
+ */
+export async function runServiceAccountList(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: [...GLOBAL_VALUE_FLAGS, "--limit", "--cursor"],
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--all", "--json"],
+  });
+  if (positionals.length > 0) {
+    throw new CliUsageError(
+      `service-account list takes no arguments; received: ${positionals.join(" ")}`,
+    );
+  }
+  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["--limit"] !== undefined) query.set("limit", flags["--limit"]);
+  if (cursor !== undefined) query.set("cursor", cursor);
+  const suffix = query.toString();
+  return suffix ? `/auth/service-accounts?${suffix}` : "/auth/service-accounts";
+}
+
+async function runListOnePage(client, flags, io) {
+  const page = await client.request(buildQuery(flags, flags["--cursor"]));
+  const items = (page.items ?? []).map(allowlistAccount);
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ items, nextCursor: page.nextCursor }, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatAccountLines(items));
+  if (page.nextCursor) {
+    io.stdout.write(
+      `more service accounts 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 ?? []).map(allowlistAccount));
+    cursor = page.nextCursor || undefined;
+    if (!cursor) break;
+    if (seenCursors.has(cursor)) {
+      throw new Error("repeated pagination cursor for /auth/service-accounts");
+    }
+    seenCursors.add(cursor);
+  }
+  if (cursor) {
+    io.stderr.write(
+      `warning: --all stopped after ${MAX_ALL_PAGES} pages; more service accounts remain ` +
+        `(nextCursor: ${cursor})\n`,
+    );
+  }
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ items }, null, 2)}\n`);
+    return 0;
+  }
+  io.stdout.write(formatAccountLines(items));
+  return 0;
+}
+
+function formatAccountLines(items) {
+  if (items.length === 0) return "(no service accounts)\n";
+  return `${items.map(formatAccountLine).join("\n")}\n`;
+}

package/src/cli/commands/service-account-rm.js

@@ -0,0 +1,48 @@
+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 { conflictDependencies, isDependencyConflict } from "./dependency-conflict.js";
+
+const USAGE = "usage: auto-harness service-account rm <id> [--json]";
+
+/** `DELETE /auth/service-accounts/<id>`. A conflict is handled here, generically — one line per
+ * dependency (`kind` + `id`) — rather than by the generic `reportError` pipeline, matching
+ * `repo rm`'s pattern without `repo rm`'s per-kind hints. */
+export async function runServiceAccountRm(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  const [id] = positionals;
+  if (!id || positionals.length > 1) throw new CliUsageError(USAGE);
+  const idSegment = pathSegment(id, "id");
+  const client = await createClient(flags, io);
+  try {
+    await client.request(`/auth/service-accounts/${idSegment}`, {
+      method: "DELETE",
+    });
+  } catch (error) {
+    if (!isDependencyConflict(error)) throw error;
+    return printConflict(io, flags, error, id);
+  }
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ deleted: true, id }, null, 2)}\n`);
+  } else {
+    io.stdout.write(`service account ${id} deleted\n`);
+  }
+  return 0;
+}
+
+function printConflict(io, flags, error, id) {
+  const dependencies = conflictDependencies(error);
+  if (flags["--json"]) {
+    io.stdout.write(`${JSON.stringify({ deleted: false, id, dependencies }, null, 2)}\n`);
+    return 1;
+  }
+  io.stderr.write(`error: ${error.message} (HTTP ${error.status}, ${error.code})\n`);
+  for (const dependency of dependencies) {
+    io.stderr.write(`  ${dependency.kind} ${dependency.id}\n`);
+  }
+  return 1;
+}

package/src/cli/commands/service-account.js

@@ -0,0 +1,19 @@
+import { CliUsageError } from "../cli-errors.js";
+import { runServiceAccountCreate } from "./service-account-create.js";
+import { runServiceAccountList } from "./service-account-list.js";
+import { runServiceAccountRm } from "./service-account-rm.js";
+
+const USAGE = `usage: auto-harness service-account <subcommand> ...
+  auto-harness service-account list [--limit N] [--cursor C] [--all] [--json]
+  auto-harness service-account create --name <name> --role <role> [--bound-host <hostId>]
+    [--repositories <id,id,...>] (--key-file <path> | --print-key) [--json]
+  auto-harness service-account rm <id> [--json]`;
+
+/** Dispatches `service-account <subcommand>` to its own module — mirrors `host.js`'s dispatch. */
+export async function runServiceAccount(argv, io) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "list") return runServiceAccountList(rest, io);
+  if (subcommand === "create") return runServiceAccountCreate(rest, io);
+  if (subcommand === "rm") return runServiceAccountRm(rest, io);
+  throw new CliUsageError(USAGE);
+}

package/src/cli/commands/whoami.js

@@ -0,0 +1,22 @@
+import { allowlistPrincipal, formatWhoami } from "../allowlist.js";
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+
+/** `GET /auth/me`, printing only the allowlisted principal fields (see allowlist.js for why the
+ * response shape is not trusted). */
+export async function runWhoami(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  if (positionals.length > 0) {
+    throw new CliUsageError(`whoami takes no arguments; received: ${positionals.join(" ")}`);
+  }
+  const client = await createClient(flags, io);
+  const principal = allowlistPrincipal(await client.request("/auth/me"));
+  io.stdout.write(
+    flags["--json"] ? `${JSON.stringify(principal, null, 2)}\n` : formatWhoami(principal),
+  );
+  return 0;
+}

package/src/cli/config.js

@@ -0,0 +1,96 @@
+import { AutoHarnessClient } from "../index.js";
+import { checkAdminLoginUsage, loginAsAdmin } from "./admin-login.js";
+import { CliConfigError } from "./cli-errors.js";
+
+export const GLOBAL_VALUE_FLAGS = ["--api-url", "--api-key-file", "--admin-username"];
+export const GLOBAL_BOOLEAN_FLAGS = ["--allow-insecure-http", "--admin-password-stdin"];
+
+/** A flag that is present wins, even with an empty value — `--api-url=` or
+ * `--api-key-file "$UNSET"` is an explicit choice that went wrong, not an absent flag. Falling
+ * back to the environment would silently use a different URL, or authenticate as a different
+ * principal, than the one the command line asked for. So an empty value is a config error. */
+function explicitFlag(flags, name) {
+  if (!Object.hasOwn(flags, name)) return undefined;
+  if (flags[name].trim() === "") throw new CliConfigError(`${name} was given an empty value`);
+  return flags[name];
+}
+
+/** `--api-url`, else `HARNESS_API_URL`, else `HARNESS_API_HTTP` (the host daemon's own alias —
+ * operators already have one of these two set). Missing entirely is a config error naming both. */
+export function resolveApiUrl(flags, env) {
+  const url = explicitFlag(flags, "--api-url") ?? (env.HARNESS_API_URL || env.HARNESS_API_HTTP);
+  if (!url) {
+    throw new CliConfigError(
+      "no API base URL configured: set --api-url, or the HARNESS_API_URL environment " +
+        "variable (alias: HARNESS_API_HTTP)",
+    );
+  }
+  return url;
+}
+
+/**
+ * Precedence: an explicit `--api-key-file` flag wins outright — it is the most specific,
+ * most intentional signal an operator can give on any one invocation. Failing that, the direct
+ * `HARNESS_API_KEY` value wins over the indirect `HARNESS_API_KEY_FILE` pointer, since a plain
+ * env var is one less level of indirection to reason about. Any consistent order satisfies the
+ * spec here; this one mirrors "flag beats env" from `resolveApiUrl` above.
+ */
+export async function resolveApiKey(flags, env, readFile) {
+  const keyFile = explicitFlag(flags, "--api-key-file");
+  if (keyFile !== undefined) return readApiKeyFile(keyFile, readFile);
+  if (env.HARNESS_API_KEY) return env.HARNESS_API_KEY.trim();
+  if (env.HARNESS_API_KEY_FILE) return readApiKeyFile(env.HARNESS_API_KEY_FILE, readFile);
+  return undefined;
+}
+
+async function readApiKeyFile(path, readFile) {
+  let contents;
+  try {
+    contents = await readFile(path, "utf8");
+  } catch (error) {
+    throw new CliConfigError(`could not read API key file ${path}: ${error.message}`);
+  }
+  const trimmed = contents.trim();
+  if (!trimmed) throw new CliConfigError(`API key file ${path} is empty`);
+  return trimmed;
+}
+
+/**
+ * `--admin-password-stdin` replaces the whole apiKey identity with an admin username/password
+ * login, so its usage checks run here — unconditionally, for every command — before either an
+ * apiKey is resolved or (in `createClient`) the login request is made.
+ */
+export async function resolveConfig(flags, io) {
+  const baseUrl = resolveApiUrl(flags, io.env);
+  checkAdminLoginUsage(flags, io.env);
+  const allowInsecureHttp = Boolean(flags["--allow-insecure-http"]);
+  if (flags["--admin-password-stdin"]) {
+    const adminUsername = explicitFlag(flags, "--admin-username") ?? "admin";
+    return { baseUrl, allowInsecureHttp, adminMode: true, adminUsername };
+  }
+  const apiKey = await resolveApiKey(flags, io.env, io.readFile);
+  return { baseUrl, apiKey, allowInsecureHttp };
+}
+
+/** Builds the real `AutoHarnessClient`; a constructor rejection (e.g. plaintext http with an
+ * apiKey set against a non-loopback host) is a configuration problem, not an API failure, so it
+ * is re-thrown as `CliConfigError` (exit 2) rather than surfacing as a generic exit-1 error. A
+ * failed admin login (a bad password, an unreachable server) is deliberately *not* wrapped this
+ * way — it is reported as a plain error (exit 1), matching a rejected API key rather than a
+ * usage/config problem. */
+export async function createClient(flags, io) {
+  const config = await resolveConfig(flags, io);
+  const fetchFn = config.adminMode
+    ? (await loginAsAdmin(io, config.baseUrl, config.adminUsername, config.allowInsecureHttp)).fetch
+    : io.fetch;
+  try {
+    return new AutoHarnessClient({
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey,
+      fetch: fetchFn,
+      allowInsecureHttp: config.allowInsecureHttp,
+    });
+  } catch (error) {
+    throw new CliConfigError(error.message);
+  }
+}

package/src/cli/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+
+import { main } from "./main.js";
+
+// A thin wrapper: every dependency on the outside world is injected here, so `main()` and
+// everything it calls stay unit-testable without spawning a process or touching the network.
+const io = {
+  env: process.env,
+  fetch: globalThis.fetch,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  stdin: process.stdin,
+  readFile,
+  // O_CREAT | O_EXCL ("wx") — never overwrites an existing file. Used only for
+  // `service-account create --key-file`, where a plaintext API key is written to disk exactly
+  // once and mode 0600 (passed by the caller) keeps it readable only by its owner.
+  writeFileExclusive: (path, data, options) => writeFile(path, data, { flag: "wx", ...options }),
+};
+
+process.exitCode = await main(process.argv.slice(2), io);

package/src/cli/main.js

@@ -0,0 +1,69 @@
+import { runApi } from "./commands/api.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runHost } from "./commands/host.js";
+import { runRepo } from "./commands/repo.js";
+import { runServiceAccount } from "./commands/service-account.js";
+import { runWhoami } from "./commands/whoami.js";
+import { GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "./config.js";
+import { reportError } from "./report-error.js";
+import { usage } from "./usage.js";
+
+const HELP_TOKENS = new Set(["help", "--help", "-h"]);
+
+/**
+ * A global flag (`--admin-password-stdin`, `--api-url`, ...) is recognized wherever it appears,
+ * not only after the command name — `auto-harness --admin-password-stdin service-account create`
+ * reads the same as `auto-harness service-account create --admin-password-stdin`. This walks
+ * only the *leading* run of `--flag` tokens (an unknown leading flag, e.g. a mistyped one or the
+ * rejected `--api-key`, is left in place and falls through to the usage/exit-2 path below,
+ * exactly as an unrecognized command would), moves each one after the command name, and hands
+ * the rest of `argv` to the matched subcommand's own `parseFlags` untouched.
+ */
+function hoistLeadingGlobalFlags(argv) {
+  const hoisted = [];
+  let index = 0;
+  while (index < argv.length && argv[index].startsWith("--")) {
+    const arg = argv[index];
+    const equals = arg.indexOf("=");
+    const name = equals === -1 ? arg : arg.slice(0, equals);
+    if (GLOBAL_BOOLEAN_FLAGS.includes(name) && equals === -1) {
+      hoisted.push(arg);
+      index += 1;
+    } else if (GLOBAL_VALUE_FLAGS.includes(name) && equals !== -1) {
+      hoisted.push(arg);
+      index += 1;
+    } else if (GLOBAL_VALUE_FLAGS.includes(name) && index + 1 < argv.length) {
+      hoisted.push(arg, argv[index + 1]);
+      index += 2;
+    } else {
+      break;
+    }
+  }
+  return { command: argv[index], rest: [...argv.slice(index + 1), ...hoisted] };
+}
+
+/**
+ * Runs the CLI end to end and resolves to a process exit code — 0 on success, 1 for an
+ * API/HTTP failure or a failed `doctor` check, 2 for a usage or configuration error. Every
+ * dependency on the outside world (env, fetch, the standard streams, file reads) is injected
+ * through `io` so this never spawns a process or touches the real network in tests.
+ */
+export async function main(argv, io) {
+  const { command, rest } = hoistLeadingGlobalFlags(argv);
+  if (command === undefined || HELP_TOKENS.has(command)) {
+    io.stdout.write(usage());
+    return 0;
+  }
+  try {
+    if (command === "api") return await runApi(rest, io);
+    if (command === "whoami") return await runWhoami(rest, io);
+    if (command === "doctor") return await runDoctor(rest, io);
+    if (command === "host") return await runHost(rest, io);
+    if (command === "repo") return await runRepo(rest, io);
+    if (command === "service-account") return await runServiceAccount(rest, io);
+    io.stderr.write(usage());
+    return 2;
+  } catch (error) {
+    return reportError(error, io);
+  }
+}