techbro 0.0.0-stage → 0.5.0

package/src/review.js

@@ -0,0 +1,165 @@
+import { execFileSync, } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { parseRepoUrl } from "./github.js";
+import { normalizeDuplication, normalizeSecurity, normalizeSonar, normalizeTest } from "../assets/review.mjs";
+import { REVIEW_CONFIG } from "./project.js";
+import { REPORT_ARTIFACT, REVIEW_WORKFLOW, classifyCaller } from "./managed.js";
+
+const ACTION = ".github/actions/techbro/action.yml";
+
+const defaultGit = (args, cwd) => execFileSync("git", args, { cwd, stdio: "pipe", encoding: "utf8" });
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const WF_FILE = REVIEW_WORKFLOW.split("/").pop();
+
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+async function inspectConfig(client, to, tr, tb, name) {
+  const missing = [];
+  let cfg = null;
+  try {
+    cfg = await client.getFile(to, tr, REVIEW_CONFIG, tb);
+  } catch (err) {
+    missing.push(`${REVIEW_CONFIG} unreadable: ${err.message}`);
+  }
+  const all = cfg?.json?.projects;
+  const pc = isObj(all) && Object.hasOwn(all, name) && isObj(all[name]) ? all[name] : null;
+  if (!cfg && !missing.length) missing.push(`${REVIEW_CONFIG} is missing in ${to}/${tr}; run techbro team upgrade`);
+  else if (cfg && !pc) missing.push(`no projects.${name} entry in ${REVIEW_CONFIG}; defaults apply and no tests run`);
+  const effective = { test: null, securityFailOn: "ERROR", sonarMode: "optional", sonarProjectKey: null, duplicationMode: "required", duplicationMaxPercent: 10 };
+  const check = (label, fn) => {
+    try {
+      return fn();
+    } catch (err) {
+      missing.push(`projects.${name}.${label} invalid: ${err.message}; the remote review would reject it`);
+      return null;
+    }
+  };
+  if (cfg && pc) {
+    const t = check("test", () => normalizeTest(pc.test));
+    const sec = check("security", () => normalizeSecurity(pc.security));
+    const son = check("sonar", () => normalizeSonar(pc.sonar));
+    if (t) effective.test = `${t.runtime}: ${t.command}`;
+    else if (!pc.test?.command && !missing.some((m) => m.includes(".test invalid"))) missing.push(`projects.${name}.test.command is not configured; tests will be skipped`);
+    const dup = check("duplication", () => normalizeDuplication(pc.duplication));
+    if (dup) {
+      effective.duplicationMode = dup.mode;
+      effective.duplicationMaxPercent = dup.maxPercent;
+    }
+    if (sec) effective.securityFailOn = sec.failOn;
+    if (son) {
+      effective.sonarMode = son.mode;
+      effective.sonarProjectKey = son.projectKey || null;
+    }
+  }
+  return { missing, effective };
+}
+
+export async function reviewProject({
+  cwd, url, ref, team, project, wait = false, dryRun = false, config, client, git = defaultGit, uuid = randomUUID, sleep = defaultSleep,
+  warn = () => {}, lookupAttempts = 10, lookupIntervalMs = 2000, waitTimeoutMs = 30 * 60 * 1000, waitIntervalMs = 10000,
+}) {
+  const teamName = team ?? config.currentTeam;
+  const t = teamName && config.teams[teamName];
+  if (!t) throw new Error(teamName ? `unknown team "${teamName}"` : "no current team; run techbro team create or team join first");
+  const { owner: to, repo: tr } = parseRepoUrl(t.url);
+
+  const { login } = await client.getUser();
+  const teamRepo = await client.getRepo(to, tr);
+  const tb = teamRepo.defaultBranch;
+  if (!teamRepo.permissions?.pull) throw new Error(`no read access to ${to}/${tr} as ${login}`);
+  const members = await client.getFile(to, tr, "members.json", tb);
+  if (!members?.json?.members?.some((m) => String(m).toLowerCase() === login.toLowerCase())) throw new Error(`${login} is not a member of team ${teamName}; run techbro team join`);
+  const reg = await client.getFile(to, tr, "projects.json", tb);
+  if (!reg || !Array.isArray(reg.json?.projects)) throw new Error(`projects.json in ${to}/${tr} is missing or malformed`);
+
+  let originUrl = null;
+  try {
+    originUrl = parseRepoUrl(git(["remote", "get-url", "origin"], cwd).trim()).url;
+  } catch {
+    // no usable origin
+  }
+  const explicitUrl = url ? parseRepoUrl(url).url : null;
+  let matches;
+  if (project) matches = reg.json.projects.filter((p) => p.name === project);
+  else if (explicitUrl ?? originUrl) matches = reg.json.projects.filter((p) => p.url === (explicitUrl ?? originUrl));
+  else throw new Error("no origin remote; pass --url or --project");
+  if (matches.length === 0) throw new Error("project is not registered with this team; run techbro project link");
+  if (matches.length > 1) throw new Error("project matches more than one registered entry; pass --project <name>");
+  const entry = matches[0];
+  const { owner: po, repo: pr, url: purl } = parseRepoUrl(entry.url);
+  if (explicitUrl && explicitUrl !== purl) throw new Error(`--url ${explicitUrl} does not match registered project ${entry.name} (${purl})`);
+
+  const projRepo = await client.getRepo(po, pr);
+  if (!projRepo.permissions?.pull) throw new Error(`no read access to ${po}/${pr} as ${login}`);
+  if (po.toLowerCase() !== to.toLowerCase()) {
+    throw new Error(`${po}/${pr} is outside the team organization ${to}; the shared review workflow is same-organization only`);
+  }
+  const pb = projRepo.defaultBranch;
+  const blockers = [];
+  if (!projRepo.permissions?.push) blockers.push(`no write access to ${po}/${pr} as ${login}; reviews are dispatched from the project repo`);
+
+  let sha;
+  const local = !ref && originUrl === purl && (!explicitUrl || explicitUrl === originUrl);
+  if (local) {
+    sha = git(["rev-parse", "HEAD"], cwd).trim();
+    if (git(["status", "--porcelain"], cwd).trim()) warn("uncommitted changes are excluded; only the committed HEAD is reviewed");
+    if ((await client.getCommitSha(po, pr, sha)) === null) throw new Error(`commit ${sha.slice(0, 12)} is not on ${po}/${pr}; push it first`);
+  } else {
+    const r = ref ?? projRepo.defaultBranch;
+    sha = await client.getCommitSha(po, pr, r);
+    if (sha === null) throw new Error(`cannot resolve ref "${r}" in ${po}/${pr}`);
+  }
+  if (!/^[0-9a-f]{40}$/.test(sha)) throw new Error(`could not resolve an immutable commit sha (got "${sha}")`);
+
+  const params = { owner: to, repo: tr };
+  const caller = await client.getFileText(po, pr, REVIEW_WORKFLOW, pb);
+  if (caller === null) blockers.push(`${REVIEW_WORKFLOW} is not on ${pb} of ${po}/${pr}; run techbro project link and merge the caller PR`);
+  else if (classifyCaller(caller, params) !== "current") warn(`${REVIEW_WORKFLOW} in ${po}/${pr} differs from the managed caller; using it as is`);
+  for (const f of [REVIEW_WORKFLOW, ACTION]) {
+    if ((await client.getFileText(to, tr, f, tb)) === null) blockers.push(`${f} is not installed in ${to}/${tr}; run techbro team upgrade`);
+  }
+  const notes = ["Sonar token/host are optional repository secrets/variables in the project caller; not inspected (the remote gate decides)"];
+  if (teamRepo.private && client.getActionsAccess) {
+    try {
+      const level = await client.getActionsAccess(to, tr);
+      if (level === "none") blockers.push(`${to}/${tr} Actions access is "none"; a team admin must allow organization repositories to use its workflows and actions`);
+    } catch (err) {
+      notes.push(`could not verify Actions sharing on ${to}/${tr} (${err.message}); a team admin must enable organization access`);
+    }
+  }
+  if (!dryRun && blockers.length) throw new Error(blockers[0]);
+
+  const { missing, effective } = await inspectConfig(client, to, tr, tb, entry.name);
+  const workflowUrl = `https://github.com/${po}/${pr}/actions/workflows/${WF_FILE}`;
+  if (dryRun) {
+    missing.unshift(...blockers);
+    return { dryRun: true, ok: missing.length === 0, project: entry.name, sha, team: teamName, workflowUrl, effective, missing, notes };
+  }
+  for (const m of missing) warn(m);
+
+  const requestId = uuid();
+  await client.dispatchWorkflow(po, pr, WF_FILE, pb, { sha, request_id: requestId });
+  const base = { project: entry.name, sha, requestId, workflowUrl, team: teamName };
+
+  let run = null;
+  for (let i = 0; i < lookupAttempts && !run; i++) {
+    if (i) await sleep(lookupIntervalMs);
+    const runs = await client.listWorkflowRuns(po, pr, WF_FILE, { branch: pb });
+    run = runs.find((x) => typeof x.title === "string" && x.title.trim().split(/\s+/).pop() === requestId) ?? null;
+  }
+  if (!run) return { ...base, status: "dispatched", ok: !wait, runUrl: null, note: "run not found yet; check the workflow page (not redispatched)" };
+  if (!wait) return { ...base, status: "dispatched", ok: true, runUrl: run.url };
+
+  const deadline = Date.now() + waitTimeoutMs;
+  let cur = run;
+  while (cur.status !== "completed") {
+    if (Date.now() >= deadline) return { ...base, status: "timeout", ok: false, runUrl: run.url };
+    await sleep(waitIntervalMs);
+    cur = await client.getRun(po, pr, run.id);
+  }
+  let artifactUrl = null;
+  const art = (await client.listRunArtifacts(po, pr, run.id)).find((a) => a.name === REPORT_ARTIFACT && !a.expired);
+  if (art) artifactUrl = `https://github.com/${po}/${pr}/actions/runs/${run.id}/artifacts/${art.id}`;
+  const ok = cur.conclusion === "success";
+  return { ...base, status: ok ? "success" : "failure", ok, conclusion: cur.conclusion, runUrl: run.url, artifactUrl };
+}

