775944c · cf2e419 · 01c1ba5 · c41f946 · 6035f0a · 144c086
@@ -5,3 +5,5 @@
Read `CLAUDE.md` first: it is the rulebook for agents editing this repo.
README.md is capped: a new feature's how-to goes in `docs/features/<name>.md`, not a new README section.
When you write an issue, end it with a `Files:` line naming the files the work touches (`Files: src/a.ts, docs/b.md`). The hot-file hold reads only that line when it is there; without it, every path the issue mentions counts.
A new `forge` command is a new file in `src/cli/commands/` (exporting `command`) plus one line in its `index.ts`.
@@ -0,0 +1,196 @@
import { ForgeApi, type Ask, type Bulk } from "../api.ts";
import { parseWish, pickAsks, type Wish } from "../decide.ts";
import { askLine, type Io } from "../io.ts";
import { parseRepoRef, type Args } from "../args.ts";
import { requireConfig } from "../context.ts";
import { EXIT } from "../exit.ts";
import { inert, type Out } from "../out.ts";
import { displayWidth, pad, truncate } from "../../tui/term/width.ts";
import type { Command } from "./types.ts";
/**
 * What waits on you, one line each, in the order the forge ranks it: kind,
 * repository, title cut to the terminal, and the address to decide it at.
 */
export async function asks(
  out: Out,
  args: Args,
  argv: readonly string[] = [],
  confirm: Confirm = confirmOn({ ask: askLine }),
): Promise<number> {
  const wish = parseWish(argv);
  if (typeof wish === "string") {
    out.err(`forge asks: ${wish}`);
    return EXIT.usage;
  }
  const only = args.value("repo");
  const ref = only === undefined ? undefined : parseRepoRef(only);
  if (only !== undefined && ref === undefined) {
    out.err("forge asks: --repo expects owner/name");
    return EXIT.usage;
  }
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const api = new ForgeApi(loaded.url, loaded.token);
  const answer = await api.asks();
  if (!answer.ok) {
    out.err(`forge asks: ${answer.error.message}`);
    return answer.error.status === 401 ? EXIT.notConfigured : EXIT.failed;
  }
  const repo = ref === undefined ? undefined : `${ref.owner}/${ref.name}`;
  if (wish !== undefined && wish.action === "undo")
    return decide(out, api, wish, [], true, confirm);
  if (wish !== undefined) {
    const rows = answer.value.asks.filter(
      (a) => repo === undefined || a.repo === repo,
    );
    return decide(out, api, wish, rows, args.flag("yes"), confirm);
  }
  if (args.flag("json")) {
    const raw = answer.value.raw;
    out.line(JSON.stringify(repo === undefined ? raw : onlyRepo(raw, repo)));
    return EXIT.ok;
  }
  const rows = answer.value.asks.filter(
    (a) => repo === undefined || a.repo === repo,
  );
  if (rows.length === 0) {
    out.line("Nothing waits on you.");
    return EXIT.ok;
  }
  const numberW = String(rows.length).length;
  const lines = askLines(rows, out.width - numberW - 2, out);
  lines.forEach((line, i) =>
    out.line(`${String(i + 1).padStart(numberW)}  ${line}`),
  );
  return EXIT.ok;
}
/** A y/N from the person at the keyboard, undefined when there is none. */
const confirmOn =
  (io: Io): Confirm =>
  async (question) => {
    const line = await io.ask(question);
    return line === null ? undefined : /^\s*y(es)?\s*$/i.test(line);
  };
/** Whether to go ahead: undefined when there is no one to ask. */
export type Confirm = (question: string) => Promise<boolean | undefined>;
/**
 * Decide asks by the numbers of the list just read: the plan first, then,
 * after a yes (or `--yes`), the deed and the line that undoes it.
 */
async function decide(
  out: Out,
  api: ForgeApi,
  wish: Wish,
  rows: readonly Ask[],
  yes: boolean,
  confirm: Confirm,
): Promise<number> {
  const fail = (e: { message: string; status: number }): number => {
    out.err(`forge asks: ${e.message}`);
    return e.status === 401 ? EXIT.notConfigured : EXIT.failed;
  };
  if (wish.action === "undo") {
    const back = await api.undo(wish.numbers[0]!);
    if (!back.ok) return fail(back.error);
    printBulk(out, back.value, "undo", true);
    return EXIT.ok;
  }
  const ids = pickAsks(wish.numbers, rows);
  if (!Array.isArray(ids)) {
    out.err(`forge asks: ${ids.refused}`);
    return EXIT.usage;
  }
  const plan = await api.bulk(wish.action, ids, wish.reason, true);
  if (!plan.ok) return fail(plan.error);
  printBulk(out, plan.value, wish.action, false);
  const changes = plan.value.rows.filter((r) => r.outcome === "change").length;
  if (changes === 0) {
    out.line("Nothing would change.");
    return EXIT.ok;
  }
  if (!yes) {
    const said = await confirm("Apply? [y/N] ");
    if (said === undefined) {
      out.err("forge asks: not applied — no terminal to ask on; add --yes");
      return EXIT.usage;
    }
    if (!said) {
      out.line("Nothing applied.");
      return EXIT.ok;
    }
  }
  const done = await api.bulk(wish.action, ids, wish.reason, false);
  if (!done.ok) return fail(done.error);
  printBulk(out, done.value, wish.action, true);
  if (done.value.id !== undefined) {
    out.line(`Receipt ${inert(done.value.id)}`);
    out.line(`Undo: forge asks --undo ${inert(done.value.id)}`);
  }
  return EXIT.ok;
}
function printBulk(out: Out, bulk: Bulk, action: string, done: boolean): void {
  out.line(done ? `Applied: ${action}` : `Would ${action}:`);
  for (const r of bulk.rows) {
    const move = r.before === r.after ? "" : `  ${r.before} → ${r.after}`;
    const why = r.reason === "" ? "" : `  (${r.reason})`;
    out.line(`  ${pad(inert(r.outcome), 9)} ${inert(r.label)}${inert(move)}${inert(why)}`);
  }
  for (const s of bulk.skipped)
    out.line(`  skipped   ${inert(s.item)}  (${inert(s.reason)})`);
}
/**
 * The asks as lines no wider than `width - 1`, so none wraps on its own:
 * kind and repository padded to their widest, the address whole, and the
 * title cut to what those leave. Coloured only when `out` is given.
 */
export function askLines(
  rows: readonly Ask[],
  width: number,
  out?: Pick<Out, "paint" | "c">,
): string[] {
  const kindW = Math.max(...rows.map((a) => displayWidth(inert(a.kind))));
  const repoW = Math.max(...rows.map((a) => displayWidth(inert(a.repo))));
  return rows.map((a) => {
    const url = inert(a.url);
    // Three two-space gaps; the title gets what the other columns leave.
    const room = Math.max(1, width - 1 - kindW - repoW - displayWidth(url) - 6);
    const kind = pad(inert(a.kind), kindW);
    return [
      out === undefined ? kind : out.paint(kind, out.c.accent),
      pad(inert(a.repo), repoW),
      truncate(inert(a.title), room),
      out === undefined ? url : out.paint(url, out.c.faint),
    ].join("  ");
  });
}
/**
 * The API's answer with only one repository's rows; the forge's own needs
 * belong to none.
 */
function onlyRepo(raw: unknown, repo: string): unknown {
  if (typeof raw !== "object" || raw === null) return raw;
  const body = raw as { rows?: unknown };
  return {
    ...body,
    rows: Array.isArray(body.rows)
      ? body.rows.filter((r) => (r as { repo?: unknown } | null)?.repo === repo)
      : body.rows,
    forge: [],
  };
}
export const command: Command = {
  name: "asks",
  usage: {
    synopsis: "forge asks",
    flags: "[--repo owner/name] [--json] | --ship|--close|--dismiss <n…> [--reason words] [--yes]",
  },
  run: (out, args, _help, io, argv) => asks(out, args, argv, confirmOn(io)),
};
@@ -0,0 +1,36 @@
/**
 * Every `forge` subcommand, in the order `forge help` lists them. A new
 * command is a new file in this directory plus one line here.
 */
import { command as ui } from "./ui.ts";
import { command as login } from "./login.ts";
import { command as logout } from "./logout.ts";
import { command as whoami } from "./whoami.ts";
import { command as sync } from "./sync.ts";
import { command as status } from "./status.ts";
import { command as ls } from "./ls.ts";
import { command as pin } from "./pin.ts";
import { command as unpin } from "./unpin.ts";
import { command as open } from "./open.ts";
import { command as pulls } from "./pulls.ts";
import { command as asks } from "./asks.ts";
import { command as search } from "./search.ts";
import { command as ship } from "./ship.ts";
import type { Command } from "./types.ts";
export const commands: readonly Command[] = [
  ui,
  login,
  logout,
  whoami,
  sync,
  status,
  ls,
  pin,
  unpin,
  open,
  pulls,
  asks,
  search,
  ship,
];
@@ -0,0 +1,101 @@
import { ForgeApi } from "../api.ts";
import type { Args } from "../args.ts";
import {
  configPath,
  normalizeUrl,
  PLAIN_HTTP_REFUSAL,
  plainHttpRemote,
  saveConfig,
} from "../config.ts";
import { EXIT } from "../exit.ts";
import type { Out } from "../out.ts";
import { G } from "../../tui/term/screen.ts";
import type { Command } from "./types.ts";
async function login(out: Out, args: Args): Promise<number> {
  const raw = args.positional[0] ?? args.value("url");
  if (raw === undefined) {
    out.err("forge login: which forge? e.g. forge login forge.example.com");
    return EXIT.usage;
  }
  const url = normalizeUrl(raw);
  // Before the token is asked for, let alone sent: nothing crosses the
  // network in clear unless the person said this host is one they trust.
  const insecure = args.flag("insecure");
  if (plainHttpRemote(url) && !insecure) {
    out.err(`forge login: ${PLAIN_HTTP_REFUSAL}`);
    return EXIT.usage;
  }
  const token = args.value("token") ?? (await askSecret(`Token for ${url}: `));
  if (token === "") {
    out.err("forge login: no token given");
    return EXIT.usage;
  }
  // Verify before storing: a config that does not work is worse than none.
  const api = new ForgeApi(url, token);
  const me = await api.whoami();
  if (!me.ok) {
    out.err(`forge login: ${me.error.message}`);
    return me.error.status === 401 ? EXIT.notConfigured : EXIT.failed;
  }
  const stored = await saveConfig({ url, token }, { insecure });
  out.line(
    `${out.paint(G.check, out.c.success)} signed in to ${url} as ${me.value.username}`,
  );
  out.line(
    out.paint(
      stored.keychain
        ? `  token in your login keychain; ${configPath()} holds only the URL`
        : `  token in ${configPath()} (0600)`,
      out.c.faint,
    ),
  );
  return EXIT.ok;
}
/**
 * A secret, read without echo. Raw mode is the only way to stop the terminal
 * printing it, and it is restored on every path — including ctrl+c, which
 * here means "no token", not "leave the tty broken".
 */
