app/cli/commands/ladder-sync.ts

 // `zz ladder sync <local-repo> <owner/repo>`: keeps an already-imported

 // zz repo in sync with ongoing changes to its real GitHub source --

 // the ongoing half of onboarding, where `zz ladder build` + `zz

 // ladder push` (cli/commands/ladder-push.ts) was the one-time half.

 //

 // Re-summarizes only files that actually changed since the last sync

 // (describeOneFile, engine/ingest.ts -- not a full re-walk of every

 // file, which is what makes this "incremental" rather than just

 // re-running the full build). Issues/PRs/releases/contributors/

 // dependencies are NOT diffed at all here: ladder-build.ts's own

 // buildAskFromIssue/buildAskFromPr/buildRelease/buildContributor/

 // buildDependency each already check isPresent first and skip

 // anything already onboarded, so calling all of them again, every

 // time, is already exactly as incremental as this file's own diffing

 // -- just for free, with no extra bookkeeping needed for any of those

 // five kinds.

 //

 // KNOWN LIMITATION: a brand-new file (one that didn't exist at the

 // last sync) gets written and registered under the repo root's own

 // children list -- mergeLaneLadder's own appendRepoChildren call does

 // this automatically for any top-level write, same as every other

 // kind onboarded here -- but NOT nested under its real parent

 // directory's own note the way ladder-build.ts's initial full walk

 // nests it (appendRepoChildren only ever targets the repo root, not

 // an arbitrary directory; generalizing that is a bigger change than

 // this first pass takes on). The file's content and summary are still

 // correctly stored and findable by path and by search either way; it

 // just won't show up when browsing into that directory in the Ladder

 // tree view. Re-run `zz ladder build --force` (a full, expensive

 // re-walk) if that gap matters for a given repo.

 //

 // Deletions are detected (git diff's own "D" status) but not acted on

 // at all -- there's no delete primitive for a rung yet. Printed as a

 // warning so they're not silently lost from view, not auto-removed.

 import { execFileSync } from "node:child_process";

 import { resolveRepo, syncClone } from "../lib/repo.js";

 import { fetchContributors, fetchIssues, fetchPullRequests, fetchReleases, parseDependencies, describeOneFile } from "../../engine/ingest.js";

 import { resolveModelBackend } from "../../engine/model.js";

 import type { Provider } from "../lib/resolveChatBackend.js";

 import { readSyncState, writeSyncState } from "../lib/syncState.js";

 import { runItemLane, resolveRepoLaneOrigin, buildAskFromIssue, buildAskFromPr, buildRelease, buildContributor, buildDependency } from "./ladder-build.js";

 import { ladderPush } from "./ladder-push.js";

 export interface SyncOptions {

  provider?: Provider;

  model?: string;

 }

 function git(repoDir: string, args: string[]): string {

  return execFileSync("git", ["-C", repoDir, ...args], { encoding: "utf8" }).trim();

 }

 export async function ladderSync(sourceSlug: string, targetSlug: string, options: SyncOptions): Promise<void> {

  const repo = resolveRepo(sourceSlug);

  const model = await resolveModelBackend(options.provider, options.model);

  console.error(`model backend: ${model.name}`);

  console.error(`fetching ${sourceSlug}'s real GitHub source...`);

  syncClone(repo);

  const head = git(repo.repoDir, ["rev-parse", "HEAD"]);

  const origin = await resolveRepoLaneOrigin(repo.slug, repo.stateDir);

  const state = readSyncState(repo.stateDir);

  if (!state) {

  console.error("no previous sync baseline on this clone (run `zz ladder push` at least once first -- it records one). Treating the entire current file tree as changed.");

  }

  if (state?.lastSyncedCommit === head) {

  console.error("no new commits since the last sync.");

  } else {

  const diffLines = state

  ? git(repo.repoDir, ["diff", "--name-status", state.lastSyncedCommit, head])

  .split("\n")

  .filter(Boolean)

  .map((l) => l.split("\t") as [string, string])

  : git(repo.repoDir, ["ls-tree", "-r", "--name-only", "HEAD"])

  .split("\n")

  .filter(Boolean)

  .map((p): [string, string] => ["A", p]);

  const changed = diffLines.filter(([status]) => status === "A" || status === "M").map(([, path]) => path);

  const deleted = diffLines.filter(([status]) => status === "D").map(([, path]) => path);

  if (deleted.length > 0) {

  console.error(`${deleted.length} file(s) deleted since the last sync -- NOT removed from the Ladder (no delete primitive exists for a rung yet): ${deleted.slice(0, 10).join(", ")}${deleted.length > 10 ? ", ..." : ""}`);

  }

  console.error(`${changed.length} file(s) added or changed -- re-summarizing...`);

  let done = 0;

  for (const path of changed) {

  await runItemLane(repo.repoDir, repo.stateDir, { id: `resync-${path}`, repo: repo.slug, name: `re-sync ${path}`, objective: path, scope: [path], origin }, () =>

  describeOneFile(repo.repoDir, path, async (p, content, mechanical) => {

  if (!content.trim()) return mechanical;

  const described = await model.summarize(`Describe in 1-3 sentences what this file does, based on its content below. Name exported functions/classes by name.\n\nFile: ${p}\n---\n${content.slice(0, 6000)}\n---\nSummary:`);

  return described ?? mechanical;

  }),

  );

  done += 1;

  if (done % 5 === 0) console.error(` files: ${done}/${changed.length}`);

  }

  }

  console.error("checking for new issues, PRs, releases, contributors, dependencies (already-onboarded ones are skipped automatically)...");

  const issues = fetchIssues(repo.slug);

  const prs = fetchPullRequests(repo.slug);

  const releases = fetchReleases(repo.slug);

  const contributors = fetchContributors(repo.slug);

  const dependencies = parseDependencies(repo.repoDir);

  for (const i of issues) await buildAskFromIssue(repo.repoDir, repo.stateDir, origin, repo.slug, model, i);

  for (const p of prs) await buildAskFromPr(repo.repoDir, repo.stateDir, origin, repo.slug, model, p);

  for (const r of releases) await buildRelease(repo.repoDir, repo.stateDir, origin, repo.slug, r);

  for (const c of contributors) await buildContributor(repo.repoDir, repo.stateDir, origin, repo.slug, model, c);

  for (const d of dependencies) await buildDependency(repo.repoDir, repo.stateDir, origin, repo.slug, model, d.name, d.versionRange);

  writeSyncState(repo.stateDir, head);

  console.error(`pushing the updated Ladder to ${targetSlug}...`);

  // Reuses ladderPush wholesale rather than pushing only the rungs

  // that changed this run -- every rung gets re-sent, not just the

  // ones touched above, so a sync costs roughly the same as a fresh

  // push regardless of how little actually changed. Correct (each

  // write is a plain overwrite, so re-sending unchanged content is

  // harmless) and simple, at the cost of not being maximally cheap --

  // an acceptable trade for a first version now that writeRungsBatch

  // makes even a full push fast (~240 rungs in under 2 minutes, not

  // the multi-hour cost a naive per-rung push used to have).

  //

  // markIngesting: false -- this is a routine update to an

  // already-ready repo, not the one-time initial import, so it

  // shouldn't disappear from search while it runs (see

  // ladder-push.ts's own comment on the option).

  await ladderPush(sourceSlug, targetSlug, { markIngesting: false });

  console.error("sync done.");

 }