package/src/secret.js

@@ -0,0 +1,80 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+export const PASSPHRASE_ENV = "TECHBRO_PASSPHRASE";
+const FORMAT = "techbro-secret-v1";
+const SCRYPT = { N: 1 << 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
+export const MIN_PASSPHRASE = 12;
+
+const deriveKey = (passphrase, salt) => scryptSync(String(passphrase).normalize("NFC"), salt, 32, SCRYPT);
+
+export function encryptSecret(plaintext, passphrase) {
+  if (!passphrase || String(passphrase).length < MIN_PASSPHRASE) throw new Error(`passphrase must be at least ${MIN_PASSPHRASE} characters`);
+  const salt = randomBytes(16);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", deriveKey(passphrase, salt), iv);
+  cipher.setAAD(Buffer.from(FORMAT));
+  const data = Buffer.concat([cipher.update(String(plaintext), "utf8"), cipher.final()]);
+  const b64 = (b) => b.toString("base64");
+  return JSON.stringify({ format: FORMAT, kdf: "scrypt", cipher: "aes-256-gcm", salt: b64(salt), iv: b64(iv), tag: b64(cipher.getAuthTag()), data: b64(data) }, null, 2) + "\n";
+}
+
+export function decryptSecret(envelope, passphrase) {
+  let e;
+  try {
+    e = typeof envelope === "string" ? JSON.parse(envelope) : envelope;
+  } catch {
+    throw new Error("encrypted secret is not valid JSON");
+  }
+  if (e?.format !== FORMAT) throw new Error("unsupported encrypted secret format");
+  if (!passphrase) throw new Error(`no passphrase: set ${PASSPHRASE_ENV} or pass --passphrase-file`);
+  try {
+    const d = createDecipheriv("aes-256-gcm", deriveKey(passphrase, Buffer.from(e.salt, "base64")), Buffer.from(e.iv, "base64"));
+    d.setAAD(Buffer.from(FORMAT));
+    d.setAuthTag(Buffer.from(e.tag, "base64"));
+    return Buffer.concat([d.update(Buffer.from(e.data, "base64")), d.final()]).toString("utf8");
+  } catch {
+    throw new Error("could not decrypt (wrong passphrase or modified file)");
+  }
+}
+
+// Order: --passphrase-file > TECHBRO_PASSPHRASE > hidden TTY prompt.
+export async function resolvePassphrase({ file, env = process.env, prompt = promptHidden, confirm = false } = {}) {
+  if (file) {
+    const p = readFileSync(file, "utf8").replace(/\r?\n$/, "");
+    if (!p) throw new Error(`passphrase file ${file} is empty`);
+    return p;
+  }
+  if (env[PASSPHRASE_ENV]) return env[PASSPHRASE_ENV];
+  if (!process.stdin.isTTY) throw new Error(`no passphrase: set ${PASSPHRASE_ENV} or pass --passphrase-file`);
+  const p = await prompt("Passphrase: ");
+  if (confirm && (await prompt("Repeat passphrase: ")) !== p) throw new Error("passphrases do not match");
+  return p;
+}
+
+function promptHidden(label) {
+  return new Promise((resolve, reject) => {
+    const { stdin, stderr } = process;
+    let buf = "";
+    stderr.write(label);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    const done = (err) => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off("data", onData);
+      stderr.write("\n");
+      err ? reject(err) : resolve(buf);
+    };
+    const onData = (chunk) => {
+      for (const ch of chunk) {
+        if (ch === "\r" || ch === "\n") return done();
+        if (ch === "\u0003") return done(Object.assign(new Error("cancelled"), { exitCode: 130 }));
+        if (ch === "\u007f" || ch === "\b") buf = buf.slice(0, -1);
+        else buf += ch;
+      }
+    };
+    stdin.on("data", onData);
+  });
+}

