techbro 0.0.0-stage → 0.5.0

package/src/cluster.js

@@ -0,0 +1,134 @@
+// Team-shared clusters: the team owner publishes a cluster profile plus an
+// encrypted, minified kubeconfig to the team repo; members decrypt it locally.
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { configPath } from "./config.js";
+import { parseRepoUrl } from "./github.js";
+import { defaultRun, validateName, validateProfile } from "./kube.js";
+import { decryptSecret, encryptSecret } from "./secret.js";
+
+const BRANCH = "main";
+const DIR = "clusters";
+const profilePath = (name) => `${DIR}/${name}.json`;
+const credPath = (name) => `${DIR}/${name}.kubeconfig.enc`;
+export const kubeconfigDir = () => join(dirname(configPath()), "kube");
+export const kubeconfigFile = (name) => join(kubeconfigDir(), `${name}.kubeconfig`);
+
+function teamRepo(config, teamName) {
+  const name = teamName ?? config.currentTeam;
+  if (!name) throw new Error("no current team: run techbro team create|join first, or pass --team");
+  const team = config.teams?.[name];
+  if (!team) throw new Error(`unknown team "${name}"`);
+  return { team: name, ...parseRepoUrl(team.url) };
+}
+
+async function requireOwner(client, o, r) {
+  const { login } = await client.getUser();
+  const members = await client.getFile(o, r, "members.json", BRANCH);
+  if (!members) throw new Error("team repo is not initialized; run team create");
+  if (members.json?.owner !== login) throw new Error(`only the team owner (${members.json?.owner}) can change shared clusters; you are ${login}`);
+  const repo = await client.getRepo(o, r);
+  if (!repo.permissions?.push) throw new Error(`no write access to ${o}/${r} as ${login}`);
+  return login;
+}
+
+// Extracts only the named context, with certificates inlined, so the owner's other contexts never leave their machine.
+export async function exportKubeconfig({ kubeconfig, context, run = defaultRun }) {
+  const res = await run("kubectl", ["config", "view", "--kubeconfig", kubeconfig, "--context", context, "--minify", "--flatten", "-o", "json"], { timeout: 15000 });
+  if (res.code !== 0) throw new Error(`could not read context ${context} from ${kubeconfig} (kubectl exit ${res.code})`);
+  let kc;
+  try {
+    kc = JSON.parse(String(res.stdout));
+  } catch {
+    throw new Error("kubectl config view did not return JSON");
+  }
+  if (kc?.contexts?.length !== 1 || kc.contexts[0].name !== context) throw new Error(`kubeconfig does not contain exactly the context ${context}`);
+  const user = kc.users?.[0]?.user ?? {};
+  const warnings = [];
+  if (user.exec || user["auth-provider"]) warnings.push("this context authenticates through an external plugin; members also need that plugin and its own login");
+  return { text: JSON.stringify(kc), namespace: kc.contexts[0].context?.namespace || null, warnings };
+}
+
+export async function addSharedCluster({ config, client, name, kubeconfig, context, namespace, profile = {}, passphrase, teamName, force = false, dryRun = false, now = new Date(), run = defaultRun }) {
+  validateName(name, "cluster name");
+  const { team, owner: o, repo: r } = teamRepo(config, teamName);
+  const login = await requireOwner(client, o, r);
+  const exported = await exportKubeconfig({ kubeconfig, context, run });
+  const clean = validateProfile({ ...profile, context, ...((namespace ?? exported.namespace) && { namespace: namespace ?? exported.namespace }) });
+  const existing = await client.getFile(o, r, profilePath(name), BRANCH);
+  if (existing && !force) throw new Error(`shared cluster "${name}" already exists in ${o}/${r} (use --force to replace or rotate)`);
+  const files = [profilePath(name), credPath(name)];
+  const summary = { team, repo: `${o}/${r}`, name, context, namespace: clean.namespace ?? null, files, warnings: exported.warnings, replaced: Boolean(existing) };
+  if (dryRun) return { ...summary, dryRun: true };
+  const envelope = encryptSecret(exported.text, passphrase);
+  const doc = { schemaVersion: 1, name, profile: clean, credential: credPath(name), updatedBy: login, updatedAt: now.toISOString() };
+  const cred = await client.getFile(o, r, credPath(name), BRANCH);
+  await client.putFile(o, r, credPath(name), { content: envelope, message: `techbro: ${existing ? "rotate" : "add"} cluster ${name} credential`, sha: cred?.sha, branch: BRANCH });
+  await client.putFile(o, r, profilePath(name), { content: JSON.stringify(doc, null, 2) + "\n", message: `techbro: ${existing ? "update" : "add"} cluster ${name}`, sha: existing?.sha, branch: BRANCH });
+  return { ...summary, dryRun: false };
+}
+
+export async function listSharedClusters({ config, client, teamName }) {
+  const { team, owner: o, repo: r } = teamRepo(config, teamName);
+  const entries = await client.listDir(o, r, DIR, BRANCH);
+  const names = entries.filter((e) => e.type === "file" && /^[a-z0-9-]+\.json$/.test(e.name)).map((e) => e.name.slice(0, -5));
+  const local = config.kube?.shared ?? {};
+  return { team, repo: `${o}/${r}`, clusters: names.map((name) => ({ name, installed: local[name]?.team === team })) };
+}
+
+function writePrivate(path, content) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, content, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, path);
+}
+
+// Returns a new config with the shared cluster installed and selected.
+export async function useSharedCluster({ config, client, name, passphrase, teamName, now = new Date() }) {
+  validateName(name, "cluster name");
+  if (config.kube?.clusters?.[name]) throw new Error(`a local cluster named "${name}" already exists; remove it from your config first`);
+  const { team, owner: o, repo: r } = teamRepo(config, teamName);
+  const doc = await client.getFile(o, r, profilePath(name), BRANCH);
+  if (!doc) throw new Error(`no shared cluster "${name}" in ${o}/${r}`);
+  if (doc.json?.schemaVersion !== 1 || doc.json.credential !== credPath(name)) throw new Error(`${profilePath(name)} in ${o}/${r} is malformed`);
+  const profile = validateProfile(doc.json.profile);
+  const enc = await client.getFile(o, r, credPath(name), BRANCH);
+  if (!enc) throw new Error(`credential ${credPath(name)} is missing in ${o}/${r}`);
+  const text = decryptSecret(enc.json, passphrase);
+  const kubeconfig = kubeconfigFile(name);
+  writePrivate(kubeconfig, text);
+  const kube = config.kube ?? {};
+  const next = {
+    ...config,
+    kube: { ...kube, current: name, shared: { ...(kube.shared ?? {}), [name]: { team, profile, kubeconfig, installedAt: now.toISOString() } } },
+  };
+  return { config: next, team, repo: `${o}/${r}`, name, context: profile.context, namespace: profile.namespace ?? null, kubeconfig };
+}
+
+export async function removeSharedCluster({ config, client, name, teamName }) {
+  validateName(name, "cluster name");
+  const { team, owner: o, repo: r } = teamRepo(config, teamName);
+  await requireOwner(client, o, r);
+  const removed = [];
+  for (const p of [credPath(name), profilePath(name)]) {
+    const f = await client.getFile(o, r, p, BRANCH);
+    if (f) {
+      await client.deleteFile(o, r, p, { message: `techbro: remove cluster ${name}`, sha: f.sha, branch: BRANCH });
+      removed.push(p);
+    }
+  }
+  if (!removed.length) throw new Error(`no shared cluster "${name}" in ${o}/${r}`);
+  return { team, repo: `${o}/${r}`, removed, config: forgetSharedCluster(config, name) };
+}
+
+// Drops the local install (config entry + decrypted kubeconfig) only.
+export function forgetSharedCluster(config, name) {
+  const shared = { ...(config.kube?.shared ?? {}) };
+  if (!shared[name]) return config;
+  rmSync(shared[name].kubeconfig, { force: true });
+  delete shared[name];
+  const kube = { ...config.kube, shared };
+  if (kube.current === name) kube.current = null;
+  return { ...config, kube };
+}

