@h-rig/cli 0.0.6-alpha.9 → 0.0.6-alpha.90

package/dist/src/commands/_cli-format.js

@@ -0,0 +1,447 @@
+// @bun
+// packages/cli/src/app/drone-ui.ts
+import { ProcessTerminal, TUI, Text, Input, SelectList, matchesKey } from "@earendil-works/pi-tui";
+
+// packages/cli/src/app/theme.ts
+var RIG_PALETTE = {
+  ink: "#f2f3f6",
+  ink2: "#aeb0ba",
+  ink3: "#6c6e79",
+  ink4: "#44464f",
+  accent: "#ccff4d",
+  accentDim: "#a9d63f",
+  cyan: "#56d8ff",
+  red: "#ff5d5d",
+  yellow: "#ffd24d"
+};
+function hexToRgb(hex) {
+  const value = hex.replace("#", "");
+  return [
+    Number.parseInt(value.slice(0, 2), 16),
+    Number.parseInt(value.slice(2, 4), 16),
+    Number.parseInt(value.slice(4, 6), 16)
+  ];
+}
+function fg(hex) {
+  const [r, g, b] = hexToRgb(hex);
+  return (text) => `\x1B[38;2;${r};${g};${b}m${text}\x1B[39m`;
+}
+var ink = fg(RIG_PALETTE.ink);
+var ink2 = fg(RIG_PALETTE.ink2);
+var ink3 = fg(RIG_PALETTE.ink3);
+var ink4 = fg(RIG_PALETTE.ink4);
+var accent = fg(RIG_PALETTE.accent);
+var accentDim = fg(RIG_PALETTE.accentDim);
+var cyan = fg(RIG_PALETTE.cyan);
+var red = fg(RIG_PALETTE.red);
+var yellow = fg(RIG_PALETTE.yellow);
+function bold(text) {
+  return `\x1B[1m${text}\x1B[22m`;
+}
+var DRONE_ART = [
+  "  .-=-.                   .-=-.   ",
+  " ( !!! )                 ( !!! )  ",
+  "  '-=-'._               _.'-=-'   ",
+  "        '._           _.'         ",
+  "           '=$$$$$$$=.'           ",
+  "          =$$$$$$$$$$$=           ",
+  "         $$$@@@@@@@@@@$$$         ",
+  "        $$$@@        @@$$$        ",
+  "        $$@    ?     @$$$         ",
+  "        $$$@   '-'   @$$$         ",
+  "        $$$@@        @@$$$        ",
+  "         $$$@@@@@@@@@@$$$         ",
+  "          =$$$$$$$$$$$=           ",
+  "           '=$$$$$$$=.'           ",
+  "        _.'           '._         ",
+  "  .-=-.'                 '.-=-.   ",
+  " ( !!! )                 ( !!! )  ",
+  "  '-=-'                   '-=-'   "
+];
+var EYE_FRAMES = ["@", "o", "."];
+var DRONE_WIDTH = DRONE_ART[0].length;
+var DRONE_HEIGHT = DRONE_ART.length;
+var MICRO_BLADES = ["---", "\\\\\\", "|||", "///"];
+function microDroneFrame(tick) {
+  const blade = MICRO_BLADES[tick % MICRO_BLADES.length];
+  const eye = EYE_FRAMES[Math.floor(tick / 2) % EYE_FRAMES.length];
+  return `(${blade})${eye}(${blade})`;
+}
+var MICRO_DRONE_FRAMES = Array.from({ length: 12 }, (_, index) => microDroneFrame(index));
+
+// packages/cli/src/app/drone-ui.ts
+function droneNote(message, title) {
+  if (title)
+    console.log(` ${accentDim("\u25C7")} ${bold(ink2(title))}`);
+  for (const line of message.split(`
+`)) {
+    console.log(` ${ink4("\u2502")} ${line}`);
+  }
+}
+
+// packages/cli/src/commands/_cli-format.ts
+import pc from "picocolors";
+var themeDim = (value) => ink3(value);
+var themeFaint = (value) => ink4(value);
+function stringField(record, key, fallback = "") {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+function numberField(record, key) {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function arrayField(record, key) {
+  const value = record[key];
+  return Array.isArray(value) ? value.flatMap((entry) => typeof entry === "string" && entry.trim() ? [entry.trim()] : []) : [];
+}
+function rawObject(record) {
+  const raw = record.raw;
+  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+}
+function truncate(value, width) {
+  if (value.length <= width)
+    return value;
+  if (width <= 1)
+    return "\u2026";
+  return `${value.slice(0, width - 1)}\u2026`;
+}
+function pad(value, width) {
+  return value.length >= width ? value : `${value}${" ".repeat(width - value.length)}`;
+}
+function statusColor(status) {
+  const normalized = status.toLowerCase();
+  if (["completed", "merged", "closed", "done", "accepted", "pass", "selected", "approved", "running"].includes(normalized))
+    return accent;
+  if (["failed", "needs_attention", "needs-attention", "blocked", "error", "rejected"].includes(normalized))
+    return red;
+  if (["reviewing", "validating", "in_progress", "in-progress", "remote", "preparing", "closing-out"].includes(normalized))
+    return cyan;
+  if (["ready", "open", "queued", "created", "local", "pending"].includes(normalized))
+    return yellow;
+  return themeDim;
+}
+function compactDate(value) {
+  if (!value.trim())
+    return "";
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed))
+    return value;
+  return new Date(parsed).toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "Z");
+}
+function compactValue(value) {
+  if (value === null || value === undefined)
+    return "";
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  if (Array.isArray(value))
+    return value.map(compactValue).filter(Boolean).join(", ");
+  return JSON.stringify(value);
+}
+function firstString(record, keys, fallback = "") {
+  for (const key of keys) {
+    const value = stringField(record, key);
+    if (value)
+      return value;
+  }
+  return fallback;
+}
+function runIdOf(run) {
+  return firstString(run, ["runId", "id"], "(unknown-run)");
+}
+function taskIdOf(run) {
+  return firstString(run, ["taskId", "task", "task_id"]);
+}
+function runTitleOf(run) {
+  return firstString(run, ["title", "summary", "name"], taskIdOf(run) || "(untitled)");
+}
+function requestIdOf(entry) {
+  return firstString(entry, ["requestId", "id", "approvalId", "inputId"], "(unknown-request)");
+}
+function shouldUseClackOutput() {
+  return Boolean(process.stdout.isTTY) && process.env.RIG_CLI_PLAIN_HELP !== "1";
+}
+function printFormattedOutput(message, options = {}) {
+  if (!shouldUseClackOutput()) {
+    console.log(message);
+    return;
+  }
+  droneNote(message, options.title);
+}
+function formatStatusPill(status) {
+  const label = status || "unknown";
+  return statusColor(label)(`\u25CF ${label}`);
+}
+function formatSection(title, subtitle) {
+  return `${pc.bold(accent("\u25C6"))} ${pc.bold(title)}${subtitle ? themeDim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatSuccessCard(title, rows = []) {
+  const body = rows.filter(([, value]) => value !== undefined && value !== null && String(value).length > 0).map(([key, value]) => `${themeFaint("\u2502")} ${themeDim(key.padEnd(12))} ${value}`);
+  return [formatSection(title), ...body].join(`
+`);
+}
+function formatNextSteps(steps) {
+  if (steps.length === 0)
+    return [];
+  return [pc.bold("Next"), ...steps.map((step) => `${accent("\u203A")} ${step}`)];
+}
+function formatTaskList(tasks, options = {}) {
+  if (options.raw)
+    return tasks.map((task) => JSON.stringify(task)).join(`
+`);
+  if (tasks.length === 0)
+    return [formatSection("Tasks", "none found"), ...formatNextSteps(["Try `rig server status` to confirm the selected server.", "Relax filters or run `rig task run --title ... --initial-prompt ...` for ad hoc work."])].join(`
+`);
+  const rows = tasks.map((task) => {
+    const raw = rawObject(task);
+    const id = stringField(task, "id", "<unknown>");
+    const status = stringField(task, "status", "unknown");
+    const title = stringField(task, "title", "Untitled task");
+    const source = stringField(task, "source", stringField(raw, "source", ""));
+    const labels = arrayField(task, "labels").length > 0 ? arrayField(task, "labels") : arrayField(raw, "labels");
+    return { id, status, title, source, labels };
+  });
+  const idWidth = Math.min(18, Math.max(4, ...rows.map((row) => row.id.length)));
+  const statusWidth = Math.min(16, Math.max(6, ...rows.map((row) => row.status.length)));
+  const header = `${pc.bold(pad("TASK", idWidth))}  ${pc.bold(pad("STATUS", statusWidth))}  ${pc.bold("TITLE")}`;
+  const body = rows.map((row) => {
+    const labels = row.labels.length > 0 ? themeDim(`  ${row.labels.slice(0, 4).map((label) => `#${label}`).join(" ")}`) : "";
+    const source = row.source ? themeDim(`  ${row.source}`) : "";
+    return [
+      pc.bold(pad(truncate(row.id, idWidth), idWidth)),
+      statusColor(row.status)(pad(truncate(row.status, statusWidth), statusWidth)),
+      `${row.title}${labels}${source}`
+    ].join("  ");
+  });
+  return [formatSection("Tasks", `${rows.length} shown`), header, ...body, "", ...formatNextSteps(["Run one: `rig task run <id>` or `rig task run --next`", "Attach later: `rig run attach <run-id> --follow`"])].join(`
+`);
+}
+function formatTaskCard(task, options = {}) {
+  const raw = rawObject(task);
+  const id = stringField(task, "id", stringField(raw, "id", "<unknown>"));
+  const status = stringField(task, "status", stringField(raw, "status", "unknown"));
+  const title = stringField(task, "title", stringField(raw, "title", "Untitled task"));
+  const source = stringField(task, "source", stringField(raw, "source", ""));
+  const url = stringField(task, "url", stringField(raw, "url", ""));
+  const number = numberField(task, "number") ?? numberField(raw, "number");
+  const labels = arrayField(task, "labels").length > 0 ? arrayField(task, "labels") : arrayField(raw, "labels");
+  const assignees = arrayField(task, "assignees").length > 0 ? arrayField(task, "assignees") : arrayField(raw, "assignees");
+  const readiness = compactValue(task.readiness ?? raw.readiness);
+  const validators = compactValue(task.validators ?? raw.validators ?? task.validation ?? raw.validation);
+  const rows = [
+    ["task", pc.bold(id)],
+    ["status", formatStatusPill(status)],
+    ["title", title],
+    ["source", source],
+    ["number", number],
+    ["labels", labels.length ? labels.map((label) => `#${label}`).join(" ") : ""],
+    ["assignees", assignees.join(", ")],
+    ["readiness", readiness],
+    ["validators", validators],
+    ["url", url]
+  ];
+  return [
+    formatSuccessCard(options.title ?? (options.selected ? "Selected task" : "Task"), rows),
+    "",
+    ...formatNextSteps([`Start: \`rig task run ${id}\``, `Details: \`rig task show ${id} --raw\``])
+  ].join(`
+`);
+}
+function formatTaskDetails(task) {
+  return formatTaskCard(task, { title: "Task details" });
+}
+function formatRunList(runs, options = {}) {
+  if (runs.length === 0) {
+    return [
+      formatSection("Runs", "none recorded"),
+      options.source === "server" ? themeDim("No runs recorded on the selected Rig server.") : themeDim("No runs recorded in .rig/runs."),
+      "",
+      ...formatNextSteps(["Start one: `rig task run --next`", "Check server: `rig server status`"])
+    ].join(`
+`);
+  }
+  const rows = runs.map((run) => {
+    const runId = stringField(run, "runId", stringField(run, "id", "(unknown-run)"));
+    const status = stringField(run, "status", "unknown");
+    const taskId = stringField(run, "taskId", "");
+    const title = stringField(run, "title", taskId || "(untitled)");
+    const runtime = stringField(run, "runtimeAdapter", "");
+    return { runId, status, title, runtime };
+  });
+  const idWidth = Math.min(36, Math.max(6, ...rows.map((row) => row.runId.length)));
+  const statusWidth = Math.min(16, Math.max(6, ...rows.map((row) => row.status.length)));
+  const header = `${pc.bold(pad("RUN", idWidth))}  ${pc.bold(pad("STATUS", statusWidth))}  ${pc.bold("TITLE")}`;
+  const body = rows.map((row) => [
+    pc.bold(pad(truncate(row.runId, idWidth), idWidth)),
+    statusColor(row.status)(pad(truncate(row.status, statusWidth), statusWidth)),
+    `${row.title}${row.runtime ? themeDim(`  ${row.runtime}`) : ""}`
+  ].join("  "));
+  return [formatSection("Runs", options.source === "server" ? "selected server" : "local state"), header, ...body, "", ...formatNextSteps(["Follow live: `rig run attach <run-id> --follow`", "Details: `rig run show <run-id>`"])].join(`
+`);
+}
+function formatSubmittedRun(input) {
+  const rows = [["run", pc.bold(input.runId)]];
+  if (input.task) {
+    const id = stringField(input.task, "id", "<unknown>");
+    const status = stringField(input.task, "status", "unknown");
+    const title = stringField(input.task, "title", "Untitled task");
+    rows.push(["task", `${pc.bold(id)} ${formatStatusPill(status)} ${title}`]);
+  }
+  const runtime = [input.runtimeAdapter || "pi", input.runtimeMode || "full-access", input.interactionMode || "default"].filter(Boolean).join(" \xB7 ");
+  rows.push(["runtime", runtime]);
+  return [
+    formatSuccessCard("Run submitted", rows),
+    "",
+    ...formatNextSteps([
+      `Attach: \`rig run attach ${input.runId} --follow\``,
+      `Inspect: \`rig run show ${input.runId}\``,
+      input.detached ? "Submitted detached; attach when you are ready." : "Interactive mode opens the enriched bundled Pi (native UI + Rig layers, worker brain)."
+    ])
+  ].join(`
+`);
+}
+function formatRunCard(run, options = {}) {
+  const raw = rawObject(run);
+  const merged = { ...raw, ...run };
+  const runId = runIdOf(merged);
+  const status = firstString(merged, ["status"], "unknown");
+  const taskId = taskIdOf(merged);
+  const title = runTitleOf(merged);
+  const runtime = firstString(merged, ["runtimeAdapter", "runtime", "adapter"]);
+  const mode = firstString(merged, ["runtimeMode", "mode"]);
+  const interaction = firstString(merged, ["interactionMode"]);
+  const created = compactDate(firstString(merged, ["createdAt"]));
+  const started = compactDate(firstString(merged, ["startedAt"]));
+  const updated = compactDate(firstString(merged, ["updatedAt"]));
+  const completed = compactDate(firstString(merged, ["completedAt", "finishedAt"]));
+  const worktree = firstString(merged, ["worktreePath", "cwd", "projectRoot"]);
+  const piSession = merged.piSession && typeof merged.piSession === "object" && !Array.isArray(merged.piSession) ? firstString(merged.piSession, ["sessionId", "id"]) : "";
+  const timeline = Array.isArray(merged.timeline) ? merged.timeline.length : null;
+  const approvals = Array.isArray(merged.approvals) ? merged.approvals.length : null;
+  const inputs = Array.isArray(merged.userInputs) ? merged.userInputs.length : null;
+  const rows = [
+    ["run", pc.bold(runId)],
+    ["status", formatStatusPill(status)],
+    ["task", taskId],
+    ["title", title],
+    ["runtime", [runtime, mode, interaction].filter(Boolean).join(" \xB7 ")],
+    ["created", created],
+    ["started", started],
+    ["updated", updated],
+    ["completed", completed],
+    ["worktree", worktree],
+    ["pi", piSession],
+    ["timeline", timeline],
+    ["approvals", approvals],
+    ["inputs", inputs]
+  ];
+  return [
+    formatSuccessCard(options.title ?? "Run details", rows),
+    "",
+    ...formatNextSteps([`Follow live: \`rig run attach ${runId} --follow\``, `Raw payload: \`rig run show ${runId} --raw\``])
+  ].join(`
+`);
+}
+function formatRunStatus(summary, options = {}) {
+  const activeRuns = summary.activeRuns ?? [];
+  const recentRuns = summary.recentRuns ?? [];
+  const lines = [formatSection("Run status", options.source === "server" ? "selected server" : "local state")];
+  lines.push("", pc.bold(`Active runs (${activeRuns.length})`));
+  if (activeRuns.length === 0) {
+    lines.push(themeDim("No active runs."));
+  } else {
+    for (const run of activeRuns) {
+      lines.push(formatRunSummaryLine(run));
+    }
+  }
+  lines.push("", pc.bold(`Recent runs (${recentRuns.length})`));
+  if (recentRuns.length === 0) {
+    lines.push(themeDim("No recent terminal runs."));
+  } else {
+    for (const run of recentRuns.slice(0, 10)) {
+      lines.push(formatRunSummaryLine(run));
+    }
+  }
+  lines.push("", ...formatNextSteps(["Start work: `rig task run --next`", "Attach: `rig run attach <run-id> --follow`", "Details: `rig run show <run-id>`"]));
+  return lines.join(`
+`);
+}
+function formatRunSummaryLine(run) {
+  const record = run;
+  const runId = runIdOf(record);
+  const status = firstString(record, ["status"], "unknown");
+  const taskId = taskIdOf(record);
+  const title = runTitleOf(record);
+  const runtime = firstString(record, ["runtimeAdapter", "runtime", "adapter"]);
+  const descriptor = [taskId, title].filter(Boolean).join(" \xB7 ");
+  return `${themeFaint("\u2502")} ${pc.bold(runId)} ${formatStatusPill(status)} ${descriptor}${runtime ? themeDim(`  ${runtime}`) : ""}`;
+}
+function formatInboxList(kind, entries) {
+  const title = kind === "approvals" ? "Approval inbox" : "Input inbox";
+  if (entries.length === 0) {
+    return [
+      formatSection(title, "empty"),
+      themeDim(kind === "approvals" ? "No pending approvals." : "No pending user-input requests."),
+      "",
+      ...formatNextSteps(["Check runs: `rig run status`", "Start work: `rig task run --next`"])
+    ].join(`
+`);
+  }
+  const lines = [formatSection(title, `${entries.length} pending`)];
+  for (const entry of entries) {
+    const record = entry.record && typeof entry.record === "object" && !Array.isArray(entry.record) ? entry.record : entry;
+    const runId = firstString(entry, ["runId"], firstString(record, ["runId"]));
+    const taskId = firstString(entry, ["taskId"], firstString(record, ["taskId", "task"]));
+    const requestId = requestIdOf(record);
+    const status = firstString(record, ["status", "state"], "pending");
+    const prompt = firstString(record, ["prompt", "message", "reason", "title", "summary"], kind === "approvals" ? "Approval requested" : "Input requested");
+    lines.push(`${themeFaint("\u2502")} ${pc.bold(requestId)} ${formatStatusPill(status)} ${prompt}`);
+    lines.push(`${themeFaint("\u2502")} ${themeDim("run      ")} ${runId || "(unknown-run)"}${taskId ? themeDim(`  task ${taskId}`) : ""}`);
+  }
+  lines.push("", ...formatNextSteps(kind === "approvals" ? ["Resolve: `rig inbox approve --run <run-id> --request <request-id> --decision approve|reject`", "Rejoin: `rig run attach <run-id> --follow`"] : ["Respond: `rig inbox respond --run <run-id> --request <request-id> --answer key=value`", "Rejoin: `rig run attach <run-id> --follow`"]));
+  return lines.join(`
+`);
+}
+function formatConnectionList(connections) {
+  const rows = [["local", { kind: "local", mode: "auto" }], ...Object.entries(connections)];
+  const aliasWidth = Math.min(24, Math.max(5, ...rows.map(([alias]) => alias.length)));
+  const lines = rows.map(([alias, connection]) => [
+    pc.bold(pad(truncate(alias, aliasWidth), aliasWidth)),
+    formatStatusPill(connection.kind),
+    connection.kind === "remote" ? connection.baseUrl ?? "" : connection.mode ?? "local"
+  ].join("  "));
+  return [formatSection("Rig servers", `${rows.length} available`), `${pc.bold(pad("ALIAS", aliasWidth))}  ${pc.bold("KIND")}  ${pc.bold("TARGET")}`, ...lines, "", ...formatNextSteps(["Select one: `rig server use <alias|local>`"])].join(`
+`);
+}
+function formatConnectionStatus(selected, connections) {
+  const connection = selected === "local" ? { kind: "local", mode: "auto" } : connections[selected];
+  const target = !connection ? "not configured" : connection.kind === "remote" ? connection.baseUrl : "local";
+  return [
+    formatSection("Rig server", "selected for this repo"),
+    `${themeFaint("\u2502")} ${themeDim("selected ")} ${pc.bold(selected)}`,
+    `${themeFaint("\u2502")} ${themeDim("kind     ")} ${formatStatusPill(connection?.kind ?? "unknown")}`,
+    `${themeFaint("\u2502")} ${themeDim("target   ")} ${target ?? "not configured"}`,
+    "",
+    ...formatNextSteps(["Change: `rig server use <alias|local>`", "List saved servers: `rig server list`"])
+  ].join(`
+`);
+}
+export {
+  printFormattedOutput,
+  formatTaskList,
+  formatTaskDetails,
+  formatTaskCard,
+  formatSuccessCard,
+  formatSubmittedRun,
+  formatStatusPill,
+  formatSection,
+  formatRunStatus,
+  formatRunList,
+  formatRunCard,
+  formatNextSteps,
+  formatInboxList,
+  formatConnectionStatus,
+  formatConnectionList
+};

