@h-rig/cli-surface-plugin 0.0.6-alpha.146

package/dist/src/commands/inspect.d.ts

@@ -0,0 +1,20 @@
+import type { RunSessionCustomEntry } from "@rig/contracts";
+import type { CommandOutcome } from "@rig/runtime/control-plane/runtime/types";
+import type { TaskArtifactReadResult } from "@rig/runtime/control-plane/native/task-ops";
+import type { RunRecord } from "@rig/client";
+import { type RunnerContext } from "../runner";
+type MaybePromise<T> = T | Promise<T>;
+type InspectCommandDeps = {
+    getRunProjection?: (projectRoot: string, taskId: string) => Promise<RunRecord | null>;
+    listRunProjections?: (projectRoot: string) => Promise<RunRecord[]>;
+    readSessionRunEntries?: (sessionPath: string | null) => RunSessionCustomEntry[];
+    taskArtifactRead?: (projectRoot: string, filename: string, options?: {
+        taskId?: string;
+        maxBytes?: number;
+    }) => MaybePromise<TaskArtifactReadResult>;
+    taskArtifacts?: (projectRoot: string, taskId?: string) => MaybePromise<void>;
+    taskDeps?: (projectRoot: string, taskId?: string) => MaybePromise<void>;
+    changedFilesForTask?: (projectRoot: string, taskId: string, scoped: boolean) => string[];
+};
+export declare function executeInspect(context: RunnerContext, args: string[], deps?: InspectCommandDeps): Promise<CommandOutcome>;
+export {};

package/dist/src/commands/inspect.js

