app/cli/commands/top.ts

 // `zz top`: real-time dashboard over every Lane in the repos you care

 // about -- watched live, not read back from a dump after the fact.

 // Remote by default, like work/review; --local stays fully supported

 // for the demo/local-backend path. Unlike work/review, `top` is

 // read-only and has to work with ZERO config: no ~/.zz/config.json,

 // no --repos, no login (remote) or other running zz process (local)

 // all mean "show an empty/starter dashboard, not a crash" -- the

 // repo-resolution chain (lib/watchedRepoResolution.ts, shared with

 // `zz work --assist`'s own ask picker) is what makes that true, and

 // Explore (reachable as its own tab, see TopApp.tsx) is how you find

 // repos to add from inside the TUI instead of hand-editing config.json.

 import React from "react";

 import { render } from "ink";

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

 import { addRepoToConfig } from "../lib/config.js";

 import { resolveCliBackendMode } from "../lib/backendMode.js";

 import { apiFetch } from "../lib/api.js";

 import { createRepoWatchStore } from "../lib/watchedRepos.js";

 import { resolveWatchedRepoSlugs } from "../lib/watchedRepoResolution.js";

 import { login } from "./login.js";

 import { clearCredentials } from "../lib/credentials.js";

 import { callRemoteTool } from "../lib/remoteTools.js";

 import { ask } from "../../engine/lane.js";

 import { readConfig } from "../lib/config.js";

 import { TopApp } from "../../tui/TopApp.js";

 import { enterFullscreen } from "../../tui/fullscreen.js";

 export interface TopOptions {

  repos?: string[];

  local?: boolean;

 }

 export async function top(options: TopOptions): Promise<void> {

  // A read-only viewer, never an actor -- "zz-top-viewer" never needs

  // to be a real identity (nothing is ever posted/claimed as it).

  // requireIdentity: false is the whole point here -- remote mode

  // with no `zz login` session is a real, supported state (an

  // anonymous Explore search, an empty dashboard), not a crash.

  const mode = await resolveCliBackendMode({ ...options, requireIdentity: false });

  process.on("SIGINT", () => void mode.cleanup().then(() => process.exit(0)));

  process.on("SIGTERM", () => void mode.cleanup().then(() => process.exit(0)));

  const repoSlugs = await resolveWatchedRepoSlugs(mode, options);

  if (repoSlugs === null) {

  await mode.cleanup();

  return; // resolveWatchedRepoSlugs already printed guidance -- nothing to render

  }

  const resolvedRepos = repoSlugs.map((slug) => resolveRepo(slug));

  const watch = createRepoWatchStore(resolvedRepos);

  // The one "track" action Explore needs, in both its remote (search)

  // and local (directory browser) modes -- which underlying store it

  // writes to depends on the exact same three-way split the original

  // spec draws: a real server-side list when you're logged in to

  // remote, a local config file otherwise (not logged in remotely, or

  // local mode entirely, where there's no server concept at all).

  const onTrack = async (slug: string): Promise<void> => {

  if (mode.useRemote && mode.identity) {

  await apiFetch("POST", `/api/repos/${slug}/track`);

  } else {

  addRepoToConfig(slug);

  }

  watch.add(resolveRepo(slug));

  };

  // Works the same regardless of --local: login/logout is always

  // about the real remote identity (~/.zz/credentials.json), which

  // other commands read independently of whatever backend *this*

  // session happens to be watching with.

  const onLogin = () => login({ quiet: true });

  const onLogout = () => {

  clearCredentials();

  };

  // A plain "work" ask (payload.description), same shape `zz repo ask`

  // itself posts -- just into whichever lane was actually selected,

  // not always "_repo". Remote mode goes through the real protocol

  // tool (callRemoteTool); local mode calls the engine primitive

  // directly -- NOT through remoteBackend, which throws on purpose for

  // every write method (see remoteBackend.ts's own notSupported) since

  // only the server side can make a Lane mutation atomic.

  const onPostAsk = async (repoSlug: string, laneId: string, description: string): Promise<void> => {

  if (mode.useRemote) {

  // LaneList's own "n" handler already blocks this unless its

  // `identity` prop is set, but don't rely on the UI guard alone --

  // posting as nobody (or worse, as some stale local-mode fallback)

  // to a real remote repo should never be possible even if that

  // check is ever bypassed.

  if (!mode.identity) throw new Error("not logged in -- press l to log in first");

  await callRemoteTool(repoSlug, "ask_post", { lane_id: laneId, kind: "work", from: mode.identity.username, payload: { description }, depends_on: [] });

  } else {

  let localAgent: string | undefined;

  try {

  localAgent = readConfig({ allowEmpty: true }).agent;

  } catch {

  // no ~/.zz/config.json agent set -- fall through to the default below

  }

  await ask(repoSlug, laneId, { kind: "work", from: localAgent ?? "local-user", payload: { description } });

  }

  };

  enterFullscreen();

  render(

  React.createElement(TopApp, {

  watch,

  remote: mode.useRemote,

  local: !mode.useRemote,

  onTrack,

  identityUsername: mode.identity?.username ?? null,

  onLogin,

  onLogout,

  onPostAsk,

  }),

  );

 }