package/dist/src/commands/_connection-state.d.ts

@@ -0,0 +1,44 @@
+export type RigConnection = {
+    kind: "local";
+    mode: "auto";
+} | {
+    kind: "remote";
+    baseUrl: string;
+};
+export type GlobalConnectionState = {
+    connections: Record<string, RigConnection>;
+};
+export type RepoConnectionState = {
+    selected: string;
+    project?: string;
+    linkedAt?: string;
+    /**
+     * The server-host project root this repo scopes to (multi-root serving).
+     * Sent as the x-rig-project-root header on every remote request.
+     */
+    serverProjectRoot?: string;
+};
+export declare function resolveGlobalConnectionsPath(env?: NodeJS.ProcessEnv): string;
+export declare function resolveRepoConnectionPath(projectRoot: string): string;
+export declare function readGlobalConnections(options?: {
+    env?: NodeJS.ProcessEnv;
+}): GlobalConnectionState;
+export declare function writeGlobalConnections(state: GlobalConnectionState, options?: {
+    env?: NodeJS.ProcessEnv;
+}): void;
+export declare function upsertGlobalConnection(alias: string, connection: RigConnection, options?: {
+    env?: NodeJS.ProcessEnv;
+}): GlobalConnectionState;
+export declare function readRepoConnection(projectRoot: string): RepoConnectionState | null;
+export declare function writeRepoConnection(projectRoot: string, state: RepoConnectionState): void;
+export declare function resolveSelectedConnection(projectRoot: string, options?: {
+    env?: NodeJS.ProcessEnv;
+}): {
+    alias: string;
+    connection: RigConnection;
+    serverProjectRoot?: string;
+} | null;
+/** Persist the server-host project root this repo scopes to (multi-root serving). */
+export declare function writeRepoServerProjectRoot(projectRoot: string, serverProjectRoot: string): void;
+/** Whether this repo's selected connection targets a remote Rig server. */
+export declare function isRemoteConnectionSelected(projectRoot: string): boolean;

