@h-rig/cli 0.0.6-alpha.7 → 0.0.6-alpha.70

package/dist/src/commands/browser.js

@@ -10,12 +10,19 @@ import pc2 from "picocolors";
 
 // 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();
+    }
+  }
+}
 function takeFlag(args, flag) {
   const rest = [];
   let value = false;
@@ -36,7 +43,7 @@ function takeOption(args, option) {
     if (current === option) {
       const next = args[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new CliError(`Missing value for ${option}`);
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
       }
       value = next;
       index += 1;
@@ -95,7 +102,7 @@ async function promptBugConfirm(message, initialValue) {
 function unwrapClackPrompt(result) {
   if (clack.isCancel(result)) {
     clack.cancel("Bug report cancelled.");
-    throw new CliError2("Bug report cancelled by user.");
+    throw new CliError("Bug report cancelled by user.");
   }
   return result;
 }
@@ -351,7 +358,7 @@ async function executeBrowser(context, args) {
     return { ok: true, group: "browser", command: "help" };
   }
   if (command === "explain") {
-    requireNoExtraArgs(rest, "bun run rig browser explain");
+    requireNoExtraArgs(rest, "rig browser explain");
     console.log(browserAgentUsageText());
     return { ok: true, group: "browser", command: "explain" };
   }
@@ -361,7 +368,7 @@ async function executeBrowser(context, args) {
   if (command === "app" || command === "hp-next") {
     const appSlug = command === "hp-next" ? "hp-next" : process.env.RIG_BROWSER_APP?.trim() || "";
     if (!appSlug) {
-      throw new CliError2(`rig browser app: set RIG_BROWSER_APP=<app-slug> to select which project app scripts to invoke.
+      throw new CliError(`rig browser app: set RIG_BROWSER_APP=<app-slug> to select which project app scripts to invoke.
 ` + `Scripts are invoked as 'bun run app:<mode>:browser:<app-slug>'.
 
 ${browserHelpText()}`);
@@ -373,11 +380,11 @@ ${browserHelpText()}`);
     }
     const modes = ["dev", "start", "check", "e2e", "reset"];
     if (!modes.includes(subcommand)) {
-      throw new CliError2(`Unknown browser ${command} command: ${subcommand}. Valid modes: ${modes.join(", ")}.
+      throw new CliError(`Unknown browser ${command} command: ${subcommand}. Valid modes: ${modes.join(", ")}.
 
 ${browserHelpText()}`);
     }
-    requireNoExtraArgs(appRest, `bun run rig browser ${command} ${subcommand}`);
+    requireNoExtraArgs(appRest, `rig browser ${command} ${subcommand}`);
     await context.runCommand(["bun", "run", `app:${subcommand}:browser:${appSlug}`]);
     return { ok: true, group: "browser", command: `${command}-${subcommand}` };
   }
@@ -389,13 +396,13 @@ ${browserHelpText()}`);
   };
   const packageScript = packageScripts[command];
   if (packageScript) {
-    requireNoExtraArgs(rest, `bun run rig browser ${command}`);
+    requireNoExtraArgs(rest, `rig browser ${command}`);
     await context.runCommand(["bun", "run", "--filter=@rig/browser", packageScript]);
     return { ok: true, group: "browser", command };
   }
-  throw new CliError2(`Unknown browser command: ${command}
+  throw new CliError(`Unknown browser command: ${command}
 
-${browserHelpText()}`);
+${browserHelpText()}`, 1, { hint: "Run `rig browser help` for the full browser command reference." });
 }
 async function executeBrowserDemo(context, args) {
   const [maybeHelp] = args;
@@ -416,13 +423,13 @@ async function executeBrowserDemo(context, args) {
   pending = keepOpenFlag.rest;
   const noBuildFlag = takeFlag(pending, "--no-build");
   pending = noBuildFlag.rest;
-  requireNoExtraArgs(pending, "bun run rig browser demo [--port <n>] [--profile <name>] [--state-dir <path>] [--target-url <url>] [--keep-open] [--no-build]");
+  requireNoExtraArgs(pending, "rig browser demo [--port <n>] [--profile <name>] [--state-dir <path>] [--target-url <url>] [--keep-open] [--no-build]");
   if (context.outputMode !== "text" || !process.stdin.isTTY || !process.stdout.isTTY) {
-    throw new CliError2("rig browser demo requires an interactive TTY in text mode.");
+    throw new CliError("rig browser demo requires an interactive TTY in text mode.", 1, { hint: "Run `rig browser demo` from an interactive terminal (no --json, no piped stdin)." });
   }
   const port = portResult.value ? Number.parseInt(portResult.value, 10) : undefined;
   if (port !== undefined && (!Number.isFinite(port) || port <= 0)) {
-    throw new CliError2(`Invalid --port value: ${portResult.value}`);
+    throw new CliError(`Invalid --port value: ${portResult.value}`, 1, { hint: "Pass a positive port number, e.g. `--port 9222`." });
   }
   const runtime = buildBrowserDemoRuntime(context.projectRoot, {
     ...port !== undefined ? { port } : {},
@@ -577,7 +584,7 @@ function runBrowserDemoBuild(projectRoot) {
   if (result.exitCode !== 0) {
     const details = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join(`
 `);
-    throw new CliError2(`Browser demo build failed.${details ? `
+    throw new CliError(`Browser demo build failed.${details ? `
 ${details}` : ""}`, result.exitCode);
   }
 }
@@ -632,7 +639,7 @@ function readBrowserDemoCommandLine(command) {
         cleanup();
         stdout.write(`
 `);
-        rejectInput(new CliError2("Browser demo cancelled."));
+        rejectInput(new CliError("Browser demo cancelled."));
         return;
       }
       if (key.name === "return" || key.name === "enter") {
@@ -698,7 +705,7 @@ async function waitForBrowserDemoReady(runtime, child) {
     return { targets: nextTargets, pageTarget: nextPageTarget };
   }, child, "CDP demo page target");
   if (!version.Browser) {
-    throw new CliError2("Browser demo reached CDP but /json/version did not include Browser metadata.");
+    throw new CliError("Browser demo reached CDP but /json/version did not include Browser metadata.");
   }
   return { version, targets, pageTarget };
 }
@@ -711,14 +718,14 @@ async function waitForBrowserDemo(check, child, label, timeoutMs = 18000) {
   let lastError = null;
   for (;; ) {
     if (child.exitCode !== null || child.signalCode !== null) {
-      throw new CliError2(`Rig Browser exited before ${label} became ready.`);
+      throw new CliError(`Rig Browser exited before ${label} became ready.`);
     }
     try {
       return await check();
     } catch (error) {
       lastError = error;
       if (Date.now() - startedAt > timeoutMs) {
-        throw new CliError2(`${label} did not become ready within ${timeoutMs}ms: ${String(lastError)}`);
+        throw new CliError(`${label} did not become ready within ${timeoutMs}ms: ${String(lastError)}`);
       }
       await new Promise((resolveDelay) => setTimeout(resolveDelay, 150));
     }

package/dist/src/commands/connect.js

@@ -1,12 +1,22 @@
 // @bun
+// packages/cli/src/commands/connect.ts
+import { cancel, isCancel, select } from "@clack/prompts";
+
 // 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();
+    }
+  }
+}
 function requireNoExtraArgs(args, usage) {
   if (args.length > 0) {
     throw new CliError(`Unexpected arguments: ${args.join(" ")}
@@ -36,7 +46,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) {
@@ -79,7 +89,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);
@@ -96,27 +106,98 @@ 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) {
   writeJsonFile(resolveRepoConnectionPath(projectRoot), state);
 }
 
+// packages/cli/src/commands/_cli-format.ts
+import { log, note } from "@clack/prompts";
+import pc from "picocolors";
+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"].includes(normalized))
+    return pc.green;
+  if (["failed", "needs_attention", "needs-attention", "blocked", "error", "rejected"].includes(normalized))
+    return pc.red;
+  if (["running", "reviewing", "validating", "in_progress", "in-progress", "remote"].includes(normalized))
+    return pc.cyan;
+  if (["ready", "open", "queued", "created", "preparing", "local", "pending"].includes(normalized))
+    return pc.yellow;
+  return pc.dim;
+}
+function formatStatusPill(status) {
+  const label = status || "unknown";
+  return statusColor(label)(`\u25CF ${label}`);
+}
+function formatSection(title, subtitle) {
+  return `${pc.bold(pc.cyan("\u25C6"))} ${pc.bold(title)}${subtitle ? pc.dim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatSuccessCard(title, rows = []) {
+  const body = rows.filter(([, value]) => value !== undefined && value !== null && String(value).length > 0).map(([key, value]) => `${pc.dim("\u2502")} ${pc.dim(key.padEnd(12))} ${value}`);
+  return [formatSection(title), ...body].join(`
+`);
+}
+function formatNextSteps(steps) {
+  if (steps.length === 0)
+    return [];
+  return [pc.bold("Next"), ...steps.map((step) => `${pc.dim("\u203A")} ${step}`)];
+}
+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"),
+    `${pc.dim("\u2502")} ${pc.dim("selected ")} ${pc.bold(selected)}`,
+    `${pc.dim("\u2502")} ${pc.dim("kind     ")} ${formatStatusPill(connection?.kind ?? "unknown")}`,
+    `${pc.dim("\u2502")} ${pc.dim("target   ")} ${target ?? "not configured"}`,
+    "",
+    ...formatNextSteps(["Change: `rig server use <alias|local>`", "List saved servers: `rig server list`"])
+  ].join(`
+`);
+}
+
 // packages/cli/src/commands/connect.ts
-function parseConnection(alias, value) {
+function usageName(options) {
+  return `rig ${options.group}`;
+}
+function parseConnection(alias, value, options) {
   if (alias === "local" && !value)
     return { kind: "local", mode: "auto" };
   if (!value)
-    throw new CliError2("Missing remote server URL. Usage: rig connect add <alias> <url>", 1);
+    throw new CliError(`Missing remote server URL. Usage: ${usageName(options)} add <alias> <url>`, 1);
   let parsed;
   try {
     parsed = new URL(value);
   } catch {
-    throw new CliError2(`Invalid Rig server URL: ${value}`, 1);
+    throw new CliError(`Invalid Rig server URL: ${value}`, 1, { hint: "Pass a full http(s) URL, e.g. `rig server add prod https://rig.example.com`." });
   }
   if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-    throw new CliError2("Rig remote server URL must be http(s).", 1);
+    throw new CliError("Rig remote server URL must be http(s).", 1, { hint: "Use an http:// or https:// URL, e.g. `rig server add prod https://rig.example.com`." });
   }
   return { kind: "remote", baseUrl: parsed.toString().replace(/\/+$/, "") };
 }
@@ -127,54 +208,86 @@ function printJsonOrText(context, payload, text) {
     console.log(text);
   }
 }
-async function executeConnect(context, args) {
+async function promptForConnectionAlias(context) {
+  const state = readGlobalConnections();
+  const repo = readRepoConnection(context.projectRoot);
+  const options = [
+    { value: "local", label: "local", hint: "Use/start a local Rig server" },
+    ...Object.entries(state.connections).map(([alias, connection]) => ({
+      value: alias,
+      label: alias,
+      hint: connection.kind === "remote" ? connection.baseUrl : "local"
+    }))
+  ].filter((option, index, all) => all.findIndex((candidate) => candidate.value === option.value) === index);
+  const answer = await select({
+    message: "Select Rig server for this repo",
+    initialValue: repo?.selected ?? "local",
+    options
+  });
+  if (isCancel(answer)) {
+    cancel("No server selected.");
+    throw new CliError("No server selected.", 3);
+  }
+  return String(answer);
+}
+async function executeConnectionCommand(context, args, options) {
   const [command, ...rest] = args;
   switch (command ?? "status") {
     case "list": {
-      requireNoExtraArgs(rest, "rig connect list");
+      requireNoExtraArgs(rest, `${usageName(options)} list`);
       const state = readGlobalConnections();
-      printJsonOrText(context, state, Object.entries(state.connections).map(([alias, connection]) => `${alias}	${connection.kind === "remote" ? connection.baseUrl : "local"}`).join(`
-`) || "No Rig connections configured.");
-      return { ok: true, group: "connect", command: "list", details: state };
+      printJsonOrText(context, state, formatConnectionList(state.connections));
+      return { ok: true, group: options.group, command: "list", details: state };
     }
     case "add": {
       const [alias, url, ...extra] = rest;
       if (!alias)
-        throw new CliError2("Missing alias. Usage: rig connect add <alias> <url>", 1);
-      requireNoExtraArgs(extra, "rig connect add <alias> <url>");
-      const connection = parseConnection(alias, url);
+        throw new CliError(`Missing alias. Usage: ${usageName(options)} add <alias> <url>`, 1);
+      requireNoExtraArgs(extra, `${usageName(options)} add <alias> <url>`);
+      const connection = parseConnection(alias, url, options);
       const state = upsertGlobalConnection(alias, connection);
-      printJsonOrText(context, { alias, connection }, `Added Rig connection ${alias}.`);
-      return { ok: true, group: "connect", command: "add", details: { alias, connection, count: Object.keys(state.connections).length } };
+      printJsonOrText(context, { alias, connection }, formatSuccessCard("Rig server saved", [
+        ["alias", alias],
+        ["target", connection.kind === "remote" ? connection.baseUrl : "local"],
+        ["next", `${usageName(options)} use ${alias}`]
+      ]));
+      return { ok: true, group: options.group, command: "add", details: { alias, connection, count: Object.keys(state.connections).length } };
     }
     case "use": {
-      const [alias, ...extra] = rest;
+      let [alias, ...extra] = rest;
+      requireNoExtraArgs(extra, `${usageName(options)} use <alias|local>`);
+      if (!alias && options.interactiveUse && context.outputMode === "text" && process.stdin.isTTY) {
+        alias = await promptForConnectionAlias(context);
+      }
       if (!alias)
-        throw new CliError2("Missing alias. Usage: rig connect use <alias|local>", 1);
-      requireNoExtraArgs(extra, "rig connect use <alias|local>");
+        throw new CliError(`Missing alias. Usage: ${usageName(options)} use <alias|local>`, 1);
       if (alias !== "local") {
         const state = readGlobalConnections();
         if (!state.connections[alias])
-          throw new CliError2(`Unknown Rig connection: ${alias}`, 1);
+          throw new CliError(`Unknown Rig server: ${alias}`, 1, { hint: "Run `rig server list` to see saved aliases, or save one with `rig server add <alias> <url>`." });
       }
       const repoState = { selected: alias, linkedAt: new Date().toISOString() };
       writeRepoConnection(context.projectRoot, repoState);
-      printJsonOrText(context, repoState, `Selected Rig connection ${alias} for this repo.`);
-      return { ok: true, group: "connect", command: "use", details: repoState };
+      printJsonOrText(context, repoState, formatSuccessCard("Rig server selected", [
+        ["selected", alias],
+        ["scope", "this repo"],
+        ["next", "rig task list"]
+      ]));
+      return { ok: true, group: options.group, command: "use", details: repoState };
     }
     case "status": {
-      requireNoExtraArgs(rest, "rig connect status");
+      requireNoExtraArgs(rest, `${usageName(options)} status`);
       const repo = readRepoConnection(context.projectRoot);
       const global = readGlobalConnections();
       const details = { selected: repo?.selected ?? "local", repo, connections: global.connections };
-      printJsonOrText(context, details, `Selected Rig connection: ${details.selected}`);
-      return { ok: true, group: "connect", command: "status", details };
+      printJsonOrText(context, details, formatConnectionStatus(details.selected, global.connections));
+      return { ok: true, group: options.group, command: "status", details };
     }
     default:
-      throw new CliError2(`Unknown connect command: ${String(command)}
-Usage: rig connect <list|add|use|status>`, 1);
+      throw new CliError(`Unknown ${options.group} command: ${String(command)}
+Usage: ${usageName(options)} <list|add|use|status>`, 1);
   }
 }
 export {
-  executeConnect
+  executeConnectionCommand
 };

package/dist/src/commands/dist.js

@@ -17,12 +17,19 @@ import { resolve as resolve3 } 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();
+    }
+  }
+}
 function takeOption(args, option) {
   const rest = [];
   let value;
@@ -31,7 +38,7 @@ function takeOption(args, option) {
     if (current === option) {
       const next = args[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new CliError(`Missing value for ${option}`);
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
       }
       value = next;
       index += 1;
@@ -67,7 +74,7 @@ function parseInstallScope(value) {
   if (value === "system") {
     return "system";
   }
-  throw new CliError2(`Invalid --scope value: ${value}. Use user|system.`);
+  throw new CliError(`Invalid --scope value: ${value}. Use user|system.`);
 }
 function resolveInstallDir(scope, explicitPath) {
   if (explicitPath) {
@@ -185,7 +192,7 @@ async function executeDist(context, args) {
   switch (command) {
     case "build": {
       const { value: outputDir, rest: pending } = takeOption(rest, "--output-dir");
-      requireNoExtraArgs(pending, "bun run rig dist build [--output-dir <dir>]");
+      requireNoExtraArgs(pending, "rig dist build [--output-dir <dir>]");
       const commandParts = ["bun", "run", "packages/cli/bin/build-rig-binaries.ts"];
       if (outputDir) {
         commandParts.push("--output-dir", outputDir);
@@ -199,7 +206,7 @@ async function executeDist(context, args) {
       pending = scopeResult.rest;
       const pathResult = takeOption(pending, "--path");
       pending = pathResult.rest;
-      requireNoExtraArgs(pending, "bun run rig dist install [--scope user|system] [--path <dir>]");
+      requireNoExtraArgs(pending, "rig dist install [--scope user|system] [--path <dir>]");
       const scope = parseInstallScope(scopeResult.value);
       const installDir = resolveInstallDir(scope, pathResult.value);
       mkdirSync(installDir, { recursive: true });
@@ -211,7 +218,7 @@ async function executeDist(context, args) {
         source = resolve3(buildDir, "bin", "rig");
       }
       if (!existsSync(source)) {
-        throw new CliError2(`Unable to locate rig binary at ${source}.`, 2);
+        throw new CliError(`Unable to locate rig binary at ${source}.`, 2, { hint: "Build it first with `rig dist build`, then re-run `rig dist install`." });
       }
       const installedPath = resolve3(installDir, "rig");
       if (existsSync(installedPath)) {
@@ -242,7 +249,7 @@ async function executeDist(context, args) {
       };
     }
     case "doctor": {
-      requireNoExtraArgs(rest, "bun run rig dist doctor");
+      requireNoExtraArgs(rest, "rig dist doctor");
       const details = await runDistDoctor(context.projectRoot);
       if (context.outputMode === "text") {
         console.log(`bun: ${details.bun.available ? `ok (${details.bun.version})` : "missing"}`);
@@ -253,7 +260,7 @@ async function executeDist(context, args) {
       return { ok: true, group: "dist", command, details };
     }
     case "rebuild-agent": {
-      requireNoExtraArgs(rest, "bun run rig dist rebuild-agent");
+      requireNoExtraArgs(rest, "rig dist rebuild-agent");
       const fp = await computeRuntimeImageFingerprint(context.projectRoot);
       const currentId = computeRuntimeImageId(fp);
       const imagesDir = resolve3(resolveControlPlaneMonorepoRuntimeDir(context.projectRoot), "images");
@@ -393,7 +400,7 @@ async function executeDist(context, args) {
       return { ok: true, group: "dist", command, details: { imageId: currentId, count: targets.length } };
     }
     default:
-      throw new CliError2(`Unknown dist command: ${command}`);
+      throw new CliError(`Unknown dist command: ${command}`, 1, { hint: "Run `rig dist --help` \u2014 commands are build|install|doctor." });
   }
 }
 export {