app/cli/lib/remoteBackend.ts

// A deliberately MINIMAL Backend (engine/backend.ts) for `zz work`
// operating against a deployed Worker's real protocol state --
// read-only. Every mutation (ask_claim, ask_post, ask_answer,
// commit_changeset, ladder_write_rung, lane_propose) goes through
// callRemoteTool directly instead of through this Backend's write
// methods, because the server's real atomicity (MaintainerDO's
// storage.transactionSync-backed withLane) only exists server-side --
// a client-side read-modify-write here would race against other
// agents working the same repo concurrently, exactly the failure mode
// this whole project exists to prevent. Reads are safe either way, so
// this Backend only implements those; its write methods throw loudly
// rather than silently doing something non-atomic, so any new code
// path that tries to use one fails fast instead of corrupting state
// under real concurrency.
//
// Not constructed per-repo: every Backend method already takes `repo`
// as its own first argument (claimableAcrossRepos iterates several
// repos through the SAME Backend instance), so this just forwards
// whichever repo each call names, rather than baking one in.
import type { Backend, LadderSearchHit } from "../../engine/backend.js";
import type { Lane } from "../../engine/types.js";
import type { EmbeddedRung } from "../../engine/ladderNotes.js";
import type { ResolvedRung } from "../../engine/ladderRender.js";
import { callRemoteTool } from "./remoteTools.js";
import { apiFetch } from "./api.js";

function notSupported(method: string): never {
  throw new Error(
    `RemoteBackend.${method}: not implemented on purpose -- mutations go through callRemoteTool (the real protocol tools: ask_post/ask_claim/ask_answer/commit_changeset/ladder_write_rung/lane_propose), never a raw Backend write, since only the server side can make a Lane mutation atomic against other concurrently-working agents.`,
  );
}

export const remoteBackend: Backend = {
  name: "remote",
  async ensureCloned() {
    // No-op here -- cli/lib/repo.ts's own mode-aware ensureCloned
    // handles getting a real local working copy (via the git smart-
    // HTTP proxy) for run_in_sandbox/threeWayMerge to use; this
    // Backend is only the Lane/Ladder/git-content read surface.
  },
  listCommits: () => notSupported("listCommits"),
  diffCommit: () => notSupported("diffCommit"),
  async readFileAtCommit(repo, sha, path) {
    return (await callRemoteTool(repo, "git_show_file", { sha, path })) as string;
  },
  commitChangeset: () => notSupported("commitChangeset"),
  async readAnchor(repo, path) {
    return (await callRemoteTool(repo, "ladder_read", { path })) as EmbeddedRung | null;
  },
  // One tool call, server-side resolved and cached -- NOT the client-
  // side resolveLadderTree(readAnchor) walk this repo used to drive
  // (tui/useLadderTrees.ts), which meant one real HTTP round trip per
  // rung. Confirmed live: that was the actual cause of `zz top`'s
  // Ladder tab being unusably slow, and would only get worse on a
  // repo with many files/changesets -- this collapses it to one call
  // regardless of tree size, server-side cached so repeat polls of an
  // unchanged tree are nearly free.
  async readLadderTree(repo) {
    return (await callRemoteTool(repo, "ladder_tree", {})) as ResolvedRung | null;
  },
  writeLadder: () => notSupported("writeLadder"),
  appendRepoChildren: () => notSupported("appendRepoChildren"),
  async readLane(repo, laneId) {
    return (await callRemoteTool(repo, "lane_get", { lane_id: laneId })) as Lane | null;
  },
  writeLane: () => notSupported("writeLane"),
  async listLanes(repo) {
    return (await callRemoteTool(repo, "lane_list", {})) as Lane[];
  },
  withLane: () => notSupported("withLane"),
  // Cross-repo, so callRemoteTool (which routes to one specific
  // repo's DO) doesn't apply here -- a direct API call instead, same
  // as any other plain CLI->Worker call. Safe specifically because
  // this file (cli/lib/remoteBackend.ts) only ever runs in the CLI's
  // own process, never bundled into the Worker -- unlike
  // agent/tools.ts's ladder_search tool, whose execute() runs
  // server-side when dispatched through the generic remote
  // tool-calling loop and so can't make this same kind of call.
  async searchLadder(query, limit) {
    const { hits } = await apiFetch<{ hits: { repo_slug: string; path: string; kind: string; commit_sha: string | null; summary: string }[] }>("GET", `/api/ladder/search?q=${encodeURIComponent(query)}&limit=${limit}`);
    return hits.map((h) => ({ repo: h.repo_slug, path: h.path, kind: h.kind as LadderSearchHit["kind"], commitSha: h.commit_sha, summary: h.summary }));
  },
  // Repo-scoped (unlike searchLadder), so callRemoteTool applies here --
  // routes to that one repo's DO, same as any other mutation-shaped call.
  async reindexLadder(repo) {
    const { indexed } = (await callRemoteTool(repo, "ladder_reindex", { repo })) as { indexed: number };
    return indexed;
  },
};