package/src/setup.js

@@ -0,0 +1,91 @@
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, statSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+export function defaultRun(cmd, args, opts = {}) {
+  execFileSync(cmd, args, { stdio: "inherit", ...opts });
+}
+
+export function defaultWhich(cmd) {
+  const exts = process.platform === "win32" ? [".exe", ".cmd", ".bat", ""] : [""];
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    for (const ext of exts) {
+      try {
+        if (statSync(join(dir, cmd + ext)).isFile()) return true;
+      } catch {
+        // keep looking
+      }
+    }
+  }
+  return false;
+}
+
+export function setupProject(
+  target,
+  { log = console.log, run = defaultRun, which = defaultWhich, skipBuild = false } = {},
+) {
+  const total = skipBuild ? 6 : 7;
+  let n = 0;
+  const step = (title, manual, fn) => {
+    n++;
+    log(`[${n}/${total}] ${title}`);
+    try {
+      fn();
+    } catch (err) {
+      throw new Error(
+        `setup step ${n}/${total} failed (${title.replace(/\.\.\.$/, "")}): ${err.message}\n` +
+          `  the scaffold is kept in ${target}; rerun manually: ${manual}`,
+        { cause: err },
+      );
+    }
+  };
+  const sh = (cmd, args, cwd = target) => run(cmd, args, { cwd });
+
+  step("Checking prerequisites...", "install node, npm and cargo (https://rustup.rs)", () => {
+    const missing = ["node", "npm", "cargo"].filter((c) => !which(c));
+    if (missing.length === 0) return;
+    const hint = missing.includes("cargo") ? " Install Rust from https://rustup.rs" : "";
+    throw new Error(`missing on PATH: ${missing.join(", ")}.${hint}`);
+  });
+
+  step("Creating .env files...", "cp .env.example .env", () => {
+    for (const dir of [".", "apps/frontend"]) {
+      const example = join(target, dir, ".env.example");
+      const env = join(target, dir, ".env");
+      if (existsSync(example) && !existsSync(env)) copyFileSync(example, env);
+    }
+  });
+
+  step("Installing frontend dependencies...", "cd apps/frontend && npm ci", () => {
+    const cwd = join(target, "apps/frontend");
+    sh("npm", [existsSync(join(cwd, "package-lock.json")) ? "ci" : "install"], cwd);
+  });
+
+  step("Fetching backend dependencies...", "cargo fetch --locked", () => {
+    sh("cargo", ["fetch", "--locked"]);
+  });
+
+  step(
+    "Installing tools (sqlx-cli, cargo-watch; slow the first time, can take minutes)...",
+    "cargo install sqlx-cli --locked --no-default-features --features sqlite,postgres && cargo install cargo-watch --locked",
+    () => {
+      if (which("sqlx")) log("  sqlx already installed");
+      else
+        sh("cargo", [
+          "install", "sqlx-cli", "--locked", "--no-default-features", "--features", "sqlite,postgres",
+        ]);
+      if (which("cargo-watch")) log("  cargo-watch already installed");
+      else sh("cargo", ["install", "cargo-watch", "--locked"]);
+    },
+  );
+
+  step("Creating the local database...", "scripts/db-migrate sqlite", () => {
+    sh("bash", ["scripts/db-migrate", "sqlite"]);
+  });
+
+  if (!skipBuild) {
+    step("Building the backend (a few minutes the first time)...", "cargo build -p backend", () => {
+      sh("cargo", ["build", "-p", "backend"]);
+    });
+  }
+}