package/dist/src/commands/_connection-state.js

@@ -6,12 +6,19 @@ import { dirname, resolve } from "path";
 
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
-import { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
-import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
 
 // packages/cli/src/commands/_connection-state.ts
 function resolveGlobalConnectionsPath(env = process.env) {
@@ -32,7 +39,7 @@ function readJsonFile(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
   } catch (error) {
-    throw new CliError2(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1);
+    throw new CliError(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1, { hint: "Fix or delete that file, then re-select a server with `rig server use <alias|local>`." });
   }
 }
 function writeJsonFile(path, value) {
@@ -75,7 +82,7 @@ function writeGlobalConnections(state, options = {}) {
 function upsertGlobalConnection(alias, connection, options = {}) {
   const cleanAlias = alias.trim();
   if (!cleanAlias)
-    throw new CliError2("Connection alias is required.", 1);
+    throw new CliError("Connection alias is required.", 1, { hint: "Save a server with `rig server add <alias> <url>`." });
   const state = readGlobalConnections(options);
   state.connections[cleanAlias] = connection;
   writeGlobalConnections(state, options);
@@ -92,7 +99,8 @@ function readRepoConnection(projectRoot) {
   return {
     selected,
     project: typeof record.project === "string" ? record.project : undefined,
-    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined
+    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined,
+    serverProjectRoot: typeof record.serverProjectRoot === "string" && record.serverProjectRoot.trim() ? record.serverProjectRoot.trim() : undefined
   };
 }
 function writeRepoConnection(projectRoot, state) {
@@ -103,15 +111,25 @@ function resolveSelectedConnection(projectRoot, options = {}) {
   if (!repo)
     return null;
   if (repo.selected === "local")
-    return { alias: "local", connection: { kind: "local", mode: "auto" } };
+    return { alias: "local", connection: { kind: "local", mode: "auto" }, serverProjectRoot: repo.serverProjectRoot };
   const global = readGlobalConnections(options);
   const connection = global.connections[repo.selected];
   if (!connection) {
-    throw new CliError2(`Selected Rig connection "${repo.selected}" was not found. Run \`rig connect list\` or \`rig connect use local\`.`, 1);
+    throw new CliError(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
   }
-  return { alias: repo.selected, connection };
+  return { alias: repo.selected, connection, serverProjectRoot: repo.serverProjectRoot };
+}
+function writeRepoServerProjectRoot(projectRoot, serverProjectRoot) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return;
+  writeRepoConnection(projectRoot, { ...repo, serverProjectRoot });
+}
+function isRemoteConnectionSelected(projectRoot) {
+  return resolveSelectedConnection(projectRoot)?.connection.kind === "remote";
 }
 export {
+  writeRepoServerProjectRoot,
   writeRepoConnection,
   writeGlobalConnections,
   upsertGlobalConnection,
@@ -119,5 +137,6 @@ export {
   resolveRepoConnectionPath,
   resolveGlobalConnectionsPath,
   readRepoConnection,
-  readGlobalConnections
+  readGlobalConnections,
+  isRemoteConnectionSelected
 };

package/dist/src/commands/_doctor-checks.d.ts

@@ -0,0 +1,52 @@
+type DoctorConfig = {
+    readonly project?: Record<string, unknown>;
+    readonly taskSource?: {
+        readonly kind?: string;
+        readonly owner?: string;
+        readonly repo?: string;
+    };
+    readonly github?: {
+        readonly projects?: {
+            readonly enabled?: boolean;
+            readonly projectId?: string;
+            readonly statusFieldId?: string;
+        };
+    };
+    readonly pr?: {
+        readonly mode?: string;
+    };
+    readonly merge?: {
+        readonly mode?: string;
+        readonly method?: string;
+    };
+};
+import { type PiInstallCheck } from "./_pi-install";
+export type DoctorStatus = "pass" | "warn" | "fail";
+export type RigDoctorCheck = {
+    readonly id: string;
+    readonly label: string;
+    readonly status: DoctorStatus;
+    readonly detail?: string;
+    readonly remediation?: string;
+};
+export type RigDoctorServer = {
+    readonly baseUrl: string;
+    readonly authToken: string | null;
+    readonly connectionKind: "local" | "remote";
+};
+export type RunRigDoctorChecksOptions = {
+    readonly projectRoot: string;
+    readonly resolveServer?: (projectRoot: string) => Promise<RigDoctorServer>;
+    readonly requestJson?: (pathname: string, init?: RequestInit) => Promise<unknown>;
+    readonly piChecks?: () => Promise<readonly PiInstallCheck[]>;
+    readonly which?: (binary: string) => string | null;
+    readonly bunVersion?: string;
+    readonly loadConfig?: (projectRoot: string) => Promise<DoctorConfig | null>;
+    /** Per-check status narration ("Checking GitHub auth…") for wait spinners. */
+    readonly onProgress?: (label: string) => void;
+};
+export declare function runRigDoctorChecks(options: RunRigDoctorChecksOptions): Promise<RigDoctorCheck[]>;
+export declare function formatDoctorChecks(checks: readonly RigDoctorCheck[]): string;
+export declare function countDoctorFailures(checks: readonly RigDoctorCheck[]): number;
+export declare function throwIfDoctorFailed(checks: readonly RigDoctorCheck[]): void;
+export {};