async function askSecret(prompt: string): Promise<string> {
  const stdin = process.stdin;
  if (stdin.isTTY !== true) {
    // Piped input: read one line. `echo $TOKEN | forge login url` is a
    // legitimate way to do this from a script.
    const text = await new Response(Bun.stdin.stream()).text();
    return text.split("\n")[0]?.trim() ?? "";
  }
  process.stdout.write(prompt);
  stdin.setRawMode(true);
  stdin.resume();
  return new Promise<string>((resolve) => {
    let value = "";
    const finish = (result: string): void => {
      stdin.off("data", onData);
      stdin.setRawMode(false);
      stdin.pause();
      process.stdout.write("\n");
      resolve(result);
    };
    const onData = (chunk: Buffer): void => {
      for (const byte of chunk) {
        if (byte === 3) return finish(""); // ctrl+c
        if (byte === 13 || byte === 10) return finish(value.trim());
        if (byte === 127 || byte === 8) {
          value = value.slice(0, -1);
          continue;
        }
        if (byte >= 0x20) value += String.fromCharCode(byte);
      }
    };
    stdin.on("data", onData);
  });
}
export const command: Command = {
  name: "login",
  usage: { synopsis: "forge login <url>", flags: "[--token T] [--insecure]" },
  run: login,
};
@@ -0,0 +1,13 @@
import { clearConfig } from "../config.ts";
import { EXIT } from "../exit.ts";
import type { Command } from "./types.ts";
export const command: Command = {
  name: "logout",
  usage: { synopsis: "forge logout" },
  async run(out) {
    await clearConfig();
    out.line("signed out");
    return EXIT.ok;
  },
};
@@ -0,0 +1,56 @@
import { ForgeApi } from "../api.ts";
import { rootDir } from "../config.ts";
import { asJson, requireConfig } from "../context.ts";
import { EXIT } from "../exit.ts";
import { cell, type Out } from "../out.ts";
import { dirtyCount, settled, since } from "../report.ts";
import { syncOnce, type RepoReport } from "../sync.ts";
import { G } from "../../tui/term/screen.ts";
import { trackText } from "../../tui/local/common.ts";
import type { Command } from "./types.ts";
function lsState(out: Out, r: RepoReport): ReturnType<typeof cell> {
  if (!r.present) return cell("not cloned", out.c.attn);
  const dirty = dirtyCount(r);
  if (dirty > 0) return cell(`${dirty} dirty`, out.c.accent);
  if (settled(r)) return cell(G.check, out.c.success);
  return cell(r.upstream === null ? "no upstream" : "", out.c.faint);
}
export const command: Command = {
  name: "ls",
  usage: { synopsis: "forge ls", flags: "[--json]" },
  async run(out, args) {
    const loaded = await requireConfig(out);
    if (typeof loaded === "number") return loaded;
    // `ls` answers from disk, so it keeps working when the forge does not.
    const report = await syncOnce({
      api: new ForgeApi(loaded.url, loaded.token),
      token: loaded.token,
      root: rootDir(args.value("root")),
      fetch: false,
    });
    if (args.flag("json")) {
      out.line(JSON.stringify(asJson(report)));
      return EXIT.ok;
    }
    out.line(out.paint(report.root, out.c.faint));
    out.table(
      [
        { header: "REPO", max: 44 },
        { header: "BRANCH", max: 24 },
        { header: "SYNC", align: "right" },
        { header: "STATE", max: 28 },
        { header: "FETCHED", align: "right" },
      ],
      report.repos.map((r) => [
        cell(`${r.owner}/${r.name}`, r.present ? out.c.fg : out.c.mutedFg),
        cell(r.present ? (r.branch ?? "detached") : "—", out.c.mutedFg),
        cell(trackText(r.ahead, r.behind), out.c.attn),
        lsState(out, r),
        cell(r.present ? since(r.lastFetch) : "", out.c.faint),
      ]),
    );
    return EXIT.ok;
  },
};
@@ -0,0 +1,37 @@
import { ForgeApi } from "../api.ts";
import { parseRepoRef } from "../args.ts";
import { requireConfig } from "../context.ts";
import { EXIT } from "../exit.ts";
import type { Command } from "./types.ts";
export const command: Command = {
  name: "open",
  usage: { synopsis: "forge open <owner/name>", flags: "[--web]" },
  async run(out, args) {
    const ref = parseRepoRef(args.positional[0]);
    if (ref === undefined) {
      out.err("forge open: expected owner/name");
      return EXIT.usage;
    }
    const loaded = await requireConfig(out);
    if (typeof loaded === "number") return loaded;
    const url = new ForgeApi(loaded.url, loaded.token).webUrl(
      ref.owner,
      ref.name,
    );
    out.line(url);
    if (!args.flag("web")) return EXIT.ok;
    const opener = process.platform === "darwin" ? "open" : "xdg-open";
    try {
      const proc = Bun.spawn([opener, url], {
        stdout: "ignore",
        stderr: "ignore",
      });
      await proc.exited;
    } catch {
      out.err(`forge open: could not run ${opener}`);
      return EXIT.failed;
    }
    return EXIT.ok;
  },
};
@@ -0,0 +1,47 @@
import { ForgeApi } from "../api.ts";
import { parseRepoRef, type Args } from "../args.ts";
import { requireConfig } from "../context.ts";
import { EXIT } from "../exit.ts";
import type { Out } from "../out.ts";
import { G } from "../../tui/term/screen.ts";
import type { Command } from "./types.ts";
/** Shared by `pin` and `unpin`: the two differ only in the call and the verb. */
export async function setPin(
  out: Out,
  args: Args,
  on: boolean,
): Promise<number> {
  const verb = on ? "pin" : "unpin";
  const ref = parseRepoRef(args.positional[0]);
  if (ref === undefined) {
    out.err(`forge ${verb}: expected owner/name`);
    return EXIT.usage;
  }
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const api = new ForgeApi(loaded.url, loaded.token);
  const result = on
    ? await api.pin(ref.owner, ref.name)
    : await api.unpin(ref.owner, ref.name);
  if (!result.ok) {
    out.err(
      result.error.status === 404
        ? `forge ${verb}: this forge does not support pins yet`
        : `forge ${verb}: ${result.error.message}`,
    );
    return EXIT.failed;
  }
  out.line(
    `${out.paint(G.check, out.c.success)} ${on ? "pinned" : "unpinned"} ${ref.owner}/${ref.name}`,
  );
  if (on)
    out.line(out.paint("  run `forge sync` to bring it down", out.c.faint));
  return EXIT.ok;
}
export const command: Command = {
  name: "pin",
  usage: { synopsis: "forge pin <owner/name>" },
  run: (out, args) => setPin(out, args, true),
};
@@ -0,0 +1,96 @@
import { ForgeApi } from "../api.ts";
import { parseRepoRef, type Args } from "../args.ts";
import { requireConfig } from "../context.ts";
import { EXIT } from "../exit.ts";
import { folderRepo } from "../folder-repo.ts";
import { inert, type Out } from "../out.ts";
import { displayWidth, pad, truncate } from "../../tui/term/width.ts";
import type { Command } from "./types.ts";
async function pulls(out: Out, args: Args): Promise<number> {
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const flagged = args.value("repo");
  const ref =
    flagged !== undefined
      ? parseRepoRef(flagged)
      : await folderRepo(process.cwd(), loaded.url);
  if (ref === undefined) {
    out.err(
      flagged !== undefined
        ? "forge pulls: --repo expects owner/name"
        : `forge pulls: this folder is not a clone of ${loaded.url} — run it in a clone, or pass --repo owner/name`,
    );
    return EXIT.usage;
  }
  const closed = args.flag("closed");
  const got = await new ForgeApi(loaded.url, loaded.token).pulls(
    ref.owner,
    ref.name,
    closed ? "closed" : "open",
  );
  if (!got.ok) {
    out.err(`forge pulls: ${got.error.message}`);
    return EXIT.failed;
  }
  if (args.flag("json")) {
    out.line(JSON.stringify(got.value));
    return EXIT.ok;
  }
  const items = got.value.items as Record<string, unknown>[];
  if (items.length === 0) {
    out.line(closed ? "No closed pulls." : "No open pulls.");
    return EXIT.ok;
  }
  const tone = {
    green: out.c.success,
    red: out.c.danger,
    running: out.c.attn,
    none: out.c.faint,
  } as const;
  const rows = items.map((item) => ({
    number: `#${String(item["number"])}`,
    title: inert(String(item["title"] ?? "")),
    author: inert(String(item["author"] ?? "")),
    check: String(item["check"]) as keyof typeof tone,
    preview: inert(typeof item["preview"] === "string" ? item["preview"] : ""),
  }));
  const wide = (pick: (r: (typeof rows)[number]) => string): number =>
    Math.max(...rows.map((r) => displayWidth(pick(r))));
  const nW = wide((r) => r.number);
  const aW = Math.min(
    20,
    wide((r) => r.author),
  );
  const cW = wide((r) => r.check);
  const pW = wide((r) => r.preview);
  const gaps = 2 * (pW > 0 ? 4 : 3);
  const tW = Math.max(12, out.width - nW - aW - cW - pW - gaps);
  for (const r of rows) {
    const parts = [
      pad(r.number, nW, "right"),
      pad(truncate(r.title, tW), tW),
      pad(truncate(r.author, aW), aW),
      out.paint(pad(r.check, cW), tone[r.check] ?? out.c.faint),
    ];
    if (pW > 0) parts.push(r.preview);
    out.line(parts.join("  ").replace(/\s+$/, ""));
  }
  if (got.value.next_cursor !== null)
    out.line(
      out.paint(
        `The list is cut after ${rows.length} pulls; the forge has more.`,
        out.c.faint,
      ),
    );
  return EXIT.ok;
}
export const command: Command = {
  name: "pulls",
  usage: {
    synopsis: "forge pulls",
    flags: "[--repo owner/name] [--closed] [--json]",
  },
  run: pulls,
};
@@ -0,0 +1,214 @@
import { ForgeApi } from "../api.ts";
import type { Args } from "../args.ts";
import { requireConfig } from "../context.ts";
import { EXIT } from "../exit.ts";
import { printUsage } from "../help.ts";
import { inert, type Out } from "../out.ts";
import { displayWidth, pad, truncate } from "../../tui/term/width.ts";
import type { Command } from "./types.ts";
/** The forge's default and ceiling for `limit` (`src/actions/search.ts`). */
const SEARCH_API_LIMIT = 20;
const SEARCH_API_LIMIT_MAX = 100;
const SEARCH_KINDS = ["code", "issues", "pulls", "repos", "all"] as const;
export type SearchFor = (typeof SEARCH_KINDS)[number];
/**
 * `GET /api/v1/search` from a shell: every hit one line, grouped by kind.
 * The API has no `pulls` kind — its `issues` answers both — so `--kind
 * issues` and `--kind pulls` ask for `issues` at the API's ceiling and
 * keep N of the one kind (`narrowConversations`): asking for N and then
 * filtering would print fewer than N, or none.
 */
async function search(out: Out, args: Args): Promise<number> {
  const words = args.positional.join(" ").trim();
  if (words === "") {
    out.err("forge search: what for? e.g. forge search retry budget");
    printUsage(out);
    return EXIT.usage;
  }
  const kindRaw = args.value("kind");
  const kind = SEARCH_KINDS.find((k) => k === kindRaw);
  if (kindRaw !== undefined && kind === undefined) {
    out.err(`forge search: --kind is one of ${SEARCH_KINDS.join(", ")}`);
    return EXIT.usage;
  }
  const limitRaw = args.value("limit");
  const limit = limitRaw === undefined ? undefined : Number(limitRaw);
  if (limit !== undefined && (!/^\d+$/.test(limitRaw!) || limit < 1)) {
    out.err("forge search: --limit expects a whole number above 0");
    return EXIT.usage;
  }
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const oneConversation = kind === "issues" || kind === "pulls";
  const answer = await new ForgeApi(loaded.url, loaded.token).search(words, {
    ...(kind === undefined ? {} : { kind: oneConversation ? "issues" : kind }),
    ...(oneConversation
      ? { limit: SEARCH_API_LIMIT_MAX }
      : limit === undefined ? {} : { limit }),
  });
  if (!answer.ok) {
    const { message, retryAfter, status } = answer.error;
    const when =
      retryAfter === undefined || new RegExp(`\\b${retryAfter}s\\b`).test(message)
        ? ""
        : ` (retry in ${retryAfter}s)`;
    out.err(`forge search: ${message}${when}`);
    if (status === 429) return EXIT.rateLimited;
    return status === 401 ? EXIT.notConfigured : EXIT.failed;
  }
  const found = oneConversation
    ? narrowConversations(answer.value, kind, limit ?? SEARCH_API_LIMIT)
    : answer.value;
  if (args.flag("json")) {
    out.line(JSON.stringify(found));
    return EXIT.ok;
  }
  const lines = searchLines(found, kind ?? "all", out.width, out);
  if (lines.length === 0) {
    out.line(`Nothing found for "${inert(words)}".`);
    return EXIT.ok;
  }
  for (const line of lines) out.line(line);
  return EXIT.ok;
}
/**
 * The answer with `issues` kept to one kind (`issue` or `pull`) and cut to
 * `limit`; `truncated.issues` is set when the cut dropped any, or when the
 * forge had already cut its own window, so `--json` and the group header
 * both say the list is not whole. Everything else passes through.
 */
export function narrowConversations(
  raw: unknown,
  kind: "issues" | "pulls",
  limit: number,
): unknown {
  if (typeof raw !== "object" || raw === null) return raw;
  const body = raw as Record<string, unknown>;
  const want = kind === "pulls" ? "pull" : "issue";
  const kept = rowsOf(body["issues"]).filter((r) => r["kind"] === want);
  const truncated = (typeof body["truncated"] === "object" && body["truncated"] !== null
    ? body["truncated"]
    : {}) as Record<string, unknown>;
  return {
    ...body,
    issues: kept.slice(0, limit),
    truncated: { ...truncated, issues: truncated["issues"] === true || kept.length > limit },
  };
}
/**
 * The search answer as lines no wider than `width - 1` where the text can
 * give way: each kind headed by its name and count, then one hit a line —
 * `owner/name:path:line  text` for code, `owner/name#N  title  state` for
 * issues and pulls, `owner/name  description` for repositories. Anything
 * the answer carries that is not the expected shape is skipped, not fatal.
 */
export function searchLines(
  raw: unknown,
  kind: SearchFor,
  width: number,
  out?: Pick<Out, "paint" | "c">,
): string[] {
  const body = (typeof raw === "object" && raw !== null ? raw : {}) as Record<string, unknown>;
  const truncated = (body["truncated"] ?? {}) as Record<string, unknown>;
  const conversations = rowsOf(body["issues"]).map(conversationRow);
  const groups: { kind: SearchFor; rows: [string, string, string][]; more: boolean }[] = [
    { kind: "code", rows: rowsOf(body["code"]).map(codeRow), more: truncated["code"] === true },
    {
      kind: "issues",
      rows: conversations.filter((r) => r[0] === "issue").map((r) => r.slice(1) as [string, string, string]),
      more: truncated["issues"] === true,
    },
    {
      kind: "pulls",
      rows: conversations.filter((r) => r[0] === "pull").map((r) => r.slice(1) as [string, string, string]),
      more: truncated["issues"] === true,
    },
    { kind: "repos", rows: rowsOf(body["repos"]).map(repoRow), more: truncated["repos"] === true },
  ];
  const lines: string[] = [];
  for (const group of groups) {
    const rows = group.rows.filter((r) => r[0] !== "");
    if (rows.length === 0 || (kind !== "all" && kind !== group.kind)) continue;
    if (lines.length > 0) lines.push("");
    const head = `${group.kind} (${rows.length}${group.more ? ", more not shown" : ""})`;
    lines.push(out === undefined ? head : out.paint(head, out.c.accent));
    // Code's place differs in width line to line; the others line up.
    const leadW = group.kind === "code" ? 0 : Math.max(...rows.map((r) => displayWidth(r[0])));
    const tails = rows.some((r) => r[2] !== "");
    const tailW = tails ? Math.max(...rows.map((r) => displayWidth(r[2]))) + 2 : 0;
    const textW = Math.max(...rows.map((r) => displayWidth(r[1])));
    for (const [lead, text, tail] of rows) {
      const first = leadW === 0 ? lead : pad(lead, leadW);
      const room = Math.max(8, width - 1 - displayWidth(first) - 2 - tailW);
      const cut = truncate(text, room);
      const shown = tails ? pad(cut, Math.min(room, textW)) : cut;
      lines.push(
        [
          first,
          shown,
          ...(tail === "" ? [] : [out === undefined ? tail : out.paint(tail, out.c.faint)]),
        ].join("  ").trimEnd(),
      );
    }
    if (group.kind === "code" && (body["moreCode"] === true || body["codeSkipped"] === true)) {
      const note = "  some repositories were not searched in time; --json says which kinds are partial";
      lines.push(out === undefined ? note : out.paint(note, out.c.faint));
    }
  }
  return lines;
}
function rowsOf(value: unknown): Record<string, unknown>[] {
  return Array.isArray(value)
    ? value.filter((v): v is Record<string, unknown> => typeof v === "object" && v !== null)
    : [];
}
/** `owner/name` from a local hit's `repo`, or an origin hit's `fullName`. */
function repoName(r: Record<string, unknown>): string {
  const repo = r["repo"] as Record<string, unknown> | undefined;
  if (typeof repo?.["owner"] === "string" && typeof repo["name"] === "string")
    return `${repo["owner"]}/${repo["name"]}`;
  if (typeof r["owner"] === "string" && typeof r["name"] === "string")
    return `${r["owner"]}/${r["name"]}`;
  return typeof r["fullName"] === "string" ? r["fullName"] : "";
}
function textOf(value: unknown): string {
  return typeof value === "string" ? inert(value) : "";
}
function codeRow(r: Record<string, unknown>): [string, string, string] {
  const name = repoName(r);
  const path = textOf(r["path"]);
  const line = typeof r["line"] === "number" ? r["line"] : 0;
  if (name === "" || path === "") return ["", "", ""];
  return [`${inert(name)}:${path}:${line}`, textOf(r["text"]).trim(), ""];
}
function conversationRow(r: Record<string, unknown>): [string, string, string, string] {
  const name = repoName(r);
  const n = r["number"];
  if (name === "" || typeof n !== "number") return ["", "", "", ""];
  return [textOf(r["kind"]), `${inert(name)}#${n}`, textOf(r["title"]), textOf(r["state"])];
}
function repoRow(r: Record<string, unknown>): [string, string, string] {
  const name = repoName(r);
  return [inert(name), textOf(r["description"]), r["archived"] === true ? "archived" : ""];
}
export const command: Command = {
  name: "search",
  usage: {
    synopsis: "forge search <words…>",
    flags: "[--kind code|issues|pulls|repos|all] [--limit N] [--json]",
  },
  run: search,
};
@@ -0,0 +1,84 @@
import { ForgeApi, type ApiError } from "../api.ts";
import type { Args } from "../args.ts";
import { requireConfig } from "../context.ts";
import { EXIT } from "../exit.ts";
import { resolveRepo } from "../here.ts";
import type { Io } from "../io.ts";
import { inert, type Out } from "../out.ts";
import { G } from "../../tui/term/screen.ts";
import type { Command } from "./types.ts";
/**
 * `forge ship 12`: read the pull, show it, ask, merge. The merge route's
 * rules stay the server's — this adds none and retries nothing; a refusal
 * prints the forge's own words.
 */