package/src/team-workflow.js

@@ -0,0 +1,106 @@
+export function teamWorkflowYaml() {
+  return `name: techbro team
+
+on:
+  issues:
+    types: [opened, reopened]
+
+permissions:
+  contents: write
+  issues: write
+
+jobs:
+  join:
+    if: contains(github.event.issue.labels.*.name, 'techbro-join')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    env:
+      GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+      REPO: \${{ github.repository }}
+      NUM: \${{ github.event.issue.number }}
+      AUTHOR: \${{ github.event.issue.user.login }}
+      ISSUE_BODY: \${{ github.event.issue.body }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+      - name: Add member
+        shell: bash
+        run: |
+          reject() {
+            gh issue comment "$NUM" --repo "$REPO" --body "$1"
+            gh issue close "$NUM" --repo "$REPO"
+            exit 0
+          }
+          perm=$(gh api "repos/$REPO/collaborators/$AUTHOR/permission" --jq .permission 2>/dev/null || echo none)
+          case "$perm" in
+            read|triage|write|maintain|admin) ;;
+            *) reject "$AUTHOR is not a collaborator on this repository." ;;
+          esac
+          LOGIN=$(node -e 'try { const b = JSON.parse(process.env.ISSUE_BODY); if (b.action === "join" && typeof b.login === "string") process.stdout.write(b.login); } catch {}')
+          if [ -z "$LOGIN" ] || [ "$LOGIN" != "$AUTHOR" ]; then
+            reject "Invalid join request: login must match the issue author."
+          fi
+          LOGIN="$LOGIN" node -e 'const fs = require("fs"); const m = JSON.parse(fs.readFileSync("members.json", "utf8")); if (!m.members.includes(process.env.LOGIN)) m.members.push(process.env.LOGIN); fs.writeFileSync("members.json", JSON.stringify(m, null, 2) + "\\n");'
+          if git diff --quiet members.json; then
+            gh issue comment "$NUM" --repo "$REPO" --body "$LOGIN is already a member."
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git add members.json
+            git commit -m "techbro: add $LOGIN to team members"
+            if ! git push origin HEAD:main; then
+              gh issue comment "$NUM" --repo "$REPO" --body "main may be protected; add the member manually."
+              exit 1
+            fi
+            gh issue comment "$NUM" --repo "$REPO" --body "added $LOGIN to members.json"
+          fi
+          gh issue close "$NUM" --repo "$REPO"
+  link:
+    if: contains(github.event.issue.labels.*.name, 'techbro-link')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    env:
+      GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+      REPO: \${{ github.repository }}
+      NUM: \${{ github.event.issue.number }}
+      AUTHOR: \${{ github.event.issue.user.login }}
+      ISSUE_BODY: \${{ github.event.issue.body }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+      - name: Link project
+        shell: bash
+        run: |
+          reject() {
+            gh issue comment "$NUM" --repo "$REPO" --body "$1"
+            gh issue close "$NUM" --repo "$REPO"
+            exit 0
+          }
+          perm=$(gh api "repos/$REPO/collaborators/$AUTHOR/permission" --jq .permission 2>/dev/null || echo none)
+          case "$perm" in
+            read|triage|write|maintain|admin) ;;
+            *) reject "$AUTHOR is not a collaborator on this repository." ;;
+          esac
+          LOGIN=$(node -e 'try { const b = JSON.parse(process.env.ISSUE_BODY); if (b.action === "link" && typeof b.login === "string") process.stdout.write(b.login); } catch {}')
+          if [ -z "$LOGIN" ] || [ "$LOGIN" != "$AUTHOR" ]; then
+            reject "Invalid join request: login must match the issue author."
+          fi
+          NAME=$(LOGIN="$LOGIN" node -e 'const fs = require("fs"); const p = JSON.parse(process.env.ISSUE_BODY).project; const m = JSON.parse(fs.readFileSync("projects.json", "utf8")); if (p && typeof p.url === "string" && typeof p.name === "string" && !m.projects.some((x) => x.url === p.url)) { m.projects.push(p); fs.writeFileSync("projects.json", JSON.stringify(m, null, 2) + "\\n"); process.stdout.write(p.name); }')
+          if git diff --quiet projects.json; then
+            gh issue comment "$NUM" --repo "$REPO" --body "project is already linked."
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git add projects.json
+            git commit -m "techbro: link project $NAME"
+            if ! git push origin HEAD:main; then
+              gh issue comment "$NUM" --repo "$REPO" --body "main may be protected; add the project manually."
+              exit 1
+            fi
+            gh issue comment "$NUM" --repo "$REPO" --body "linked $NAME to projects.json"
+          fi
+          gh issue close "$NUM" --repo "$REPO"
+`;
+}