package/src/config.js

@@ -0,0 +1,35 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const configPath = () =>
+  join(process.env.TECHBRO_CONFIG_DIR ?? join(homedir(), ".config", "techbro"), "config.json");
+
+export function loadConfig() {
+  const path = configPath();
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return { schemaVersion: 1, currentTeam: null, teams: {} };
+    throw err;
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(raw);
+  } catch {
+    throw new Error(`malformed config file ${path}: not valid JSON`);
+  }
+  if (!cfg || typeof cfg !== "object" || Array.isArray(cfg) || typeof cfg.teams !== "object" || cfg.teams === null) {
+    throw new Error(`malformed config file ${path}: unexpected shape`);
+  }
+  return cfg;
+}
+
+export function saveConfig(cfg) {
+  const path = configPath();
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n");
+  renameSync(tmp, path);
+}

package/src/doctor.js

@@ -0,0 +1,125 @@
+// Read-only health check of local setup. Never prints secret values.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { loadConfig } from "./config.js";
+import { listClusters, defaultRun, preflight, resolveCluster } from "./kube.js";
+import { SECRET_NAME } from "./kube-project.js";
+import { REVIEW_WORKFLOW } from "./managed.js";
+import { parseRepoUrl } from "./github.js";
+import { MIN_PASSPHRASE, PASSPHRASE_ENV } from "./secret.js";
+
+const ok = (area, name, detail = "") => ({ area, name, status: "ok", detail });
+const warn = (area, name, detail, fix) => ({ area, name, status: "warn", detail, fix });
+const fail = (area, name, detail, fix) => ({ area, name, status: "fail", detail, fix });
+
+async function tool(run, file, args) {
+  try {
+    const r = await run(file, args, { timeout: 10000 });
+    return r.code === 0 ? String(r.stdout ?? "").trim().split("\n")[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function doctor({ env = process.env, cwd = process.cwd(), run = defaultRun, load = loadConfig, online = false, client, nodeVersion = process.versions.node } = {}) {
+  const checks = [];
+  const add = (c) => checks.push(c);
+
+  const major = Number(nodeVersion.split(".")[0]);
+  add(major >= 20 ? ok("env", "node", nodeVersion) : fail("env", "node", `${nodeVersion} is older than 20`, "install Node 20 or newer"));
+  const git = await tool(run, "git", ["--version"]);
+  add(git ? ok("env", "git", git) : fail("env", "git", "not found", "install git"));
+  const kubectl = await tool(run, "kubectl", ["version", "--client"]);
+  add(kubectl ? ok("env", "kubectl", kubectl) : warn("env", "kubectl", "not found; kube and cluster commands need it", "install kubectl"));
+  const gh = env.GITHUB_TOKEN ? "GITHUB_TOKEN is set" : (await tool(run, "gh", ["auth", "token"])) ? "gh is logged in" : null;
+  add(gh ? ok("secrets", "github token", gh) : fail("secrets", "github token", "missing; team, project and cluster commands need it", "gh auth login (or set GITHUB_TOKEN)"));
+
+  const pass = env[PASSPHRASE_ENV];
+  if (!pass) add(warn("secrets", PASSPHRASE_ENV, "not set; cluster add/use will prompt or need --passphrase-file", `export ${PASSPHRASE_ENV}=... (ask your team owner)`));
+  else if (pass.length < MIN_PASSPHRASE) add(fail("secrets", PASSPHRASE_ENV, `set but shorter than ${MIN_PASSPHRASE} characters`, "use the team passphrase"));
+  else add(ok("secrets", PASSPHRASE_ENV, "set"));
+
+  let config = null;
+  try {
+    config = load();
+    add(ok("config", "config file", "parsed"));
+  } catch (e) {
+    add(fail("config", "config file", e.message, "fix or remove the techbro config file"));
+  }
+
+  let team = null;
+  if (config) {
+    const name = config.currentTeam;
+    if (!name) add(warn("config", "team", "no current team", "techbro team join <name> --url <repo>"));
+    else if (!config.teams?.[name]) add(fail("config", "team", `current team "${name}" is not configured`, "techbro team use <name>"));
+    else {
+      team = { name, ...config.teams[name] };
+      add(ok("config", "team", `${name} (${team.url})`));
+    }
+
+    let clusters = null;
+    try {
+      clusters = listClusters(config);
+    } catch (e) {
+      add(fail("cluster", "cluster config", e.message, "fix config.kube in the techbro config file"));
+    }
+    if (clusters) {
+      const cur = clusters.current;
+      if (!cur) add(warn("cluster", "current cluster", "none selected; kube commands need one", "techbro cluster use <name> (or techbro kube cluster add/use)"));
+      else add(clusters.clusters.some((c) => c.name === cur) ? ok("cluster", "current cluster", cur) : fail("cluster", "current cluster", `"${cur}" is not configured`, "techbro cluster use <name>"));
+    }
+    for (const [name, s] of Object.entries(config.kube?.shared ?? {})) {
+      const label = `cluster ${name} kubeconfig`;
+      if (!s?.kubeconfig || !existsSync(s.kubeconfig)) {
+        add(fail("cluster", label, "missing", `techbro cluster use ${name}`));
+        continue;
+      }
+      const mode = statSync(s.kubeconfig).mode & 0o777;
+      if (mode & 0o077) add(fail("cluster", label, `permissions ${mode.toString(8)} allow other users to read credentials`, `chmod 600 ${s.kubeconfig}`));
+      else add(ok("cluster", label, "present, mode 600"));
+    }
+  }
+
+  const metaPath = join(cwd, ".techbro.json");
+  if (existsSync(metaPath)) {
+    try {
+      JSON.parse(readFileSync(metaPath, "utf8"));
+      add(ok("project", ".techbro.json", "parsed"));
+    } catch {
+      add(fail("project", ".techbro.json", "not valid JSON", "fix .techbro.json"));
+    }
+    add(existsSync(join(cwd, REVIEW_WORKFLOW)) ? ok("project", "review workflow", REVIEW_WORKFLOW) : warn("project", "review workflow", `${REVIEW_WORKFLOW} missing`, "techbro project link"));
+  }
+  const tracked = await run("git", ["-C", cwd, "ls-files", "-z"], { timeout: 10000 }).catch(() => null);
+  if (tracked?.code === 0) {
+    const bad = String(tracked.stdout).split("\0").filter((f) => f && SECRET_NAME.test(f) && !/(^|\/)\.env\.example$/.test(f));
+    add(bad.length ? fail("project", "tracked secrets", `${bad.length} secret-like file(s): ${bad.slice(0, 5).join(", ")}`, "git rm --cached <file> and rotate the secret") : ok("project", "tracked secrets", "none"));
+  }
+
+  if (online) {
+    if (client && gh) {
+      try {
+        const { login } = await client.getUser();
+        add(ok("online", "github login", login));
+        if (team) {
+          const { owner, repo } = parseRepoUrl(team.url);
+          const r = await client.getRepo(owner, repo);
+          add(r.permissions?.pull ? ok("online", "team repo", `${owner}/${repo}${r.permissions.push ? " (write)" : " (read)"}`) : fail("online", "team repo", "no read access", "ask the team owner for access"));
+        }
+      } catch (e) {
+        add(fail("online", "github", e.message, "check your token and network"));
+      }
+    }
+    if (config && kubectl && config.kube?.current) {
+      try {
+        const profile = await resolveCluster({ config, run });
+        const r = await preflight({ profile, run });
+        for (const c of r.checks) add(c.ok ? ok("online", `kube ${c.name}`, profile.name) : fail("online", `kube ${c.name}`, c.detail, `techbro kube check --cluster ${profile.name}`));
+      } catch (e) {
+        add(fail("online", "kube", e.message, "techbro cluster use <name> or pass --namespace via kube check"));
+      }
+    }
+  }
+
+  return { ok: checks.every((c) => c.status !== "fail"), checks };
+}

package/src/github.js

@@ -0,0 +1,152 @@
+import { execFileSync } from "node:child_process";
+
+export function parseRepoUrl(url) {
+  const m =
+    /^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec(String(url).trim()) ??
+    /^git@github\.com:([\w.-]+)\/([\w.-]+?)(?:\.git)?$/.exec(String(url).trim());
+  if (!m) throw new Error(`not a GitHub repository URL: "${url}" (expected https://github.com/<owner>/<repo>)`);
+  return { owner: m[1], repo: m[2], url: `https://github.com/${m[1]}/${m[2]}` };
+}
+
+export function resolveToken() {
+  if (process.env.GITHUB_TOKEN) return process.env.GITHUB_TOKEN;
+  try {
+    const t = execFileSync("gh", ["auth", "token"], { stdio: "pipe", encoding: "utf8" }).trim();
+    if (t) return t;
+  } catch {
+    // fall through
+  }
+  throw new Error("no GitHub token: set GITHUB_TOKEN or run gh auth login");
+}
+
+export function createClient({ token, fetch: f = globalThis.fetch }) {
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+    "User-Agent": "techbro",
+  };
+  async function call(method, path, body, { allow404 = false, raw = false } = {}) {
+    const h = { ...headers };
+    if (raw) h.Accept = "application/vnd.github.raw+json";
+    if (body) h["Content-Type"] = "application/json";
+    const res = await f(`https://api.github.com${path}`, { method, headers: h, body: body ? JSON.stringify(body) : undefined });
+    if (allow404 && res.status === 404) return null;
+    if (raw && res.ok) return res.text();
+    if (res.status === 204) return {};
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw Object.assign(new Error(`GitHub ${res.status}: ${data.message ?? "request failed"}`), { status: res.status });
+    }
+    return data;
+  }
+  const repoPath = (o, r) => `/repos/${o}/${r}`;
+  const filePath = (o, r, p) => `${repoPath(o, r)}/contents/${p.split("/").map(encodeURIComponent).join("/")}`;
+  return {
+    async getUser() {
+      return { login: (await call("GET", "/user")).login };
+    },
+    async getRepo(o, r) {
+      const d = await call("GET", repoPath(o, r));
+      return {
+        defaultBranch: d.default_branch,
+        hasIssues: d.has_issues,
+        private: d.private === true,
+        permissions: d.permissions ?? {},
+      };
+    },
+    async listIssues(o, r, { labels, state = "open", creator } = {}) {
+      const q = new URLSearchParams({ state });
+      if (labels) q.set("labels", labels);
+      if (creator) q.set("creator", creator);
+      const d = await call("GET", `${repoPath(o, r)}/issues?${q}`);
+      return d.filter((i) => !i.pull_request).map((i) => ({ number: i.number, url: i.html_url }));
+    },
+    async createIssue(o, r, { title, body, labels }) {
+      const d = await call("POST", `${repoPath(o, r)}/issues`, { title, body, labels });
+      return { number: d.number, url: d.html_url };
+    },
+    async getFile(o, r, path, ref) {
+      const d = await call("GET", `${filePath(o, r, path)}?ref=${encodeURIComponent(ref)}`, undefined, { allow404: true });
+      if (!d) return null;
+      let json;
+      try {
+        json = JSON.parse(Buffer.from(d.content ?? "", "base64").toString("utf8"));
+      } catch {
+        throw new Error(`${path} in ${o}/${r} is not valid JSON`);
+      }
+      return { sha: d.sha, json };
+    },
+    async getFileText(o, r, path, ref) {
+      return call("GET", `${filePath(o, r, path)}?ref=${encodeURIComponent(ref)}`, undefined, { allow404: true, raw: true });
+    },
+    async getBranchSha(o, r, branch) {
+      const d = await call("GET", `${repoPath(o, r)}/git/ref/heads/${branch.split("/").map(encodeURIComponent).join("/")}`, undefined, { allow404: true });
+      return d ? d.object.sha : null;
+    },
+    async getCommitSha(o, r, ref) {
+      const d = await call("GET", `${repoPath(o, r)}/commits/${encodeURIComponent(ref)}`, undefined, { allow404: true });
+      return d ? d.sha : null;
+    },
+    async createRef(o, r, branch, sha) {
+      await call("POST", `${repoPath(o, r)}/git/refs`, { ref: `refs/heads/${branch}`, sha });
+    },
+    async updateRef(o, r, branch, sha) {
+      await call("PATCH", `${repoPath(o, r)}/git/refs/heads/${branch.split("/").map(encodeURIComponent).join("/")}`, { sha, force: false });
+    },
+    async commitFiles(o, r, { baseSha, files, message }) {
+      const base = await call("GET", `${repoPath(o, r)}/git/commits/${baseSha}`);
+      const tree = [];
+      for (const file of files) {
+        const blob = await call("POST", `${repoPath(o, r)}/git/blobs`, { content: file.content, encoding: "utf-8" });
+        tree.push({ path: file.path, mode: "100644", type: "blob", sha: blob.sha });
+      }
+      const t = await call("POST", `${repoPath(o, r)}/git/trees`, { base_tree: base.tree.sha, tree });
+      const c = await call("POST", `${repoPath(o, r)}/git/commits`, { message, tree: t.sha, parents: [baseSha] });
+      return c.sha;
+    },
+    async listPulls(o, r, { head, base }) {
+      const q = new URLSearchParams({ state: "open", head: `${o}:${head}`, base });
+      const d = await call("GET", `${repoPath(o, r)}/pulls?${q}`);
+      return d.map((p) => ({ number: p.number, url: p.html_url }));
+    },
+    async createPull(o, r, { title, body, head, base }) {
+      const d = await call("POST", `${repoPath(o, r)}/pulls`, { title, body, head, base });
+      return { number: d.number, url: d.html_url };
+    },
+    async dispatchWorkflow(o, r, file, ref, inputs) {
+      await call("POST", `${repoPath(o, r)}/actions/workflows/${encodeURIComponent(file)}/dispatches`, { ref, inputs });
+    },
+    async listWorkflowRuns(o, r, file, { branch }) {
+      const q = new URLSearchParams({ event: "workflow_dispatch", branch, per_page: "30" });
+      const d = await call("GET", `${repoPath(o, r)}/actions/workflows/${encodeURIComponent(file)}/runs?${q}`);
+      return (d.workflow_runs ?? []).map((x) => ({ id: x.id, url: x.html_url, title: x.display_title, status: x.status, conclusion: x.conclusion }));
+    },
+    async getRun(o, r, id) {
+      const x = await call("GET", `${repoPath(o, r)}/actions/runs/${id}`);
+      return { id: x.id, url: x.html_url, status: x.status, conclusion: x.conclusion };
+    },
+    async listRunArtifacts(o, r, id) {
+      const d = await call("GET", `${repoPath(o, r)}/actions/runs/${id}/artifacts`);
+      return (d.artifacts ?? []).map((a) => ({ id: a.id, name: a.name, expired: a.expired }));
+    },
+    async getActionsAccess(o, r) {
+      const d = await call("GET", `${repoPath(o, r)}/actions/permissions/access`, undefined, { allow404: true });
+      return d ? d.access_level : null;
+    },
+    async putFile(o, r, path, { content, message, sha, branch }) {
+      const body = { message, content: Buffer.from(content).toString("base64"), branch };
+      if (sha) body.sha = sha;
+      await call("PUT", filePath(o, r, path), body);
+    },
+    async listDir(o, r, path, ref) {
+      const d = await call("GET", `${filePath(o, r, path)}?ref=${encodeURIComponent(ref)}`, undefined, { allow404: true });
+      if (!d) return [];
+      if (!Array.isArray(d)) throw new Error(`${path} in ${o}/${r} is not a directory`);
+      return d.map((e) => ({ name: e.name, path: e.path, type: e.type, sha: e.sha }));
+    },
+    async deleteFile(o, r, path, { message, sha, branch }) {
+      await call("DELETE", filePath(o, r, path), { message, sha, branch });
+    },
+  };
+}

package/src/init.js

@@ -0,0 +1,167 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { execFileSync } from "node:child_process";
+import { basename, join, relative, resolve } from "node:path";
+import { packageRoot, templatePath } from "./templates.js";
+
+const EXCLUDED_NAMES = new Set([
+  "node_modules",
+  "target",
+  "dist",
+  ".env",
+  "local.db",
+  ".DS_Store",
+  "coverage",
+]);
+
+export function isExcluded(name) {
+  return EXCLUDED_NAMES.has(name) || name.endsWith(".db") || name.endsWith(".sqlite");
+}
+
+export function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "app";
+}
+
+const RENAMES = { _gitignore: ".gitignore", _dockerignore: ".dockerignore" };
+
+function walk(dir, fn) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) walk(p, fn);
+    else fn(p, entry.name);
+  }
+}
+
+function edit(file, fn) {
+  if (!existsSync(file)) return;
+  const before = readFileSync(file, "utf8");
+  const after = fn(before);
+  if (after !== before) writeFileSync(file, after);
+}
+
+/**
+ * Runs `git init -b main` in `target` unless it is already inside a repository.
+ * @returns {"initialized" | "existing" | "skipped"} outcome; "skipped" when git is unavailable
+ */
+export function initGit(target) {
+  const run = (args, opts = {}) =>
+    execFileSync("git", args, { cwd: target, stdio: ["ignore", "pipe", "ignore"], ...opts });
+  try {
+    run(["--version"]);
+  } catch {
+    return "skipped";
+  }
+  try {
+    if (run(["rev-parse", "--is-inside-work-tree"]).toString().trim() === "true") return "existing";
+  } catch {
+    // not a repository yet
+  }
+  run(["init", "-q", "-b", "main"]);
+  return "initialized";
+}
+
+export function initProject({ template = "_default", dir, name, force = false, git = true }) {
+  const src = templatePath(template);
+  const target = resolve(dir ?? ".");
+
+  if (existsSync(target)) {
+    if (!statSync(target).isDirectory()) throw new Error(`${target} is not a directory`);
+    if (readdirSync(target).length > 0 && !force) {
+      throw new Error("directory is not empty (use --force to overwrite)");
+    }
+  }
+  const metadataPath = join(target, ".techbro.json");
+  const hasMetadata = existsSync(metadataPath);
+  if (hasMetadata) {
+    try {
+      const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+      if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+        throw new Error("expected a JSON object");
+      }
+    } catch (err) {
+      throw new Error(`invalid .techbro.json: ${err.message}`, { cause: err });
+    }
+  }
+  mkdirSync(target, { recursive: true });
+
+  cpSync(src, target, {
+    recursive: true,
+    force: true,
+    preserveTimestamps: true,
+    filter: (s) => s !== join(src, ".techbro.json") && !isExcluded(basename(s)),
+  });
+
+  let count = 0;
+  walk(target, (p, base) => {
+    count++;
+    if (RENAMES[base]) renameSync(p, join(p, "..", RENAMES[base]));
+  });
+
+  const appName = slugify(name ?? basename(target));
+  if (!hasMetadata) {
+    const techbroVersion = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")).version;
+    writeFileSync(metadataPath, JSON.stringify({
+      schemaVersion: 1,
+      name: appName,
+      template,
+      techbroVersion,
+      config: {},
+    }, null, 2) + "\n");
+    count++;
+  }
+  edit(join(target, "package.json"), (t) =>
+    t.replace(/("name"\s*:\s*)"project-template"/, `$1"${appName}"`),
+  );
+  edit(join(target, ".env.example"), (t) => t.replace(/^APP_NAME=my-app$/m, `APP_NAME=${appName}`));
+  edit(join(target, "apps/frontend/.env.example"), (t) =>
+    t.replace(/^VITE_APP_NAME=.*$/m, `VITE_APP_NAME=${appName}`),
+  );
+
+  const gitStatus = git ? initGit(target) : "disabled";
+  return { template, target, appName, files: count, git: gitStatus };
+}
+
+const GIT_LINES = {
+  initialized: "Git:       initialized (branch main)",
+  existing: "Git:       existing repository, left as is",
+  skipped: "Git:       not initialized (git not found)",
+  disabled: "Git:       not initialized (--no-git)",
+};
+
+export function printSummary(r, dirArg) {
+  const rel = relative(process.cwd(), r.target) || ".";
+  const lines = [
+    `Template:  ${r.template}`,
+    `Target:    ${r.target}`,
+    `App name:  ${r.appName}`,
+    `Files:     ${r.files}`,
+    GIT_LINES[r.git] ?? "",
+    "",
+    "Next steps:",
+  ];
+  if (rel !== ".") lines.push(`  cd ${dirArg ?? rel}`);
+  if (r.setup) {
+    lines.push(
+      "  cargo watch -x 'run -p backend'     # http://localhost:8080",
+      "  npm run dev:frontend                # http://localhost:5173 (second terminal)",
+    );
+  } else {
+    lines.push(
+      "  scripts/setup",
+      "  scripts/db-migrate sqlite",
+      "  cargo watch -x 'run -p backend'",
+      "  npm run dev:frontend",
+    );
+  }
+  if (r.git === "initialized") lines.push("  git add -A && git commit -m 'Initial commit'");
+  lines.push("", "See docs/getting-started.md");
+  return lines.join("\n");
+}