@@ -0,0 +1,337 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/inspect.ts
+import {
+  changedFilesForTask,
+  extractRunLogs,
+  getRun,
+  listRuns,
+  runsForTask,
+  summarizeRunFailures,
+  taskArtifactRead,
+  taskArtifacts,
+  taskDeps
+} from "@rig/client";
+
+// packages/cli-surface-plugin/src/runner.ts
+import { EventBus } from "@rig/runtime/control-plane/runtime/events";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
+import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
+import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
+
+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;
+  for (let index = 0;index < args.length; index += 1) {
+    const current = args[index];
+    if (current === option) {
+      const next = args[index + 1];
+      if (!next || next.startsWith("-")) {
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
+      }
+      value = next;
+      index += 1;
+      continue;
+    }
+    if (current !== undefined) {
+      rest.push(current);
+    }
+  }
+  return { value, rest };
+}
+function requireNoExtraArgs(args, usage) {
+  if (args.length > 0) {
+    throw new CliError(`Unexpected arguments: ${args.join(" ")}
+Usage: ${usage}`);
+  }
+}
+function requireTask(taskId, usage) {
+  if (!taskId) {
+    throw new CliError(`Missing --task option.
+Usage: ${usage}`);
+  }
+  return taskId;
+}
+
+// packages/cli-surface-plugin/src/commands/_cli-format.ts
+import pc from "picocolors";
+import { runStatusColorRole, runStatusText, statusColorRole } from "@rig/client";
+var dim = pc.dim;
+var faintBar = pc.dim("\u2502");
+var accent = pc.cyan;
+function truncate(value, width) {
+  return value.length <= width ? value : `${value.slice(0, Math.max(0, width - 1))}\u2026`;
+}
+function pad(value, width) {
+  return value.length >= width ? value : `${value}${" ".repeat(width - value.length)}`;
+}
+function colorForRole(role) {
+  switch (role) {
+    case "success":
+      return pc.green;
+    case "action-yellow":
+      return pc.yellow;
+    case "active-cyan":
+      return pc.cyan;
+    case "failure":
+      return pc.red;
+    case "muted":
+    case "neutral":
+      return pc.dim;
+  }
+}
+function firstString(record, keys, fallback = "") {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim())
+      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 runLikeStatusText(run) {
+  return runStatusText(run);
+}
+function runLikeStatusColor(run) {
+  return colorForRole(runStatusColorRole(run));
+}
+function printFormattedOutput(message) {
+  console.log(message);
+}
+function formatSection(title, subtitle) {
+  return `${pc.bold(accent("\u25C6"))} ${pc.bold(title)}${subtitle ? dim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatLegacyAutomationSurface() {
+  return [];
+}
+function formatRunList(runs, options = {}) {
+  if (runs.length === 0) {
+    return [
+      formatSection("Runs", "none recorded"),
+      options.source === "server" ? dim("No runs recorded on the selected server.") : dim("No runs recorded in local state."),
+      "",
+      ...formatLegacyAutomationSurface()
+    ].join(`
+`);
+  }
+  const body = runs.map((run) => {
+    const row = run;
+    const runId = runIdOf(row);
+    const status = runLikeStatusText(run);
+    const runtime = firstString(row, ["runtime", "runtimeAdapter"], "");
+    return [
+      pc.bold(runId),
+      runLikeStatusColor(run)(pad(truncate(status, 12), 12)),
+      `${runTitleOf(row)}${runtime ? dim(`  ${runtime}`) : ""}`
+    ].join("  ");
+  });
+  return [formatSection("Runs", options.source === "server" ? "selected server" : "local state"), ...body, "", ...formatLegacyAutomationSurface()].join(`
+`);
+}
+
+// packages/cli-surface-plugin/src/commands/inspect.ts
+var INSPECT_USAGE = "rig inspect <logs|artifact|artifacts|run-logs|runs|failures|graph|diff>";
+function inspectHelpText() {
+  return [
+    `Usage: ${INSPECT_USAGE}`,
+    "",
+    "Commands:",
+    "  logs --task <id>              Print log lines from the latest projected run for a task.",
+    "  artifact --task <id> --file <name>",
+    "                                Preview a single task artifact.",
+    "  artifacts --task <id>         List task artifacts.",
+    "  run-logs --run <id>           Print log lines from a run journal.",
+    "  runs                          List all projected runs.",
+    "  diff --task <id>              List files changed by a task.",
+    "  graph [--task <id>]           Print the task dependency graph.",
+    "  failures --task <id>          Summarize failed runs, closeout failures, and journal anomalies."
+  ].join(`
+`);
+}
+function printInspectHelp() {
+  printFormattedOutput(inspectHelpText());
+}
+function toRunLike(run) {
+  return {
+    runId: run.runId,
+    taskId: run.taskId,
+    title: run.title,
+    status: run.status,
+    source: run.source,
+    live: run.live,
+    stale: run.stale,
+    startedAt: run.startedAt,
+    updatedAt: run.updatedAt,
+    completedAt: run.completedAt,
+    joinLink: run.joinLink,
+    prUrl: run.prUrl,
+    pendingApprovals: run.pendingApprovals,
+    pendingInputs: run.pendingInputs,
+    steeringCount: run.steeringCount,
+    stallCount: run.stallCount
+  };
+}
+function requireRunId(value, usage) {
+  if (!value || !value.trim())
+    throw new CliError(`${usage} requires a run id.`, 2, { hint: "Run `rig inspect runs` to find run ids." });
+  return value.trim();
+}
+async function executeLogs(context, args, deps) {
+  const taskResult = takeOption(args, "--task");
+  requireNoExtraArgs(taskResult.rest, "rig inspect logs --task <id>");
+  const taskId = requireTask(taskResult.value, "rig inspect logs --task <id>");
+  const runs = await runsForTask(context.projectRoot, taskId, {
+    listRuns: deps.listRunProjections ?? listRuns,
+    getRun: deps.getRunProjection ?? getRun
+  });
+  const projection = runs[0];
+  if (!projection)
+    throw new CliError(`No projected runs found for task ${taskId}.`, 1, { hint: "Run `rig run list` to confirm the run journal is discoverable." });
+  const lines = extractRunLogs(projection, { readSessionRunEntries: deps.readSessionRunEntries });
+  if (context.outputMode === "text") {
+    if (lines.length === 0)
+      console.log(`No log entries found for task ${taskId}.`);
+    else
+      for (const line of lines)
+        console.log(line);
+  }
+  return { ok: true, group: "inspect", command: "logs", details: { taskId, runId: projection.runId, count: lines.length, lines } };
+}
+async function executeArtifact(context, args, deps) {
+  const taskResult = takeOption(args, "--task");
+  const fileResult = takeOption(taskResult.rest, "--file");
+  requireNoExtraArgs(fileResult.rest, "rig inspect artifact --task <id> --file <name>");
+  const taskId = requireTask(taskResult.value, "rig inspect artifact --task <id> --file <name>");
+  const filename = fileResult.value?.trim();
+  if (!filename)
+    throw new CliError("rig inspect artifact --task <id> --file <name> requires an artifact file name.", 2);
+  const preview = await (deps.taskArtifactRead ?? taskArtifactRead)(context.projectRoot, filename, { taskId, maxBytes: 64 * 1024 });
+  if (context.outputMode === "text") {
+    console.log(preview.contents);
+    if (preview.truncated)
+      console.log(`
+[truncated at ${preview.maxBytes} bytes; artifact is ${preview.sizeBytes} bytes]`);
+  }
+  return { ok: true, group: "inspect", command: "artifact", details: { taskId, file: filename, ...preview } };
+}
+async function executeRunLogs(context, args, deps) {
+  const runResult = takeOption(args, "--run");
+  requireNoExtraArgs(runResult.rest, "rig inspect run-logs --run <id>");
+  const runId = requireRunId(runResult.value, "rig inspect run-logs --run <id>");
+  const projection = await (deps.getRunProjection ?? getRun)(context.projectRoot, runId);
+  if (!projection)
+    throw new CliError(`Run not found: ${runId}`, 2, { hint: "Run `rig inspect runs` to see runs." });
+  const lines = extractRunLogs(projection, { readSessionRunEntries: deps.readSessionRunEntries });
+  if (context.outputMode === "text") {
+    if (lines.length === 0)
+      console.log(`No log entries found for run ${projection.runId}.`);
+    else
+      for (const line of lines)
+        console.log(line);
+  }
+  return { ok: true, group: "inspect", command: "run-logs", details: { runId: projection.runId, taskId: projection.taskId, count: lines.length, lines } };
+}
+async function executeRuns(context, args, deps) {
+  requireNoExtraArgs(args, "rig inspect runs");
+  const runs = await (deps.listRunProjections ?? listRuns)(context.projectRoot);
+  const formatted = runs.map(toRunLike);
+  if (context.outputMode === "text")
+    printFormattedOutput(formatRunList(formatted));
+  return { ok: true, group: "inspect", command: "runs", details: { runs: formatted } };
+}
+async function executeArtifacts(context, args, deps) {
+  const taskResult = takeOption(args, "--task");
+  requireNoExtraArgs(taskResult.rest, "rig inspect artifacts --task <id>");
+  const taskId = requireTask(taskResult.value, "rig inspect artifacts --task <id>");
+  if (context.outputMode === "text")
+    await (deps.taskArtifacts ?? taskArtifacts)(context.projectRoot, taskId);
+  return { ok: true, group: "inspect", command: "artifacts", details: { taskId, printed: context.outputMode === "text" } };
+}
+async function executeDiff(context, args, deps) {
+  const taskResult = takeOption(args, "--task");
+  requireNoExtraArgs(taskResult.rest, "rig inspect diff --task <id>");
+  const taskId = requireTask(taskResult.value, "rig inspect diff --task <id>");
+  const files = (deps.changedFilesForTask ?? changedFilesForTask)(context.projectRoot, taskId, true);
+  if (context.outputMode === "text")
+    for (const file of files)
+      console.log(file);
+  return { ok: true, group: "inspect", command: "diff", details: { taskId, files } };
+}
+async function executeGraph(context, args, deps) {
+  const taskResult = takeOption(args, "--task");
+  requireNoExtraArgs(taskResult.rest, "rig inspect graph [--task <id>]");
+  if (context.outputMode === "text")
+    await (deps.taskDeps ?? taskDeps)(context.projectRoot, taskResult.value);
+  return { ok: true, group: "inspect", command: "graph", details: { taskId: taskResult.value ?? null, printed: context.outputMode === "text" } };
+}
+async function executeFailures(context, args, deps) {
+  const taskResult = takeOption(args, "--task");
+  requireNoExtraArgs(taskResult.rest, "rig inspect failures --task <id>");
+  const taskId = requireTask(taskResult.value, "rig inspect failures --task <id>");
+  const runs = await runsForTask(context.projectRoot, taskId, {
+    listRuns: deps.listRunProjections ?? listRuns,
+    getRun: deps.getRunProjection ?? getRun
+  });
+  const failures = runs.flatMap(summarizeRunFailures);
+  if (context.outputMode === "text") {
+    if (failures.length === 0)
+      console.log(`No failures recorded for task ${taskId}.`);
+    else
+      for (const failure of failures)
+        console.log(failure);
+  }
+  return { ok: true, group: "inspect", command: "failures", details: { taskId, count: failures.length, failures } };
+}
+function executeAudit(args) {
+  requireNoExtraArgs(args, "rig inspect audit");
+  throw new CliError("rig inspect audit cannot read the controlled-command audit trail yet: current code only writes audit JSONL and exposes no supported reader API.", 2, { hint: "Use the OMP session history for operator audit context until a controlled-bash audit reader is added." });
+}
+async function executeInspect(context, args, deps = {}) {
+  const [command = "failures", ...rest] = args;
+  if (command === "--help" || command === "-h" || command === "help") {
+    if (context.outputMode === "text")
+      printInspectHelp();
+    return { ok: true, group: "inspect", command: "help" };
+  }
+  switch (command) {
+    case "logs":
+      return executeLogs(context, rest, deps);
+    case "artifact":
+      return executeArtifact(context, rest, deps);
+    case "artifacts":
+      return executeArtifacts(context, rest, deps);
+    case "run-logs":
+      return executeRunLogs(context, rest, deps);
+    case "runs":
+      return executeRuns(context, rest, deps);
+    case "diff":
+      return executeDiff(context, rest, deps);
+    case "graph":
+      return executeGraph(context, rest, deps);
+    case "failures":
+      return executeFailures(context, rest, deps);
+    case "audit":
+      return executeAudit(rest);
+    default:
+      throw new CliError(`Unknown inspect command: ${command}`, 1, { hint: "Run `rig inspect --help` to list inspect commands." });
+  }
+}
+export {
+  executeInspect
+};

package/dist/src/commands/pi.d.ts

@@ -0,0 +1,3 @@
+import { type RunnerContext } from "../runner";
+import type { CommandOutcome } from "@rig/runtime";
+export declare function executePi(context: RunnerContext, args: string[]): Promise<CommandOutcome>;

package/dist/src/commands/pi.js

@@ -0,0 +1,177 @@
+// @bun
+// packages/cli-surface-plugin/src/commands/pi.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
+
+// packages/cli-surface-plugin/src/runner.ts
+import { EventBus } from "@rig/runtime/control-plane/runtime/events";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
+import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
+import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
+
+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(" ")}
+Usage: ${usage}`);
+  }
+}
+
+// packages/cli-surface-plugin/src/commands/pi.ts
+function settingsPath(root) {
+  return resolve(root, ".pi", "settings.json");
+}
+function userSettingsPath() {
+  return resolve(homedir(), ".pi", "agent", "settings.json");
+}
+function readJson(path, fallback) {
+  if (!existsSync(path))
+    return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return fallback;
+  }
+}
+function packageKey(entry) {
+  if (typeof entry === "string")
+    return entry;
+  if (entry && typeof entry === "object" && typeof entry.source === "string") {
+    return entry.source;
+  }
+  return JSON.stringify(entry);
+}
+function writeSettings(path, settings) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}
+`, "utf-8");
+}
+async function searchNpmForPiExtensions(term) {
+  const query = encodeURIComponent(term ? `${term} pi extension` : "pi extension");
+  const url = `https://registry.npmjs.org/-/v1/search?text=${query}&size=20`;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new CliError(`npm registry search failed (${response.status}).`, 2, { hint: "Check network access to registry.npmjs.org, then retry `rig pi search <term>`." });
+  }
+  const payload = await response.json();
+  const results = [];
+  for (const entry of payload.objects ?? []) {
+    const pkg = entry.package;
+    if (!pkg?.name)
+      continue;
+    const keywords = (pkg.keywords ?? []).map((k) => k.toLowerCase());
+    const piLike = pkg.name.startsWith("pi-") || pkg.name.includes("-pi") || keywords.includes("pi") || keywords.includes("pi-extension") || (pkg.description ?? "").toLowerCase().includes("pi extension") || (pkg.description ?? "").toLowerCase().includes("pi coding agent");
+    if (!piLike)
+      continue;
+    results.push({ name: pkg.name, version: pkg.version ?? "", description: pkg.description ?? "" });
+  }
+  return results;
+}
+async function executePi(context, args) {
+  const [command = "list", ...rest] = args;
+  const projectSettingsPath = settingsPath(context.projectRoot);
+  const managedRecordPath = resolve(context.projectRoot, ".rig", "state", "pi-managed-packages.json");
+  switch (command) {
+    case "list": {
+      requireNoExtraArgs(rest, "rig pi list");
+      const project = readJson(projectSettingsPath, {});
+      const managed = new Set(readJson(managedRecordPath, []));
+      const user = readJson(userSettingsPath(), {});
+      const projectPackages = (Array.isArray(project.packages) ? project.packages : []).map((entry) => ({
+        source: packageKey(entry),
+        managedByRigConfig: managed.has(packageKey(entry))
+      }));
+      const userPackages = (Array.isArray(user.packages) ? user.packages : []).map(packageKey);
+      if (context.outputMode === "text") {
+        console.log("Project Pi packages (.pi/settings.json):");
+        if (projectPackages.length === 0)
+          console.log("  (none)");
+        for (const pkg of projectPackages) {
+          console.log(`  ${pkg.source}${pkg.managedByRigConfig ? "  [from rig.config runtime.pi.packages]" : ""}`);
+        }
+        console.log("User Pi packages (~/.pi/agent/settings.json):");
+        if (userPackages.length === 0)
+          console.log("  (none)");
+        for (const pkg of userPackages)
+          console.log(`  ${pkg}`);
+        console.log("Add more: `rig pi add <npm-package>` \xB7 discover: `rig pi search <term>`");
+      }
+      return { ok: true, group: "pi", command, details: { projectPackages, userPackages } };
+    }
+    case "add": {
+      const [source, ...extra] = rest;
+      requireNoExtraArgs(extra, "rig pi add <package-source>");
+      if (!source) {
+        throw new CliError("Usage: rig pi add <package-source> (npm name, name@version, or git URL)", 2);
+      }
+      const settings = readJson(projectSettingsPath, {});
+      const packages = Array.isArray(settings.packages) ? settings.packages : [];
+      if (packages.some((entry) => packageKey(entry) === source)) {
+        throw new CliError(`"${source}" is already in ${projectSettingsPath}.`, 2, { hint: "Run `rig pi list` to see installed extensions." });
+      }
+      writeSettings(projectSettingsPath, { ...settings, packages: [...packages, source] });
+      if (context.outputMode === "text") {
+        console.log(`Added ${source} to ${projectSettingsPath}.`);
+        console.log("Pi installs missing packages automatically at the next session start (local and worker).");
+      }
+      return { ok: true, group: "pi", command, details: { source, settingsPath: projectSettingsPath } };
+    }
+    case "remove": {
+      const [source, ...extra] = rest;
+      requireNoExtraArgs(extra, "rig pi remove <package-source>");
+      if (!source) {
+        throw new CliError("Usage: rig pi remove <package-source>", 2);
+      }
+      const managed = new Set(readJson(managedRecordPath, []));
+      if (managed.has(source)) {
+        throw new CliError(`"${source}" is managed by rig.config.ts (runtime.pi.packages); remove it there instead.`, 2);
+      }
+      const settings = readJson(projectSettingsPath, {});
+      const packages = Array.isArray(settings.packages) ? settings.packages : [];
+      const next = packages.filter((entry) => packageKey(entry) !== source);
+      if (next.length === packages.length) {
+        throw new CliError(`"${source}" is not in ${projectSettingsPath}.`, 2, { hint: "Run `rig pi list` to see what is installed, then `rig pi remove <source>` with an exact entry." });
+      }
+      const nextSettings = { ...settings };
+      if (next.length > 0)
+        nextSettings.packages = next;
+      else
+        delete nextSettings.packages;
+      writeSettings(projectSettingsPath, nextSettings);
+      if (context.outputMode === "text") {
+        console.log(`Removed ${source} from ${projectSettingsPath}.`);
+      }
+      return { ok: true, group: "pi", command, details: { source } };
+    }
+    case "search": {
+      const term = rest.join(" ").trim();
+      const results = await searchNpmForPiExtensions(term);
+      if (context.outputMode === "text") {
+        if (results.length === 0) {
+          console.log(`No Pi extension packages found on npm${term ? ` for "${term}"` : ""}.`);
+        } else {
+          console.log(`Pi extension packages on npm${term ? ` matching "${term}"` : ""}:`);
+          for (const pkg of results) {
+            console.log(`  ${pkg.name}@${pkg.version}  ${pkg.description.slice(0, 80)}`);
+          }
+          console.log("Install one: `rig pi add <name>`");
+        }
+      }
+      return { ok: true, group: "pi", command, details: { term, results } };
+    }
+    default:
+      throw new CliError(`Unknown pi command: ${command}. Use list|add|remove|search.`, 1, { hint: "Run `rig pi --help` for usage." });
+  }
+}
+export {
+  executePi
+};

package/dist/src/commands/plugin.d.ts

@@ -0,0 +1,20 @@
+import { type RunnerContext } from "../runner";
+import type { CommandOutcome } from "@rig/runtime";
+export declare function executePlugin(context: RunnerContext, args: string[]): Promise<CommandOutcome>;
+/**
+ * Resolve a plugin CLI command by exact id ("my-plugin:deploy") or by the
+ * unambiguous local part after the namespace colon ("deploy").
+ */
+export declare function resolvePluginCliCommand(commands: readonly {
+    id: string;
+    family?: string;
+    command?: string;
+    description?: string;
+    aliases?: readonly string[];
+}[], requested: string): {
+    id: string;
+    family?: string;
+    command?: string;
+    description?: string;
+    aliases?: readonly string[];
+} | undefined;