@a5c-ai/git-a5c 1.0.2

package/src/commands/journal.ts

@@ -0,0 +1,75 @@
+import type { CommandArgs } from "./types.js";
+import { parseSinceToEpochMs } from "../time.js";
+
+function typeMatches(kind: string, patterns: string[] | undefined): boolean {
+  if (!patterns || patterns.length === 0) return true;
+  return patterns.some((p) => (p.endsWith(".*") ? kind.startsWith(p.slice(0, -2)) : kind === p));
+}
+
+function entityMatches(ev: any, entity: string | undefined): boolean {
+  if (!entity) return true;
+  const kind = ev.kind as string;
+  const payload = ev.payload ?? {};
+
+  if (kind === "issue.event.created") return payload.issueId === entity;
+  if (kind.startsWith("comment.")) return payload.entity?.id === entity;
+  if (kind.startsWith("pr.")) return payload.prKey === entity;
+  if (kind === "dep.changed" || kind === "gate.changed") return payload.entity?.id === entity;
+  if (kind.startsWith("agent.")) return payload.entity?.id === entity;
+  if (kind.startsWith("ops.")) return payload.entity?.id === entity;
+  return false;
+}
+
+export async function handleJournal(args: CommandArgs): Promise<number | undefined> {
+  if (args.positionals[0] !== "journal") return;
+
+  const limit = Number.isFinite(args.flags.limit as any) ? (args.flags.limit as number) : 20;
+  const sinceMs = args.flags.since ? parseSinceToEpochMs(args.flags.since, args.nowMs()) : undefined;
+  const events = [...args.snap.collabEvents, ...(args.snap.inbox?.events ?? [])]
+    .map((e: any) => ({
+      time: (e.event as any).time as string,
+      actor: (e.event as any).actor as string,
+      kind: e.kind,
+      id: (e.event as any).id as string,
+      payload: (e.event as any).payload as any
+    }))
+    .filter((e: any) => typeMatches(e.kind, args.flags.types))
+    .filter((e: any) => entityMatches({ kind: e.kind, payload: e.payload }, args.flags.entity))
+    .filter((e: any) => {
+      if (!sinceMs) return true;
+      const t = Date.parse(e.time);
+      return Number.isFinite(t) && t >= sinceMs;
+    })
+    .sort((a: any, b: any) => (a.time < b.time ? 1 : a.time > b.time ? -1 : a.id < b.id ? 1 : -1))
+    .slice(0, limit);
+
+  if (args.flags.json) {
+    const base = events.map(({ payload: _p, ...rest }: any) => rest);
+    if (!args.flags.active) {
+      args.io.writeLine(args.io.out, JSON.stringify(base, null, 2));
+      return 0;
+    }
+    const now = args.nowMs();
+    const byAgent = new Map<string, any>();
+    for (const e of events) {
+      if (e.kind !== "agent.heartbeat.created") continue;
+      const agentId = String(e.payload?.agentId ?? "");
+      if (!agentId) continue;
+      byAgent.set(agentId, e);
+    }
+    const active = [...byAgent.values()].filter((e) => {
+      const ttlSeconds = Number(e.payload?.ttlSeconds ?? 0);
+      const t = Date.parse(e.time);
+      return Number.isFinite(t) && ttlSeconds > 0 && t + ttlSeconds * 1000 >= now;
+    });
+    args.io.writeLine(args.io.out, JSON.stringify({ events: base, activeAgents: active }, null, 2));
+    return 0;
+  }
+
+  for (const e of events) {
+    args.io.writeLine(args.io.out, `${e.time} ${e.actor} ${e.kind} ${e.id}`);
+  }
+  return 0;
+}
+
+

package/src/commands/ops.ts