package/src/team.js

@@ -0,0 +1,145 @@
+import { parseRepoUrl } from "./github.js";
+import { teamWorkflowYaml } from "./team-workflow.js";
+import { REVIEW_WORKFLOW, managedFiles } from "./managed.js";
+
+const WORKFLOW = ".github/workflows/techbro-team.yml";
+
+const BRANCH = "main";
+const HINT =
+  "main may be protected, or the token lacks permission to write .github/workflows (classic `workflow` scope / fine-grained Workflows: write, and Actions workflow permissions); allow the token or open a PR manually";
+
+export async function createTeam({ name, url, config, client, now = new Date(), force = false }) {
+  if (!/^[a-z0-9-]+$/.test(name ?? "")) throw new Error(`invalid team name "${name}" (use lowercase letters, digits, and hyphens)`);
+  if (config.teams[name] && !force) throw new Error(`team "${name}" already exists (use --force to overwrite)`);
+  const { owner: o, repo: r, url: normalized } = parseRepoUrl(url);
+  const { login } = await client.getUser();
+  const repo = await client.getRepo(o, r);
+  if (!repo.permissions?.push) throw new Error(`no write access to ${o}/${r} as ${login}`);
+
+  const put = async (path, args) => {
+    try {
+      await client.putFile(o, r, path, { ...args, 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;
+    }
+  };
+  const json = (v) => JSON.stringify(v, null, 2) + "\n";
+  const created = [];
+  const updated = [];
+
+  const members = await client.getFile(o, r, "members.json", BRANCH);
+  let owner = login;
+  let count = 1;
+  if (!members) {
+    await put("members.json", {
+      content: json({ schemaVersion: 1, team: name, owner: login, members: [login] }),
+      message: "techbro: initialize team members",
+    });
+    created.push("members.json");
+  } else {
+    const m = members.json;
+    if (!m || typeof m !== "object" || !Array.isArray(m.members) || typeof m.owner !== "string") {
+      throw new Error(`members.json in ${o}/${r} is malformed`);
+    }
+    owner = m.owner;
+    count = m.members.length;
+    if (!m.members.includes(login)) {
+      m.members.push(login);
+      count = m.members.length;
+      await put("members.json", { content: json(m), message: `techbro: add ${login} to team members`, sha: members.sha });
+      updated.push("members.json");
+    }
+  }
+
+  if (!(await client.getFile(o, r, "projects.json", BRANCH))) {
+    await put("projects.json", {
+      content: json({ schemaVersion: 1, projects: [] }),
+      message: "techbro: initialize team projects",
+    });
+    created.push("projects.json");
+  }
+
+  if ((await client.getFileText(o, r, WORKFLOW, BRANCH)) === null) {
+    await put(WORKFLOW, { content: teamWorkflowYaml(), message: "techbro: add team workflow" });
+    created.push(WORKFLOW);
+  }
+
+  const files = managedFiles({ owner: o, repo: r });
+  const ordered = [...files.filter((f) => f.path !== REVIEW_WORKFLOW), ...files.filter((f) => f.path === REVIEW_WORKFLOW)];
+  for (const f of ordered) {
+    if ((await client.getFileText(o, r, f.path, BRANCH)) === null) {
+      await put(f.path, { content: f.content, message: `techbro: add ${f.path}` });
+      created.push(f.path);
+    }
+  }
+
+  config.teams[name] = { url: normalized, owner, addedAt: now.toISOString() };
+  config.currentTeam = name;
+  return { name, repo: `${o}/${r}`, owner, members: count, created, updated };
+}
+
+export async function joinTeam({ name, url, config, client, now = new Date(), force = false }) {
+  if (!/^[a-z0-9-]+$/.test(name ?? "")) throw new Error(`invalid team name "${name}" (use lowercase letters, digits, and hyphens)`);
+  if (config.teams[name] && !force) throw new Error(`team "${name}" already exists (use --force to overwrite)`);
+  const { owner: o, repo: r, url: normalized } = parseRepoUrl(url);
+  const { login } = await client.getUser();
+  const repo = await client.getRepo(o, r);
+  if (!repo.permissions?.pull) throw new Error(`no read access to ${o}/${r} as ${login}`);
+
+  const file = await client.getFile(o, r, "members.json", BRANCH);
+  if (!file) throw new Error("team repo is not initialized; run team create");
+  const m = structuredClone(file.json);
+  if (!m || typeof m !== "object" || !Array.isArray(m.members) || typeof m.owner !== "string") {
+    throw new Error(`members.json in ${o}/${r} is malformed`);
+  }
+
+  let status = "member";
+  let issueUrl;
+  if (!m.members.includes(login)) {
+    if (repo.permissions.push) {
+      m.members.push(login);
+      try {
+        await client.putFile(o, r, "members.json", {
+          content: JSON.stringify(m, null, 2) + "\n",
+          message: `techbro: add ${login} to team members`,
+          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 (!repo.hasIssues) throw new Error(`issues are disabled on ${o}/${r}; ask the owner to enable them or add you manually`);
+      const open = await client.listIssues(o, r, { labels: "techbro-join", state: "open", creator: login });
+      issueUrl = open[0]?.url;
+      if (!issueUrl) {
+        issueUrl = (
+          await client.createIssue(o, r, {
+            title: "techbro: join request",
+            body: JSON.stringify({ schemaVersion: 1, action: "join", login }),
+            labels: ["techbro-join"],
+          })
+        ).url;
+      }
+      status = "pending";
+    }
+  }
+
+  config.teams[name] = { url: normalized, owner: m.owner, addedAt: now.toISOString() };
+  config.currentTeam = name;
+  return { name, repo: `${o}/${r}`, login, status, ...(issueUrl && { issueUrl }) };
+}
+
+export function listTeams(config) {
+  return Object.entries(config.teams).map(([name, t]) => ({ name, url: t.url, owner: t.owner, current: config.currentTeam === name }));
+}
+
+export function useTeam(config, name) {
+  if (!config.teams[name]) throw new Error(`unknown team "${name}"`);
+  config.currentTeam = name;
+}

package/src/templates.js

@@ -0,0 +1,44 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export function templatesDir() {
+  const bundled = join(packageRoot, "templates");
+  if (existsSync(bundled)) return bundled;
+  const dev = resolve(packageRoot, ".project_templates");
+  if (existsSync(dev)) return dev;
+  throw new Error("no templates found (expected ./templates or ./.project_templates)");
+}
+
+export function listTemplates() {
+  const dir = templatesDir();
+  return readdirSync(dir)
+    .filter((n) => statSync(join(dir, n)).isDirectory())
+    .sort();
+}
+
+export function templatePath(name) {
+  const available = listTemplates();
+  const hint = `available templates: ${available.join(", ") || "(none)"}`;
+  if (!name) throw new Error(`missing template name; ${hint}`);
+  if (name.includes("/") || name.includes("\\") || name.includes("..")) {
+    throw new Error(`invalid template name "${name}"; ${hint}`);
+  }
+  if (!available.includes(name)) {
+    throw new Error(`unknown template "${name}"; ${hint}`);
+  }
+  return join(templatesDir(), name);
+}
+
+export function describeTemplate(name) {
+  const dir = templatePath(name);
+  for (const file of ["TEMPLATE.md", "README.md"]) {
+    const p = join(dir, file);
+    if (!existsSync(p)) continue;
+    const m = readFileSync(p, "utf8").match(/^# (.+)$/m);
+    if (m) return m[1].trim();
+  }
+  return "";
+}