@ricsam/r5dctl 0.0.34 → 0.0.35

package/dist/cjs/cli.cjs

@@ -38,6 +38,7 @@ __export(cli_exports, {
   parseEnvFlags: () => parseEnvFlags,
   parseGlobalArgs: () => parseGlobalArgs,
   parsePromptArgs: () => parsePromptArgs,
+  parsePsHistoryArgs: () => parsePsHistoryArgs,
   parsePsListArgs: () => parsePsListArgs,
   parseSetEnvArgs: () => parseSetEnvArgs,
   parseShellArgs: () => parseShellArgs,
@@ -45,6 +46,8 @@ __export(cli_exports, {
   renderConversationOverviewResponse: () => renderConversationOverviewResponse,
   renderConversationResponse: () => renderConversationResponse,
   renderConversationWorkResponse: () => renderConversationWorkResponse,
+  renderProcessHistory: () => renderProcessHistory,
+  renderProcessInspection: () => renderProcessInspection,
   renderProcessList: () => renderProcessList,
   resolveCommandExecution: () => resolveCommandExecution,
   runR5dctlCli: () => runR5dctlCli,
@@ -112,10 +115,12 @@ const CLI_ONLY_COMMAND_HELP = [
 const PS_HELP_TEXT = [
   "Usage:",
   "  r5dctl ps list [--worker <label>]",
+  "  r5dctl ps history [--worker <label>] [--limit <n>]",
+  "  r5dctl ps inspect <run-id>",
   "  r5dctl ps stop <run-id>",
   "",
-  "List or gracefully stop active r5d-managed worker processes.",
-  "Use -p/--project, -b/--branch, or -s/--session to filter ps list.",
+  "List, inspect, or gracefully stop r5d-managed worker processes.",
+  "Use -p/--project, -b/--branch, or -s/--session to filter list and history.",
   ""
 ].join("\n");
 const SHARED_HELP_ENTRIES = [
@@ -197,6 +202,16 @@ const SHARED_HELP_ENTRIES = [
     usage: "ps list [--worker <label>]",
     description: "List active r5d-managed worker processes; global project, branch, and session filters apply."
   },
+  {
+    section: "processes",
+    usage: "ps history [--worker <label>] [--limit <n>]",
+    description: "List recent process runs, defaulting to the 50 most recent; global filters apply."
+  },
+  {
+    section: "processes",
+    usage: "ps inspect <run-id>",
+    description: "Inspect execution, synchronization, repository outcomes, and bounded output tails."
+  },
   { section: "processes", usage: "ps stop <run-id>", description: "Gracefully stop an active process with SIGTERM." },
   {
     section: "agents",
@@ -817,6 +832,25 @@ function parsePsListArgs(args) {
   }
   return input;
 }
+function parsePsHistoryArgs(args) {
+  const filterArgs = [];
+  let limit;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--limit" || arg?.startsWith("--limit=")) {
+      if (limit !== void 0) throw new Error("Use only one --limit value");
+      const raw = arg === "--limit" ? args[++index] : parseLongOptionWithEquals(arg, "--limit");
+      const parsed = Number(requireValue(raw, "Missing value for --limit"));
+      if (!Number.isInteger(parsed) || parsed < 1 || parsed > 200) {
+        throw new Error("--limit must be an integer between 1 and 200");
+      }
+      limit = parsed;
+      continue;
+    }
+    if (arg) filterArgs.push(arg);
+  }
+  return { ...parsePsListArgs(filterArgs), ...limit !== void 0 ? { limit } : {} };
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     (0, import_node_child_process.spawn)("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -1002,6 +1036,46 @@ function renderProcessList(processes, nowMs = Date.now()) {
   return `${[formatRow(headers), separator, ...rows.map(formatRow)].join("\n")}
 `;
 }
+function renderProcessHistory(processes, nowMs = Date.now()) {
+  return processes.length === 0 ? "No process history.\n" : renderProcessList(processes, nowMs);
+}
+function renderProcessInspection(process2) {
+  const repositories = process2.repositoryOutcomes.length === 0 ? "  (none)" : process2.repositoryOutcomes.map(
+    (outcome) => `  ${outcome.projectPath ?? outcome.projectId} ${outcome.branchName}: ${outcome.status}${outcome.startCommitHash ? `; start ${outcome.startCommitHash}` : ""}${outcome.publishedCommitHash ? ` (${outcome.publishedCommitHash})` : ""}${outcome.branchActionId ? `; branch action ${outcome.branchActionId}` : ""}${outcome.largeDiffIncidentId ? `; incident ${outcome.largeDiffIncidentId}` : ""}${outcome.diffSizeBytes !== void 0 ? `; ${outcome.diffSizeBytes} diff bytes` : ""}${outcome.principalSynchronizationState ? `; principal ${outcome.principalSynchronizationState}` : ""}${outcome.fanOutState ? `; fan-out ${outcome.fanOutState}` : ""}${outcome.error ? ` \u2014 ${outcome.error}` : ""}`
+  ).join("\n");
+  return [
+    `Run: ${process2.runId}`,
+    `Status: ${process2.status} / sync ${process2.syncState}`,
+    `Mode: ${process2.mode}`,
+    `Worker: ${process2.workerLabel} (${process2.platform ?? "unknown"}/${process2.arch ?? "unknown"})`,
+    `Project: ${process2.projectPath} ${process2.branchName}`,
+    `Session: ${process2.sessionId}`,
+    `Command: ${process2.command}`,
+    `Argv: ${JSON.stringify(process2.argv)}`,
+    `CWD: ${process2.cwd ?? "(default checkout)"}`,
+    `PID/process group: ${process2.pid ?? "(unknown)"}/${process2.processGroupId ?? "(unknown)"}`,
+    `Starting canonical commit: ${process2.startCommitHash}`,
+    `Started: ${process2.startedAt}`,
+    `Updated: ${process2.updatedAt}`,
+    `Completed: ${process2.completedAt ?? "(running)"}`,
+    `Exit code: ${process2.exitCode ?? "(none)"}`,
+    `Error: ${process2.error ?? "(none)"}`,
+    `Launch action: ${process2.launchWorkspaceActionId ?? "(none)"}`,
+    `Terminal sync action: ${process2.terminalWorkspaceActionId ?? "(pending)"}`,
+    `Terminal sync claimed: ${process2.terminalSyncClaimedAt ?? "(pending)"}`,
+    `Published origin commit: ${process2.publishedCommitHash ?? "(none)"}`,
+    `Principal synchronization: ${process2.principalSynchronizationState ?? "(pending)"}`,
+    "Repositories observed during synchronization:",
+    repositories,
+    "",
+    `stdout tail${process2.stdoutTailTruncated ? " (truncated)" : ""}:`,
+    process2.stdoutTail || "(empty)",
+    "",
+    `stderr tail${process2.stderrTailTruncated ? " (truncated)" : ""}:`,
+    process2.stderrTail || "(empty)",
+    ""
+  ].join("\n");
+}
 function summarizeEnvData(data) {
   return Object.fromEntries(
     Object.entries(data).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
@@ -1276,6 +1350,16 @@ async function executeR5dctlCommand(client, json, args) {
     write(processes, renderProcessList(processes));
     return;
   }
+  if (first === "ps" && second === "history") {
+    const processes = await client.processes.history(parsePsHistoryArgs(args.slice(2)));
+    write(processes, renderProcessHistory(processes));
+    return;
+  }
+  if (first === "ps" && second === "inspect") {
+    const process2 = await client.processes.inspect(requireValue(args[2], "Missing process run id"));
+    write(process2, renderProcessInspection(process2));
+    return;
+  }
   if (first === "ps" && second === "stop") {
     const process2 = await client.processes.stop(requireValue(args[2], "Missing process run id"));
     write(process2, `Stopped process ${process2.runId}: ${process2.command}
@@ -1593,6 +1677,31 @@ function resolveCommandExecution(options, rest) {
       }
       return { kind: "plugin", pluginArgs };
     }
+    if (subcommand === "history") {
+      const commandFilters = parsePsHistoryArgs(commandArgs.slice(1));
+      const filters = {
+        ...commandFilters,
+        ...options.project ? { project: options.project } : {},
+        ...options.branch ? { branch: options.branch } : {},
+        ...options.session ? { session: options.session } : {}
+      };
+      const pluginArgs = ["ps", "history"];
+      for (const [flag, value] of [
+        ["--project", filters.project],
+        ["--branch", filters.branch],
+        ["--session", filters.session],
+        ["--worker", filters.worker],
+        ["--limit", filters.limit?.toString()]
+      ]) {
+        if (value) pluginArgs.push(flag, value);
+      }
+      return { kind: "plugin", pluginArgs };
+    }
+    if (subcommand === "inspect") {
+      const runId = requireValue(commandArgs[1], "Missing process run id");
+      if (commandArgs.length > 2) throw new Error(`Unexpected ps inspect value: ${commandArgs[2]}`);
+      return { kind: "plugin", pluginArgs: ["ps", "inspect", runId] };
+    }
     if (subcommand === "stop") {
       const runId = requireValue(commandArgs[1], "Missing process run id");
       if (commandArgs.length > 2) {
@@ -2025,6 +2134,7 @@ async function main(argv = process.argv.slice(2)) {
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
+  parsePsHistoryArgs,
   parsePsListArgs,
   parseSetEnvArgs,
   parseShellArgs,
@@ -2032,6 +2142,8 @@ async function main(argv = process.argv.slice(2)) {
   renderConversationOverviewResponse,
   renderConversationResponse,
   renderConversationWorkResponse,
+  renderProcessHistory,
+  renderProcessInspection,
   renderProcessList,
   resolveCommandExecution,
   runR5dctlCli,

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "type": "commonjs"
 }

package/dist/mjs/cli.mjs

@@ -62,10 +62,12 @@ const CLI_ONLY_COMMAND_HELP = [
 const PS_HELP_TEXT = [
   "Usage:",
   "  r5dctl ps list [--worker <label>]",
+  "  r5dctl ps history [--worker <label>] [--limit <n>]",
+  "  r5dctl ps inspect <run-id>",
   "  r5dctl ps stop <run-id>",
   "",
-  "List or gracefully stop active r5d-managed worker processes.",
-  "Use -p/--project, -b/--branch, or -s/--session to filter ps list.",
+  "List, inspect, or gracefully stop r5d-managed worker processes.",
+  "Use -p/--project, -b/--branch, or -s/--session to filter list and history.",
   ""
 ].join("\n");
 const SHARED_HELP_ENTRIES = [
@@ -147,6 +149,16 @@ const SHARED_HELP_ENTRIES = [
     usage: "ps list [--worker <label>]",
     description: "List active r5d-managed worker processes; global project, branch, and session filters apply."
   },
+  {
+    section: "processes",
+    usage: "ps history [--worker <label>] [--limit <n>]",
+    description: "List recent process runs, defaulting to the 50 most recent; global filters apply."
+  },
+  {
+    section: "processes",
+    usage: "ps inspect <run-id>",
+    description: "Inspect execution, synchronization, repository outcomes, and bounded output tails."
+  },
   { section: "processes", usage: "ps stop <run-id>", description: "Gracefully stop an active process with SIGTERM." },
   {
     section: "agents",
@@ -767,6 +779,25 @@ function parsePsListArgs(args) {
   }
   return input;
 }
+function parsePsHistoryArgs(args) {
+  const filterArgs = [];
+  let limit;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--limit" || arg?.startsWith("--limit=")) {
+      if (limit !== void 0) throw new Error("Use only one --limit value");
+      const raw = arg === "--limit" ? args[++index] : parseLongOptionWithEquals(arg, "--limit");
+      const parsed = Number(requireValue(raw, "Missing value for --limit"));
+      if (!Number.isInteger(parsed) || parsed < 1 || parsed > 200) {
+        throw new Error("--limit must be an integer between 1 and 200");
+      }
+      limit = parsed;
+      continue;
+    }
+    if (arg) filterArgs.push(arg);
+  }
+  return { ...parsePsListArgs(filterArgs), ...limit !== void 0 ? { limit } : {} };
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     spawn("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -952,6 +983,46 @@ function renderProcessList(processes, nowMs = Date.now()) {
   return `${[formatRow(headers), separator, ...rows.map(formatRow)].join("\n")}
 `;
 }
+function renderProcessHistory(processes, nowMs = Date.now()) {
+  return processes.length === 0 ? "No process history.\n" : renderProcessList(processes, nowMs);
+}
+function renderProcessInspection(process2) {
+  const repositories = process2.repositoryOutcomes.length === 0 ? "  (none)" : process2.repositoryOutcomes.map(
+    (outcome) => `  ${outcome.projectPath ?? outcome.projectId} ${outcome.branchName}: ${outcome.status}${outcome.startCommitHash ? `; start ${outcome.startCommitHash}` : ""}${outcome.publishedCommitHash ? ` (${outcome.publishedCommitHash})` : ""}${outcome.branchActionId ? `; branch action ${outcome.branchActionId}` : ""}${outcome.largeDiffIncidentId ? `; incident ${outcome.largeDiffIncidentId}` : ""}${outcome.diffSizeBytes !== void 0 ? `; ${outcome.diffSizeBytes} diff bytes` : ""}${outcome.principalSynchronizationState ? `; principal ${outcome.principalSynchronizationState}` : ""}${outcome.fanOutState ? `; fan-out ${outcome.fanOutState}` : ""}${outcome.error ? ` \u2014 ${outcome.error}` : ""}`
+  ).join("\n");
+  return [
+    `Run: ${process2.runId}`,
+    `Status: ${process2.status} / sync ${process2.syncState}`,
+    `Mode: ${process2.mode}`,
+    `Worker: ${process2.workerLabel} (${process2.platform ?? "unknown"}/${process2.arch ?? "unknown"})`,
+    `Project: ${process2.projectPath} ${process2.branchName}`,
+    `Session: ${process2.sessionId}`,
+    `Command: ${process2.command}`,
+    `Argv: ${JSON.stringify(process2.argv)}`,
+    `CWD: ${process2.cwd ?? "(default checkout)"}`,
+    `PID/process group: ${process2.pid ?? "(unknown)"}/${process2.processGroupId ?? "(unknown)"}`,
+    `Starting canonical commit: ${process2.startCommitHash}`,
+    `Started: ${process2.startedAt}`,
+    `Updated: ${process2.updatedAt}`,
+    `Completed: ${process2.completedAt ?? "(running)"}`,
+    `Exit code: ${process2.exitCode ?? "(none)"}`,
+    `Error: ${process2.error ?? "(none)"}`,
+    `Launch action: ${process2.launchWorkspaceActionId ?? "(none)"}`,
+    `Terminal sync action: ${process2.terminalWorkspaceActionId ?? "(pending)"}`,
+    `Terminal sync claimed: ${process2.terminalSyncClaimedAt ?? "(pending)"}`,
+    `Published origin commit: ${process2.publishedCommitHash ?? "(none)"}`,
+    `Principal synchronization: ${process2.principalSynchronizationState ?? "(pending)"}`,
+    "Repositories observed during synchronization:",
+    repositories,
+    "",
+    `stdout tail${process2.stdoutTailTruncated ? " (truncated)" : ""}:`,
+    process2.stdoutTail || "(empty)",
+    "",
+    `stderr tail${process2.stderrTailTruncated ? " (truncated)" : ""}:`,
+    process2.stderrTail || "(empty)",
+    ""
+  ].join("\n");
+}
 function summarizeEnvData(data) {
   return Object.fromEntries(
     Object.entries(data).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
@@ -1226,6 +1297,16 @@ async function executeR5dctlCommand(client, json, args) {
     write(processes, renderProcessList(processes));
     return;
   }
+  if (first === "ps" && second === "history") {
+    const processes = await client.processes.history(parsePsHistoryArgs(args.slice(2)));
+    write(processes, renderProcessHistory(processes));
+    return;
+  }
+  if (first === "ps" && second === "inspect") {
+    const process2 = await client.processes.inspect(requireValue(args[2], "Missing process run id"));
+    write(process2, renderProcessInspection(process2));
+    return;
+  }
   if (first === "ps" && second === "stop") {
     const process2 = await client.processes.stop(requireValue(args[2], "Missing process run id"));
     write(process2, `Stopped process ${process2.runId}: ${process2.command}
@@ -1543,6 +1624,31 @@ function resolveCommandExecution(options, rest) {
       }
       return { kind: "plugin", pluginArgs };
     }
+    if (subcommand === "history") {
+      const commandFilters = parsePsHistoryArgs(commandArgs.slice(1));
+      const filters = {
+        ...commandFilters,
+        ...options.project ? { project: options.project } : {},
+        ...options.branch ? { branch: options.branch } : {},
+        ...options.session ? { session: options.session } : {}
+      };
+      const pluginArgs = ["ps", "history"];
+      for (const [flag, value] of [
+        ["--project", filters.project],
+        ["--branch", filters.branch],
+        ["--session", filters.session],
+        ["--worker", filters.worker],
+        ["--limit", filters.limit?.toString()]
+      ]) {
+        if (value) pluginArgs.push(flag, value);
+      }
+      return { kind: "plugin", pluginArgs };
+    }
+    if (subcommand === "inspect") {
+      const runId = requireValue(commandArgs[1], "Missing process run id");
+      if (commandArgs.length > 2) throw new Error(`Unexpected ps inspect value: ${commandArgs[2]}`);
+      return { kind: "plugin", pluginArgs: ["ps", "inspect", runId] };
+    }
     if (subcommand === "stop") {
       const runId = requireValue(commandArgs[1], "Missing process run id");
       if (commandArgs.length > 2) {
@@ -1974,6 +2080,7 @@ export {
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
+  parsePsHistoryArgs,
   parsePsListArgs,
   parseSetEnvArgs,
   parseShellArgs,
@@ -1981,6 +2088,8 @@ export {
   renderConversationOverviewResponse,
   renderConversationResponse,
   renderConversationWorkResponse,
+  renderProcessHistory,
+  renderProcessInspection,
   renderProcessList,
   resolveCommandExecution,
   runR5dctlCli,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "type": "module"
 }

package/dist/types/cli.d.ts

@@ -1,4 +1,4 @@
-import { type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlProcessListInput, type R5dctlProcessRun, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
+import { type R5dctlConversationRenderOptions, type R5dctlConversationResponse, type R5dctlConversationOverviewResponse, type R5dctlConversationWorkDetail, type R5dctlConversationWorkResponse, type R5dctlEnvData, type R5dctlProcessListInput, type R5dctlProcessInspection, type R5dctlProcessRun, type ChatMode, type ModelTier } from "@ricsam/r5d-api";
 export type GlobalOptions = {
     baseUrl?: string;
     json: boolean;
@@ -61,8 +61,11 @@ export declare function parseShellArgs(args: string[]): {
     command?: string;
 };
 export declare function parsePsListArgs(args: string[]): R5dctlProcessListInput;
+export declare function parsePsHistoryArgs(args: string[]): R5dctlProcessListInput;
 export declare function formatProcessAge(startedAt: string, nowMs?: number): string;
 export declare function renderProcessList(processes: R5dctlProcessRun[], nowMs?: number): string;
+export declare function renderProcessHistory(processes: R5dctlProcessRun[], nowMs?: number): string;
+export declare function renderProcessInspection(process: R5dctlProcessInspection): string;
 export type EnvSummaryData = Record<string, {
     optional: boolean;
     description: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.34",
+  "version": "0.0.35",
   "type": "module",
   "main": "./dist/cjs/cli.cjs",
   "module": "./dist/mjs/cli.mjs",
@@ -26,7 +26,7 @@
     "r5dctl": "dist/cjs/main.cjs"
   },
   "dependencies": {
-    "@ricsam/r5d-api": "^0.0.34",
+    "@ricsam/r5d-api": "^0.0.35",
     "dotenv": "^17",
     "ws": "^8.18.3"
   },