async function ship(out: Out, args: Args, io: Io): Promise<number> {
  const raw = args.positional[0];
  const number = raw === undefined ? NaN : Number(raw.replace(/^#/, ""));
  if (!Number.isSafeInteger(number) || number < 1) {
    out.err("forge ship: which pull? e.g. forge ship 12");
    return EXIT.usage;
  }
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const ref = await resolveRepo(args.value("repo"), loaded.url);
  if (typeof ref === "string") {
    out.err(`forge ship: ${ref}`);
    return EXIT.usage;
  }
  const api = new ForgeApi(loaded.url, loaded.token);
  const pull = await api.pull(ref.owner, ref.name, number);
  if (!pull.ok) return shipError(out, pull.error);
  const check = await api.pullCheck(ref.owner, ref.name, number);
  const p = pull.value;
  out.line(`${ref.owner}/${ref.name}#${p.number}  ${inert(p.title)}`);
  const facts = [
    `check ${check.ok ? inert(check.value) : "unknown"}`,
    p.merged
      ? "already merged"
      : p.state !== "open"
        ? p.state
        : p.mergeable === false
          ? "not mergeable"
          : p.mergeable === true
            ? "mergeable"
            : "mergeable unknown",
    ...(p.held ? ["held"] : []),
  ];
  out.line(out.paint(`  ${facts.join(" · ")}`, out.c.faint));
  if (!args.flag("yes")) {
    const answer = await io.ask(`Ship #${p.number}? [y/N] `);
    if (answer === null) {
      out.err("forge ship: not a terminal — pass --yes to ship without asking");
      return EXIT.usage;
    }
    if (answer.trim().toLowerCase() !== "y") {
      out.line("not shipped");
      return EXIT.ok;
    }
  }
  const merged = await api.merge(ref.owner, ref.name, number);
  if (!merged.ok) return shipError(out, merged.error);
  out.line(
    `${out.paint(G.check, out.c.success)} shipped #${p.number} as ${merged.value.mergeOid.slice(0, 7)}`,
  );
  out.line(api.pullUrl(ref.owner, ref.name, number));
  return EXIT.ok;
      
        junipercrew
        17d ago
        
      
      Non-blocking: add a blank line before shipError and run prettier on this file.
    
      
        junipercrew
        13d ago
        
      
      Non-blocking: blank line between ship and shipError, as in the other modules.
    
}
function shipError(out: Out, error: ApiError): number {
  out.err(`forge ship: ${inert(error.message)}`);
  if (error.status === 401) return EXIT.notConfigured;
  if (error.status === 403 || error.status === 409 || error.status === 422)
    return EXIT.refused;
  return EXIT.failed;
}
export const command: Command = {
  name: "ship",
  usage: { synopsis: "forge ship <number>", flags: "[--repo owner/name] [--yes]" },
  run: (out, args, _help, io) => ship(out, args, io),
};
@@ -0,0 +1,8 @@
import { runSync } from "./sync.ts";
import type { Command } from "./types.ts";
export const command: Command = {
  name: "status",
  usage: { synopsis: "forge status", flags: "[--root DIR] [--json]" },
  run: (out, args) => runSync(out, args, false),
};
@@ -0,0 +1,102 @@
import { ForgeApi } from "../api.ts";
import { parseDuration, type Args } from "../args.ts";
import { rootDir } from "../config.ts";
import { asJson, requireConfig } from "../context.ts";
import { EXIT } from "../exit.ts";
import { systemNotifier } from "../notify.ts";
import type { Out } from "../out.ts";
import { printReport } from "../report.ts";
import { changesBetween, syncOnce, type SyncReport } from "../sync.ts";
import type { Command } from "./types.ts";
export async function runSync(
      
        junipercrew
        17d ago
        outdated
      
      Signature is over 80 columns; format it like its neighbours.
    
  out: Out,
  args: Args,
  network: boolean,
): Promise<number> {
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const api = new ForgeApi(loaded.url, loaded.token);
  const root = rootDir(args.value("root"));
  const ff = args.flag("ff");
  const json = args.flag("json");
  const once = async (
    previous: SyncReport | null,
    quiet: boolean,
  ): Promise<SyncReport> => {
    const report = await syncOnce({
      api,
      token: loaded.token,
      root,
      fetch: network,
      ff,
      ...(quiet || json || !out.color
        ? {}
        : { onProgress: (repo, text) => status(out, `${repo}: ${text}`) }),
    });
    if (!quiet && !json && out.color) status(out, "");
    if (previous === null || !quiet) {
      if (json) out.line(JSON.stringify(asJson(report)));
      else printReport(out, report);
    }
    return report;
  };
  if (!args.flag("watch")) {
    const report = await once(null, false);
    return report.failures > 0 ? EXIT.partial : EXIT.ok;
  }
  const interval = parseDuration(args.value("interval")) ?? 300_000;
  const notify = systemNotifier();
  let previous = await once(null, false);
  if (!json) {
    out.line();
    out.line(
      out.paint(
        `watching ${previous.repos.length} repos every ${args.value("interval") ?? "5m"} — ctrl+c to stop`,
        out.c.faint,
      ),
    );
  }
  for (;;) {
    await sleep(interval);
    const report = await once(previous, true);
    const changes = changesBetween(previous, report);
    previous = report;
    // Only a real transition reaches the user; everything else is the
    // report, which is there when they choose to look at it. A watch that
    // notified on every pass would be muted within the hour.
    if (changes.length === 0) continue;
    if (json) out.line(JSON.stringify({ ...asJson(report), changes }));
    else {
      out.line();
      out.line(new Date().toLocaleTimeString());
      printReport(out, report);
    }
    await notify("forge", changes.slice(0, 4).join("\n"));
  }
}
/** One transient line, overwritten in place. Never printed to a pipe. */
function status(out: Out, text: string): void {
  if (!out.color) return;
  const room = Math.max(0, out.width - 1);
  process.stdout.write(`\r\x1b[K${text.slice(0, room)}`);
  if (text === "") process.stdout.write("\r");
}
function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}
export const command: Command = {
  name: "sync",
  usage: {
    synopsis: "forge sync",
    flags: "[--watch] [--interval 5m] [--ff] [--root DIR]",
  },
  run: (out, args) => runSync(out, args, true),
};
@@ -0,0 +1,21 @@
import type { Args } from "../args.ts";
import type { Io } from "../io.ts";
import type { Out } from "../out.ts";
/**
 * One `forge` subcommand. `usage` is its line in `forge help`: the synopsis
 * is painted, `flags` is the plain text after it.
 */
export interface Command {
  name: string;
  usage: { synopsis: string; flags?: string };
  /** `help` prints the usage; it is handed in so commands never import it. */
  run(
    out: Out,
    args: Args,
    help: (out: Out) => void,
    io: Io,
    /** What followed the command name, as typed. */
    argv: readonly string[],
  ): Promise<number>;
}
@@ -0,0 +1,26 @@
import { loadConfig, PLAIN_HTTP_REFUSAL, rootDir } from "../config.ts";
import { EXIT } from "../exit.ts";
import type { Command } from "./types.ts";
      
        junipercrew
        17d ago
        outdated
      
      Cycle: help.ts -> commands/index.ts -> ui.ts -> help.ts. Inject the usage printer instead of importing it.
    
export const command: Command = {
  name: "ui",
  usage: { synopsis: "forge", flags: "the local terminal UI" },
  async run(out, args, help) {
    if (process.stdout.isTTY !== true) {
      help(out);
      return EXIT.usage;
    }
    const loaded = await loadConfig();
    if (loaded === "plain_http") {
      out.err(`forge: ${PLAIN_HTTP_REFUSAL}`);
      return EXIT.usage;
    }
    const config = typeof loaded === "string" ? null : loaded.config;
    const { runLocalTui } = await import("../../tui/local/app.ts");
    await runLocalTui({
      root: rootDir(args.value("root")),
      ...(config === null ? {} : { config }),
    });
    return EXIT.ok;
  },
};
@@ -0,0 +1,8 @@
import { setPin } from "./pin.ts";
import type { Command } from "./types.ts";
export const command: Command = {
  name: "unpin",
  usage: { synopsis: "forge unpin <owner/name>" },
  run: (out, args) => setPin(out, args, false),
};
@@ -0,0 +1,21 @@
import { ForgeApi } from "../api.ts";
import { requireConfig } from "../context.ts";
import { EXIT } from "../exit.ts";
import type { Command } from "./types.ts";
export const command: Command = {
  name: "whoami",
  usage: { synopsis: "forge whoami" },
  async run(out) {
    const loaded = await requireConfig(out);
    if (typeof loaded === "number") return loaded;
    const api = new ForgeApi(loaded.url, loaded.token);
    const me = await api.whoami();
    if (!me.ok) {
      out.err(`forge whoami: ${me.error.message}`);
      return EXIT.failed;
    }
    out.line(`${me.value.username} at ${loaded.url}`);
    return EXIT.ok;
  },
};
@@ -0,0 +1,63 @@
/** What more than one command needs: the signed-in config and the report as data. */
import {
  configPath,
  loadConfig,
  PLAIN_HTTP_REFUSAL,
  type Config,
} from "./config.ts";
import { EXIT } from "./exit.ts";
import type { Out } from "./out.ts";
import { dirtyCount } from "./report.ts";
import type { RepoReport, SyncReport } from "./sync.ts";
export async function requireConfig(out: Out): Promise<Config | number> {
  const loaded = await loadConfig();
  if (loaded === "no_config") {
    out.err("forge: not signed in — run `forge login <url>`");
    return EXIT.notConfigured;
  }
  if (loaded === "no_token") {
    out.err(`forge: ${configPath()} has no usable token — run \`forge login\``);
    return EXIT.notConfigured;
  }
  if (loaded === "plain_http") {
    out.err(`forge: ${PLAIN_HTTP_REFUSAL}`);
    return EXIT.usage;
  }
  return loaded.config;
}
/**
 * The report as data. `--json` exists so a script can branch on the same
 * facts the table shows without parsing columns — so every field the table
 * draws from is here, spelled the way the rest of the client spells it.
 */
export function asJson(report: SyncReport): Record<string, unknown> {
  return {
    root: report.root,
    pinsUnavailable: report.pinsUnavailable,
    failures: report.failures,
    repos: report.repos.map((r: RepoReport) => ({
      owner: r.owner,
      name: r.name,
      path: r.dir,
      present: r.present,
      cloned: r.cloned,
      pinned: r.pinned,
      branch: r.branch,
      upstream: r.upstream,
      ahead: r.ahead,
      behind: r.behind,
      staged: r.staged,
      changed: r.changed,
      untracked: r.untracked,
      conflicted: r.conflicted,
      dirty: dirtyCount(r),
      stashes: r.stashes,
      unpushed: r.unpushed,
      fastForwarded: r.fastForwarded,
      lastFetch: r.lastFetch === null ? null : r.lastFetch.toISOString(),
      error: r.error,
    })),
  };
}
@@ -0,0 +1,13 @@
/** The exit codes a script can branch on without parsing text. */
export const EXIT = {
  ok: 0,
  failed: 1,
  usage: 2,
  notConfigured: 3,
  /** The run completed, but at least one repo did not. */
  partial: 4,
  /** The forge heard the request and said no: a rule, a conflict, a hold. */
  refused: 5,
  /** The forge said "not now"; it named when to try again. */
  rateLimited: 6,
} as const;
@@ -0,0 +1,39 @@
import { configPath, rootDir } from "./config.ts";
import { commands } from "./commands/index.ts";
import type { Out } from "./out.ts";
/**
 * The CLI's own number, kept by hand: it ships compiled, to machines no
 * release stamps. The server's comes from its build (`kernel/version.ts`).
 */
export const VERSION = "0.0.1";
/** Where the flags column starts, so every command's notes line up. */
const FLAGS_COLUMN = 31;
/** `forge help`: one line per command, in the table's order. */
export function printUsage(out: Out): void {
  const b = (text: string): string => out.paint(text, out.c.fg);
  out.line(`forge ${VERSION} — your workbench, on this machine`);
  out.line();
  for (const { usage } of commands) {
    const head = `  ${usage.synopsis}`;
    out.line(
      usage.flags === undefined
        ? b(head)
        : b(head) +
            " ".repeat(Math.max(1, FLAGS_COLUMN - head.length)) +
            usage.flags,
    );
  }
  out.line();
  out.line(
    out.paint(`  config ${configPath()}   root ${rootDir()}`, out.c.faint),
  );
  out.line(
    out.paint(
      "  FORGE_URL, FORGE_TOKEN, FORGE_ROOT and NO_COLOR are honoured.",
      out.c.faint,
    ),
  );
}
@@ -0,0 +1,32 @@
/** What the CLI needs from the person at the keyboard; a test fakes it. */
export interface Io {
  /** One answered line, or null when there is no terminal to ask. */
  ask(prompt: string): Promise<string | null>;
}
/** One line from the terminal, echoed; null when stdin is not a terminal. */
export async function askLine(prompt: string): Promise<string | null> {
  const stdin = process.stdin;
  if (stdin.isTTY !== true || process.stdout.isTTY !== true) return null;
  process.stdout.write(prompt);
  stdin.resume();
  return new Promise<string>((resolve) => {
    // ctrl+d or a closed terminal is an answer too, and the answer is N.
    const finish = (answer: string): void => {
      stdin.off("data", onData);
      stdin.off("end", onEnd);
      stdin.off("close", onEnd);
      stdin.pause();
      resolve(answer);
    };
    const onData = (chunk: Buffer): void =>
      finish(chunk.toString("utf8").split("\n")[0] ?? "");
    const onEnd = (): void => {
      process.stdout.write("\n");
      finish("");
    };
    stdin.on("data", onData);
    stdin.once("end", onEnd);
    stdin.once("close", onEnd);
  });
}
@@ -18,62 +18,23 @@
 * an exit code — so a script can branch on the result without parsing text.
 */
import { parseArgs, parseDuration, parseRepoRef, type Args } from "./args.ts";
import { ForgeApi, type ApiError, type Ask, type Bulk } from "./api.ts";
import { parseWish, pickAsks, type Wish } from "./decide.ts";
import {
  clearConfig,
  configPath,
  loadConfig,
  normalizeUrl,
  PLAIN_HTTP_REFUSAL,
  plainHttpRemote,
  rootDir,
  saveConfig,
  type Config,
} from "./config.ts";
import { folderRepo } from "./folder-repo.ts";
import { systemNotifier } from "./notify.ts";
import { resolveRepo } from "./here.ts";
import { cell, createOut, inert, type Out } from "./out.ts";
import { dirtyCount, printReport, settled, since } from "./report.ts";
import {
  changesBetween,
  syncOnce,
  type RepoReport,
  type SyncReport,
} from "./sync.ts";
import { G } from "../tui/term/screen.ts";
import { trackText } from "../tui/local/common.ts";
import { displayWidth, pad, truncate } from "../tui/term/width.ts";
import { parseArgs } from "./args.ts";
import { commands } from "./commands/index.ts";
import { EXIT } from "./exit.ts";
import { printUsage, VERSION } from "./help.ts";
import { askLine, type Io } from "./io.ts";
import { createOut } from "./out.ts";
/**
 * The CLI's own number, kept by hand: it ships compiled, to machines no
 * release stamps. The server's comes from its build (`kernel/version.ts`).
 */
const VERSION = "0.0.1";
// Callers (and tests) have always reached these through this file.
export { asks, askLines, type Confirm } from "./commands/asks.ts";
export { searchLines, narrowConversations, type SearchFor } from "./commands/search.ts";
export { EXIT };
export const EXIT = {
  ok: 0,
  failed: 1,
  usage: 2,
  notConfigured: 3,
  /** The run completed, but at least one repo did not. */
  partial: 4,
  /** The forge heard the request and said no: a rule, a conflict, a hold. */
  refused: 5,
  /** The forge said "not now"; it named when to try again. */
  rateLimited: 6,
} as const;
/** Every command by name, built once from `commands/index.ts`. */
const TABLE = new Map(commands.map((c) => [c.name, c]));
const VALUE_FLAGS = ["token", "interval", "root", "url", "limit", "repo", "kind", "reason"];
/** What the CLI needs from the person at the keyboard; a test fakes it. */
export interface Io {
  /** One answered line, or null when there is no terminal to ask. */
  ask(prompt: string): Promise<string | null>;
}
export async function main(
  argv: readonly string[],
  io: Io = { ask: askLine },
@@ -85,1026 +46,19 @@
export async function main(
    out.line(`forge ${VERSION}`);
    return EXIT.ok;
  }
  if (args.command === undefined) {
    if (args.flag("help") || args.flag("h")) {
      usage(out);
      return EXIT.ok;
    }
    return openTui(out, args);
  }
  if (args.flag("help") || args.flag("h")) {
    usage(out);
  if (args.flag("help") || args.flag("h") || args.command === "help") {
    printUsage(out);
    return EXIT.ok;
  }
  switch (args.command) {
    case "help":
      usage(out);
      return EXIT.ok;
    case "login":
      return login(out, args);
    case "logout":
      return logout(out);
    case "whoami":
      return whoami(out);
    case "sync":
      return sync(out, args, true);
    case "status":
      return sync(out, args, false);
    case "ls":
      return list(out, args);
    case "pin":
      return setPin(out, args, true);
    case "unpin":
      return setPin(out, args, false);
    case "pulls":
      return pulls(out, args);
    case "open":
      return openRepo(out, args);
    case "asks":
      return asks(out, args, argv.slice(1));
    case "search":
      return search(out, args);
    case "ship":
      return ship(out, args, io);
    case "ui":
      return openTui(out, args);
    default:
      out.err(`forge: unknown command "${args.command}"`);
      usage(out);
      return EXIT.usage;
  }
}
function usage(out: Out): void {
  const b = (text: string): string => out.paint(text, out.c.fg);
  out.line(`forge ${VERSION} — your workbench, on this machine`);
  out.line();
  out.line(b("  forge") + "                        the local terminal UI");
  out.line(b("  forge login <url>") + "            [--token T] [--insecure]");
  out.line(b("  forge logout"));
  out.line(b("  forge whoami"));
  out.line(
    b("  forge sync") +
      "                   [--watch] [--interval 5m] [--ff] [--root DIR]",
  );
  out.line(b("  forge status") + "                 [--root DIR] [--json]");
  out.line(b("  forge ls") + "                     [--json]");
  out.line(b("  forge pin <owner/name>"));
  out.line(b("  forge unpin <owner/name>"));
  out.line(b("  forge open <owner/name>") + "      [--web]");
  out.line(
    b("  forge pulls") + "                  [--repo owner/name] [--closed] [--json]",
  );
  out.line(
    b("  forge asks") + "                   [--repo owner/name] [--json]",
  );
  out.line(
    b("  forge search <words…>") +
      "        [--kind code|issues|pulls|repos|all] [--limit N] [--json]",
  );
  out.line(
    b("  forge asks --ship|--close|--dismiss <n…>") +
      "  [--reason words] [--yes]",
  );
  out.line(b("  forge ship <number>") + "          [--repo owner/name] [--yes]");
  out.line();
  out.line(
    out.paint(`  config ${configPath()}   root ${rootDir()}`, out.c.faint),
  );
  out.line(
    out.paint(
      "  FORGE_URL, FORGE_TOKEN, FORGE_ROOT and NO_COLOR are honoured.",
      out.c.faint,
    ),
  );
}
// ── account ──────────────────────────────────────────────────────────────
async function login(out: Out, args: Args): Promise<number> {
  const raw = args.positional[0] ?? args.value("url");
  if (raw === undefined) {
    out.err("forge login: which forge? e.g. forge login forge.example.com");
  // No command is the terminal UI.
  const command = TABLE.get(args.command ?? "ui");
  if (command === undefined) {
    out.err(`forge: unknown command "${args.command}"`);
    printUsage(out);
    return EXIT.usage;
  }
  const url = normalizeUrl(raw);
  // Before the token is asked for, let alone sent: nothing crosses the
  // network in clear unless the person said this host is one they trust.
  const insecure = args.flag("insecure");
  if (plainHttpRemote(url) && !insecure) {
    out.err(`forge login: ${PLAIN_HTTP_REFUSAL}`);
    return EXIT.usage;
  }
  const token = args.value("token") ?? (await askSecret(`Token for ${url}: `));
  if (token === "") {
    out.err("forge login: no token given");
    return EXIT.usage;
  }
  // Verify before storing: a config that does not work is worse than none.
  const api = new ForgeApi(url, token);
  const me = await api.whoami();
  if (!me.ok) {
    out.err(`forge login: ${me.error.message}`);
    return me.error.status === 401 ? EXIT.notConfigured : EXIT.failed;
  }
  const stored = await saveConfig({ url, token }, { insecure });
  out.line(
    `${out.paint(G.check, out.c.success)} signed in to ${url} as ${me.value.username}`,
  );
  out.line(
    out.paint(
      stored.keychain
        ? `  token in your login keychain; ${configPath()} holds only the URL`
        : `  token in ${configPath()} (0600)`,
      out.c.faint,
    ),
  );
  return EXIT.ok;
}
async function logout(out: Out): Promise<number> {
  await clearConfig();
  out.line("signed out");
  return EXIT.ok;
}
async function whoami(out: Out): Promise<number> {
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const api = new ForgeApi(loaded.url, loaded.token);
  const me = await api.whoami();
  if (!me.ok) {
    out.err(`forge whoami: ${me.error.message}`);
    return EXIT.failed;
  }
  out.line(`${me.value.username} at ${loaded.url}`);
  return EXIT.ok;
}
// ── sync and status ──────────────────────────────────────────────────────
async function sync(out: Out, args: Args, network: boolean): Promise<number> {
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const api = new ForgeApi(loaded.url, loaded.token);
  const root = rootDir(args.value("root"));
  const ff = args.flag("ff");
  const json = args.flag("json");
  const once = async (
    previous: SyncReport | null,
    quiet: boolean,
  ): Promise<SyncReport> => {
    const report = await syncOnce({
      api,
      token: loaded.token,
      root,
      fetch: network,
      ff,
      ...(quiet || json || !out.color
        ? {}
        : { onProgress: (repo, text) => status(out, `${repo}: ${text}`) }),
    });
    if (!quiet && !json && out.color) status(out, "");
    if (previous === null || !quiet) {
      if (json) out.line(JSON.stringify(asJson(report)));
      else printReport(out, report);
    }
    return report;
  };
  if (!args.flag("watch")) {
    const report = await once(null, false);
    return report.failures > 0 ? EXIT.partial : EXIT.ok;
  }
  const interval = parseDuration(args.value("interval")) ?? 300_000;
  const notify = systemNotifier();
  let previous = await once(null, false);
  if (!json) {
    out.line();
    out.line(
      out.paint(
        `watching ${previous.repos.length} repos every ${args.value("interval") ?? "5m"} — ctrl+c to stop`,
        out.c.faint,
      ),
    );
  }
  for (;;) {
    await sleep(interval);
    const report = await once(previous, true);
    const changes = changesBetween(previous, report);
    previous = report;
    // Only a real transition reaches the user; everything else is the
    // report, which is there when they choose to look at it. A watch that
    // notified on every pass would be muted within the hour.
    if (changes.length === 0) continue;
    if (json) out.line(JSON.stringify({ ...asJson(report), changes }));
    else {
      out.line();
      out.line(new Date().toLocaleTimeString());
      printReport(out, report);
    }
    await notify("forge", changes.slice(0, 4).join("\n"));
  }
}
async function list(out: Out, args: Args): Promise<number> {
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  // `ls` answers from disk, so it keeps working when the forge does not.
  const report = await syncOnce({
    api: new ForgeApi(loaded.url, loaded.token),
    token: loaded.token,
    root: rootDir(args.value("root")),
    fetch: false,
  });
  if (args.flag("json")) {
    out.line(JSON.stringify(asJson(report)));
    return EXIT.ok;
  }
  out.line(out.paint(report.root, out.c.faint));
  out.table(
    [
      { header: "REPO", max: 44 },
      { header: "BRANCH", max: 24 },
      { header: "SYNC", align: "right" },
      { header: "STATE", max: 28 },
      { header: "FETCHED", align: "right" },
    ],
    report.repos.map((r) => [
      cell(`${r.owner}/${r.name}`, r.present ? out.c.fg : out.c.mutedFg),
      cell(r.present ? (r.branch ?? "detached") : "—", out.c.mutedFg),
      cell(trackText(r.ahead, r.behind), out.c.attn),
      lsState(out, r),
      cell(r.present ? since(r.lastFetch) : "", out.c.faint),
    ]),
  );
  return EXIT.ok;
}
function lsState(out: Out, r: RepoReport): ReturnType<typeof cell> {
  if (!r.present) return cell("not cloned", out.c.attn);
  const dirty = dirtyCount(r);
  if (dirty > 0) return cell(`${dirty} dirty`, out.c.accent);
  if (settled(r)) return cell(G.check, out.c.success);
  return cell(r.upstream === null ? "no upstream" : "", out.c.faint);
}
/**
 * The report as data. `--json` exists so a script can branch on the same
 * facts the table shows without parsing columns — so every field the table
 * draws from is here, spelled the way the rest of the client spells it.
 */
function asJson(report: SyncReport): Record<string, unknown> {
  return {
    root: report.root,
    pinsUnavailable: report.pinsUnavailable,
    failures: report.failures,
    repos: report.repos.map((r: RepoReport) => ({
      owner: r.owner,
      name: r.name,
      path: r.dir,
      present: r.present,
      cloned: r.cloned,
      pinned: r.pinned,
      branch: r.branch,
      upstream: r.upstream,
      ahead: r.ahead,
      behind: r.behind,
      staged: r.staged,
      changed: r.changed,
      untracked: r.untracked,
      conflicted: r.conflicted,
      dirty: dirtyCount(r),
      stashes: r.stashes,
      unpushed: r.unpushed,
      fastForwarded: r.fastForwarded,
      lastFetch: r.lastFetch === null ? null : r.lastFetch.toISOString(),
      error: r.error,
    })),
  };
}
// ── pins ─────────────────────────────────────────────────────────────────
async function setPin(out: Out, args: Args, on: boolean): Promise<number> {
  const verb = on ? "pin" : "unpin";
  const ref = parseRepoRef(args.positional[0]);
  if (ref === undefined) {
    out.err(`forge ${verb}: expected owner/name`);
    return EXIT.usage;
  }
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const api = new ForgeApi(loaded.url, loaded.token);
  const result = on
    ? await api.pin(ref.owner, ref.name)
    : await api.unpin(ref.owner, ref.name);
  if (!result.ok) {
    out.err(
      result.error.status === 404
        ? `forge ${verb}: this forge does not support pins yet`
        : `forge ${verb}: ${result.error.message}`,
    );
    return EXIT.failed;
  }
  out.line(
    `${out.paint(G.check, out.c.success)} ${on ? "pinned" : "unpinned"} ${ref.owner}/${ref.name}`,
  );
  if (on)
    out.line(out.paint("  run `forge sync` to bring it down", out.c.faint));
  return EXIT.ok;
}
async function openRepo(out: Out, args: Args): Promise<number> {
  const ref = parseRepoRef(args.positional[0]);
  if (ref === undefined) {
    out.err("forge open: expected owner/name");
    return EXIT.usage;
  }
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const url = new ForgeApi(loaded.url, loaded.token).webUrl(
    ref.owner,
    ref.name,
  );
  out.line(url);
  if (!args.flag("web")) return EXIT.ok;
  const opener = process.platform === "darwin" ? "open" : "xdg-open";
  try {
    const proc = Bun.spawn([opener, url], {
      stdout: "ignore",
      stderr: "ignore",
    });
    await proc.exited;
  } catch {
    out.err(`forge open: could not run ${opener}`);
    return EXIT.failed;
  }
  return EXIT.ok;
}
// ── pulls ────────────────────────────────────────────────────────────────
async function pulls(out: Out, args: Args): Promise<number> {
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const flagged = args.value("repo");
  const ref =
    flagged !== undefined
      ? parseRepoRef(flagged)
      : await folderRepo(process.cwd(), loaded.url);
  if (ref === undefined) {
    out.err(
      flagged !== undefined
        ? "forge pulls: --repo expects owner/name"
        : `forge pulls: this folder is not a clone of ${loaded.url} — run it in a clone, or pass --repo owner/name`,
    );
    return EXIT.usage;
  }
  const closed = args.flag("closed");
  const got = await new ForgeApi(loaded.url, loaded.token).pulls(
    ref.owner,
    ref.name,
    closed ? "closed" : "open",
  );
  if (!got.ok) {
    out.err(`forge pulls: ${got.error.message}`);
    return EXIT.failed;
  }
  if (args.flag("json")) {
    out.line(JSON.stringify(got.value));
    return EXIT.ok;
  }
  const items = got.value.items as Record<string, unknown>[];
  if (items.length === 0) {
    out.line(closed ? "No closed pulls." : "No open pulls.");
    return EXIT.ok;
  }
  const tone = {
    green: out.c.success,
    red: out.c.danger,
    running: out.c.attn,
    none: out.c.faint,
  } as const;
  const rows = items.map((item) => ({
    number: `#${String(item["number"])}`,
    title: inert(String(item["title"] ?? "")),
    author: inert(String(item["author"] ?? "")),
    check: String(item["check"]) as keyof typeof tone,
    preview: inert(typeof item["preview"] === "string" ? item["preview"] : ""),
  }));
  const wide = (pick: (r: (typeof rows)[number]) => string): number =>
    Math.max(...rows.map((r) => displayWidth(pick(r))));
  const nW = wide((r) => r.number);
  const aW = Math.min(20, wide((r) => r.author));
  const cW = wide((r) => r.check);
  const pW = wide((r) => r.preview);
  const gaps = 2 * (pW > 0 ? 4 : 3);
  const tW = Math.max(12, out.width - nW - aW - cW - pW - gaps);
  for (const r of rows) {
    const parts = [
      pad(r.number, nW, "right"),
      pad(truncate(r.title, tW), tW),
      pad(truncate(r.author, aW), aW),
      out.paint(pad(r.check, cW), tone[r.check] ?? out.c.faint),
    ];
    if (pW > 0) parts.push(r.preview);
    out.line(parts.join("  ").replace(/\s+$/, ""));
  }
  if (got.value.next_cursor !== null)
    out.line(
      out.paint(
        `The list is cut after ${rows.length} pulls; the forge has more.`,
        out.c.faint,
      ),
    );
  return EXIT.ok;
}
// ── asks ─────────────────────────────────────────────────────────────────
/**
 * What waits on you, one line each, in the order the forge ranks it: kind,
 * repository, title cut to the terminal, and the address to decide it at.
 */
export async function asks(
  out: Out,
  args: Args,
  argv: readonly string[] = [],
  confirm: Confirm = confirmOnTty,
): Promise<number> {
  const wish = parseWish(argv);
  if (typeof wish === "string") {
    out.err(`forge asks: ${wish}`);
    return EXIT.usage;
  }
  const only = args.value("repo");
  const ref = only === undefined ? undefined : parseRepoRef(only);
  if (only !== undefined && ref === undefined) {
    out.err("forge asks: --repo expects owner/name");
    return EXIT.usage;
  }
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const api = new ForgeApi(loaded.url, loaded.token);
  const answer = await api.asks();
  if (!answer.ok) {
    out.err(`forge asks: ${answer.error.message}`);
    return answer.error.status === 401 ? EXIT.notConfigured : EXIT.failed;
  }
  const repo = ref === undefined ? undefined : `${ref.owner}/${ref.name}`;
  if (wish !== undefined && wish.action === "undo")
    return decide(out, api, wish, [], true, confirm);
  if (wish !== undefined) {
    const rows = answer.value.asks.filter(
      (a) => repo === undefined || a.repo === repo,
    );
    return decide(out, api, wish, rows, args.flag("yes"), confirm);
  }
  if (args.flag("json")) {
    const raw = answer.value.raw;
    out.line(JSON.stringify(repo === undefined ? raw : onlyRepo(raw, repo)));
    return EXIT.ok;
  }
  const rows = answer.value.asks.filter(
    (a) => repo === undefined || a.repo === repo,
  );
  if (rows.length === 0) {
    out.line("Nothing waits on you.");
    return EXIT.ok;
  }
  const numberW = String(rows.length).length;
  const lines = askLines(rows, out.width - numberW - 2, out);
  lines.forEach((line, i) =>
    out.line(`${String(i + 1).padStart(numberW)}  ${line}`),
  );
  return EXIT.ok;
}
/** Whether to go ahead: undefined when there is no one to ask. */
export type Confirm = (question: string) => Promise<boolean | undefined>;
const confirmOnTty: Confirm = async (question) => {
  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true)
    return undefined;
  process.stdout.write(question);
  const line = await new Promise<string>((resolve) => {
    const stdin = process.stdin;
    stdin.setEncoding("utf8");
    stdin.once("data", (chunk) => {
      stdin.pause();
      resolve(String(chunk));
    });
    stdin.resume();
  });
  return /^\s*y(es)?\s*$/i.test(line);
};
/**
 * Decide asks by the numbers of the list just read: the plan first, then,
 * after a yes (or `--yes`), the deed and the line that undoes it.
 */
async function decide(
  out: Out,
  api: ForgeApi,
  wish: Wish,
  rows: readonly Ask[],
  yes: boolean,
  confirm: Confirm,
): Promise<number> {
  const fail = (e: { message: string; status: number }): number => {
    out.err(`forge asks: ${e.message}`);
    return e.status === 401 ? EXIT.notConfigured : EXIT.failed;
  };
  if (wish.action === "undo") {
    const back = await api.undo(wish.numbers[0]!);
    if (!back.ok) return fail(back.error);
    printBulk(out, back.value, "undo", true);
    return EXIT.ok;
  }
  const ids = pickAsks(wish.numbers, rows);
  if (!Array.isArray(ids)) {
    out.err(`forge asks: ${ids.refused}`);
    return EXIT.usage;
  }
  const plan = await api.bulk(wish.action, ids, wish.reason, true);
  if (!plan.ok) return fail(plan.error);
  printBulk(out, plan.value, wish.action, false);
  const changes = plan.value.rows.filter((r) => r.outcome === "change").length;
  if (changes === 0) {
    out.line("Nothing would change.");
    return EXIT.ok;
  }
  if (!yes) {
    const said = await confirm("Apply? [y/N] ");
    if (said === undefined) {
      out.err("forge asks: not applied — no terminal to ask on; add --yes");
      return EXIT.usage;
    }
    if (!said) {
      out.line("Nothing applied.");
      return EXIT.ok;
    }
  }
  const done = await api.bulk(wish.action, ids, wish.reason, false);
  if (!done.ok) return fail(done.error);
  printBulk(out, done.value, wish.action, true);
  if (done.value.id !== undefined) {
    out.line(`Receipt ${inert(done.value.id)}`);
    out.line(`Undo: forge asks --undo ${inert(done.value.id)}`);
  }
  return EXIT.ok;
}
function printBulk(out: Out, bulk: Bulk, action: string, done: boolean): void {
  out.line(done ? `Applied: ${action}` : `Would ${action}:`);
  for (const r of bulk.rows) {
    const move = r.before === r.after ? "" : `  ${r.before} → ${r.after}`;
    const why = r.reason === "" ? "" : `  (${r.reason})`;
    out.line(`  ${pad(inert(r.outcome), 9)} ${inert(r.label)}${inert(move)}${inert(why)}`);
  }
  for (const s of bulk.skipped)
    out.line(`  skipped   ${inert(s.item)}  (${inert(s.reason)})`);
}
/**
 * The asks as lines no wider than `width - 1`, so none wraps on its own:
 * kind and repository padded to their widest, the address whole, and the
 * title cut to what those leave. Coloured only when `out` is given.
 */
export function askLines(
  rows: readonly Ask[],
  width: number,
  out?: Pick<Out, "paint" | "c">,
): string[] {
  const kindW = Math.max(...rows.map((a) => displayWidth(inert(a.kind))));
  const repoW = Math.max(...rows.map((a) => displayWidth(inert(a.repo))));
  return rows.map((a) => {
    const url = inert(a.url);
    // Three two-space gaps; the title gets what the other columns leave.
    const room = Math.max(
      1,
      width - 1 - kindW - repoW - displayWidth(url) - 6,
    );
    const kind = pad(inert(a.kind), kindW);
    return [
      out === undefined ? kind : out.paint(kind, out.c.accent),
      pad(inert(a.repo), repoW),
      truncate(inert(a.title), room),
      out === undefined ? url : out.paint(url, out.c.faint),
    ].join("  ");
  });
}
/**
 * The API's answer with only one repository's rows; the forge's own needs
 * belong to none.
 */
function onlyRepo(raw: unknown, repo: string): unknown {
  if (typeof raw !== "object" || raw === null) return raw;
  const body = raw as { rows?: unknown };
  return {
    ...body,
    rows: Array.isArray(body.rows)
      ? body.rows.filter(
          (r) => (r as { repo?: unknown } | null)?.repo === repo,
        )
      : body.rows,
    forge: [],
  };
}
// ── search ───────────────────────────────────────────────────────────────
/** The forge's default and ceiling for `limit` (`src/actions/search.ts`). */
const SEARCH_API_LIMIT = 20;
const SEARCH_API_LIMIT_MAX = 100;
const SEARCH_KINDS = ["code", "issues", "pulls", "repos", "all"] as const;
export type SearchFor = (typeof SEARCH_KINDS)[number];
/**
 * `GET /api/v1/search` from a shell: every hit one line, grouped by kind.
 * The API has no `pulls` kind — its `issues` answers both — so `--kind
 * issues` and `--kind pulls` ask for `issues` at the API's ceiling and
 * keep N of the one kind (`narrowConversations`): asking for N and then
 * filtering would print fewer than N, or none.
 */
async function search(out: Out, args: Args): Promise<number> {
  const words = args.positional.join(" ").trim();
  if (words === "") {
    out.err("forge search: what for? e.g. forge search retry budget");
    usage(out);
    return EXIT.usage;
  }
  const kindRaw = args.value("kind");
  const kind = SEARCH_KINDS.find((k) => k === kindRaw);
  if (kindRaw !== undefined && kind === undefined) {
    out.err(`forge search: --kind is one of ${SEARCH_KINDS.join(", ")}`);
    return EXIT.usage;
  }
  const limitRaw = args.value("limit");
  const limit = limitRaw === undefined ? undefined : Number(limitRaw);
  if (limit !== undefined && (!/^\d+$/.test(limitRaw!) || limit < 1)) {
    out.err("forge search: --limit expects a whole number above 0");
    return EXIT.usage;
  }
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const oneConversation = kind === "issues" || kind === "pulls";
  const answer = await new ForgeApi(loaded.url, loaded.token).search(words, {
    ...(kind === undefined ? {} : { kind: oneConversation ? "issues" : kind }),
    ...(oneConversation
      ? { limit: SEARCH_API_LIMIT_MAX }
      : limit === undefined ? {} : { limit }),
  });
  if (!answer.ok) {
    const { message, retryAfter, status } = answer.error;
    const when =
      retryAfter === undefined || new RegExp(`\\b${retryAfter}s\\b`).test(message)
        ? ""
        : ` (retry in ${retryAfter}s)`;
    out.err(`forge search: ${message}${when}`);
    if (status === 429) return EXIT.rateLimited;
    return status === 401 ? EXIT.notConfigured : EXIT.failed;
  }
  const found = oneConversation
    ? narrowConversations(answer.value, kind, limit ?? SEARCH_API_LIMIT)
    : answer.value;
  if (args.flag("json")) {
    out.line(JSON.stringify(found));
    return EXIT.ok;
  }
  const lines = searchLines(found, kind ?? "all", out.width, out);
  if (lines.length === 0) {
    out.line(`Nothing found for "${inert(words)}".`);
    return EXIT.ok;
  }
  for (const line of lines) out.line(line);
  return EXIT.ok;
}
/**
 * The answer with `issues` kept to one kind (`issue` or `pull`) and cut to
 * `limit`; `truncated.issues` is set when the cut dropped any, or when the
 * forge had already cut its own window, so `--json` and the group header
 * both say the list is not whole. Everything else passes through.
 */
export function narrowConversations(
  raw: unknown,
  kind: "issues" | "pulls",
  limit: number,
): unknown {
  if (typeof raw !== "object" || raw === null) return raw;
  const body = raw as Record<string, unknown>;
  const want = kind === "pulls" ? "pull" : "issue";
  const kept = rowsOf(body["issues"]).filter((r) => r["kind"] === want);
  const truncated = (typeof body["truncated"] === "object" && body["truncated"] !== null
    ? body["truncated"]
    : {}) as Record<string, unknown>;
  return {
    ...body,
    issues: kept.slice(0, limit),
    truncated: { ...truncated, issues: truncated["issues"] === true || kept.length > limit },
  };
}
/**
 * The search answer as lines no wider than `width - 1` where the text can
 * give way: each kind headed by its name and count, then one hit a line —
 * `owner/name:path:line  text` for code, `owner/name#N  title  state` for
 * issues and pulls, `owner/name  description` for repositories. Anything
 * the answer carries that is not the expected shape is skipped, not fatal.
 */
export function searchLines(
  raw: unknown,
  kind: SearchFor,
  width: number,
  out?: Pick<Out, "paint" | "c">,
): string[] {
  const body = (typeof raw === "object" && raw !== null ? raw : {}) as Record<string, unknown>;
  const truncated = (body["truncated"] ?? {}) as Record<string, unknown>;
  const conversations = rowsOf(body["issues"]).map(conversationRow);
  const groups: { kind: SearchFor; rows: [string, string, string][]; more: boolean }[] = [
    { kind: "code", rows: rowsOf(body["code"]).map(codeRow), more: truncated["code"] === true },
    {
      kind: "issues",
      rows: conversations.filter((r) => r[0] === "issue").map((r) => r.slice(1) as [string, string, string]),
      more: truncated["issues"] === true,
    },
    {
      kind: "pulls",
      rows: conversations.filter((r) => r[0] === "pull").map((r) => r.slice(1) as [string, string, string]),
      more: truncated["issues"] === true,
    },
    { kind: "repos", rows: rowsOf(body["repos"]).map(repoRow), more: truncated["repos"] === true },
  ];
  const lines: string[] = [];
  for (const group of groups) {
    const rows = group.rows.filter((r) => r[0] !== "");
    if (rows.length === 0 || (kind !== "all" && kind !== group.kind)) continue;
    if (lines.length > 0) lines.push("");
    const head = `${group.kind} (${rows.length}${group.more ? ", more not shown" : ""})`;
    lines.push(out === undefined ? head : out.paint(head, out.c.accent));
    // Code's place differs in width line to line; the others line up.
    const leadW = group.kind === "code" ? 0 : Math.max(...rows.map((r) => displayWidth(r[0])));
    const tails = rows.some((r) => r[2] !== "");
    const tailW = tails ? Math.max(...rows.map((r) => displayWidth(r[2]))) + 2 : 0;
    const textW = Math.max(...rows.map((r) => displayWidth(r[1])));
    for (const [lead, text, tail] of rows) {
      const first = leadW === 0 ? lead : pad(lead, leadW);
      const room = Math.max(8, width - 1 - displayWidth(first) - 2 - tailW);
      const cut = truncate(text, room);
      const shown = tails ? pad(cut, Math.min(room, textW)) : cut;
      lines.push(
        [
          first,
          shown,
          ...(tail === "" ? [] : [out === undefined ? tail : out.paint(tail, out.c.faint)]),
        ].join("  ").trimEnd(),
      );
    }
    if (group.kind === "code" && (body["moreCode"] === true || body["codeSkipped"] === true)) {
      const note = "  some repositories were not searched in time; --json says which kinds are partial";
      lines.push(out === undefined ? note : out.paint(note, out.c.faint));
    }
  }
  return lines;
}
function rowsOf(value: unknown): Record<string, unknown>[] {
  return Array.isArray(value)
    ? value.filter((v): v is Record<string, unknown> => typeof v === "object" && v !== null)
    : [];
}
/** `owner/name` from a local hit's `repo`, or an origin hit's `fullName`. */
function repoName(r: Record<string, unknown>): string {
  const repo = r["repo"] as Record<string, unknown> | undefined;
  if (typeof repo?.["owner"] === "string" && typeof repo["name"] === "string")
    return `${repo["owner"]}/${repo["name"]}`;
  if (typeof r["owner"] === "string" && typeof r["name"] === "string")
    return `${r["owner"]}/${r["name"]}`;
  return typeof r["fullName"] === "string" ? r["fullName"] : "";
}
function textOf(value: unknown): string {
  return typeof value === "string" ? inert(value) : "";
}
function codeRow(r: Record<string, unknown>): [string, string, string] {
  const name = repoName(r);
  const path = textOf(r["path"]);
  const line = typeof r["line"] === "number" ? r["line"] : 0;
  if (name === "" || path === "") return ["", "", ""];
  return [`${inert(name)}:${path}:${line}`, textOf(r["text"]).trim(), ""];
}
function conversationRow(r: Record<string, unknown>): [string, string, string, string] {
  const name = repoName(r);
  const n = r["number"];
  if (name === "" || typeof n !== "number") return ["", "", "", ""];
  return [textOf(r["kind"]), `${inert(name)}#${n}`, textOf(r["title"]), textOf(r["state"])];
}
function repoRow(r: Record<string, unknown>): [string, string, string] {
  const name = repoName(r);
  return [inert(name), textOf(r["description"]), r["archived"] === true ? "archived" : ""];
}
// ── landing a pull ───────────────────────────────────────────────────────
/**
 * `forge ship 12`: read the pull, show it, ask, merge. The merge route's
 * rules stay the server's — this adds none and retries nothing; a refusal
 * prints the forge's own words.
 */
async function ship(out: Out, args: Args, io: Io): Promise<number> {
  const raw = args.positional[0];
  const number = raw === undefined ? NaN : Number(raw.replace(/^#/, ""));
  if (!Number.isSafeInteger(number) || number < 1) {
    out.err("forge ship: which pull? e.g. forge ship 12");
    return EXIT.usage;
  }
  const loaded = await requireConfig(out);
  if (typeof loaded === "number") return loaded;
  const ref = await resolveRepo(args.value("repo"), loaded.url);
  if (typeof ref === "string") {
    out.err(`forge ship: ${ref}`);
    return EXIT.usage;
  }
  const api = new ForgeApi(loaded.url, loaded.token);
  const pull = await api.pull(ref.owner, ref.name, number);
  if (!pull.ok) return shipError(out, pull.error);
  const check = await api.pullCheck(ref.owner, ref.name, number);
  const p = pull.value;
  out.line(`${ref.owner}/${ref.name}#${p.number}  ${inert(p.title)}`);
  const facts = [
    `check ${check.ok ? inert(check.value) : "unknown"}`,
    p.merged
      ? "already merged"
      : p.state !== "open"
        ? p.state
        : p.mergeable === false
          ? "not mergeable"
          : p.mergeable === true
            ? "mergeable"
            : "mergeable unknown",
    ...(p.held ? ["held"] : []),
  ];
  out.line(out.paint(`  ${facts.join(" · ")}`, out.c.faint));
  if (!args.flag("yes")) {
    const answer = await io.ask(`Ship #${p.number}? [y/N] `);
    if (answer === null) {
      out.err("forge ship: not a terminal — pass --yes to ship without asking");
      return EXIT.usage;
    }
    if (answer.trim().toLowerCase() !== "y") {
      out.line("not shipped");
      return EXIT.ok;
    }
  }
  const merged = await api.merge(ref.owner, ref.name, number);
  if (!merged.ok) return shipError(out, merged.error);
  out.line(
    `${out.paint(G.check, out.c.success)} shipped #${p.number} as ${merged.value.mergeOid.slice(0, 7)}`,
  );
  out.line(api.pullUrl(ref.owner, ref.name, number));
  return EXIT.ok;
}
function shipError(out: Out, error: ApiError): number {
  out.err(`forge ship: ${inert(error.message)}`);
  if (error.status === 401) return EXIT.notConfigured;
  if (error.status === 403 || error.status === 409 || error.status === 422)
    return EXIT.refused;
  return EXIT.failed;
}
// ── the terminal UI ──────────────────────────────────────────────────────
async function openTui(out: Out, args: Args): Promise<number> {
  if (process.stdout.isTTY !== true) {
    usage(out);
    return EXIT.usage;
  }
  const loaded = await loadConfig();
  if (loaded === "plain_http") {
    out.err(`forge: ${PLAIN_HTTP_REFUSAL}`);
    return EXIT.usage;
  }
  const config = typeof loaded === "string" ? null : loaded.config;
  const { runLocalTui } = await import("../tui/local/app.ts");
  await runLocalTui({
    root: rootDir(args.value("root")),
    ...(config === null ? {} : { config }),
  });
  return EXIT.ok;
}
// ── plumbing ─────────────────────────────────────────────────────────────
async function requireConfig(out: Out): Promise<Config | number> {
  const loaded = await loadConfig();
  if (loaded === "no_config") {
    out.err("forge: not signed in — run `forge login <url>`");
    return EXIT.notConfigured;
  }
  if (loaded === "no_token") {
    out.err(`forge: ${configPath()} has no usable token — run \`forge login\``);
    return EXIT.notConfigured;
  }
  if (loaded === "plain_http") {
    out.err(`forge: ${PLAIN_HTTP_REFUSAL}`);
    return EXIT.usage;
  }
  return loaded.config;
}
/** One transient line, overwritten in place. Never printed to a pipe. */
function status(out: Out, text: string): void {
  if (!out.color) return;
  const room = Math.max(0, out.width - 1);
  process.stdout.write(`\r\x1b[K${text.slice(0, room)}`);
  if (text === "") process.stdout.write("\r");
}
function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}
/** One line from the terminal, echoed; null when stdin is not a terminal. */
async function askLine(prompt: string): Promise<string | null> {
  const stdin = process.stdin;
  if (stdin.isTTY !== true || process.stdout.isTTY !== true) return null;
  process.stdout.write(prompt);
  stdin.resume();
  return new Promise<string>((resolve) => {
    // ctrl+d or a closed terminal is an answer too, and the answer is N.
    const finish = (answer: string): void => {
      stdin.off("data", onData);
      stdin.off("end", onEnd);
      stdin.off("close", onEnd);
      stdin.pause();
      resolve(answer);
    };
    const onData = (chunk: Buffer): void =>
      finish(chunk.toString("utf8").split("\n")[0] ?? "");
    const onEnd = (): void => {
      process.stdout.write("\n");
      finish("");
    };
    stdin.on("data", onData);
    stdin.once("end", onEnd);
    stdin.once("close", onEnd);
  });
}
/**
 * A secret, read without echo. Raw mode is the only way to stop the terminal
 * printing it, and it is restored on every path — including ctrl+c, which
 * here means "no token", not "leave the tty broken".
 */
async function askSecret(prompt: string): Promise<string> {
  const stdin = process.stdin;
  if (stdin.isTTY !== true) {
    // Piped input: read one line. `echo $TOKEN | forge login url` is a
    // legitimate way to do this from a script.
    const text = await new Response(Bun.stdin.stream()).text();
    return text.split("\n")[0]?.trim() ?? "";
  }
  process.stdout.write(prompt);
  stdin.setRawMode(true);
  stdin.resume();
  return new Promise<string>((resolve) => {
    let value = "";
    const finish = (result: string): void => {
      stdin.off("data", onData);
      stdin.setRawMode(false);
      stdin.pause();
      process.stdout.write("\n");
      resolve(result);
    };
    const onData = (chunk: Buffer): void => {
      for (const byte of chunk) {
        if (byte === 3) return finish(""); // ctrl+c
        if (byte === 13 || byte === 10) return finish(value.trim());
        if (byte === 127 || byte === 8) {
          value = value.slice(0, -1);
          continue;
        }
        if (byte >= 0x20) value += String.fromCharCode(byte);
      }
    };
    stdin.on("data", onData);
  });
  return command.run(out, args, printUsage, io, argv.slice(1));
}
// `import.meta.main` is false when a test imports `main` directly, which is
@@ -0,0 +1,84 @@
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { EXIT, main } from "../src/cli/main.ts";
import { readdirSync } from "node:fs";
import { commands } from "../src/cli/commands/index.ts";
import { printUsage } from "../src/cli/help.ts";
import { createOut } from "../src/cli/out.ts";
const DIR = new URL("../src/cli/commands/", import.meta.url).pathname;
const files = readdirSync(DIR)
  .filter((f) => f.endsWith(".ts") && f !== "index.ts" && f !== "types.ts")
  .map((f) => f.slice(0, -3));
test("every module in commands/ is in the table, named for its file", async () => {
  for (const file of files) {
    const mod = (await import(`${DIR}${file}.ts`)) as { command?: unknown };
    expect(commands).toContain(mod.command as never);
    expect(commands.map((c) => c.name)).toContain(file);
  }
  expect(commands.length).toBe(files.length);
  expect(new Set(commands.map((c) => c.name)).size).toBe(commands.length);
});
test("forge help lists every command", () => {
  const lines: string[] = [];
  const out = { ...createOut(), line: (t = "") => void lines.push(t) };
      
        junipercrew
        17d ago
        outdated
      
      Add dispatch tests: unknown command -> EXIT.usage, help/--help -> EXIT.ok, a known command reaches its run.
    
  printUsage(out);
  const text = lines.join("\n").replace(/\x1b\[[0-9;]*m/g, "");
  for (const c of commands) expect(text).toContain(`  ${c.usage.synopsis}`);
});
// ── dispatch, driven through main() as the shell does ────────────────────
describe("main() dispatch", () => {
  const ENV = [
    "FORGE_CONFIG_DIR",
    "FORGE_KEYCHAIN",
    "FORGE_URL",
    "FORGE_TOKEN",
  ];
  const saved = new Map<string, string | undefined>();
  let dir = "";
  const realErr = process.stderr.write.bind(process.stderr);
  const realOut = process.stdout.write.bind(process.stdout);
  beforeEach(async () => {
    for (const key of ENV) saved.set(key, process.env[key]);
    dir = await mkdtemp(join(tmpdir(), "forge-dispatch-"));
    process.env["FORGE_CONFIG_DIR"] = dir;
    process.env["FORGE_KEYCHAIN"] = "0";
    delete process.env["FORGE_URL"];
    delete process.env["FORGE_TOKEN"];
    process.stderr.write = (() => true) as typeof process.stderr.write;
    process.stdout.write = (() => true) as typeof process.stdout.write;
  });
  afterEach(async () => {
    process.stderr.write = realErr;
    process.stdout.write = realOut;
    for (const key of ENV) {
      const was = saved.get(key);
      if (was === undefined) delete process.env[key];
      else process.env[key] = was;
    }
    await rm(dir, { recursive: true, force: true });
  });
  test("an unknown command is a usage error", async () => {
    expect(await main(["nope"])).toBe(EXIT.usage);
  });
  test("help, --help and -h succeed", async () => {
    expect(await main(["help"])).toBe(EXIT.ok);
    expect(await main(["--help"])).toBe(EXIT.ok);
    expect(await main(["sync", "-h"])).toBe(EXIT.ok);
  });
  test("a known command reaches its run", async () => {
    expect(await main(["whoami"])).toBe(EXIT.notConfigured);
    expect(await main(["pin", "nonsense"])).toBe(EXIT.usage);
  });
});
		@@ -5,3 +5,5 @@ Read `CLAUDE.md` first: it is the rulebook for agents editing this repo.
5	5	README.md is capped: a new feature's how-to goes in `docs/features/<name>.md`, not a new README section.
6	6
7	7	When you write an issue, end it with a `Files:` line naming the files the work touches (`Files: src/a.ts, docs/b.md`). The hot-file hold reads only that line when it is there; without it, every path the issue mentions counts.
	8
	9	A new `forge` command is a new file in `src/cli/commands/` (exporting `command`) plus one line in its `index.ts`.
		@@ -0,0 +1,196 @@
	1	import { ForgeApi, type Ask, type Bulk } from "../api.ts";
	2	import { parseWish, pickAsks, type Wish } from "../decide.ts";
	3	import { askLine, type Io } from "../io.ts";
	4	import { parseRepoRef, type Args } from "../args.ts";
	5	import { requireConfig } from "../context.ts";
	6	import { EXIT } from "../exit.ts";
	7	import { inert, type Out } from "../out.ts";
	8	import { displayWidth, pad, truncate } from "../../tui/term/width.ts";
	9	import type { Command } from "./types.ts";
	10
	11	/**
	12	* What waits on you, one line each, in the order the forge ranks it: kind,
	13	* repository, title cut to the terminal, and the address to decide it at.
	14	*/
	15	export async function asks(
	16	out: Out,
	17	args: Args,
	18	argv: readonly string[] = [],
	19	confirm: Confirm = confirmOn({ ask: askLine }),
	20	): Promise<number> {
	21	const wish = parseWish(argv);
	22	if (typeof wish === "string") {
	23	out.err(`forge asks: ${wish}`);
	24	return EXIT.usage;
	25	}
	26	const only = args.value("repo");
	27	const ref = only === undefined ? undefined : parseRepoRef(only);
	28	if (only !== undefined && ref === undefined) {
	29	out.err("forge asks: --repo expects owner/name");
	30	return EXIT.usage;
	31	}
	32	const loaded = await requireConfig(out);
	33	if (typeof loaded === "number") return loaded;
	34	const api = new ForgeApi(loaded.url, loaded.token);
	35	const answer = await api.asks();
	36	if (!answer.ok) {
	37	out.err(`forge asks: ${answer.error.message}`);
	38	return answer.error.status === 401 ? EXIT.notConfigured : EXIT.failed;
	39	}
	40	const repo = ref === undefined ? undefined : `${ref.owner}/${ref.name}`;
	41	if (wish !== undefined && wish.action === "undo")
	42	return decide(out, api, wish, [], true, confirm);
	43	if (wish !== undefined) {
	44	const rows = answer.value.asks.filter(
	45	(a) => repo === undefined \|\| a.repo === repo,
	46	);
	47	return decide(out, api, wish, rows, args.flag("yes"), confirm);
	48	}
	49	if (args.flag("json")) {
	50	const raw = answer.value.raw;
	51	out.line(JSON.stringify(repo === undefined ? raw : onlyRepo(raw, repo)));
	52	return EXIT.ok;
	53	}
	54	const rows = answer.value.asks.filter(
	55	(a) => repo === undefined \|\| a.repo === repo,
	56	);
	57	if (rows.length === 0) {
	58	out.line("Nothing waits on you.");
	59	return EXIT.ok;
	60	}
	61	const numberW = String(rows.length).length;
	62	const lines = askLines(rows, out.width - numberW - 2, out);
	63	lines.forEach((line, i) =>
	64	out.line(`${String(i + 1).padStart(numberW)} ${line}`),
	65	);
	66	return EXIT.ok;
	67	}
	68
	69	/** A y/N from the person at the keyboard, undefined when there is none. */
	70	const confirmOn =
	71	(io: Io): Confirm =>
	72	async (question) => {
	73	const line = await io.ask(question);
	74	return line === null ? undefined : /^\sy(es)?\s$/i.test(line);
	75	};
	76
	77	/** Whether to go ahead: undefined when there is no one to ask. */
	78	export type Confirm = (question: string) => Promise<boolean \| undefined>;
	79
	80	/**
	81	* Decide asks by the numbers of the list just read: the plan first, then,
	82	* after a yes (or `--yes`), the deed and the line that undoes it.
	83	*/
	84	async function decide(
	85	out: Out,
	86	api: ForgeApi,
	87	wish: Wish,
	88	rows: readonly Ask[],
	89	yes: boolean,
	90	confirm: Confirm,
	91	): Promise<number> {
	92	const fail = (e: { message: string; status: number }): number => {
	93	out.err(`forge asks: ${e.message}`);
	94	return e.status === 401 ? EXIT.notConfigured : EXIT.failed;
	95	};
	96	if (wish.action === "undo") {
	97	const back = await api.undo(wish.numbers[0]!);
	98	if (!back.ok) return fail(back.error);
	99	printBulk(out, back.value, "undo", true);
	100	return EXIT.ok;
	101	}
	102	const ids = pickAsks(wish.numbers, rows);
	103	if (!Array.isArray(ids)) {
	104	out.err(`forge asks: ${ids.refused}`);
	105	return EXIT.usage;
	106	}
	107	const plan = await api.bulk(wish.action, ids, wish.reason, true);
	108	if (!plan.ok) return fail(plan.error);
	109	printBulk(out, plan.value, wish.action, false);
	110	const changes = plan.value.rows.filter((r) => r.outcome === "change").length;
	111	if (changes === 0) {
	112	out.line("Nothing would change.");
	113	return EXIT.ok;
	114	}
	115	if (!yes) {
	116	const said = await confirm("Apply? [y/N] ");
	117	if (said === undefined) {
	118	out.err("forge asks: not applied — no terminal to ask on; add --yes");
	119	return EXIT.usage;
	120	}
	121	if (!said) {
	122	out.line("Nothing applied.");
	123	return EXIT.ok;
	124	}
	125	}
	126	const done = await api.bulk(wish.action, ids, wish.reason, false);
	127	if (!done.ok) return fail(done.error);
	128	printBulk(out, done.value, wish.action, true);
	129	if (done.value.id !== undefined) {
	130	out.line(`Receipt ${inert(done.value.id)}`);
	131	out.line(`Undo: forge asks --undo ${inert(done.value.id)}`);
	132	}
	133	return EXIT.ok;
	134	}
	135
	136	function printBulk(out: Out, bulk: Bulk, action: string, done: boolean): void {
	137	out.line(done ? `Applied: ${action}` : `Would ${action}:`);
	138	for (const r of bulk.rows) {
	139	const move = r.before === r.after ? "" : ` ${r.before} → ${r.after}`;
	140	const why = r.reason === "" ? "" : ` (${r.reason})`;
	141	out.line(` ${pad(inert(r.outcome), 9)} ${inert(r.label)}${inert(move)}${inert(why)}`);
	142	}
	143	for (const s of bulk.skipped)
	144	out.line(` skipped ${inert(s.item)} (${inert(s.reason)})`);
	145	}
	146
	147	/**
	148	* The asks as lines no wider than `width - 1`, so none wraps on its own:
	149	* kind and repository padded to their widest, the address whole, and the
	150	* title cut to what those leave. Coloured only when `out` is given.
	151	*/
	152	export function askLines(
	153	rows: readonly Ask[],
	154	width: number,
	155	out?: Pick<Out, "paint" \| "c">,
	156	): string[] {
	157	const kindW = Math.max(...rows.map((a) => displayWidth(inert(a.kind))));
	158	const repoW = Math.max(...rows.map((a) => displayWidth(inert(a.repo))));
	159	return rows.map((a) => {
	160	const url = inert(a.url);
	161	// Three two-space gaps; the title gets what the other columns leave.
	162	const room = Math.max(1, width - 1 - kindW - repoW - displayWidth(url) - 6);
	163	const kind = pad(inert(a.kind), kindW);
	164	return [
	165	out === undefined ? kind : out.paint(kind, out.c.accent),
	166	pad(inert(a.repo), repoW),
	167	truncate(inert(a.title), room),
	168	out === undefined ? url : out.paint(url, out.c.faint),
	169	].join(" ");
	170	});
	171	}
	172
	173	/**
	174	* The API's answer with only one repository's rows; the forge's own needs
	175	* belong to none.
	176	*/
	177	function onlyRepo(raw: unknown, repo: string): unknown {
	178	if (typeof raw !== "object" \|\| raw === null) return raw;
	179	const body = raw as { rows?: unknown };
	180	return {
	181	...body,
	182	rows: Array.isArray(body.rows)
	183	? body.rows.filter((r) => (r as { repo?: unknown } \| null)?.repo === repo)
	184	: body.rows,
	185	forge: [],
	186	};
	187	}
	188
	189	export const command: Command = {
	190	name: "asks",
	191	usage: {
	192	synopsis: "forge asks",
	193	flags: "[--repo owner/name] [--json] \| --ship\|--close\|--dismiss <n…> [--reason words] [--yes]",
	194	},
	195	run: (out, args, _help, io, argv) => asks(out, args, argv, confirmOn(io)),
	196	};
		@@ -0,0 +1,36 @@
	1	/**
	2	* Every `forge` subcommand, in the order `forge help` lists them. A new
	3	* command is a new file in this directory plus one line here.
	4	*/
	5	import { command as ui } from "./ui.ts";
	6	import { command as login } from "./login.ts";
	7	import { command as logout } from "./logout.ts";
	8	import { command as whoami } from "./whoami.ts";
	9	import { command as sync } from "./sync.ts";
	10	import { command as status } from "./status.ts";
	11	import { command as ls } from "./ls.ts";
	12	import { command as pin } from "./pin.ts";
	13	import { command as unpin } from "./unpin.ts";
	14	import { command as open } from "./open.ts";
	15	import { command as pulls } from "./pulls.ts";
	16	import { command as asks } from "./asks.ts";
	17	import { command as search } from "./search.ts";
	18	import { command as ship } from "./ship.ts";
	19	import type { Command } from "./types.ts";
	20
	21	export const commands: readonly Command[] = [
	22	ui,
	23	login,
	24	logout,
	25	whoami,
	26	sync,
	27	status,
	28	ls,
	29	pin,
	30	unpin,
	31	open,
	32	pulls,
	33	asks,
	34	search,
	35	ship,
	36	];
		@@ -0,0 +1,101 @@
	1	import { ForgeApi } from "../api.ts";
	2	import type { Args } from "../args.ts";
	3	import {
	4	configPath,
	5	normalizeUrl,
	6	PLAIN_HTTP_REFUSAL,
	7	plainHttpRemote,
	8	saveConfig,
	9	} from "../config.ts";
	10	import { EXIT } from "../exit.ts";
	11	import type { Out } from "../out.ts";
	12	import { G } from "../../tui/term/screen.ts";
	13	import type { Command } from "./types.ts";
	14
	15	async function login(out: Out, args: Args): Promise<number> {
	16	const raw = args.positional[0] ?? args.value("url");
	17	if (raw === undefined) {
	18	out.err("forge login: which forge? e.g. forge login forge.example.com");
	19	return EXIT.usage;
	20	}
	21	const url = normalizeUrl(raw);
	22	// Before the token is asked for, let alone sent: nothing crosses the
	23	// network in clear unless the person said this host is one they trust.
	24	const insecure = args.flag("insecure");
	25	if (plainHttpRemote(url) && !insecure) {
	26	out.err(`forge login: ${PLAIN_HTTP_REFUSAL}`);
	27	return EXIT.usage;
	28	}
	29	const token = args.value("token") ?? (await askSecret(`Token for ${url}: `));
	30	if (token === "") {
	31	out.err("forge login: no token given");
	32	return EXIT.usage;
	33	}
	34
	35	// Verify before storing: a config that does not work is worse than none.
	36	const api = new ForgeApi(url, token);
	37	const me = await api.whoami();
	38	if (!me.ok) {
	39	out.err(`forge login: ${me.error.message}`);
	40	return me.error.status === 401 ? EXIT.notConfigured : EXIT.failed;
	41	}
	42	const stored = await saveConfig({ url, token }, { insecure });
	43	out.line(
	44	`${out.paint(G.check, out.c.success)} signed in to ${url} as ${me.value.username}`,
	45	);
	46	out.line(
	47	out.paint(
	48	stored.keychain
	49	? ` token in your login keychain; ${configPath()} holds only the URL`
	50	: ` token in ${configPath()} (0600)`,
	51	out.c.faint,
	52	),
	53	);
	54	return EXIT.ok;
	55	}
	56
	57	/**
	58	* A secret, read without echo. Raw mode is the only way to stop the terminal
	59	* printing it, and it is restored on every path — including ctrl+c, which
	60	* here means "no token", not "leave the tty broken".
	61	*/
	62	async function askSecret(prompt: string): Promise<string> {
	63	const stdin = process.stdin;
	64	if (stdin.isTTY !== true) {
	65	// Piped input: read one line. `echo $TOKEN \| forge login url` is a
	66	// legitimate way to do this from a script.
	67	const text = await new Response(Bun.stdin.stream()).text();
	68	return text.split("\n")[0]?.trim() ?? "";
	69	}
	70	process.stdout.write(prompt);
	71	stdin.setRawMode(true);
	72	stdin.resume();
	73	return new Promise<string>((resolve) => {
	74	let value = "";
	75	const finish = (result: string): void => {
	76	stdin.off("data", onData);
	77	stdin.setRawMode(false);
	78	stdin.pause();
	79	process.stdout.write("\n");
	80	resolve(result);
	81	};
	82	const onData = (chunk: Buffer): void => {
	83	for (const byte of chunk) {
	84	if (byte === 3) return finish(""); // ctrl+c
	85	if (byte === 13 \|\| byte === 10) return finish(value.trim());
	86	if (byte === 127 \|\| byte === 8) {
	87	value = value.slice(0, -1);
	88	continue;
	89	}
	90	if (byte >= 0x20) value += String.fromCharCode(byte);
	91	}
	92	};
	93	stdin.on("data", onData);
	94	});
	95	}
	96
	97	export const command: Command = {
	98	name: "login",
	99	usage: { synopsis: "forge login <url>", flags: "[--token T] [--insecure]" },
	100	run: login,
	101	};
		@@ -0,0 +1,13 @@
	1	import { clearConfig } from "../config.ts";
	2	import { EXIT } from "../exit.ts";
	3	import type { Command } from "./types.ts";
	4
	5	export const command: Command = {
	6	name: "logout",
	7	usage: { synopsis: "forge logout" },
	8	async run(out) {
	9	await clearConfig();
	10	out.line("signed out");
	11	return EXIT.ok;
	12	},
	13	};
		@@ -0,0 +1,56 @@
	1	import { ForgeApi } from "../api.ts";
	2	import { rootDir } from "../config.ts";
	3	import { asJson, requireConfig } from "../context.ts";
	4	import { EXIT } from "../exit.ts";
	5	import { cell, type Out } from "../out.ts";
	6	import { dirtyCount, settled, since } from "../report.ts";
	7	import { syncOnce, type RepoReport } from "../sync.ts";
	8	import { G } from "../../tui/term/screen.ts";
	9	import { trackText } from "../../tui/local/common.ts";
	10	import type { Command } from "./types.ts";
	11
	12	function lsState(out: Out, r: RepoReport): ReturnType<typeof cell> {
	13	if (!r.present) return cell("not cloned", out.c.attn);
	14	const dirty = dirtyCount(r);
	15	if (dirty > 0) return cell(`${dirty} dirty`, out.c.accent);
	16	if (settled(r)) return cell(G.check, out.c.success);
	17	return cell(r.upstream === null ? "no upstream" : "", out.c.faint);
	18	}
	19
	20	export const command: Command = {
	21	name: "ls",
	22	usage: { synopsis: "forge ls", flags: "[--json]" },
	23	async run(out, args) {
	24	const loaded = await requireConfig(out);
	25	if (typeof loaded === "number") return loaded;
	26	// `ls` answers from disk, so it keeps working when the forge does not.
	27	const report = await syncOnce({
	28	api: new ForgeApi(loaded.url, loaded.token),
	29	token: loaded.token,
	30	root: rootDir(args.value("root")),
	31	fetch: false,
	32	});
	33	if (args.flag("json")) {
	34	out.line(JSON.stringify(asJson(report)));
	35	return EXIT.ok;
	36	}
	37	out.line(out.paint(report.root, out.c.faint));
	38	out.table(
	39	[
	40	{ header: "REPO", max: 44 },
	41	{ header: "BRANCH", max: 24 },
	42	{ header: "SYNC", align: "right" },
	43	{ header: "STATE", max: 28 },
	44	{ header: "FETCHED", align: "right" },
	45	],
	46	report.repos.map((r) => [
	47	cell(`${r.owner}/${r.name}`, r.present ? out.c.fg : out.c.mutedFg),
	48	cell(r.present ? (r.branch ?? "detached") : "—", out.c.mutedFg),
	49	cell(trackText(r.ahead, r.behind), out.c.attn),
	50	lsState(out, r),
	51	cell(r.present ? since(r.lastFetch) : "", out.c.faint),
	52	]),
	53	);
	54	return EXIT.ok;
	55	},
	56	};
		@@ -0,0 +1,37 @@
	1	import { ForgeApi } from "../api.ts";
	2	import { parseRepoRef } from "../args.ts";
	3	import { requireConfig } from "../context.ts";
	4	import { EXIT } from "../exit.ts";
	5	import type { Command } from "./types.ts";
	6
	7	export const command: Command = {
	8	name: "open",
	9	usage: { synopsis: "forge open <owner/name>", flags: "[--web]" },
	10	async run(out, args) {
	11	const ref = parseRepoRef(args.positional[0]);
	12	if (ref === undefined) {
	13	out.err("forge open: expected owner/name");
	14	return EXIT.usage;
	15	}
	16	const loaded = await requireConfig(out);
	17	if (typeof loaded === "number") return loaded;
	18	const url = new ForgeApi(loaded.url, loaded.token).webUrl(
	19	ref.owner,
	20	ref.name,
	21	);
	22	out.line(url);
	23	if (!args.flag("web")) return EXIT.ok;
	24	const opener = process.platform === "darwin" ? "open" : "xdg-open";
	25	try {
	26	const proc = Bun.spawn([opener, url], {
	27	stdout: "ignore",
	28	stderr: "ignore",
	29	});
	30	await proc.exited;
	31	} catch {
	32	out.err(`forge open: could not run ${opener}`);
	33	return EXIT.failed;
	34	}
	35	return EXIT.ok;
	36	},
	37	};
		@@ -0,0 +1,47 @@
	1	import { ForgeApi } from "../api.ts";
	2	import { parseRepoRef, type Args } from "../args.ts";
	3	import { requireConfig } from "../context.ts";
	4	import { EXIT } from "../exit.ts";
	5	import type { Out } from "../out.ts";
	6	import { G } from "../../tui/term/screen.ts";
	7	import type { Command } from "./types.ts";
	8
	9	/** Shared by `pin` and `unpin`: the two differ only in the call and the verb. */
	10	export async function setPin(
	11	out: Out,
	12	args: Args,
	13	on: boolean,
	14	): Promise<number> {
	15	const verb = on ? "pin" : "unpin";
	16	const ref = parseRepoRef(args.positional[0]);
	17	if (ref === undefined) {
	18	out.err(`forge ${verb}: expected owner/name`);
	19	return EXIT.usage;
	20	}
	21	const loaded = await requireConfig(out);
	22	if (typeof loaded === "number") return loaded;
	23	const api = new ForgeApi(loaded.url, loaded.token);
	24	const result = on
	25	? await api.pin(ref.owner, ref.name)
	26	: await api.unpin(ref.owner, ref.name);
	27	if (!result.ok) {
	28	out.err(
	29	result.error.status === 404
	30	? `forge ${verb}: this forge does not support pins yet`
	31	: `forge ${verb}: ${result.error.message}`,
	32	);
	33	return EXIT.failed;
	34	}
	35	out.line(
	36	`${out.paint(G.check, out.c.success)} ${on ? "pinned" : "unpinned"} ${ref.owner}/${ref.name}`,
	37	);
	38	if (on)
	39	out.line(out.paint(" run `forge sync` to bring it down", out.c.faint));
	40	return EXIT.ok;
	41	}
	42
	43	export const command: Command = {
	44	name: "pin",
	45	usage: { synopsis: "forge pin <owner/name>" },
	46	run: (out, args) => setPin(out, args, true),
	47	};
		@@ -0,0 +1,96 @@
	1	import { ForgeApi } from "../api.ts";
	2	import { parseRepoRef, type Args } from "../args.ts";
	3	import { requireConfig } from "../context.ts";
	4	import { EXIT } from "../exit.ts";
	5	import { folderRepo } from "../folder-repo.ts";
	6	import { inert, type Out } from "../out.ts";
	7	import { displayWidth, pad, truncate } from "../../tui/term/width.ts";
	8	import type { Command } from "./types.ts";
	9
	10	async function pulls(out: Out, args: Args): Promise<number> {
	11	const loaded = await requireConfig(out);
	12	if (typeof loaded === "number") return loaded;
	13	const flagged = args.value("repo");
	14	const ref =
	15	flagged !== undefined
	16	? parseRepoRef(flagged)
	17	: await folderRepo(process.cwd(), loaded.url);
	18	if (ref === undefined) {
	19	out.err(
	20	flagged !== undefined
	21	? "forge pulls: --repo expects owner/name"
	22	: `forge pulls: this folder is not a clone of ${loaded.url} — run it in a clone, or pass --repo owner/name`,
	23	);
	24	return EXIT.usage;
	25	}
	26	const closed = args.flag("closed");
	27	const got = await new ForgeApi(loaded.url, loaded.token).pulls(
	28	ref.owner,
	29	ref.name,
	30	closed ? "closed" : "open",
	31	);
	32	if (!got.ok) {
	33	out.err(`forge pulls: ${got.error.message}`);
	34	return EXIT.failed;
	35	}
	36	if (args.flag("json")) {
	37	out.line(JSON.stringify(got.value));
	38	return EXIT.ok;
	39	}
	40	const items = got.value.items as Record<string, unknown>[];
	41	if (items.length === 0) {
	42	out.line(closed ? "No closed pulls." : "No open pulls.");
	43	return EXIT.ok;
	44	}
	45	const tone = {
	46	green: out.c.success,
	47	red: out.c.danger,
	48	running: out.c.attn,
	49	none: out.c.faint,
	50	} as const;
	51	const rows = items.map((item) => ({
	52	number: `#${String(item["number"])}`,
	53	title: inert(String(item["title"] ?? "")),
	54	author: inert(String(item["author"] ?? "")),
	55	check: String(item["check"]) as keyof typeof tone,
	56	preview: inert(typeof item["preview"] === "string" ? item["preview"] : ""),
	57	}));
	58	const wide = (pick: (r: (typeof rows)[number]) => string): number =>
	59	Math.max(...rows.map((r) => displayWidth(pick(r))));
	60	const nW = wide((r) => r.number);
	61	const aW = Math.min(
	62	20,
	63	wide((r) => r.author),
	64	);
	65	const cW = wide((r) => r.check);
	66	const pW = wide((r) => r.preview);
	67	const gaps = 2 * (pW > 0 ? 4 : 3);
	68	const tW = Math.max(12, out.width - nW - aW - cW - pW - gaps);
	69	for (const r of rows) {
	70	const parts = [
	71	pad(r.number, nW, "right"),
	72	pad(truncate(r.title, tW), tW),
	73	pad(truncate(r.author, aW), aW),
	74	out.paint(pad(r.check, cW), tone[r.check] ?? out.c.faint),
	75	];
	76	if (pW > 0) parts.push(r.preview);
	77	out.line(parts.join(" ").replace(/\s+$/, ""));
	78	}
	79	if (got.value.next_cursor !== null)
	80	out.line(
	81	out.paint(
	82	`The list is cut after ${rows.length} pulls; the forge has more.`,
	83	out.c.faint,
	84	),
	85	);
	86	return EXIT.ok;
	87	}
	88
	89	export const command: Command = {
	90	name: "pulls",
	91	usage: {
	92	synopsis: "forge pulls",
	93	flags: "[--repo owner/name] [--closed] [--json]",
	94	},
	95	run: pulls,
	96	};
		@@ -0,0 +1,214 @@
	1	import { ForgeApi } from "../api.ts";
	2	import type { Args } from "../args.ts";
	3	import { requireConfig } from "../context.ts";
	4	import { EXIT } from "../exit.ts";
	5	import { printUsage } from "../help.ts";
	6	import { inert, type Out } from "../out.ts";
	7	import { displayWidth, pad, truncate } from "../../tui/term/width.ts";
	8	import type { Command } from "./types.ts";
	9
	10	/** The forge's default and ceiling for `limit` (`src/actions/search.ts`). */
	11	const SEARCH_API_LIMIT = 20;
	12	const SEARCH_API_LIMIT_MAX = 100;
	13
	14	const SEARCH_KINDS = ["code", "issues", "pulls", "repos", "all"] as const;
	15	export type SearchFor = (typeof SEARCH_KINDS)[number];
	16
	17	/**
	18	* `GET /api/v1/search` from a shell: every hit one line, grouped by kind.
	19	* The API has no `pulls` kind — its `issues` answers both — so `--kind
	20	* issues` and `--kind pulls` ask for `issues` at the API's ceiling and
	21	* keep N of the one kind (`narrowConversations`): asking for N and then
	22	* filtering would print fewer than N, or none.
	23	*/
	24	async function search(out: Out, args: Args): Promise<number> {
	25	const words = args.positional.join(" ").trim();
	26	if (words === "") {
	27	out.err("forge search: what for? e.g. forge search retry budget");
	28	printUsage(out);
	29	return EXIT.usage;
	30	}
	31	const kindRaw = args.value("kind");
	32	const kind = SEARCH_KINDS.find((k) => k === kindRaw);
	33	if (kindRaw !== undefined && kind === undefined) {
	34	out.err(`forge search: --kind is one of ${SEARCH_KINDS.join(", ")}`);
	35	return EXIT.usage;
	36	}
	37	const limitRaw = args.value("limit");
	38	const limit = limitRaw === undefined ? undefined : Number(limitRaw);
	39	if (limit !== undefined && (!/^\d+$/.test(limitRaw!) \|\| limit < 1)) {
	40	out.err("forge search: --limit expects a whole number above 0");
	41	return EXIT.usage;
	42	}
	43	const loaded = await requireConfig(out);
	44	if (typeof loaded === "number") return loaded;
	45	const oneConversation = kind === "issues" \|\| kind === "pulls";
	46	const answer = await new ForgeApi(loaded.url, loaded.token).search(words, {
	47	...(kind === undefined ? {} : { kind: oneConversation ? "issues" : kind }),
	48	...(oneConversation
	49	? { limit: SEARCH_API_LIMIT_MAX }
	50	: limit === undefined ? {} : { limit }),
	51	});
	52	if (!answer.ok) {
	53	const { message, retryAfter, status } = answer.error;
	54	const when =
	55	retryAfter === undefined \|\| new RegExp(`\\b${retryAfter}s\\b`).test(message)
	56	? ""
	57	: ` (retry in ${retryAfter}s)`;
	58	out.err(`forge search: ${message}${when}`);
	59	if (status === 429) return EXIT.rateLimited;
	60	return status === 401 ? EXIT.notConfigured : EXIT.failed;
	61	}
	62	const found = oneConversation
	63	? narrowConversations(answer.value, kind, limit ?? SEARCH_API_LIMIT)
	64	: answer.value;
	65	if (args.flag("json")) {
	66	out.line(JSON.stringify(found));
	67	return EXIT.ok;
	68	}
	69	const lines = searchLines(found, kind ?? "all", out.width, out);
	70	if (lines.length === 0) {
	71	out.line(`Nothing found for "${inert(words)}".`);
	72	return EXIT.ok;
	73	}
	74	for (const line of lines) out.line(line);
	75	return EXIT.ok;
	76	}
	77
	78	/**
	79	* The answer with `issues` kept to one kind (`issue` or `pull`) and cut to
	80	* `limit`; `truncated.issues` is set when the cut dropped any, or when the
	81	* forge had already cut its own window, so `--json` and the group header
	82	* both say the list is not whole. Everything else passes through.
	83	*/
	84	export function narrowConversations(
	85	raw: unknown,
	86	kind: "issues" \| "pulls",
	87	limit: number,
	88	): unknown {
	89	if (typeof raw !== "object" \|\| raw === null) return raw;
	90	const body = raw as Record<string, unknown>;
	91	const want = kind === "pulls" ? "pull" : "issue";
	92	const kept = rowsOf(body["issues"]).filter((r) => r["kind"] === want);
	93	const truncated = (typeof body["truncated"] === "object" && body["truncated"] !== null
	94	? body["truncated"]
	95	: {}) as Record<string, unknown>;
	96	return {
	97	...body,
	98	issues: kept.slice(0, limit),
	99	truncated: { ...truncated, issues: truncated["issues"] === true \|\| kept.length > limit },
	100	};
	101	}
	102
	103	/**
	104	* The search answer as lines no wider than `width - 1` where the text can
	105	* give way: each kind headed by its name and count, then one hit a line —
	106	* `owner/name:path:line text` for code, `owner/name#N title state` for
	107	* issues and pulls, `owner/name description` for repositories. Anything
	108	* the answer carries that is not the expected shape is skipped, not fatal.
	109	*/
	110	export function searchLines(
	111	raw: unknown,
	112	kind: SearchFor,
	113	width: number,
	114	out?: Pick<Out, "paint" \| "c">,
	115	): string[] {
	116	const body = (typeof raw === "object" && raw !== null ? raw : {}) as Record<string, unknown>;
	117	const truncated = (body["truncated"] ?? {}) as Record<string, unknown>;
	118	const conversations = rowsOf(body["issues"]).map(conversationRow);
	119	const groups: { kind: SearchFor; rows: [string, string, string][]; more: boolean }[] = [
	120	{ kind: "code", rows: rowsOf(body["code"]).map(codeRow), more: truncated["code"] === true },
	121	{
	122	kind: "issues",
	123	rows: conversations.filter((r) => r[0] === "issue").map((r) => r.slice(1) as [string, string, string]),
	124	more: truncated["issues"] === true,
	125	},
	126	{
	127	kind: "pulls",
	128	rows: conversations.filter((r) => r[0] === "pull").map((r) => r.slice(1) as [string, string, string]),
	129	more: truncated["issues"] === true,
	130	},
	131	{ kind: "repos", rows: rowsOf(body["repos"]).map(repoRow), more: truncated["repos"] === true },
	132	];
	133	const lines: string[] = [];
	134	for (const group of groups) {
	135	const rows = group.rows.filter((r) => r[0] !== "");
	136	if (rows.length === 0 \|\| (kind !== "all" && kind !== group.kind)) continue;
	137	if (lines.length > 0) lines.push("");
	138	const head = `${group.kind} (${rows.length}${group.more ? ", more not shown" : ""})`;
	139	lines.push(out === undefined ? head : out.paint(head, out.c.accent));
	140	// Code's place differs in width line to line; the others line up.
	141	const leadW = group.kind === "code" ? 0 : Math.max(...rows.map((r) => displayWidth(r[0])));
	142	const tails = rows.some((r) => r[2] !== "");
	143	const tailW = tails ? Math.max(...rows.map((r) => displayWidth(r[2]))) + 2 : 0;
	144	const textW = Math.max(...rows.map((r) => displayWidth(r[1])));
	145	for (const [lead, text, tail] of rows) {
	146	const first = leadW === 0 ? lead : pad(lead, leadW);
	147	const room = Math.max(8, width - 1 - displayWidth(first) - 2 - tailW);
	148	const cut = truncate(text, room);
	149	const shown = tails ? pad(cut, Math.min(room, textW)) : cut;
	150	lines.push(
	151	[
	152	first,
	153	shown,
	154	...(tail === "" ? [] : [out === undefined ? tail : out.paint(tail, out.c.faint)]),
	155	].join(" ").trimEnd(),
	156	);
	157	}
	158	if (group.kind === "code" && (body["moreCode"] === true \|\| body["codeSkipped"] === true)) {
	159	const note = " some repositories were not searched in time; --json says which kinds are partial";
	160	lines.push(out === undefined ? note : out.paint(note, out.c.faint));
	161	}
	162	}
	163	return lines;
	164	}
	165
	166	function rowsOf(value: unknown): Record<string, unknown>[] {
	167	return Array.isArray(value)
	168	? value.filter((v): v is Record<string, unknown> => typeof v === "object" && v !== null)
	169	: [];
	170	}
	171
	172	/** `owner/name` from a local hit's `repo`, or an origin hit's `fullName`. */
	173	function repoName(r: Record<string, unknown>): string {
	174	const repo = r["repo"] as Record<string, unknown> \| undefined;
	175	if (typeof repo?.["owner"] === "string" && typeof repo["name"] === "string")
	176	return `${repo["owner"]}/${repo["name"]}`;
	177	if (typeof r["owner"] === "string" && typeof r["name"] === "string")
	178	return `${r["owner"]}/${r["name"]}`;
	179	return typeof r["fullName"] === "string" ? r["fullName"] : "";
	180	}
	181
	182	function textOf(value: unknown): string {
	183	return typeof value === "string" ? inert(value) : "";
	184	}
	185
	186	function codeRow(r: Record<string, unknown>): [string, string, string] {
	187	const name = repoName(r);
	188	const path = textOf(r["path"]);
	189	const line = typeof r["line"] === "number" ? r["line"] : 0;
	190	if (name === "" \|\| path === "") return ["", "", ""];
	191	return [`${inert(name)}:${path}:${line}`, textOf(r["text"]).trim(), ""];
	192	}
	193
	194	function conversationRow(r: Record<string, unknown>): [string, string, string, string] {
	195	const name = repoName(r);
	196	const n = r["number"];
	197	if (name === "" \|\| typeof n !== "number") return ["", "", "", ""];
	198	return [textOf(r["kind"]), `${inert(name)}#${n}`, textOf(r["title"]), textOf(r["state"])];
	199	}
	200
	201	function repoRow(r: Record<string, unknown>): [string, string, string] {
	202	const name = repoName(r);
	203	return [inert(name), textOf(r["description"]), r["archived"] === true ? "archived" : ""];
	204	}
	205
	206
	207	export const command: Command = {
	208	name: "search",
	209	usage: {
	210	synopsis: "forge search <words…>",
	211	flags: "[--kind code\|issues\|pulls\|repos\|all] [--limit N] [--json]",
	212	},
	213	run: search,
	214	};