@@ -0,0 +1,41 @@
+import type { CommandArgs } from "./types.js";
+import { git, gitConfigGet } from "../git.js";
+import { HlcClock, loadHlcState, saveHlcState, stageFiles, writeOpsBuild, writeOpsDeploy, writeOpsTest } from "@a5cforge/sdk";
+
+export async function handleOps(args: CommandArgs): Promise<number | undefined> {
+  if (args.positionals[0] !== "ops") return;
+  const sub = args.positionals[1];
+  if (sub !== "deploy" && sub !== "build" && sub !== "test") {
+    args.io.writeLine(args.io.err, "usage: git a5c ops deploy|build|test --entity <id> [--artifact ...] [--rev ...] [--env ...]");
+    return 2;
+  }
+  const entityId = args.flags.entity;
+  if (!entityId) {
+    args.io.writeLine(args.io.err, "missing --entity");
+    return 2;
+  }
+  const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+  const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+  const clock = new HlcClock(persisted);
+  let nonce = 0;
+  const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+  const time = new Date(args.nowMs()).toISOString();
+  const entity = { type: entityId.startsWith("pr-") ? "pr" : "issue", id: entityId } as const;
+  const artifact = args.flags.artifact ? { name: args.flags.artifact, uri: args.flags.artifact } : undefined;
+  const res =
+    sub === "build"
+      ? await writeOpsBuild(ctx, { entity, status: args.flags.message as any, artifact, time })
+      : sub === "test"
+        ? await writeOpsTest(ctx, { entity, status: args.flags.message as any, artifact, time })
+        : await writeOpsDeploy(ctx, { entity, status: args.flags.message as any, artifact, time });
+  await saveHlcState(actor, clock.now());
+  if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+  if (args.flags.commit) {
+    const msg = args.flags.message ?? `a5c: ops ${sub} ${entityId}`;
+    await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+  }
+  args.io.writeLine(args.io.out, res.path);
+  return 0;
+}
+
+

package/src/commands/pr.ts

