postgresai 0.16.0-dev.1 → 0.16.0-dev.3

package/lib/joe.ts

@@ -0,0 +1,730 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "node:crypto";
+import { formatHttpError, maskSecret, normalizeBaseUrl } from "./util";
+import * as config from "./config";
+
+/**
+ * Joe API v2 client (`postgres-ai` CLI / MCP surface).
+ *
+ * Every Joe command is a thin wrapper over the platform rpc `v1.joe_command_submit`
+ * (with the command's fixed `command`) plus a *client-side* status/result poll — there
+ * is no DB-side sync wrapper (a single PostgREST transaction cannot both submit a
+ * command and observe Joe's cross-connection callback). See SPEC §1/§5/§6.
+ *
+ * The backend rpcs (`joe_command_submit` / `joe_command_status` / `joe_command_result`
+ * and the org-level projects listing) do not exist yet — this module is written against
+ * the documented contract and exercised entirely with mocked fetch responses.
+ */
+
+/** The Joe command set (SPEC §5/§6 + the per-command contract matrix). */
+export const JOE_COMMANDS = [
+  "plan",
+  "explain",
+  "exec",
+  "hypo",
+  "activity",
+  "terminate",
+  "reset",
+  "describe",
+] as const;
+
+export type JoeCommand = (typeof JOE_COMMANDS)[number];
+
+/** Terminal + non-terminal command lifecycle states returned by the platform. */
+export type JoeStatus = "queued" | "running" | "done" | "error" | "timed_out";
+
+const TERMINAL_STATES: ReadonlySet<JoeStatus> = new Set<JoeStatus>([
+  "done",
+  "error",
+  "timed_out",
+]);
+
+/** Commands whose result reaches the caller's LLM — gated on the org `ai_enabled`. */
+export const AI_ENABLED_COMMANDS: ReadonlySet<JoeCommand> = new Set<JoeCommand>([
+  "plan",
+  "explain",
+  "exec",
+  "hypo",
+  "activity",
+  "describe",
+]);
+
+/** Commands that execute against the disposable clone (at-most-once posture). */
+const EXECUTING_COMMANDS: ReadonlySet<JoeCommand> = new Set<JoeCommand>([
+  "exec",
+  "explain",
+]);
+
+/** Default one-shot poll budget (SPEC §6: ≤ 25 s, then resume by handle). */
+export const DEFAULT_BUDGET_MS = 25_000;
+const DEFAULT_POLL_INTERVAL_MS = 800;
+
+// ---------------------------------------------------------------------------
+// Response shapes (documented contract — mocked in tests)
+// ---------------------------------------------------------------------------
+
+export interface JoeSubmitResponse {
+  command_id: string;
+  session_id: string | null;
+  status: JoeStatus;
+}
+
+export interface JoeStatusResponse {
+  command_id: string;
+  status: JoeStatus;
+  enqueued_at?: string | null;
+  started_at?: string | null;
+  finished_at?: string | null;
+  error?: string | null;
+}
+
+/**
+ * Command-appropriate result body (SPEC §1 + per-command contract matrix Part B).
+ * A single interface is used with per-command optional keys; only the keys for the
+ * submitted command are populated.
+ */
+export interface JoeCommandResult {
+  command_id: string;
+  command?: JoeCommand;
+  status: JoeStatus;
+  error: string | null;
+  // plan / explain
+  queryid?: string | null;
+  plan_fingerprint?: string | null;
+  plan_text?: string | null;
+  plan_json?: unknown;
+  // exec
+  row_count?: number | null;
+  result_rows?: unknown[] | null;
+  notices?: string[] | null;
+  // hypo
+  hypo_plan?: unknown;
+  hypo_used?: boolean | null;
+  // activity / describe
+  snapshot?: unknown;
+  // terminate
+  terminated?: boolean | null;
+  pid?: number | null;
+  // reset
+  reset?: boolean | null;
+}
+
+export interface ProjectListItem {
+  project_id: number;
+  alias: string | null;
+  name: string | null;
+  label: string | null;
+  /** Whether the project's single Joe instance is `joe_api_v2_enabled` + conformant. */
+  joe_ready: boolean;
+  /** Whether the project's DBLab tunnel is connected. */
+  tunnel: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Low-level rpc caller
+// ---------------------------------------------------------------------------
+
+interface RpcCallParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  fn: string;
+  body: Record<string, unknown>;
+  operation: string;
+  debug?: boolean;
+}
+
+async function callRpc<T>(params: RpcCallParams): Promise<T> {
+  const { apiKey, apiBaseUrl, fn, body, operation, debug } = params;
+  if (!apiKey) {
+    throw new Error("API key is required");
+  }
+
+  const base = normalizeBaseUrl(apiBaseUrl);
+  const url = new URL(`${base}/rpc/${fn}`);
+  const payload = JSON.stringify(body);
+
+  const headers: Record<string, string> = {
+    "access-token": apiKey,
+    "Content-Type": "application/json",
+    "Connection": "close",
+  };
+
+  if (debug) {
+    const debugHeaders: Record<string, string> = { ...headers, "access-token": maskSecret(apiKey) };
+    console.error(`Debug: POST URL: ${url.toString()}`);
+    console.error(`Debug: Request headers: ${JSON.stringify(debugHeaders)}`);
+    console.error(`Debug: Request body: ${payload}`);
+  }
+
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers,
+    body: payload,
+  });
+
+  const text = await response.text();
+
+  if (debug) {
+    console.error(`Debug: Response status: ${response.status}`);
+    console.error(`Debug: Response body: ${text}`);
+  }
+
+  if (!response.ok) {
+    // PostgREST maps a custom `PTxyz` sqlstate to HTTP status `xyz`, so PT403 →
+    // HTTP 403, PT404 → 404, PT429 → 429, etc. formatHttpError surfaces the JSON
+    // `message` (e.g. the "AI features disabled for this org" text for AC36).
+    throw new Error(formatHttpError(operation, response.status, text));
+  }
+
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`${operation}: failed to parse response: ${text}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Individual rpc client functions
+// ---------------------------------------------------------------------------
+
+export interface SubmitCommandParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  command: JoeCommand;
+  projectId: number;
+  sql?: string | null;
+  args?: Record<string, unknown> | null;
+  /** 64-bit session id, carried verbatim as a string to avoid precision loss. */
+  sessionId?: string | null;
+  idempotencyKey?: string | null;
+  debug?: boolean;
+}
+
+/** Submit a Joe command (`v1.joe_command_submit`); returns the queued handle. */
+export async function submitCommand(params: SubmitCommandParams): Promise<JoeSubmitResponse> {
+  const { apiKey, apiBaseUrl, command, projectId, sql, args, sessionId, idempotencyKey, debug } = params;
+  if (!JOE_COMMANDS.includes(command)) {
+    throw new Error(`Unknown Joe command: ${command}`);
+  }
+  const body: Record<string, unknown> = {
+    project_id: projectId,
+    command,
+    sql: sql ?? null,
+    args: args ?? null,
+    // session_id is a bigint server-side; sent as a numeric string when known so a
+    // 64-bit id survives JS number precision, null to start a fresh session/clone.
+    session_id: sessionId ?? null,
+  };
+  if (idempotencyKey) {
+    body.idempotency_key = idempotencyKey;
+  }
+  return callRpc<JoeSubmitResponse>({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_submit",
+    body,
+    operation: `Failed to submit ${command} command`,
+    debug,
+  });
+}
+
+export interface CommandIdParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  commandId: string;
+  debug?: boolean;
+}
+
+/** Poll a command's status metadata (`v1.joe_command_status`). */
+export async function getCommandStatus(params: CommandIdParams): Promise<JoeStatusResponse> {
+  const { apiKey, apiBaseUrl, commandId, debug } = params;
+  if (!commandId) {
+    throw new Error("commandId is required");
+  }
+  return callRpc<JoeStatusResponse>({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_status",
+    body: { command_id: commandId },
+    operation: "Failed to fetch command status",
+    debug,
+  });
+}
+
+/** Fetch a command's result body (`v1.joe_command_result`). */
+export async function getCommandResult(params: CommandIdParams): Promise<JoeCommandResult> {
+  const { apiKey, apiBaseUrl, commandId, debug } = params;
+  if (!commandId) {
+    throw new Error("commandId is required");
+  }
+  return callRpc<JoeCommandResult>({
+    apiKey,
+    apiBaseUrl,
+    fn: "joe_command_result",
+    body: { command_id: commandId },
+    operation: "Failed to fetch command result",
+    debug,
+  });
+}
+
+export interface ListProjectsParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  orgId?: number;
+  debug?: boolean;
+}
+
+interface RawProjectRow {
+  id?: number;
+  project_id?: number;
+  alias?: string | null;
+  name?: string | null;
+  label?: string | null;
+  joe_ready?: boolean;
+  joe_api_v2_enabled?: boolean;
+  tunnel?: boolean;
+  tunnel_ready?: boolean;
+}
+
+function normalizeProjectRow(row: RawProjectRow): ProjectListItem {
+  const projectId = row.project_id ?? row.id ?? 0;
+  return {
+    project_id: Number(projectId),
+    alias: row.alias ?? null,
+    name: row.name ?? null,
+    label: row.label ?? null,
+    joe_ready: Boolean(row.joe_ready ?? row.joe_api_v2_enabled ?? false),
+    tunnel: Boolean(row.tunnel ?? row.tunnel_ready ?? false),
+  };
+}
+
+/**
+ * List the org's projects (org-level discovery — NOT a Joe endpoint; SPEC §6).
+ * Backed by the general platform projects rpc, extended by item S.1 to surface the
+ * per-project `joe_ready` + `tunnel` state so an agent knows which it may address.
+ */
+export async function listProjects(params: ListProjectsParams): Promise<ProjectListItem[]> {
+  const { apiKey, apiBaseUrl, orgId, debug } = params;
+  const body: Record<string, unknown> = {};
+  if (typeof orgId === "number") {
+    body.org_id = orgId;
+  }
+  const rows = await callRpc<RawProjectRow[]>({
+    apiKey,
+    apiBaseUrl,
+    fn: "projects_list",
+    body,
+    operation: "Failed to list projects",
+    debug,
+  });
+  if (!Array.isArray(rows)) {
+    return [];
+  }
+  return rows.map(normalizeProjectRow);
+}
+
+// ---------------------------------------------------------------------------
+// Project id-or-alias resolution (S.0)
+// ---------------------------------------------------------------------------
+
+/** A bare numeric `--project` value is a project id; anything else is an alias/name. */
+export function isNumericProjectRef(ref: string): boolean {
+  return /^[0-9]+$/.test(ref.trim());
+}
+
+export interface ResolveProjectParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  project: string;
+  orgId?: number;
+  debug?: boolean;
+}
+
+/**
+ * Resolve `--project <id|alias>` to a numeric project id. A numeric ref is used
+ * directly (no lookup); an alias/name is resolved against the projects list, so
+ * `--project main-db` ≡ `--project 12` (SPEC §6, finding S.0).
+ */
+export async function resolveProjectId(params: ResolveProjectParams): Promise<number> {
+  // TODO(joe-v2): unify --project resolution once projects_list (S.1) returns the dblab instance id
+  const ref = String(params.project ?? "").trim();
+  if (!ref) {
+    throw new Error("project is required (--project <id|alias>)");
+  }
+  if (isNumericProjectRef(ref)) {
+    return Number(ref);
+  }
+  const projects = await listProjects({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    orgId: params.orgId,
+    debug: params.debug,
+  });
+  const needle = ref.toLowerCase();
+  const match = projects.find(
+    (p) =>
+      (p.alias !== null && p.alias.toLowerCase() === needle) ||
+      (p.name !== null && p.name.toLowerCase() === needle)
+  );
+  if (!match) {
+    throw new Error(
+      `Project not found for alias/name '${ref}'. Run 'pgai projects' to see available projects.`
+    );
+  }
+  return match.project_id;
+}
+
+// ---------------------------------------------------------------------------
+// Per-project session persistence (auto-threaded optimize loop, finding B-1)
+// ---------------------------------------------------------------------------
+
+function sessionStorePath(dir?: string): string {
+  return path.join(dir ?? config.getConfigDir(), "joe-sessions.json");
+}
+
+function readSessionStore(dir?: string): Record<string, string> {
+  const file = sessionStorePath(dir);
+  if (!fs.existsSync(file)) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as Record<string, string>;
+    }
+  } catch {
+    // Corrupt store — treat as empty rather than failing a command.
+  }
+  return {};
+}
+
+export function readStoredSessionId(projectId: number, dir?: string): string | null {
+  const store = readSessionStore(dir);
+  const value = store[String(projectId)];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+export function writeStoredSessionId(projectId: number, sessionId: string, dir?: string): void {
+  const baseDir = dir ?? config.getConfigDir();
+  if (!fs.existsSync(baseDir)) {
+    fs.mkdirSync(baseDir, { recursive: true, mode: 0o700 });
+  }
+  const store = readSessionStore(dir);
+  store[String(projectId)] = sessionId;
+  fs.writeFileSync(sessionStorePath(dir), JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
+}
+
+export function clearStoredSessionId(projectId: number, dir?: string): void {
+  const file = sessionStorePath(dir);
+  if (!fs.existsSync(file)) {
+    return;
+  }
+  const store = readSessionStore(dir);
+  if (String(projectId) in store) {
+    delete store[String(projectId)];
+    fs.writeFileSync(file, JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Idempotency keys
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the idempotency key for a submit. Executing commands (`exec`/`explain`)
+ * mint a STABLE key derived from `(project_id, command, sql, args)` so a
+ * timeout-resubmit dedupes back to the original command_id (at-most-once — SPEC M8);
+ * non-executing commands generate a fresh per-invocation key.
+ */
+export function computeIdempotencyKey(
+  command: JoeCommand,
+  projectId: number,
+  sql: string | null | undefined,
+  args: Record<string, unknown> | null | undefined
+): string {
+  if (EXECUTING_COMMANDS.has(command)) {
+    const canonical = `${projectId}\n${command}\n${sql ?? ""}\n${JSON.stringify(args ?? null)}`;
+    return `joe-${crypto.createHash("sha256").update(canonical).digest("hex")}`;
+  }
+  return `joe-${crypto.randomUUID()}`;
+}
+
+// ---------------------------------------------------------------------------
+// Submit-then-poll one-shot
+// ---------------------------------------------------------------------------
+
+export interface RunCommandParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  command: JoeCommand;
+  projectId: number;
+  sql?: string | null;
+  args?: Record<string, unknown> | null;
+  sessionId?: string | null;
+  idempotencyKey?: string | null;
+  budgetMs?: number;
+  pollIntervalMs?: number;
+  debug?: boolean;
+  /** Injectable clock/sleep for deterministic tests. */
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface RunCommandOutcome {
+  commandId: string;
+  /** The session id returned by submit (thread back / persist for the next command). */
+  sessionId: string | null;
+  status: JoeStatus;
+  /** Populated once the command reaches a terminal state (done/error/timed_out). */
+  result: JoeCommandResult | null;
+  /** True when the ≤ budget one-shot expired before a terminal state — resume by id. */
+  budgetExpired: boolean;
+}
+
+const defaultSleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Submit a command then client-side poll status/result within the one-shot budget.
+ * On a terminal state returns the result; on budget expiry returns a resume handle
+ * (`budgetExpired: true`) so the caller can `pgai result <command_id>` later.
+ */
+export async function runCommand(params: RunCommandParams): Promise<RunCommandOutcome> {
+  const {
+    apiKey,
+    apiBaseUrl,
+    command,
+    projectId,
+    sql,
+    args,
+    sessionId,
+    debug,
+  } = params;
+  const budgetMs = params.budgetMs ?? DEFAULT_BUDGET_MS;
+  const pollIntervalMs = params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  const now = params.now ?? Date.now;
+  const sleep = params.sleep ?? defaultSleep;
+  const idempotencyKey =
+    params.idempotencyKey ?? computeIdempotencyKey(command, projectId, sql, args);
+
+  const submitted = await submitCommand({
+    apiKey,
+    apiBaseUrl,
+    command,
+    projectId,
+    sql,
+    args,
+    sessionId,
+    idempotencyKey,
+    debug,
+  });
+
+  const commandId = submitted.command_id;
+  const newSessionId = submitted.session_id ?? sessionId ?? null;
+  const deadline = now() + budgetMs;
+  let status: JoeStatus = submitted.status;
+
+  // Poll status until terminal or the one-shot budget is exhausted.
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const statusResp = await getCommandStatus({ apiKey, apiBaseUrl, commandId, debug });
+    status = statusResp.status;
+    if (TERMINAL_STATES.has(status)) {
+      break;
+    }
+    if (now() >= deadline) {
+      return { commandId, sessionId: newSessionId, status, result: null, budgetExpired: true };
+    }
+    await sleep(pollIntervalMs);
+  }
+
+  const result = await getCommandResult({ apiKey, apiBaseUrl, commandId, debug });
+  return { commandId, sessionId: newSessionId, status, result, budgetExpired: false };
+}
+
+// ---------------------------------------------------------------------------
+// High-level orchestrator shared by the CLI and MCP surfaces
+// ---------------------------------------------------------------------------
+
+export interface ExecuteJoeParams {
+  apiKey: string;
+  apiBaseUrl: string;
+  command: JoeCommand;
+  /** Raw `--project <id|alias>` value. */
+  project: string;
+  sql?: string | null;
+  args?: Record<string, unknown> | null;
+  /** Explicit `--session <id>` (overrides the stored/auto session). */
+  session?: string | null;
+  /** `--new-session` — force a fresh clone (null session). */
+  newSession?: boolean;
+  orgId?: number;
+  budgetMs?: number;
+  pollIntervalMs?: number;
+  debug?: boolean;
+  /** Session-store directory (defaults to the user config dir). */
+  sessionDir?: string;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface ExecuteJoeOutcome extends RunCommandOutcome {
+  command: JoeCommand;
+  projectId: number;
+}
+
+/**
+ * Resolve the project (id-or-alias), pick the session (explicit / stored / new),
+ * run the submit-then-poll one-shot, and persist the returned session for the next
+ * command on the same project — the auto-threaded optimize loop.
+ */
+export async function executeJoeCommand(params: ExecuteJoeParams): Promise<ExecuteJoeOutcome> {
+  const projectId = await resolveProjectId({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    project: params.project,
+    orgId: params.orgId,
+    debug: params.debug,
+  });
+
+  let sessionId: string | null;
+  if (params.newSession) {
+    clearStoredSessionId(projectId, params.sessionDir);
+    sessionId = null;
+  } else if (params.session) {
+    sessionId = String(params.session);
+  } else {
+    sessionId = readStoredSessionId(projectId, params.sessionDir);
+  }
+
+  const outcome = await runCommand({
+    apiKey: params.apiKey,
+    apiBaseUrl: params.apiBaseUrl,
+    command: params.command,
+    projectId,
+    sql: params.sql,
+    args: params.args,
+    sessionId,
+    budgetMs: params.budgetMs,
+    pollIntervalMs: params.pollIntervalMs,
+    debug: params.debug,
+    now: params.now,
+    sleep: params.sleep,
+  });
+
+  if (outcome.sessionId) {
+    writeStoredSessionId(projectId, outcome.sessionId, params.sessionDir);
+  }
+
+  return { ...outcome, command: params.command, projectId };
+}
+
+// ---------------------------------------------------------------------------
+// Presentation helpers (pure — unit tested)
+// ---------------------------------------------------------------------------
+
+interface PlanNode {
+  "Node Type"?: string;
+  "Relation Name"?: string;
+  Plans?: PlanNode[];
+  [key: string]: unknown;
+}
+
+/**
+ * Lightweight CLIENT-SIDE plan flagging (SPEC §6). The API returns no
+ * server-authored recommendations (dropped as an injection vector), so the CLI
+ * flags obvious issues (e.g. a Seq Scan) from the returned plan_json itself.
+ */
+export function clientSidePlanFlags(planJson: unknown): string[] {
+  const flags: string[] = [];
+  const walk = (node: PlanNode | undefined): void => {
+    if (!node || typeof node !== "object") {
+      return;
+    }
+    const nodeType = node["Node Type"];
+    if (nodeType === "Seq Scan") {
+      const rel = node["Relation Name"];
+      flags.push(
+        `client-side: Seq Scan${rel ? ` on ${rel}` : ""} — no index serves this predicate; consider adding one.`
+      );
+    }
+    if (Array.isArray(node.Plans)) {
+      for (const child of node.Plans) {
+        walk(child);
+      }
+    }
+  };
+  if (planJson && typeof planJson === "object") {
+    const root = planJson as { Plan?: PlanNode };
+    walk(root.Plan ?? (planJson as PlanNode));
+  }
+  return flags;
+}
+
+/** Format a terminal command result as human-readable text (non-JSON mode). */
+export function formatJoeResult(command: JoeCommand, result: JoeCommandResult): string {
+  const lines: string[] = [];
+  switch (command) {
+    case "plan":
+    case "explain": {
+      if (result.plan_text) {
+        lines.push(result.plan_text);
+      }
+      for (const flag of clientSidePlanFlags(result.plan_json)) {
+        lines.push(`⚑ ${flag}`);
+      }
+      if (result.queryid || result.plan_fingerprint) {
+        lines.push(`(queryid ${result.queryid ?? "?"} · plan_fp ${result.plan_fingerprint ?? "?"})`);
+      }
+      break;
+    }
+    case "exec": {
+      const notices = result.notices ?? [];
+      const rowCount = result.row_count ?? 0;
+      lines.push(`${notices.join(" ") || "OK"} · ${rowCount} row${rowCount === 1 ? "" : "s"}`);
+      if (result.result_rows && result.result_rows.length > 0) {
+        lines.push(JSON.stringify(result.result_rows, null, 2));
+      }
+      break;
+    }
+    case "hypo": {
+      lines.push(result.hypo_used ? "hypothetical index would be used" : "hypothetical index would NOT be used");
+      if (result.hypo_plan !== undefined) {
+        lines.push(JSON.stringify(result.hypo_plan, null, 2));
+      }
+      break;
+    }
+    case "activity":
+    case "describe": {
+      lines.push(JSON.stringify(result.snapshot ?? null, null, 2));
+      break;
+    }
+    case "terminate": {
+      lines.push(`terminated ${result.terminated ? "yes" : "no"} · pid ${result.pid ?? "?"}`);
+      break;
+    }
+    case "reset": {
+      lines.push(`reset ${result.reset ? "ok" : "no"}`);
+      break;
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Render `pgai projects` as the brief's fixed-width table. */
+export function formatProjectsTable(projects: ProjectListItem[]): string {
+  const header = ["PROJECT_ID", "ALIAS", "PROJECT", "JOE", "TUNNEL"];
+  const rows = projects.map((p) => [
+    String(p.project_id),
+    p.alias ?? "-",
+    p.name ?? "-",
+    p.joe_ready ? "ready" : "no",
+    p.tunnel ? "yes" : "no",
+  ]);
+  const widths = header.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => r[i].length), 0)
+  );
+  const pad = (cells: string[]): string =>
+    cells.map((c, i) => c.padEnd(i === cells.length - 1 ? 0 : widths[i])).join("  ").trimEnd();
+  return [pad(header), ...rows.map(pad)].join("\n");
+}