techbro 0.0.0-stage → 0.5.0

package/src/cli.js

@@ -0,0 +1,690 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { loadConfig, saveConfig } from "./config.js";
+import { createClient, resolveToken } from "./github.js";
+import { createTeam, joinTeam, listTeams, useTeam } from "./team.js";
+import { linkProject } from "./project.js";
+import { reviewProject } from "./review.js";
+import { upgradeTeam } from "./upgrade.js";
+import { initProject, printSummary } from "./init.js";
+import { setupProject } from "./setup.js";
+import { addCluster, defaultRun, listClusters, LOGS_WARNING, OPERATIONS, performKube, preflight, resolveCluster, useCluster, validateName } from "./kube.js";
+import { buildProject, deployProject, generateManifest } from "./kube-project.js";
+import { describeTemplate, listTemplates, packageRoot } from "./templates.js";
+import { addSharedCluster, listSharedClusters, removeSharedCluster, useSharedCluster } from "./cluster.js";
+import { doctor } from "./doctor.js";
+import { PASSPHRASE_ENV, resolvePassphrase } from "./secret.js";
+
+const USAGE = `Usage:
+  techbro project init [dir] [--template <name>] [--name <app-name>] [--force] [--no-git] [--skip-setup] [--skip-build]
+  techbro project link [--url <github-repo-url>] [--name <name>]
+  techbro project list
+  techbro project review [--url <repo>] [--ref <ref>] [--team <name>] [--project <name>] [--wait] [--dry-run]
+  techbro team create <name> --url <github-repo-url> [--force]
+  techbro team join <name> --url <github-repo-url> [--force]
+  techbro team list
+  techbro team use <name>
+  techbro team upgrade [--team <name>] [--dry-run]
+  techbro cluster add|list|use|remove ...   (team-shared clusters)
+  techbro doctor [--online] [--json]
+  techbro kube cluster list|add|use ...
+  techbro kube check|status|logs|restart|rollback|rollout-status [--cluster <name>] [--namespace <ns>]
+  techbro kube generate|build|deploy [--app <name>] [--image <ref>] [--cluster <name>] [--namespace <ns>]
+  techbro --help | --version
+`;
+
+const KUBE_USAGE = `Usage:
+  techbro kube cluster list
+  techbro kube cluster add <name> --context <kube-context> [--namespace <ns>] [--profile-file <json>]
+  techbro kube cluster use <name>
+  techbro kube check    [--cluster <name>] [--namespace <ns>]
+  techbro kube status   [--app <name>] [--cluster <name>] [--namespace <ns>]
+  techbro kube logs     [--app <name>] [--tail <n>] [--cluster <name>] [--namespace <ns>]
+  techbro kube rollout-status [--app <name>] [--cluster <name>] [--namespace <ns>]
+  techbro kube restart  [--app <name>] [--dry-run] [--yes] [--cluster <name>] [--namespace <ns>]
+  techbro kube rollback [--app <name>] [--dry-run] [--yes] [--cluster <name>] [--namespace <ns>]
+  techbro kube generate --image <ref> [--app <name>] [--port <n>] [--replicas <1-3>] [--memory <Mi|Gi>] [--health-path <path>] [--with-creds] [--force] [--cluster <name>] [--namespace <ns>]
+  techbro kube build    [--app <name>] [--dockerfile <path>] [--dry-run] --yes [--cluster <name>] [--namespace <ns>]
+  techbro kube deploy   --image <ref> [--app <name>] [--port <n>] [--replicas <1-3>] [--memory <Mi|Gi>] [--health-path <path>] [--with-creds] [--dry-run] [--server-validate] --yes [--cluster <name>] [--namespace <ns>]
+
+generate writes k8s/<cluster>.json locally (no cluster changes). build uploads
+the committed source (clean git tree) to an in-cluster builder and pushes an
+image; it never deploys. deploy applies Deployment/Service/Ingress generated
+from options (immutable image tag or digest; no :latest) and waits for rollout.
+build and deploy require --yes, or --dry-run to preview without changes;
+--server-validate (with --dry-run) additionally contacts the cluster.
+
+There is no default cluster. "cluster use" only changes techbro's own
+setting; your kubeconfig is never read for credentials or switched. Every
+operation passes an explicit --context and --namespace. Mutations (restart,
+rollback) require --yes, or --dry-run to only print the plan. App defaults to
+the name in ./.techbro.json; project overrides come from its config.kube.
+`;
+
+const CLUSTER_USAGE = `Usage:
+  techbro cluster add <name> --kubeconfig <file> --context <kube-context> [--namespace <ns>] [--profile-file <json>] [--team <name>] [--passphrase-file <file>] [--force] [--dry-run] --yes
+  techbro cluster list [--team <name>]
+  techbro cluster use <name> [--team <name>] [--passphrase-file <file>]
+  techbro cluster remove <name> [--team <name>] --yes
+
+Team-shared clusters. The team owner runs "add" once: techbro extracts only the
+given context from the kubeconfig (certificates inlined), encrypts it with the
+team passphrase, and commits it to the team repo under clusters/. Members run
+"use" to decrypt it into a private file (mode 600) that every "techbro kube"
+command then passes via --kubeconfig; ~/.kube/config is never changed.
+"add --force" replaces or rotates. Everyone with the passphrase gets the same
+access, so share a namespace-scoped credential, not a cluster-admin one.
+
+Passphrase: --passphrase-file, else ${PASSPHRASE_ENV}, else a hidden prompt.
+`;
+
+const DOCTOR_USAGE = `Usage:
+  techbro doctor [--online] [--json]
+
+Checks tools, GitHub token, ${PASSPHRASE_ENV}, techbro config, team, shared
+cluster kubeconfigs (presence, mode 600) and secret-like files tracked in the
+current git repo. Offline by default; --online also checks GitHub access and
+runs "kube check" on the current cluster. Never prints secret values. Exits 1
+if any check fails.
+`;
+
+const TEAM_USAGE = `Usage:
+  techbro team create <name> --url <github-repo-url> [--force]
+  techbro team join <name> --url <github-repo-url> [--force]
+  techbro team list
+  techbro team use <name>
+  techbro team upgrade [--team <name>] [--dry-run]
+
+Options (create, join):
+  -u, --url <repo>  GitHub repository holding shared team state
+  -f, --force       overwrite an existing local team of the same name
+`;
+
+const PROJECT_USAGE = `Usage:
+  techbro project init [dir] [--template <name>] [--name <app-name>] [--force] [--no-git] [--skip-setup] [--skip-build]
+  techbro project link [--url <github-repo-url>] [--name <name>]
+  techbro project list
+  techbro project review [--url <repo>] [--ref <ref>] [--team <name>] [--project <name>] [--wait] [--dry-run]
+
+Options (review):
+  -u, --url <repo>     registered project (default: origin of the current directory)
+  -r, --ref <ref>      branch/tag/sha to review (default: local HEAD, else remote default branch)
+  -t, --team <name>    team to use (default: current)
+  -p, --project <name> registered project name
+  -w, --wait           wait for the run and exit non-zero unless it succeeds
+      --dry-run        read-only preflight: show effective checks and missing setup; dispatches nothing
+
+Options (link):
+  -u, --url <repo>   project repository (default: git remote "origin" of the current directory)
+  -n, --name <name>  project name (default: .techbro.json name, else repo name)
+
+Options (init):
+  -t, --template <name>  template to scaffold (default: _default; see "project list")
+  -n, --name <app-name>  app name (default: slug of the target directory)
+  -f, --force            allow a non-empty target directory
+      --no-git           skip "git init -b main" (default: initialize a repository)
+      --skip-setup       scaffold only; do not install dependencies or tools
+      --skip-build       skip the final "cargo build -p backend"
+`;
+
+const KUBE_OPTS = {
+  cluster: { type: "string", short: "c" },
+  namespace: { type: "string", short: "n" },
+  app: { type: "string", short: "a" },
+  tail: { type: "string" },
+  context: { type: "string" },
+  "profile-file": { type: "string" },
+  image: { type: "string" },
+  port: { type: "string" },
+  replicas: { type: "string" },
+  memory: { type: "string" },
+  "health-path": { type: "string" },
+  dockerfile: { type: "string" },
+  "with-creds": { type: "boolean", default: false },
+  force: { type: "boolean", short: "f", default: false },
+  "server-validate": { type: "boolean", default: false },
+  "dry-run": { type: "boolean", default: false },
+  yes: { type: "boolean", short: "y", default: false },
+  help: { type: "boolean", short: "h", default: false },
+};
+
+function readJson(path, what) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (e) {
+    throw new Error(`cannot read ${what} ${path}: ${e.code ?? e.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(`malformed ${what} ${path}: not valid JSON`);
+  }
+}
+
+function loadProjectMeta(cwd) {
+  const path = join(cwd, ".techbro.json");
+  if (!existsSync(path)) return { name: null, config: {} };
+  const meta = readJson(path, ".techbro.json");
+  if (!meta || typeof meta !== "object" || Array.isArray(meta)) throw new Error(`malformed .techbro.json: expected an object`);
+  const config = meta.config ?? {};
+  if (typeof config !== "object" || config === null || Array.isArray(config)) throw new Error("malformed .techbro.json: config must be an object");
+  if (config.kube != null) {
+    const k = config.kube;
+    if (typeof k !== "object" || Array.isArray(k)) throw new Error("malformed .techbro.json: config.kube must be an object");
+    for (const key of Object.keys(k)) {
+      if (!["cluster", "namespace"].includes(key)) throw new Error(`malformed .techbro.json: unknown config.kube field: ${key}`);
+    }
+    if (k.cluster != null) validateName(k.cluster, "config.kube.cluster");
+    if (k.namespace != null) validateName(k.namespace, "config.kube.namespace");
+  }
+  return { name: typeof meta.name === "string" ? meta.name : null, config };
+}
+
+async function kubeCommand(sub, rest, { run, cwd = process.cwd() } = {}) {
+  const runOpt = run ? { run } : {};
+  run ??= defaultRun;
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    out(KUBE_USAGE);
+    return sub ? 0 : 2;
+  }
+  const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: KUBE_OPTS });
+  if (values.help) {
+    out(KUBE_USAGE);
+    return 0;
+  }
+  if (sub === "cluster") {
+    const [action, ...pos] = positionals;
+    if (action === "list") {
+      if (pos.length) throw new Error("too many arguments");
+      const { current, clusters } = listClusters(loadConfig());
+      for (const c of clusters) out(`${c.name === current ? "*" : " "} ${c.name.padEnd(16)}${c.context}${c.builtin ? "  (built-in)" : ""}${c.team ? `  (team ${c.team})` : ""}`);
+      return 0;
+    }
+    if (action === "use") {
+      if (pos.length !== 1) throw new Error("usage: techbro kube cluster use <name>");
+      saveConfig(useCluster(loadConfig(), pos[0]));
+      out(`Current cluster: ${pos[0]} (kubeconfig unchanged)`);
+      return 0;
+    }
+    if (action === "add") {
+      if (pos.length !== 1) throw new Error("usage: techbro kube cluster add <name> --context <kube-context>");
+      if (!values.context) throw new Error("--context is required");
+      const profile = values["profile-file"] ? readJson(values["profile-file"], "profile file") : {};
+      if (!profile || typeof profile !== "object" || Array.isArray(profile)) throw new Error("profile file must be a JSON object");
+      for (const k of ["context", "namespace"]) {
+        if (k in profile) throw new Error(`profile file must not set ${k}; use --${k}`);
+      }
+      profile.context = values.context;
+      if (values.namespace) profile.namespace = values.namespace;
+      saveConfig(addCluster(loadConfig(), pos[0], profile));
+      out(`Added cluster ${pos[0]} (context ${values.context}); use "techbro kube cluster use ${pos[0]}" to select it`);
+      return 0;
+    }
+    throw new Error("usage: techbro kube cluster list|add|use");
+  }
+  const PROJECT_OPS = ["generate", "build", "deploy"];
+  const ops = ["check", ...OPERATIONS, ...PROJECT_OPS];
+  if (!ops.includes(sub)) return null;
+  if (positionals.length) throw new Error("too many arguments");
+  const meta = loadProjectMeta(cwd);
+  const profile = await resolveCluster({ config: loadConfig(), project: meta.config, cluster: values.cluster, namespace: values.namespace, run });
+  const target = `cluster=${profile.name} context=${profile.context} namespace=${profile.namespace}`;
+  if (sub === "check") {
+    out(`Target: ${target}`);
+    const r = await preflight({ profile, run });
+    for (const c of r.checks) out(`  ${c.ok ? "ok  " : "FAIL"} ${c.name}${c.ok ? "" : `: ${c.detail}`}`);
+    return r.ok ? 0 : 1;
+  }
+  const app = values.app ?? meta.name;
+  if (!app) throw new Error("app name required: pass --app or run in a project with .techbro.json name");
+  let tail;
+  if (values.tail != null) {
+    if (sub !== "logs") throw new Error("--tail applies to logs only");
+    if (!/^[0-9]+$/.test(values.tail)) throw new Error("--tail must be an integer");
+    tail = Number(values.tail);
+  }
+  if (PROJECT_OPS.includes(sub)) return projectOp(sub, { values, profile, app, target, runOpt, cwd });
+  const mutation = sub === "restart" || sub === "rollback";
+  if (mutation && !values.yes && !values["dry-run"]) throw new Error(`${sub} changes the cluster; confirm with --yes (or preview with --dry-run)`);
+  out(`Target: ${target} app=${app}`);
+  if (sub === "logs") process.stderr.write(`techbro: warning: ${LOGS_WARNING}\n`);
+  const r = await performKube({ profile, operation: sub, app, tail, yes: values.yes, dryRun: values["dry-run"], run });
+  if (r.dryRun) {
+    out("Dry run: nothing executed");
+    for (const l of r.plan) out(`  ${l}`);
+  } else if (r.output) out(r.output);
+  return 0;
+}
+
+const intOpt = (v, name) => {
+  if (v == null) return undefined;
+  if (!/^[0-9]+$/.test(v)) throw new Error(`--${name} must be an integer`);
+  return Number(v);
+};
+
+async function projectOp(sub, { values, profile, app, target, runOpt, cwd }) {
+  const dry = values["dry-run"];
+  if (sub !== "generate" && !values.yes && !dry) throw new Error(`${sub} changes the cluster or registry; confirm with --yes (or preview with --dry-run)`);
+  if (values["server-validate"] && !(sub === "deploy" && dry)) throw new Error("--server-validate applies to deploy --dry-run only");
+  if (sub !== "deploy" && sub !== "generate" && values.image) throw new Error("--image does not apply to build; the image name is generated");
+  const manifestOpts = {
+    image: values.image,
+    port: intOpt(values.port, "port"),
+    replicas: intOpt(values.replicas, "replicas"),
+    memory: values.memory,
+    healthPath: values["health-path"],
+    withCreds: values["with-creds"],
+  };
+  for (const k of Object.keys(manifestOpts)) if (manifestOpts[k] === undefined || manifestOpts[k] === false) delete manifestOpts[k];
+  if (sub !== "build") {
+    if (!values.image) throw new Error(`--image is required for ${sub} (registry-qualified, with an immutable tag or digest)`);
+  } else if (Object.keys(manifestOpts).length) throw new Error("build does not take manifest options");
+  const warn = (m) => process.stderr.write(`techbro: warning: ${m}\n`);
+  out(`Target: ${target} app=${app}`);
+  try {
+    if (sub === "generate") {
+      const r = await generateManifest({ root: cwd, force: values.force, profile, app, ...manifestOpts });
+      out(`Wrote ${r.path} (${r.manifests.items.map((i) => i.kind).join(", ")}); nothing applied to the cluster`);
+      return 0;
+    }
+    if (sub === "build") {
+      const r = await buildProject({ profile, app, root: cwd, dockerfile: values.dockerfile, yes: values.yes, dryRun: dry, ...runOpt });
+      if (r.dryRun) {
+        out("Dry run: nothing uploaded or built");
+        out(`  image: ${r.image}\n  builder: ${r.buildImage}${r.privileged ? " (privileged)" : ""}\n  files: ${r.files}\n  policy: ${r.filePolicy}`);
+      } else {
+        out(`Built and pushed image: ${r.image}\nNext: techbro kube deploy --image ${r.image} --yes`);
+        for (const w of r.warnings ?? []) warn(w);
+      }
+      return 0;
+    }
+    const r = await deployProject({ profile, app, yes: values.yes, dryRun: dry, serverValidate: values["server-validate"], ...runOpt, ...manifestOpts });
+    if (r.dryRun) {
+      out(`Dry run: nothing applied (${r.kinds.join(", ")})`);
+      for (const l of r.plan) out(`  ${l}`);
+      if (r.serverValidation) out(r.serverValidation);
+    } else {
+      out(`Deployed ${r.kinds.join(", ")} for ${app}`);
+      if (r.applied) out(r.applied);
+      if (r.rollout) out(r.rollout);
+    }
+    return 0;
+  } catch (e) {
+    if (e.exitCode) {
+      process.stderr.write(`techbro: ${e.message}\n`);
+      return e.exitCode;
+    }
+    throw e;
+  }
+}
+
+const out = (s) => process.stdout.write(s.endsWith("\n") ? s : s + "\n");
+
+function version() {
+  return JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")).version;
+}
+
+function projectInit(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      template: { type: "string", short: "t", default: "_default" },
+      name: { type: "string", short: "n" },
+      force: { type: "boolean", short: "f", default: false },
+      "no-git": { type: "boolean", default: false },
+      "skip-setup": { type: "boolean", default: false },
+      "skip-build": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+  if (values.help) {
+    out(PROJECT_USAGE);
+    return 0;
+  }
+  if (positionals.length > 1) throw new Error("too many arguments");
+  const dir = positionals[0];
+  const result = initProject({
+    template: values.template,
+    dir,
+    name: values.name,
+    force: values.force,
+    git: !values["no-git"],
+  });
+  const setup = !values["skip-setup"];
+  if (setup) {
+    out(`Scaffolded ${result.target}`);
+    setupProject(result.target, { log: out, skipBuild: values["skip-build"] });
+  }
+  out(printSummary({ ...result, setup }, dir));
+  return 0;
+}
+
+async function teamCommand(sub, rest) {
+  if (!sub || sub === "--help" || sub === "-h") {
+    out(TEAM_USAGE);
+    return sub ? 0 : 2;
+  }
+  if (sub === "list") {
+    for (const t of listTeams(loadConfig())) out(`${t.current ? "*" : " "} ${t.name.padEnd(16)}${t.url}`);
+    return 0;
+  }
+  if (sub === "use") {
+    if (rest.length !== 1) throw new Error("usage: techbro team use <name>");
+    const config = loadConfig();
+    useTeam(config, rest[0]);
+    saveConfig(config);
+    out(`Current team: ${rest[0]}`);
+    return 0;
+  }
+  if (sub === "upgrade") {
+    const { values } = parseArgs({
+      args: rest,
+      options: {
+        team: { type: "string", short: "t" },
+        "dry-run": { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+    if (values.help) {
+      out(TEAM_USAGE);
+      return 0;
+    }
+    const client = createClient({ token: resolveToken() });
+    const s = await upgradeTeam({ teamName: values.team, config: loadConfig(), client, dryRun: values["dry-run"] });
+    out(`Repository: ${s.repo} (${s.base})`);
+    for (const a of s.actions) {
+      out(`  ${a.action.padEnd(10)}${a.path}${a.candidate ? `  -> candidate ${a.candidate}; merge by hand` : ""}`);
+    }
+    if (s.status === "current") out("managed files are up to date");
+    else if (s.status === "dry-run") out(`dry run: would write ${s.changes.join(", ")}`);
+    else out(`${s.status === "pr-created" ? "opened" : "reusing"} PR: ${s.prUrl} (branch ${s.branch})`);
+    return 0;
+  }
+  if (sub === "join") {
+    const { values, positionals } = parseArgs({
+      args: rest,
+      allowPositionals: true,
+      options: {
+        url: { type: "string", short: "u" },
+        force: { type: "boolean", short: "f", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+    if (values.help) {
+      out(TEAM_USAGE);
+      return 0;
+    }
+    if (positionals.length !== 1 || !values.url) throw new Error("usage: techbro team join <name> --url <github-repo-url>");
+    const config = loadConfig();
+    const client = createClient({ token: resolveToken() });
+    const s = await joinTeam({ name: positionals[0], url: values.url, config, client, force: values.force });
+    saveConfig(config);
+    out(`Repository: ${s.repo}`);
+    if (s.status === "member") out("already a member");
+    else if (s.status === "added") out(`added ${s.login} to members.json`);
+    else out(`membership pending: ${s.issueUrl} (the team workflow will add you)`);
+    out(`Current team: ${s.name}`);
+    return 0;
+  }
+  if (sub === "create") {
+    const { values, positionals } = parseArgs({
+      args: rest,
+      allowPositionals: true,
+      options: {
+        url: { type: "string", short: "u" },
+        force: { type: "boolean", short: "f", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+    if (values.help) {
+      out(TEAM_USAGE);
+      return 0;
+    }
+    if (positionals.length !== 1 || !values.url) throw new Error("usage: techbro team create <name> --url <github-repo-url>");
+    const config = loadConfig();
+    const client = createClient({ token: resolveToken() });
+    const s = await createTeam({ name: positionals[0], url: values.url, config, client, force: values.force });
+    saveConfig(config);
+    out(`Repository: ${s.repo}`);
+    out(`Owner: ${s.owner}`);
+    out(`Members: ${s.members}`);
+    if (s.created.length) out(`Created: ${s.created.join(", ")}`);
+    if (s.updated.length) out(`Updated: ${s.updated.join(", ")}`);
+    out(`Current team: ${s.name}`);
+    return 0;
+  }
+  return null;
+}
+
+async function projectLink(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      url: { type: "string", short: "u" },
+      name: { type: "string", short: "n" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+  if (values.help) {
+    out(PROJECT_USAGE);
+    return 0;
+  }
+  if (positionals.length) throw new Error("too many arguments");
+  const config = loadConfig();
+  const client = createClient({ token: resolveToken() });
+  const s = await linkProject({ cwd: process.cwd(), url: values.url, name: values.name, config, client });
+  if (s.status === "linked") out("already linked");
+  else if (s.status === "added") out(`linked ${s.name} (${s.url}) to team ${s.team}`);
+  else out(`link pending: ${s.issueUrl} (the team workflow will add it)`);
+  const rc = s.reviewConfig;
+  if (rc.status === "seeded") out("seeded review config for this project");
+  if (rc.warning) process.stderr.write(`techbro: warning: ${rc.warning}\n`);
+  if (rc.status === "pending-admin" || rc.status === "skipped" || rc.status === "failed") {
+    out(`Proposed review config (add under projects.${s.name}):\n${JSON.stringify(rc.proposal, null, 2)}`);
+  }
+  const cl = s.caller;
+  if (cl.prUrl) out(`review caller PR (${cl.status === "pr-created" ? "opened" : "reusing"}): ${cl.prUrl}`);
+  else if (cl.status === "current") out("review caller is up to date");
+  if (cl.warning) process.stderr.write(`techbro: warning: ${cl.warning}\n`);
+  return 0;
+}
+
+async function projectReview(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      url: { type: "string", short: "u" },
+      ref: { type: "string", short: "r" },
+      team: { type: "string", short: "t" },
+      project: { type: "string", short: "p" },
+      wait: { type: "boolean", short: "w", default: false },
+      "dry-run": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+  if (values.help) {
+    out(PROJECT_USAGE);
+    return 0;
+  }
+  if (positionals.length) throw new Error("too many arguments");
+  const client = createClient({ token: resolveToken() });
+  const s = await reviewProject({
+    cwd: process.cwd(), url: values.url, ref: values.ref, team: values.team, project: values.project, wait: values.wait, dryRun: values["dry-run"],
+    config: loadConfig(), client, warn: (m) => process.stderr.write(`techbro: warning: ${m}\n`),
+  });
+  out(`Project: ${s.project} @ ${s.sha}`);
+  if (s.dryRun) {
+    out("Dry run: nothing dispatched");
+    out(`Tests: ${s.effective.test ?? "none"}`);
+    out(`Security fail-on: ${s.effective.securityFailOn}`);
+    out(`Duplication: ${s.effective.duplicationMode}${s.effective.duplicationMode === "required" ? ` max ${s.effective.duplicationMaxPercent}%` : ""}`);
+    out(`Sonar: ${s.effective.sonarMode}${s.effective.sonarProjectKey ? ` (${s.effective.sonarProjectKey})` : ""}`);
+    for (const m of s.missing) out(`Missing: ${m}`);
+    for (const n of s.notes) out(`Note: ${n}`);
+    return s.ok ? 0 : 1;
+  }
+  out(`Request: ${s.requestId}`);
+  out(`Run: ${s.runUrl ?? s.workflowUrl}`);
+  if (s.note) out(s.note);
+  if (s.status === "timeout") process.stderr.write("techbro: timed out waiting for the review\n");
+  else if (s.status === "failure") process.stderr.write(`techbro: review ${s.conclusion}\n`);
+  if (s.artifactUrl) out(`Report artifact: ${s.artifactUrl}`);
+  return s.ok ? 0 : 1;
+}
+
+async function clusterCommand(sub, rest, deps) {
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    out(CLUSTER_USAGE);
+    return sub ? 0 : 2;
+  }
+  const { values, positionals } = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    options: {
+      team: { type: "string", short: "t" },
+      kubeconfig: { type: "string" },
+      context: { type: "string" },
+      namespace: { type: "string", short: "n" },
+      "profile-file": { type: "string" },
+      "passphrase-file": { type: "string" },
+      force: { type: "boolean", short: "f", default: false },
+      "dry-run": { type: "boolean", default: false },
+      yes: { type: "boolean", short: "y", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+  if (values.help) {
+    out(CLUSTER_USAGE);
+    return 0;
+  }
+  if (!["add", "list", "use", "remove"].includes(sub)) return null;
+  if (sub === "list" ? positionals.length : positionals.length !== 1) throw new Error(`usage: techbro cluster ${sub}${sub === "list" ? "" : " <name>"}`);
+  const name = positionals[0];
+  const config = loadConfig();
+  const client = deps.client ?? createClient({ token: resolveToken() });
+  const passphrase = (confirm) => (deps.resolvePassphrase ?? resolvePassphrase)({ file: values["passphrase-file"], confirm });
+  const teamName = values.team;
+
+  if (sub === "list") {
+    const r = await listSharedClusters({ config, client, teamName });
+    out(`Team ${r.team} (${r.repo})`);
+    if (!r.clusters.length) out("  no shared clusters");
+    for (const c of r.clusters) out(`  ${c.name.padEnd(16)}${c.installed ? "installed" : `run: techbro cluster use ${c.name}`}`);
+    return 0;
+  }
+  if (sub === "use") {
+    const r = await useSharedCluster({ config, client, name, teamName, passphrase: await passphrase(false) });
+    saveConfig(r.config);
+    out(`Installed cluster ${name} from ${r.repo} (context ${r.context}${r.namespace ? `, namespace ${r.namespace}` : ""})`);
+    out(`Kubeconfig: ${r.kubeconfig} (mode 600; ~/.kube/config unchanged)`);
+    out(`Current cluster: ${name}; try: techbro kube check`);
+    return 0;
+  }
+  if (sub === "remove") {
+    if (!values.yes) throw new Error("remove deletes the shared cluster for the whole team; confirm with --yes");
+    const r = await removeSharedCluster({ config, client, name, teamName });
+    saveConfig(r.config);
+    out(`Removed ${r.removed.join(", ")} from ${r.repo}`);
+    out("Members keep any copy they already decrypted; rotate the credential on the cluster.");
+    return 0;
+  }
+  if (!values.kubeconfig || !values.context) throw new Error("--kubeconfig and --context are required");
+  if (!values.yes && !values["dry-run"]) throw new Error("add commits an encrypted credential to the team repo; confirm with --yes (or preview with --dry-run)");
+  const profile = values["profile-file"] ? readJson(values["profile-file"], "profile file") : {};
+  if (!profile || typeof profile !== "object" || Array.isArray(profile)) throw new Error("profile file must be a JSON object");
+  for (const k of ["context", "namespace"]) if (k in profile) throw new Error(`profile file must not set ${k}; use --${k}`);
+  const r = await addSharedCluster({
+    config, client, name, teamName, profile, force: values.force, dryRun: values["dry-run"],
+    kubeconfig: values.kubeconfig, context: values.context, namespace: values.namespace,
+    passphrase: values["dry-run"] ? null : await passphrase(true),
+    run: deps.run ?? defaultRun,
+  });
+  for (const w of r.warnings) process.stderr.write(`techbro: warning: ${w}\n`);
+  if (r.dryRun) {
+    out(`Dry run: nothing committed to ${r.repo}`);
+    out(`  would ${r.replaced ? "replace" : "add"}: ${r.files.join(", ")} (context ${r.context}${r.namespace ? `, namespace ${r.namespace}` : ""})`);
+    return 0;
+  }
+  out(`${r.replaced ? "Replaced" : "Added"} shared cluster ${name} in ${r.repo} (context ${r.context}${r.namespace ? `, namespace ${r.namespace}` : ""})`);
+  out(`Members: techbro team join ${r.team} --url <repo>, set ${PASSPHRASE_ENV}, then techbro cluster use ${name}`);
+  return 0;
+}
+
+async function doctorCommand(rest, deps) {
+  const { values, positionals } = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    options: { online: { type: "boolean", default: false }, json: { type: "boolean", default: false }, help: { type: "boolean", short: "h", default: false } },
+  });
+  if (values.help) {
+    out(DOCTOR_USAGE);
+    return 0;
+  }
+  if (positionals.length) throw new Error("too many arguments");
+  let client = deps.client;
+  if (!client && values.online) {
+    try {
+      client = createClient({ token: resolveToken() });
+    } catch {
+      client = null;
+    }
+  }
+  const r = await doctor({ online: values.online, client, cwd: deps.cwd ?? process.cwd(), ...(deps.run && { run: deps.run }), ...(deps.env && { env: deps.env }) });
+  if (values.json) {
+    out(JSON.stringify(r, null, 2));
+    return r.ok ? 0 : 1;
+  }
+  const tag = { ok: "ok  ", warn: "warn", fail: "FAIL" };
+  for (const c of r.checks) {
+    out(`${tag[c.status]} ${c.area.padEnd(8)}${c.name}${c.detail ? `: ${c.detail}` : ""}`);
+    if (c.fix && c.status !== "ok") out(`     ${" ".repeat(8)}fix: ${c.fix}`);
+  }
+  const n = (s) => r.checks.filter((c) => c.status === s).length;
+  out(`\n${n("ok")} ok, ${n("warn")} warning(s), ${n("fail")} failure(s)`);
+  return r.ok ? 0 : 1;
+}
+
+export async function main(argv, deps = {}) {
+  const [cmd, sub, ...rest] = argv;
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+    out(USAGE);
+    return cmd ? 0 : 2;
+  }
+  if (cmd === "--version" || cmd === "-v") {
+    out(version());
+    return 0;
+  }
+  if (cmd === "project") {
+    if (!sub || sub === "--help" || sub === "-h") {
+      out(PROJECT_USAGE);
+      return sub ? 0 : 2;
+    }
+    if (sub === "list") {
+      for (const n of listTemplates()) out(`${n.padEnd(16)}${describeTemplate(n)}`);
+      return 0;
+    }
+    if (sub === "init") return projectInit(rest);
+    if (sub === "link") return projectLink(rest);
+    if (sub === "review") return projectReview(rest);
+  }
+  if (cmd === "team") {
+    const code = await teamCommand(sub, rest);
+    if (code !== null) return code;
+  }
+  if (cmd === "cluster") {
+    const code = await clusterCommand(sub, rest, deps);
+    if (code !== null) return code;
+  }
+  if (cmd === "doctor") return doctorCommand(sub ? [sub, ...rest] : [], deps);
+  if (cmd === "kube") {
+    const code = await kubeCommand(sub, rest, deps);
+    if (code !== null) return code;
+  }
+  process.stderr.write(`techbro: unknown command "${argv.join(" ")}"\n\n${USAGE}`);
+  return 2;
+}