@@ -0,0 +1,147 @@
+import type { CommandArgs } from "./types.js";
+import { git, gitConfigGet } from "../git.js";
+import {
+  HlcClock,
+  UlidGenerator,
+  loadHlcState,
+  saveHlcState,
+  stageFiles,
+  listPRs,
+  renderPR,
+  writePrProposal,
+  writePrRequest,
+  writePrEvent
+} from "@a5cforge/sdk";
+
+export async function handlePr(args: CommandArgs): Promise<number | undefined> {
+  if (args.positionals[0] !== "pr") return;
+  const sub = args.positionals[1];
+
+  if (sub === "list") {
+    const keys = listPRs(args.snap);
+    if (args.flags.json) args.io.writeLine(args.io.out, JSON.stringify(keys, null, 2));
+    else keys.forEach((k) => args.io.writeLine(args.io.out, k));
+    return 0;
+  }
+
+  if (sub === "show") {
+    const key = args.positionals[2];
+    if (!key) throw new Error("missing prKey");
+    const pr = renderPR(args.snap, key);
+    if (!pr) {
+      args.io.writeLine(args.io.err, `not found: ${key}`);
+      return 2;
+    }
+    if (args.flags.json) args.io.writeLine(args.io.out, JSON.stringify(pr, null, 2));
+    else {
+      args.io.writeLine(args.io.out, `${pr.prKey}: ${pr.title}`);
+      args.io.writeLine(args.io.out, `base: ${pr.baseRef}`);
+      if (pr.headRef) args.io.writeLine(args.io.out, `head: ${pr.headRef}`);
+      args.io.writeLine(args.io.out, `events: ${pr.events.length}`);
+    }
+    return 0;
+  }
+
+  if (sub === "propose") {
+    const baseRef = args.flags.base;
+    const headRef = args.flags.head;
+    const title = args.flags.title;
+    if (!baseRef || !headRef || !title) {
+      args.io.writeLine(args.io.err, "missing --base, --head, or --title");
+      return 2;
+    }
+    const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+    const prKey = args.flags.id ?? `pr-${new UlidGenerator().generate()}`;
+    const time = new Date(args.nowMs()).toISOString();
+    const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+    const clock = new HlcClock(persisted);
+    let nonce = 0;
+    const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+    const res = await writePrProposal(ctx, { prKey, baseRef, headRef, title, body: args.flags.body, time });
+    await saveHlcState(actor, clock.now());
+    if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+    if (args.flags.commit) {
+      const msg = args.flags.message ?? `a5c: pr propose ${prKey}`;
+      await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+    }
+    args.io.writeLine(args.io.out, prKey);
+    return 0;
+  }
+
+  if (sub === "request") {
+    const baseRef = args.flags.base;
+    const title = args.flags.title;
+    if (!baseRef || !title) {
+      args.io.writeLine(args.io.err, "missing --base or --title");
+      return 2;
+    }
+    const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+    const prKey = args.flags.id ?? `pr-${new UlidGenerator().generate()}`;
+    const time = new Date(args.nowMs()).toISOString();
+    const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+    const clock = new HlcClock(persisted);
+    let nonce = 0;
+    const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+    const res = await writePrRequest(ctx, { prKey, baseRef, title, body: args.flags.body, time });
+    await saveHlcState(actor, clock.now());
+    if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+    if (args.flags.commit) {
+      const msg = args.flags.message ?? `a5c: pr request ${prKey}`;
+      await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+    }
+    args.io.writeLine(args.io.out, prKey);
+    return 0;
+  }
+
+  if (sub === "claim") {
+    const prKey = args.positionals[2];
+    const headRef = args.flags.headRef;
+    if (!prKey || !headRef) {
+      args.io.writeLine(args.io.err, "missing prKey or --head-ref");
+      return 2;
+    }
+    const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+    const time = new Date(args.nowMs()).toISOString();
+    const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+    const clock = new HlcClock(persisted);
+    let nonce = 0;
+    const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+    const res = await writePrEvent(ctx, { prKey, action: "claim", headRef, message: args.flags.message as any, time });
+    await saveHlcState(actor, clock.now());
+    if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+    if (args.flags.commit) {
+      const msg = args.flags.message ?? `a5c: pr claim ${prKey}`;
+      await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+    }
+    args.io.writeLine(args.io.out, res.path);
+    return 0;
+  }
+
+  if (sub === "bind-head") {
+    const prKey = args.positionals[2];
+    const headRef = args.flags.headRef;
+    if (!prKey || !headRef) {
+      args.io.writeLine(args.io.err, "missing prKey or --head-ref");
+      return 2;
+    }
+    const actor = process.env.A5C_ACTOR ?? (await gitConfigGet(args.repoRoot, "user.name")) ?? "unknown";
+    const time = new Date(args.nowMs()).toISOString();
+    const persisted = (await loadHlcState(actor)) ?? { wallMs: 0, counter: 0 };
+    const clock = new HlcClock(persisted);
+    let nonce = 0;
+    const ctx = { repoRoot: args.repoRoot, actor, clock, nextNonce: () => String(++nonce).padStart(4, "0") };
+    const res = await writePrEvent(ctx, { prKey, action: "bindHead", headRef, message: args.flags.message as any, time });
+    await saveHlcState(actor, clock.now());
+    if (args.flags.stageOnly || args.flags.commit) await stageFiles(args.repoRoot, [res.path]);
+    if (args.flags.commit) {
+      const msg = args.flags.message ?? `a5c: pr bind-head ${prKey}`;
+      await git(["-c", "user.name=a5c", "-c", "user.email=a5c@example.invalid", "commit", "-m", msg], args.repoRoot);
+    }
+    args.io.writeLine(args.io.out, res.path);
+    return 0;
+  }
+
+  return;
+}
+
+

package/src/commands/status.ts

@@ -0,0 +1,18 @@
+import type { CommandArgs } from "./types.js";
+import { listIssues, listPRs } from "@a5cforge/sdk";
+
+export function handleStatus(args: CommandArgs): number | undefined {
+  if (args.positionals[0] !== "status") return;
+  const issues = listIssues(args.snap).length;
+  const prs = listPRs(args.snap).length;
+  if (args.flags.json) {
+    args.io.writeLine(args.io.out, JSON.stringify({ treeish: args.treeish, issues, prs }, null, 2));
+  } else {
+    args.io.writeLine(args.io.out, `treeish: ${args.treeish}`);
+    args.io.writeLine(args.io.out, `issues: ${issues}`);
+    args.io.writeLine(args.io.out, `prs: ${prs}`);
+  }
+  return 0;
+}
+
+

package/src/commands/types.ts

@@ -0,0 +1,20 @@
+import type { ParsedArgs } from "../args.js";
+
+export type CommandIO = {
+  out: (s: string) => void;
+  err: (s: string) => void;
+  writeLine: (write: (s: string) => void, s?: string) => void;
+};
+
+export type CommandArgs = {
+  repoRoot: string;
+  treeish: string;
+  flags: ParsedArgs["flags"];
+  positionals: string[];
+  repo: any;
+  snap: any;
+  nowMs: () => number;
+  io: CommandIO;
+};
+
+

