techbro 0.0.0-stage → 0.5.0

package/src/kube.js

@@ -0,0 +1,317 @@
+// Kubernetes core: cluster profiles, safe kubectl argv, and app operations.
+// Never reads credentials, never modifies kubeconfig, never runs `use-context`.
+// Team-shared clusters pass their techbro-owned kubeconfig file via --kubeconfig.
+//
+// CONTRACT (consumed by src/kube-project.js):
+//   resolveCluster(...) -> { name, context, namespace, registry, domain, tlsResolver,
+//                            platform, memory, build, secretRefs, caEnv }
+//   kubeArgs(profile, args) -> argv with explicit --context/--namespace prepended
+//   kubectl(profile, args, { run, input, timeoutMs }) -> stdout string (throws on failure)
+// `run(file, argv, { input, timeout })` is an injected subprocess runner returning
+// { code, stdout, stderr } (or a Promise of it). The default uses execFile (no shell).
+import { execFile } from "node:child_process";
+
+const DNS_LABEL = /^[a-z0-9]([-a-z0-9]{0,61}[a-z0-9])?$/;
+const DNS_NAME = /^[a-z0-9]([-a-z0-9.]{0,251}[a-z0-9])?$/;
+const CONTEXT_RE = /^[A-Za-z0-9][A-Za-z0-9._:@\/-]{0,252}$/;
+const REGISTRY_RE = /^[A-Za-z0-9][A-Za-z0-9._:\/-]{0,252}$/;
+const IMAGE_RE = /^[A-Za-z0-9][A-Za-z0-9._:@\/-]{0,252}$/;
+const MEMORY_RE = /^[1-9][0-9]{0,5}(Mi|Gi)$/;
+const PLATFORM_RE = /^linux\/(amd64|arm64|arm\/v[67])$/;
+const RESOLVER_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$/;
+const PROFILE_KEYS = ["context", "namespace", "registry", "domain", "tlsResolver", "platform", "memory", "build", "secretRefs", "caEnv"];
+const BUILD_KEYS = ["image", "privileged", "memory", "insecure"];
+export const DEFAULT_CLUSTER = null;
+
+// No cluster ships built in; teams share profiles with `techbro cluster add`.
+export const BUILTIN_PROFILES = Object.freeze({});
+
+const need = (ok, msg) => {
+  if (!ok) throw new Error(msg);
+};
+const str = (v) => typeof v === "string";
+const isObj = (v) => v && typeof v === "object" && !Array.isArray(v);
+
+export function validateName(name, what = "name") {
+  need(str(name) && DNS_LABEL.test(name), `invalid ${what}: must be a DNS label`);
+  return name;
+}
+
+export const validateNamespace = (ns) => validateName(ns, "namespace");
+
+// Validates a stored/custom profile block; returns a cleaned copy (unknown keys rejected).
+export function validateProfile(p) {
+  need(isObj(p), "cluster profile must be an object");
+  for (const k of Object.keys(p)) need(PROFILE_KEYS.includes(k), `unknown profile field: ${k}`);
+  need(str(p.context) && CONTEXT_RE.test(p.context), "profile.context is required and must be a plain kube context name");
+  const out = { context: p.context };
+  if (p.namespace != null) out.namespace = validateNamespace(p.namespace);
+  if (p.registry != null) {
+    need(str(p.registry) && REGISTRY_RE.test(p.registry), "invalid profile.registry");
+    out.registry = p.registry;
+  }
+  if (p.domain != null) {
+    need(str(p.domain) && DNS_NAME.test(p.domain), "invalid profile.domain");
+    out.domain = p.domain;
+  }
+  if (p.tlsResolver != null) {
+    need(str(p.tlsResolver) && RESOLVER_RE.test(p.tlsResolver), "invalid profile.tlsResolver");
+    out.tlsResolver = p.tlsResolver;
+  }
+  if (p.platform != null) {
+    need(str(p.platform) && PLATFORM_RE.test(p.platform), "invalid profile.platform");
+    out.platform = p.platform;
+  }
+  if (p.memory != null) {
+    need(str(p.memory) && MEMORY_RE.test(p.memory), "invalid profile.memory");
+    out.memory = p.memory;
+  }
+  if (p.build != null) {
+    const b = p.build;
+    need(isObj(b), "profile.build must be an object");
+    for (const k of Object.keys(b)) need(BUILD_KEYS.includes(k), `unknown profile.build field: ${k}`);
+    const nb = {};
+    if (b.image != null) {
+      need(str(b.image) && IMAGE_RE.test(b.image), "invalid profile.build.image");
+      nb.image = b.image;
+    }
+    if (b.memory != null) {
+      need(str(b.memory) && MEMORY_RE.test(b.memory), "invalid profile.build.memory");
+      nb.memory = b.memory;
+    }
+    for (const k of ["privileged", "insecure"]) {
+      if (b[k] != null) {
+        need(typeof b[k] === "boolean", `profile.build.${k} must be boolean`);
+        nb[k] = b[k];
+      }
+    }
+    out.build = nb;
+  }
+  if (p.caEnv != null) {
+    need(str(p.caEnv) && /^[A-Z][A-Z0-9_]{0,62}$/.test(p.caEnv), "invalid profile.caEnv (an env var name)");
+    out.caEnv = p.caEnv;
+  }
+  if (p.secretRefs != null) {
+    need(isObj(p.secretRefs), "profile.secretRefs must be an object of secret names");
+    out.secretRefs = {};
+    for (const [k, v] of Object.entries(p.secretRefs)) {
+      need(/^[A-Za-z][A-Za-z0-9_]{0,62}$/.test(k), `invalid secretRefs key: ${k}`);
+      out.secretRefs[k] = validateName(v, `secretRefs.${k}`);
+    }
+  }
+  return out;
+}
+
+const customClusters = (config) => {
+  const c = isObj(config?.kube?.clusters) ? config.kube.clusters : {};
+  for (const n of Object.keys(BUILTIN_PROFILES)) need(!(n in c), `config.kube.clusters.${n} overrides a reserved built-in profile`);
+  return c;
+};
+
+const sharedClusters = (config) => (isObj(config?.kube?.shared) ? config.kube.shared : {});
+
+// Returns { current, clusters: [{ name, context, builtin, team }] }; team-shared entries shadow built-ins.
+export function listClusters(config) {
+  const custom = customClusters(config);
+  const shared = sharedClusters(config);
+  const clusters = Object.entries(BUILTIN_PROFILES)
+    .filter(([name]) => !(name in shared))
+    .map(([name, p]) => ({ name, context: p.context, builtin: true }));
+  for (const [name, s] of Object.entries(shared)) clusters.push({ name, context: s.profile?.context, builtin: false, team: s.team });
+  for (const [name, p] of Object.entries(custom)) {
+    if (!(name in BUILTIN_PROFILES) && !(name in shared)) clusters.push({ name, context: p.context, builtin: false });
+  }
+  return { current: config?.kube?.current ?? DEFAULT_CLUSTER, clusters };
+}
+
+// Returns a new config with the cluster added; other config keys are preserved.
+export function addCluster(config, name, profile) {
+  validateName(name, "cluster name");
+  need(!(name in BUILTIN_PROFILES), `cluster name is reserved by a built-in profile: ${name}`);
+  const clean = validateProfile(profile);
+  const kube = config?.kube ?? {};
+  return {
+    ...config,
+    kube: { ...kube, current: kube.current ?? null, clusters: { ...customClusters(config), [name]: clean } },
+  };
+}
+
+// Returns a new config with kube.current set. Never touches kubeconfig.
+export function useCluster(config, name) {
+  validateName(name, "cluster name");
+  need(name in BUILTIN_PROFILES || name in customClusters(config) || name in sharedClusters(config), `unknown cluster: ${name}`);
+  const kube = config?.kube ?? {};
+  return { ...config, kube: { ...kube, current: name, clusters: customClusters(config) } };
+}
+
+export function defaultRun(file, args, { input, timeout, inputFile } = {}) {
+  return new Promise((resolve, reject) => {
+    if (inputFile != null) return reject(new Error("defaultRun does not support inputFile; inject a streaming runner"));
+    const child = execFile(file, args, { timeout, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" }, (err, stdout, stderr) => {
+      if (err && typeof err.code !== "number") return resolve({ code: 1, stdout: stdout ?? "", stderr: stderr || err.message });
+      resolve({ code: err ? err.code : 0, stdout: stdout ?? "", stderr: stderr ?? "" });
+    });
+    if (input != null) child.stdin.end(input);
+  });
+}
+
+// Resolution precedence: explicit flags > project config.kube > local config > builtin.
+// Namespace: explicit > project > profile > `kubectl config view --minify` lookup (no raw config).
+export async function resolveCluster({ config = {}, project = {}, cluster, namespace, run = defaultRun } = {}) {
+  const name = cluster ?? project?.kube?.cluster ?? config?.kube?.current ?? DEFAULT_CLUSTER;
+  need(name, "no cluster selected: run techbro cluster use <name> (team-shared) or techbro kube cluster add/use");
+  validateName(name, "cluster name");
+  const custom = customClusters(config)[name];
+  const shared = sharedClusters(config)[name];
+  need(shared || custom || name in BUILTIN_PROFILES, `unknown cluster: ${name}`);
+  let raw;
+  let kubeconfig = null;
+  if (shared) {
+    need(str(shared.kubeconfig) && shared.kubeconfig.startsWith("/"), `shared cluster ${name} has no local kubeconfig; run techbro cluster use ${name}`);
+    raw = { ...(BUILTIN_PROFILES[name] ?? {}), ...validateProfile(shared.profile) };
+    kubeconfig = shared.kubeconfig;
+  } else raw = name in BUILTIN_PROFILES && !custom ? BUILTIN_PROFILES[name] : validateProfile(custom);
+  const prof = {
+    name,
+    kubeconfig,
+    context: raw.context,
+    namespace: null,
+    registry: raw.registry ?? null,
+    domain: raw.domain ?? null,
+    tlsResolver: raw.tlsResolver ?? null,
+    platform: raw.platform ?? null,
+    memory: raw.memory ?? null,
+    build: raw.build ? { ...raw.build } : null,
+    secretRefs: { ...(raw.secretRefs ?? {}) },
+    caEnv: raw.caEnv ?? null,
+  };
+  const lookup = async () => {
+    const res = await run(
+      "kubectl",
+      ["config", "view", ...(kubeconfig ? ["--kubeconfig", kubeconfig] : []), "--minify", "--context", prof.context, "-o", "jsonpath={.contexts[0].context.namespace}"],
+      { timeout: 15000 },
+    );
+    need(res.code === 0, `could not determine namespace for context ${prof.context}; pass --namespace`);
+    return String(res.stdout ?? "").trim();
+  };
+  let ns = namespace;
+  if (ns == null) {
+    const projectNs = project?.kube?.namespace ?? null;
+    const def = raw.namespace ?? (await lookup());
+    if (projectNs != null) {
+      validateNamespace(projectNs);
+      need(def === projectNs, `project namespace ${projectNs} differs from the cluster default${def ? ` ${def}` : ""}; pass --namespace to confirm`);
+    }
+    ns = def;
+    need(ns, `context ${prof.context} has no namespace; pass --namespace`);
+  }
+  prof.namespace = validateNamespace(ns);
+  return prof;
+}
+
+const FORBIDDEN_FLAG = /^-v|^--v|^(--context|--namespace|-n|--kubeconfig|--cluster|--user|--server|-s|--token|--as|--as-group|--as-uid|--all-namespaces|-A|--insecure-skip-tls-verify|--certificate-authority|--client-certificate|--client-key|--username|--password|--tls-server-name|--request-timeout)(=|$)|^-n.|^-s.|^-A/;
+const READ_KINDS = new Set(["deployment", "deployments", "deploy", "service", "services", "svc", "ingress", "ingresses", "ing", "pod", "pods", "po"]);
+
+// Builds a safe argv. Throws on conflicting context/namespace/kubeconfig flags,
+// all-namespace requests, secret access, or verbs outside the allow-list.
+export function kubeArgs(profile, args) {
+  need(isObj(profile) && str(profile.context) && CONTEXT_RE.test(profile.context), "profile.context required");
+  validateNamespace(profile.namespace);
+  need(profile.kubeconfig == null || (str(profile.kubeconfig) && /^\/[^\0\n]*$/.test(profile.kubeconfig)), "profile.kubeconfig must be an absolute path");
+  need(Array.isArray(args) && args.length > 0 && args.every(str), "kubectl args must be a non-empty string array");
+  for (const a of args) {
+    need(!FORBIDDEN_FLAG.test(a), `forbidden kubectl flag: ${a}`);
+    need(!/secret/i.test(a), `secret access is not allowed: ${a}`);
+  }
+  const [verb, ...rest] = args;
+  const positional = rest.filter((a) => !a.startsWith("-"));
+  switch (verb) {
+    case "get": {
+      need(positional.length > 0, "get requires a resource");
+      const kinds = positional[0].split(",").map((k) => k.split("/")[0].toLowerCase());
+      need(kinds.every((k) => READ_KINDS.has(k)), `get of this resource is not allowed: ${positional[0]}`);
+      break;
+    }
+    case "logs":
+      need(positional.length === 1, "logs takes exactly one target");
+      break;
+    case "rollout":
+      need(["status", "restart", "undo"].includes(rest[0]), "rollout supports status|restart|undo only");
+      break;
+    case "auth":
+      need(rest[0] === "can-i" && positional.length >= 3, "auth supports `can-i <verb> <resource>` only");
+      break;
+    case "apply": {
+      const ok = (rest.length === 2 || (rest.length === 3 && rest[2] === "--dry-run=server")) && rest[0] === "-f" && rest[1] === "-";
+      need(ok, "apply is limited to `apply -f -` with optional --dry-run=server");
+      break;
+    }
+    case "delete":
+      need(positional.length === 2 && positional[0] === "pod" && !rest.includes("--all") && !rest.some((a) => /^(-l|--selector)/.test(a)),
+        "delete is limited to a single named pod");
+      break;
+    default:
+      throw new Error(`kubectl command not allowed: ${verb}`);
+  }
+  const kc = profile.kubeconfig ? ["--kubeconfig", profile.kubeconfig] : [];
+  return [...kc, "--context", profile.context, "--namespace", profile.namespace, ...args];
+}
+
+// Runs kubectl with safe argv. Returns stdout; throws with trimmed stderr on failure.
+export async function kubectl(profile, args, { run = defaultRun, input, inputFile, timeoutMs = 60000 } = {}) {
+  const argv = kubeArgs(profile, args);
+  const watch = args[0] === "logs" || (args[0] === "rollout" && args[1] === "status");
+  if (!watch) argv.push("--request-timeout=30s");
+  const res = await run("kubectl", argv, { input, inputFile, timeout: timeoutMs });
+  if (res.code !== 0) throw new Error(`kubectl ${args[0]} failed: ${String(res.stderr ?? "").trim() || `exit ${res.code}`}`);
+  return String(res.stdout ?? "");
+}
+
+// Namespaced checks only; never throws on a failing check.
+export async function preflight({ profile, run = defaultRun }) {
+  const checks = [];
+  const add = async (name, args) => {
+    try {
+      const out = (await kubectl(profile, args, { run })).trim();
+      checks.push({ name, ok: !args.includes("can-i") || out === "yes", detail: out.slice(0, 200) });
+    } catch (e) {
+      checks.push({ name, ok: false, detail: e.message });
+    }
+  };
+  await add("get deployments", ["auth", "can-i", "get", "deployments"]);
+  await add("create deployments", ["auth", "can-i", "create", "deployments"]);
+  await add("list deployments", ["get", "deployments", "-o", "name"]);
+  return { ok: checks.every((c) => c.ok), checks };
+}
+
+export const LOGS_WARNING =
+  "Logs may contain application secrets or personal data; they are shown as-is and NOT redacted.";
+const MUTATIONS = new Set(["restart", "rollback"]);
+export const OPERATIONS = ["status", "logs", "rollout-status", "restart", "rollback"];
+
+// Operations: status, logs, rollout-status, restart, rollback. Mutations need yes (or dryRun).
+// dryRun returns the plan without running anything.
+export async function performKube({ profile, operation, app, tail = 100, yes = false, dryRun = false, run = defaultRun }) {
+  need(OPERATIONS.includes(operation), `unknown operation: ${operation}`);
+  validateName(app, "app name");
+  need(Number.isInteger(tail) && tail >= 1 && tail <= 5000, "tail must be an integer between 1 and 5000");
+  const target = `deployment/${app}`;
+  const argsByOp = {
+    status: ["get", "deployment", app, "-o", "wide"],
+    logs: ["logs", target, `--tail=${tail}`],
+    "rollout-status": ["rollout", "status", target, "--timeout=120s"],
+    restart: ["rollout", "restart", target],
+    rollback: ["rollout", "undo", target],
+  };
+  const args = argsByOp[operation];
+  const mutation = MUTATIONS.has(operation);
+  const argv = kubeArgs(profile, args);
+  if (dryRun) {
+    return { operation, app, mutation, dryRun: true, plan: [["kubectl", ...argv].join(" ")] };
+  }
+  need(!mutation || yes === true, `${operation} changes the cluster; confirm with --yes`);
+  const output = await kubectl(profile, args, { run, timeoutMs: operation === "rollout-status" ? 150000 : 60000 });
+  const result = { operation, app, mutation, dryRun: false, output };
+  if (operation === "logs") result.warning = LOGS_WARNING;
+  return result;
+}

