app/cli/zz.ts

 #!/usr/bin/env node

 import { Command } from "commander";

 import { ladderBuild } from "./commands/ladder-build.js";

 import { ladderDump, type DumpFormat } from "./commands/ladder-dump.js";

 import { ladderReplayCommits } from "./commands/ladder-replay-commits.js";

 import { laneLog, type LaneLogFormat } from "./commands/lane-log.js";

 const program = new Command();

 program.name("zz").description("zz: a coordination layer for agentic open source").version("0.1.0");

 const ladder = program.command("ladder").description("build and read a repo's Ladder");

 ladder

  .command("build <repo>")

  .description("onboard a real GitHub repo (owner/repo) into a Ladder, from its real git history and issue/PR/release data")

  .option("--force", "rebuild the file tree and overwrite any existing asks/releases/contributors instead of leaving them alone")

  .action(async (repo: string, opts: { force?: boolean }) => {

  await ladderBuild(repo, { force: opts.force });

  });

 ladder

  .command("dump <repo>")

  .description("materialize an onboarded repo's Ladder for reading")

  .option("--format <format>", "text, json, or html", "text")

  .option("--out <path>", "write to a file instead of stdout")

  .action(async (repo: string, opts: { format: string; out?: string }) => {

  const format = opts.format as DumpFormat;

  if (format !== "text" && format !== "json" && format !== "html") {

  console.error(`unknown format "${opts.format}"; expected text, json, or html`);

  process.exitCode = 1;

  return;

  }

  await ladderDump(repo, { format, out: opts.out });

  });

 ladder

  .command("replay-commits <repo>")

  .description("walk the commit log from the root commit forward, one Lane per commit, building changeset/filechange/linechange rungs")

  .option("--limit <n>", "only replay the first N not-yet-onboarded commits", (v) => parseInt(v, 10))

  .option("--force", "re-replay commits that already have a changeset rung")

  .option("--max-files <n>", "commits touching more files than this get a mechanical summary instead of per-file/per-hunk analysis (default: 25)", (v) => parseInt(v, 10))

  .action(async (repo: string, opts: { limit?: number; force?: boolean; maxFiles?: number }) => {

  await ladderReplayCommits(repo, { limit: opts.limit, force: opts.force, maxFiles: opts.maxFiles });

  });

 const lane = program.command("lane").description("inspect the Lane/ASK/ANSWER protocol trail");

 lane

  .command("log <repo>")

  .description("chronological log of every ASK/ANSWER across every Lane for a repo")

  .option("--format <format>", "text or json", "text")

  .option("--lane <id>", "show only one lane")

  .option("--out <path>", "write to a file instead of stdout")

  .action(async (repo: string, opts: { format: string; lane?: string; out?: string }) => {

  const format = opts.format as LaneLogFormat;

  if (format !== "text" && format !== "json") {

  console.error(`unknown format "${opts.format}"; expected text or json`);

  process.exitCode = 1;

  return;

  }

  await laneLog(repo, { format, lane: opts.lane, out: opts.out });

  });

 program.parseAsync(process.argv);