package/src/commands/verify.ts

@@ -0,0 +1,20 @@
+import type { CommandArgs } from "./types.js";
+import { verify } from "@a5cforge/sdk";
+
+export function handleVerify(args: CommandArgs): number | undefined {
+  if (args.positionals[0] !== "verify") return;
+  const v = verify(args.snap);
+  if (args.flags.json) {
+    args.io.writeLine(args.io.out, JSON.stringify(v, null, 2));
+  } else {
+    const counts = v.reduce<Record<string, number>>((acc, x: any) => {
+      acc[x.status] = (acc[x.status] ?? 0) + 1;
+      return acc;
+    }, {});
+    args.io.writeLine(args.io.out, `events: ${v.length}`);
+    for (const k of Object.keys(counts).sort()) args.io.writeLine(args.io.out, `${k}: ${counts[k]}`);
+  }
+  return 0;
+}
+
+

package/src/commands/webhook.ts

@@ -0,0 +1,63 @@
+import type { CommandArgs } from "./types.js";
+import path from "node:path";
+
+export async function handleWebhook(args: CommandArgs): Promise<number | undefined> {
+  if (args.positionals[0] !== "webhook") return;
+
+  const sub = args.positionals[1];
+  if (sub === "status") {
+    try {
+      const commitOid = await args.repo.git.revParse(args.treeish);
+      const raw = await args.repo.git.readBlob(commitOid, ".collab/webhooks.json");
+      const cfg = JSON.parse(raw.toString("utf8"));
+      const endpoints = Array.isArray(cfg?.endpoints) ? cfg.endpoints : [];
+      if (args.flags.json) args.io.writeLine(args.io.out, JSON.stringify({ schema: cfg?.schema, endpoints }, null, 2));
+      else {
+        args.io.writeLine(args.io.out, `schema: ${cfg?.schema ?? "?"}`);
+        args.io.writeLine(args.io.out, `endpoints: ${endpoints.length}`);
+        for (const e of endpoints) {
+          args.io.writeLine(args.io.out, `- ${e.id}: ${e.url} (${(e.events ?? []).join(",")}) ${e.enabled === false ? "[disabled]" : ""}`);
+        }
+      }
+      return 0;
+    } catch {
+      args.io.writeLine(args.io.err, `no webhooks config at .collab/webhooks.json in ${args.treeish}`);
+      return 2;
+    }
+  }
+
+  if (sub === "test") {
+    const url = args.flags.url;
+    if (!url) {
+      args.io.writeLine(args.io.err, "usage: git a5c webhook test --url <url> [--type <type>]");
+      return 2;
+    }
+    const type = args.flags.type ?? "git.ref.updated";
+    const envelope = {
+      schema: "a5cforge/v1",
+      type,
+      id: `cli:${Date.now()}`,
+      time: new Date(args.nowMs()).toISOString(),
+      repo: { id: path.basename(args.repoRoot), path: args.repoRoot },
+      source: { serverId: "cli", keyId: undefined },
+      data: { note: "test" }
+    };
+    const r = await fetch(String(url), {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(envelope, null, 2) + "\n"
+    });
+    const text = await r.text();
+    if (args.flags.json) args.io.writeLine(args.io.out, JSON.stringify({ status: r.status, body: text }, null, 2));
+    else {
+      args.io.writeLine(args.io.out, `status: ${r.status}`);
+      args.io.writeLine(args.io.out, text.trim());
+    }
+    return r.ok ? 0 : 1;
+  }
+
+  args.io.writeLine(args.io.err, "usage: git a5c webhook status|test ...");
+  return 2;
+}
+
+

package/src/git.ts