package/src/managed.js

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+export const MANAGED_VERSION = 5;
+export const REVIEW_WORKFLOW = ".github/workflows/techbro-review.yml";
+export const REPORT_ARTIFACT = "techbro-review-report";
+
+const asset = (n) => readFileSync(new URL(`../assets/${n}`, import.meta.url), "utf8");
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+
+const FILES = [
+  { path: REVIEW_WORKFLOW, src: "review-workflow.yml", c: "#", team: true },
+  { path: ".github/actions/techbro/action.yml", src: "review-action.yml", c: "#", team: true },
+  { path: ".github/techbro/review.mjs", src: "review.mjs", c: "//" },
+  { path: ".github/techbro/rules/baseline.yml", src: "baseline-rules.yml", c: "#" },
+  { path: ".github/techbro-review.json", src: "review-config.json", c: null, seed: true },
+];
+const CALLER = { path: REVIEW_WORKFLOW, src: "caller-workflow.yml", c: "#", team: true };
+
+const HEADER_RE = /^(?:#|\/\/) techbro-managed v(\d+) sha256=([0-9a-f]{64})\n/;
+const OWNER_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
+const REPO_RE = /^[A-Za-z0-9._-]{1,100}$/;
+
+function teamOf(params) {
+  const { owner, repo } = params ?? {};
+  if (typeof owner !== "string" || typeof repo !== "string" || !OWNER_RE.test(owner) || !REPO_RE.test(repo) || repo === "." || repo === "..") {
+    throw new Error("valid team { owner, repo } is required to render managed files");
+  }
+  return `${owner}/${repo}`;
+}
+
+function render(f, params) {
+  let body = asset(f.src);
+  if (f.team) body = body.replaceAll("__TEAM__", teamOf(params)).replaceAll("__VERSION__", String(MANAGED_VERSION));
+  return f.c ? `${f.c} techbro-managed v${MANAGED_VERSION} sha256=${sha(body)}\n${body}` : body;
+}
+
+function classify(f, current, params) {
+  if (current === null || current === undefined) return "missing";
+  if (current === render(f, params)) return "current";
+  if (!f.c) return "customized";
+  const m = HEADER_RE.exec(current);
+  if (!m) return "customized";
+  return sha(current.slice(m[0].length)) === m[2] ? "pristine-old" : "customized";
+}
+
+export function managedFiles(params) {
+  return FILES.map((f) => ({ path: f.path, content: render(f, params), ...(f.seed ? { seed: true } : {}) }));
+}
+
+export function callerFile(params) {
+  return { path: CALLER.path, content: render(CALLER, params) };
+}
+
+export function classifyManaged(path, current, params) {
+  const f = FILES.find((x) => x.path === path);
+  if (!f) throw new Error(`not a managed file: ${path}`);
+  return classify(f, current, params);
+}
+
+export function classifyCaller(current, params) {
+  return classify(CALLER, current, params);
+}

package/src/project.js

@@ -0,0 +1,202 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseRepoUrl } from "./github.js";
+import { MANAGED_VERSION, callerFile, classifyCaller } from "./managed.js";
+
+const BRANCH = "main";
+const HINT = "main may be protected; allow the token or open a PR manually";
+export const REVIEW_CONFIG = ".github/techbro-review.json";
+const defaultGit = (args, cwd) => execFileSync("git", args, { cwd, stdio: "pipe", encoding: "utf8" });
+
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const readJson = (f) => {
+  try {
+    return JSON.parse(readFileSync(f, "utf8"));
+  } catch {
+    return null;
+  }
+};
+
+export function proposeConfig(cwd, meta) {
+  const pkg = readJson(join(cwd, "package.json"));
+  let test = null;
+  if (meta?.template === "_default" && pkg && existsSync(join(cwd, "Cargo.toml"))) {
+    test = { runtime: "rust-node", install: "npm --prefix apps/frontend ci", command: "npm run check", workdir: "." };
+  } else if (pkg?.scripts?.test) {
+    test = { runtime: "node", command: "npm test", workdir: "." };
+    if (existsSync(join(cwd, "package-lock.json"))) test.install = "npm ci";
+  }
+  if (!test) return null;
+  return { test, security: { failOn: "ERROR" }, sonar: { mode: "optional" }, duplication: { mode: "required", maxPercent: 10 } };
+}
+
+async function seedConfig({ client, to, tr, name, proposal, canPush }) {
+  if (!proposal) {
+    return {
+      status: "unrecognized",
+      warning: `project type not recognized; no test config seeded. Add projects.${name} with a "test" command to ${REVIEW_CONFIG} in ${to}/${tr} (see README)`,
+    };
+  }
+  if (!canPush) {
+    return { status: "pending-admin", proposal, warning: `no write access to ${to}/${tr}; a team admin must add projects.${name} to ${REVIEW_CONFIG}` };
+  }
+  let file;
+  try {
+    file = await client.getFile(to, tr, REVIEW_CONFIG, BRANCH);
+  } catch (err) {
+    return { status: "failed", proposal, warning: `could not read ${REVIEW_CONFIG}: ${err.message}; not modified` };
+  }
+  if (file && !isObj(file.json?.projects)) {
+    return { status: "skipped", proposal, warning: `${REVIEW_CONFIG} has no "projects" object; not modified` };
+  }
+  if (file && Object.hasOwn(file.json.projects, name)) return { status: "exists" };
+  const next = file ? structuredClone(file.json) : { schemaVersion: 1, projects: {} };
+  next.projects[name] = proposal;
+  try {
+    await client.putFile(to, tr, REVIEW_CONFIG, {
+      content: JSON.stringify(next, null, 2) + "\n",
+      message: `techbro: seed review config for ${name}`,
+      sha: file?.sha,
+      branch: BRANCH,
+    });
+  } catch (err) {
+    const hint = err.status === 409 || err.status === 422 ? "changed concurrently or protected; rerun project link" : HINT;
+    return { status: "failed", proposal, warning: `could not seed ${REVIEW_CONFIG}: ${err.message} (${hint})` };
+  }
+  return { status: "seeded", proposal };
+}
+
+export const callerBranch = () => `techbro/review-caller-v${MANAGED_VERSION}`;
+
+async function installCaller({ client, team, po, pr, proj }) {
+  const params = { owner: team.owner, repo: team.repo };
+  if (po.toLowerCase() !== team.owner.toLowerCase()) {
+    return { status: "unsupported", warning: `project ${po}/${pr} is outside the team organization ${team.owner}; the shared review workflow is same-organization only, no caller installed` };
+  }
+  const base = proj.defaultBranch;
+  const want = callerFile(params);
+  const cur = await client.getFileText(po, pr, want.path, base);
+  const kind = classifyCaller(cur, params);
+  if (kind === "current") return { status: "current" };
+  if (kind === "customized") return { status: "customized", warning: `${want.path} in ${po}/${pr} is customized; left unchanged (compare with the managed caller by hand)` };
+  if (!proj.permissions?.push) {
+    return { status: "pending-admin", warning: `no write access to ${po}/${pr}; a project writer must run techbro project link to open the ${want.path} PR` };
+  }
+  const branch = callerBranch();
+  try {
+    let head = await client.getBranchSha(po, pr, branch);
+    let note;
+    if (head === null) {
+      head = await client.getBranchSha(po, pr, base);
+      await client.createRef(po, pr, branch, head);
+      const commit = await client.commitFiles(po, pr, { baseSha: head, files: [want], message: `techbro: ${kind === "missing" ? "add" : "update"} review caller` });
+      await client.updateRef(po, pr, branch, commit);
+    } else if ((await client.getFileText(po, pr, want.path, branch)) !== want.content) {
+      note = `branch ${branch} already exists with different ${want.path}; not overwritten`;
+    }
+    const open = await client.listPulls(po, pr, { head: branch, base });
+    if (open.length) return { status: "pr-existing", prUrl: open[0].url, branch, ...(note && { warning: note }) };
+    const pull = await client.createPull(po, pr, {
+      title: "techbro: add review caller",
+      head: branch,
+      base,
+      body: `Adds the tiny \`${want.path}\` caller that runs the team's shared review workflow (${team.owner}/${team.repo}@main).\n\nNothing is pushed to ${base}; merge this PR to enable \`techbro project review\`.`,
+    });
+    return { status: "pr-created", prUrl: pull.url, branch, ...(note && { warning: note }) };
+  } catch (err) {
+    return { status: "failed", warning: `could not open the review caller PR on ${po}/${pr}: ${err.message}` };
+  }
+}
+
+export async function linkProject({ cwd, url, name, config, client, git = defaultGit, now = new Date() }) {
+  const teamName = config.currentTeam;
+  if (!teamName || !config.teams[teamName]) {
+    throw new Error("no current team; run techbro team create or team join first");
+  }
+  const { owner: to, repo: tr } = parseRepoUrl(config.teams[teamName].url);
+
+  if (!url) {
+    try {
+      url = git(["remote", "get-url", "origin"], cwd).trim();
+    } catch {
+      url = "";
+    }
+    if (!url) throw new Error("no origin remote; pass --url");
+  }
+  const { owner: po, repo: pr, url: normalized } = parseRepoUrl(url);
+
+  const { login } = await client.getUser();
+  const proj = await client.getRepo(po, pr);
+  if (!proj.permissions?.pull) throw new Error(`no read access to ${po}/${pr} as ${login}`);
+
+  const members = await client.getFile(to, tr, "members.json", BRANCH);
+  if (!members) throw new Error("team repo is not initialized; run team create");
+  if (!members.json?.members?.includes(login)) {
+    throw new Error(`${login} is not a member of team ${teamName}; run techbro team join`);
+  }
+
+  const metaPath = join(cwd, ".techbro.json");
+  const meta = existsSync(metaPath) ? JSON.parse(readFileSync(metaPath, "utf8")) : null;
+  const entry = {
+    name: name ?? meta?.name ?? pr,
+    url: normalized,
+    template: meta?.template ?? null,
+    linkedBy: login,
+    linkedAt: now.toISOString(),
+  };
+
+  const file = await client.getFile(to, tr, "projects.json", BRANCH);
+  if (!file) throw new Error("team repo is not initialized; run team create");
+  const list = structuredClone(file.json);
+  if (!list || !Array.isArray(list.projects)) throw new Error(`projects.json in ${to}/${tr} is malformed`);
+
+  let status = "linked";
+  let issueUrl;
+  const teamRepo = await client.getRepo(to, tr);
+  const registered = list.projects.find((p) => p.url === normalized);
+  if (!registered) {
+    if (teamRepo.permissions?.push) {
+      list.projects.push(entry);
+      try {
+        await client.putFile(to, tr, "projects.json", {
+          content: JSON.stringify(list, null, 2) + "\n",
+          message: `techbro: link project ${entry.name}`,
+          sha: file.sha,
+          branch: BRANCH,
+        });
+      } catch (err) {
+        if (err.status === 409 || err.status === 422 || /protect/i.test(err.message)) throw new Error(`${err.message}\n${HINT}`);
+        throw err;
+      }
+      status = "added";
+    } else {
+      if (!teamRepo.hasIssues) throw new Error(`issues are disabled on ${to}/${tr}; ask the owner to enable them or add it manually`);
+      const open = await client.listIssues(to, tr, { labels: "techbro-link", state: "open", creator: login });
+      issueUrl = open[0]?.url;
+      if (!issueUrl) {
+        issueUrl = (
+          await client.createIssue(to, tr, {
+            title: "techbro: link request",
+            body: JSON.stringify({ schemaVersion: 1, action: "link", login, project: entry }),
+            labels: ["techbro-link"],
+          })
+        ).url;
+      }
+      status = "pending";
+    }
+  }
+
+  if (meta) {
+    writeFileSync(metaPath, JSON.stringify({ ...meta, team: teamName, repo: normalized }, null, 2) + "\n");
+  }
+  const cfgName = registered?.name ?? entry.name;
+  const reviewConfig = await seedConfig({
+    client, to, tr, name: cfgName, proposal: proposeConfig(cwd, meta), canPush: teamRepo.permissions?.push === true,
+  });
+  const caller =
+    status === "pending"
+      ? { status: "deferred", warning: "review caller not installed yet; rerun techbro project link once the project is registered" }
+      : await installCaller({ client, team: { owner: to, repo: tr }, po, pr, proj });
+  return { name: entry.name, url: normalized, team: teamName, status, reviewConfig, caller, ...(issueUrl && { issueUrl }) };
+}