@@ -0,0 +1,38 @@
+import { spawn } from "node:child_process";
+
+export async function git(args: string[], cwd: string): Promise<string> {
+  return await new Promise((resolve, reject) => {
+    const child = spawn("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    child.stdout.on("data", (d: Buffer) => out.push(Buffer.from(d)));
+    child.stderr.on("data", (d: Buffer) => err.push(Buffer.from(d)));
+    child.on("error", reject);
+    child.on("close", (code: number | null) => {
+      if (code === 0) return resolve(Buffer.concat(out).toString("utf8"));
+      reject(new Error(`git ${args.join(" ")} failed (code=${code}): ${Buffer.concat(err).toString("utf8")}`));
+    });
+  });
+}
+
+export async function detectRepoRoot(cwd: string): Promise<string> {
+  const out = await git(["rev-parse", "--show-toplevel"], cwd);
+  return out.trim();
+}
+
+export async function gitConfigGet(cwd: string, key: string): Promise<string | undefined> {
+  try {
+    const out = await git(["config", "--get", key], cwd);
+    const v = out.trim();
+    return v.length ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function gitPath(cwd: string, name: string): Promise<string> {
+  const out = await git(["rev-parse", "--git-path", name], cwd);
+  return out.trim();
+}
+
+

package/src/run.ts

@@ -0,0 +1,99 @@
+import { detectRepoRoot } from "./git.js";
+import { parseArgs } from "./args.js";
+import { createLogger, loadSnapshot, openRepo, parseLogLevel } from "@a5cforge/sdk";
+import type { CommandArgs } from "./commands/types.js";
+import { handleHelp } from "./commands/help.js";
+import { handleWebhook } from "./commands/webhook.js";
+import { handleStatus } from "./commands/status.js";
+import { handleIssue } from "./commands/issue.js";
+import { handlePr } from "./commands/pr.js";
+import { handleBlock } from "./commands/block.js";
+import { handleGate } from "./commands/gate.js";
+import { handleAgent } from "./commands/agent.js";
+import { handleOps } from "./commands/ops.js";
+import { handleHooks } from "./commands/hooks.js";
+import { handleVerify } from "./commands/verify.js";
+import { handleJournal } from "./commands/journal.js";
+
+export type RunOptions = {
+  cwd?: string;
+  stdout?: (s: string) => void;
+  stderr?: (s: string) => void;
+};
+
+function writeLine(write: (s: string) => void, s = "") {
+  write(s + "\n");
+}
+
+function nowMs(): number {
+  // Test hook for deterministic journal/active: set A5C_NOW_ISO=...
+  const iso = process.env.A5C_NOW_ISO;
+  if (iso) {
+    const ms = Date.parse(iso);
+    if (Number.isFinite(ms)) return ms;
+  }
+  return Date.now();
+}
+
+export async function runCli(argv: string[], opts: RunOptions = {}): Promise<number> {
+  const cwd = opts.cwd ?? process.cwd();
+  const out = opts.stdout ?? ((s) => process.stdout.write(s));
+  const err = opts.stderr ?? ((s) => process.stderr.write(s));
+  const log = createLogger({ base: { component: "cli" }, level: parseLogLevel(process.env.A5C_LOG_LEVEL ?? "silent") });
+
+  const { flags, positionals } = parseArgs(argv);
+  const cmd = positionals[0] ?? "help";
+
+  let repoRoot: string;
+  try {
+    repoRoot = typeof flags.repo === "string" ? flags.repo : await detectRepoRoot(cwd);
+  } catch {
+    writeLine(err, "not a git repository (use --repo <path>)");
+    return 2;
+  }
+  const treeish = typeof flags.treeish === "string" ? flags.treeish : "HEAD";
+
+  log.debug("start", { cmd, treeish, repoRoot });
+  const repo = await openRepo(repoRoot);
+  const snap = await loadSnapshot({ git: repo.git, treeish, inboxRefs: flags.inboxRefs });
+
+  const baseArgs: CommandArgs = {
+    repoRoot,
+    treeish,
+    flags,
+    positionals,
+    repo,
+    snap,
+    nowMs,
+    io: { out, err, writeLine }
+  };
+
+  const handlers: Array<() => number | undefined | Promise<number | undefined>> = [
+    () => handleHelp(baseArgs),
+    () => handleWebhook(baseArgs),
+    () => handleStatus(baseArgs),
+    () => handleIssue(baseArgs),
+    () => handlePr(baseArgs),
+    () => handleBlock(baseArgs),
+    () => handleGate(baseArgs),
+    () => handleAgent(baseArgs),
+    () => handleOps(baseArgs),
+    () => handleHooks(baseArgs),
+    () => handleVerify(baseArgs),
+    () => handleJournal(baseArgs)
+  ];
+
+  for (const h of handlers) {
+    const r = await h();
+    if (r !== undefined) {
+      log.debug("done", { code: r });
+      return r;
+    }
+  }
+
+  writeLine(err, `unknown command: ${cmd}`);
+  log.warn("unknown_command", { cmd });
+  return 2;
+}
+
+

package/src/time.ts

@@ -0,0 +1,16 @@
+export function parseSinceToEpochMs(since: string, nowMs: number): number {
+  // Accept:
+  // - ISO timestamp
+  // - durations like 2h, 15m, 30s, 7d
+  const iso = Date.parse(since);
+  if (Number.isFinite(iso)) return iso;
+
+  const m = /^(\d+)(s|m|h|d)$/.exec(since.trim());
+  if (!m) throw new Error(`Invalid --since: ${since}`);
+  const n = Number(m[1]);
+  const unit = m[2];
+  const mult = unit === "s" ? 1000 : unit === "m" ? 60_000 : unit === "h" ? 3_600_000 : 86_400_000;
+  return nowMs - n * mult;
+}
+
+

package/test/_util.ts

@@ -0,0 +1,88 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+
+export function run(cmd: string, args: string[], cwd: string): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    child.stdout.on("data", (d) => out.push(Buffer.from(d)));
+    child.stderr.on("data", (d) => err.push(Buffer.from(d)));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      const stdout = Buffer.concat(out).toString("utf8");
+      const stderr = Buffer.concat(err).toString("utf8");
+      if (code === 0) return resolve({ stdout, stderr });
+      reject(new Error(`${cmd} ${args.join(" ")} failed (code=${code}): ${stderr}`));
+    });
+  });
+}
+
+export async function copyDir(src: string, dst: string) {
+  await fs.mkdir(dst, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const e of entries) {
+    const s = path.join(src, e.name);
+    const d = path.join(dst, e.name);
+    if (e.isDirectory()) await copyDir(s, d);
+    else if (e.isFile()) await fs.copyFile(s, d);
+  }
+}
+
+export async function makeRepoFromFixture(fixtureName: string): Promise<string> {
+  const root = path.resolve(import.meta.dirname, "../../..");
+  const fixture = path.join(root, "fixtures", fixtureName);
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), `a5cforge-cli-${fixtureName}-`));
+  await copyDir(fixture, dir);
+  await run("git", ["init", "-q", "-b", "main"], dir);
+  await run("git", ["add", "-A"], dir);
+  await run("git", ["add", "-f", ".collab"], dir);
+  await run("git", ["-c", "user.name=test", "-c", "user.email=test@example.com", "commit", "-q", "-m", "fixture"], dir);
+  return dir;
+}
+
+export async function makeEmptyRepo(tmpPrefix = "a5cforge-cli-write-"): Promise<string> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), tmpPrefix));
+  await run("git", ["init", "-q", "-b", "main"], dir);
+  await run("git", ["-c", "user.name=test", "-c", "user.email=test@example.com", "commit", "--allow-empty", "-q", "-m", "init"], dir);
+  return dir;
+}
+
+export function listenOnce(handler: (req: http.IncomingMessage, body: Buffer) => Promise<void> | void): Promise<{ url: string; close: () => Promise<void> }> {
+  const srv = http.createServer(async (req, res) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (d) => chunks.push(Buffer.from(d)));
+    req.on("end", async () => {
+      try {
+        await handler(req, Buffer.concat(chunks));
+        res.statusCode = 200;
+        res.setHeader("content-type", "text/plain");
+        res.end("ok\n");
+      } catch (e: any) {
+        res.statusCode = 500;
+        res.setHeader("content-type", "text/plain");
+        res.end(String(e?.message ?? e));
+      }
+    });
+  });
+
+  return new Promise((resolve, reject) => {
+    srv.on("error", reject);
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      if (!addr || typeof addr === "string") return reject(new Error("bad listen addr"));
+      resolve({
+        url: `http://127.0.0.1:${addr.port}`,
+        close: async () =>
+          await new Promise<void>((r) => {
+            srv.close(() => r());
+          })
+      });
+    });
+  });
+}
+
+