@ricsam/r5dctl 0.0.22 → 0.0.24

package/dist/mjs/cli.mjs

@@ -8,6 +8,7 @@ import {
   R5dctlApiError,
   R5dctlClient
 } from "@ricsam/r5d-api";
+import { runR5dctlShell } from "./shell.mjs";
 const CHAT_MODES = /* @__PURE__ */ new Set([
   "ask",
   "plan",
@@ -40,14 +41,32 @@ const CLI_ONLY_HELP_ENTRIES = [
     section: "auth",
     usage: "auth login [--no-open]",
     description: "Start the browser login flow."
+  },
+  {
+    section: "shell",
+    usage: "-p <project> -b <branch> shell [-c <command>]",
+    description: "Open an interactive worker shell or run one command through a PTY."
   }
 ];
 const CLI_ONLY_COMMAND_HELP = [
   {
     path: ["auth", "login"],
     usage: "auth login [--no-open]"
+  },
+  {
+    path: ["shell"],
+    usage: "-p <project> -b <branch> shell [-c <command>]"
   }
 ];
+const PS_HELP_TEXT = [
+  "Usage:",
+  "  r5dctl ps list [--worker <label>]",
+  "  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.",
+  ""
+].join("\n");
 const SHARED_HELP_ENTRIES = [
   { section: "auth", usage: "auth status", description: "Show the current authenticated user and credential source." },
   { section: "auth", usage: "auth logout", description: "Revoke the current credential and clear saved auth." },
@@ -71,12 +90,12 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "envs",
-    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--target <backend|frontend>] [--only-missing]",
+    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--only-missing]",
     description: "Securely import branch envs from a dotenv file without putting values in command arguments."
   },
   {
     section: "envs",
-    usage: "-p <project> -b <branch> set envs -e backend/KEY=value [--description <text>] [--only-missing]",
+    usage: "-p <project> -b <branch> set envs -e KEY=value [--description <text>] [--only-missing]",
     description: "Set one or more branch envs directly."
   },
   {
@@ -109,9 +128,15 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: "-s <session-id> apply-required-envs -e backend/KEY=value -e frontend/KEY=value",
-    description: "Apply required backend or frontend env values."
+    usage: "-s <session-id> apply-required-envs -e KEY=value",
+    description: "Apply required environment variable values."
+  },
+  {
+    section: "processes",
+    usage: "ps list [--worker <label>]",
+    description: "List active r5d-managed worker processes; global project, branch, and session filters apply."
   },
+  { section: "processes", usage: "ps stop <run-id>", description: "Gracefully stop an active process with SIGTERM." },
   {
     section: "agents",
     usage: '-p <project> start-agent <src-branch> <agent-type> "<prompt>"',
@@ -127,13 +152,25 @@ const SHARED_HELP_ENTRIES = [
   { section: "merges", usage: "-p <project> continue-merge <target-branch>", description: "Commit a resolved merge." },
   { section: "merges", usage: "-p <project> abort-merge <target-branch>", description: "Abort an in-progress merge." }
 ];
-const HELP_SECTION_ORDER = ["auth", "projects", "branches", "envs", "sessions", "agents", "merges"];
+const HELP_SECTION_ORDER = [
+  "auth",
+  "projects",
+  "branches",
+  "envs",
+  "sessions",
+  "processes",
+  "shell",
+  "agents",
+  "merges"
+];
 const HELP_SECTION_TITLES = {
   auth: "Auth",
   projects: "Projects",
   branches: "Branches",
   envs: "Environment variables",
   sessions: "Sessions",
+  processes: "Processes",
+  shell: "Shell",
   agents: "Agents",
   merges: "Merges"
 };
@@ -233,7 +270,7 @@ function renderCliOnlyCommandHelp(entry) {
 }
 function renderSharedCommandHelp(pathSegments) {
   const entry = SHARED_HELP_ENTRIES.find((candidate) => {
-    const usageSegments = candidate.usage.split(" ").filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["));
+    const usageSegments = candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["));
     return usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index]);
   });
   if (!entry) {
@@ -469,33 +506,24 @@ function parseAnswerFlags(args) {
 function validateEnvAssignment(value) {
   const equalsIndex = value.indexOf("=");
   if (equalsIndex <= 0) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
-  }
-  const assignment = value.slice(0, equalsIndex);
-  const slashIndex = assignment.indexOf("/");
-  if (slashIndex <= 0) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
+    throw new Error(`Invalid env assignment '${value}'. Expected KEY=value`);
   }
-  const target = assignment.slice(0, slashIndex);
-  const key = assignment.slice(slashIndex + 1);
-  if (target !== "backend" && target !== "frontend" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
+  const key = value.slice(0, equalsIndex);
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    throw new Error(`Invalid env assignment '${value}'. Expected KEY=value`);
   }
 }
 function parseEnvAssignment(value) {
   validateEnvAssignment(value);
   const equalsIndex = value.indexOf("=");
-  const slashIndex = value.indexOf("/");
   return {
-    target: value.slice(0, slashIndex),
-    name: value.slice(slashIndex + 1, equalsIndex),
+    name: value.slice(0, equalsIndex),
     value: value.slice(equalsIndex + 1)
   };
 }
 function parseSetEnvArgs(args) {
   const parsed = {
     assignments: [],
-    target: "backend",
     onlyMissing: false,
     includeEmpty: false
   };
@@ -525,23 +553,6 @@ function parseSetEnvArgs(args) {
       parsed.fromEnvFile = requireValue(inlineFile, "Missing value for --from-env-file");
       continue;
     }
-    if (arg === "--target") {
-      const target = requireValue(args[index + 1], "Missing value for --target");
-      if (target !== "backend" && target !== "frontend") {
-        throw new Error("Invalid --target. Expected backend or frontend");
-      }
-      parsed.target = target;
-      index += 1;
-      continue;
-    }
-    const inlineTarget = parseLongOptionWithEquals(arg, "--target");
-    if (inlineTarget !== void 0) {
-      if (inlineTarget !== "backend" && inlineTarget !== "frontend") {
-        throw new Error("Invalid --target. Expected backend or frontend");
-      }
-      parsed.target = inlineTarget;
-      continue;
-    }
     if (arg === "--description") {
       parsed.description = requireValue(args[index + 1], "Missing value for --description");
       index += 1;
@@ -615,7 +626,7 @@ function parseEnvFlags(args) {
     if (arg.startsWith("-")) {
       throw new Error(`Unknown env flag: ${arg}`);
     }
-    throw new Error(`Unexpected value '${arg}'. Use -e backend/KEY=value.`);
+    throw new Error(`Unexpected value '${arg}'. Use -e KEY=value.`);
   }
   if (envs.length === 0) {
     throw new Error("At least one -e/--env value is required.");
@@ -682,6 +693,67 @@ function parsePromptArgs(args) {
     message
   };
 }
+function parseShellArgs(args) {
+  let command;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "-c" || arg === "--command") {
+      if (command !== void 0) {
+        throw new Error("Use only one -c/--command value");
+      }
+      command = requireValue(args[index + 1], `Missing value for ${arg}`);
+      index += 1;
+      continue;
+    }
+    const inlineCommand = parseLongOptionWithEquals(arg, "--command");
+    if (inlineCommand !== void 0) {
+      if (command !== void 0) {
+        throw new Error("Use only one -c/--command value");
+      }
+      command = requireValue(inlineCommand, "Missing value for --command");
+      continue;
+    }
+    throw new Error(arg.startsWith("-") ? `Unknown shell flag: ${arg}` : `Unexpected shell value: ${arg}`);
+  }
+  return command === void 0 ? {} : { command };
+}
+function parsePsListArgs(args) {
+  const input = {};
+  const definitions = [
+    { flag: "--project", key: "project" },
+    { flag: "--branch", key: "branch" },
+    { flag: "--session", key: "session" },
+    { flag: "--worker", key: "worker" }
+  ];
+  const assign = (key, value, flag) => {
+    if (input[key] !== void 0) {
+      throw new Error(`Use only one ${flag} value`);
+    }
+    input[key] = requireValue(value, `Missing value for ${flag}`);
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    const definition = definitions.find(({ flag }) => arg === flag || arg.startsWith(`${flag}=`));
+    if (!definition) {
+      throw new Error(arg.startsWith("-") ? `Unknown ps list flag: ${arg}` : `Unexpected ps list value: ${arg}`);
+    }
+    if (arg === definition.flag) {
+      assign(definition.key, requireValue(args[index + 1], `Missing value for ${definition.flag}`), definition.flag);
+      index += 1;
+      continue;
+    }
+    assign(
+      definition.key,
+      requireValue(parseLongOptionWithEquals(arg, definition.flag), `Missing value for ${definition.flag}`),
+      definition.flag
+    );
+  }
+  return input;
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     spawn("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -823,34 +895,66 @@ function renderSessionList(sessions) {
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\n";
 }
+function formatProcessAge(startedAt, nowMs = Date.now()) {
+  const startedAtMs = Date.parse(startedAt);
+  if (!Number.isFinite(startedAtMs)) {
+    return "unknown";
+  }
+  const totalSeconds = Math.max(0, Math.floor((nowMs - startedAtMs) / 1e3));
+  if (totalSeconds < 60) {
+    return `${totalSeconds}s`;
+  }
+  if (totalSeconds < 60 * 60) {
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+  }
+  if (totalSeconds < 24 * 60 * 60) {
+    const hours2 = Math.floor(totalSeconds / (60 * 60));
+    const minutes = Math.floor(totalSeconds % (60 * 60) / 60);
+    return `${hours2}h ${String(minutes).padStart(2, "0")}m`;
+  }
+  const days = Math.floor(totalSeconds / (24 * 60 * 60));
+  const hours = Math.floor(totalSeconds % (24 * 60 * 60) / (60 * 60));
+  return `${days}d ${hours}h`;
+}
+function renderProcessList(processes, nowMs = Date.now()) {
+  if (processes.length === 0) {
+    return "No active processes.\n";
+  }
+  const headers = ["RUN ID", "STATUS", "AGE", "WORKER", "PROJECT", "BRANCH", "SESSION", "COMMAND"];
+  const rows = processes.map((process2) => [
+    process2.runId,
+    process2.status,
+    formatProcessAge(process2.startedAt, nowMs),
+    process2.workerLabel,
+    process2.projectPath,
+    process2.branchName,
+    process2.sessionId,
+    process2.command
+  ]);
+  const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)));
+  const formatRow = (row) => row.map((value, column) => column === row.length - 1 ? value : value.padEnd(widths[column] ?? value.length)).join("  ");
+  const separator = widths.map((width) => "-".repeat(width)).join("  ");
+  return `${[formatRow(headers), separator, ...rows.map(formatRow)].join("\n")}
+`;
+}
 function summarizeEnvData(data) {
-  const summary = {};
-  for (const target of ["backend", "frontend"]) {
-    const entries = data[target];
-    if (!entries) continue;
-    summary[target] = Object.fromEntries(
-      Object.entries(entries).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
-        name,
-        {
-          optional: env.optional ?? false,
-          description: env.description,
-          hasValue: env.value !== null
-        }
-      ])
-    );
-  }
-  return summary;
+  return Object.fromEntries(
+    Object.entries(data).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
+      name,
+      {
+        optional: env.optional ?? false,
+        description: env.description,
+        hasValue: env.value !== null
+      }
+    ])
+  );
 }
 function renderEnvSummary(data) {
   const lines = [];
-  for (const target of ["backend", "frontend"]) {
-    const entries = Object.entries(data[target] ?? {});
-    if (entries.length === 0) continue;
-    if (lines.length > 0) lines.push("");
-    lines.push(`${target}:`);
-    for (const [name, env] of entries) {
-      lines.push(`  ${name}  ${env.hasValue ? "set" : "missing"}  ${env.optional ? "optional" : "required"}  ${env.description}`);
-    }
+  for (const [name, env] of Object.entries(data)) {
+    lines.push(`${name}  ${env.hasValue ? "set" : "missing"}  ${env.optional ? "optional" : "required"}  ${env.description}`);
   }
   return lines.length > 0 ? `${lines.join("\n")}
 ` : "No environment variables declared.\n";
@@ -862,7 +966,7 @@ function renderEnvSetResult(result) {
   if (result.skippedExisting.length > 0) lines.push(`Skipped ${result.skippedExisting.length} existing value(s).`);
   if (result.skippedEmpty.length > 0) lines.push(`Skipped ${result.skippedEmpty.length} empty value(s).`);
   if (result.updated.length > 0) {
-    lines.push(...result.updated.map(({ target, name }) => `  ${target}/${name}`));
+    lines.push(...result.updated.map(({ name }) => `  ${name}`));
   }
   return `${lines.join("\n")}
 `;
@@ -875,10 +979,10 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
       throw new Error(`Invalid environment variable name in dotenv file: ${name}`);
     }
-    return { target: options.target, name, value };
+    return { name, value };
   }) : options.assignments.map(parseEnvAssignment);
   const uniqueAssignments = /* @__PURE__ */ new Map();
-  for (const assignment of assignments) uniqueAssignments.set(`${assignment.target}/${assignment.name}`, assignment);
+  for (const assignment of assignments) uniqueAssignments.set(assignment.name, assignment);
   const update = {};
   const result = {
     success: true,
@@ -891,12 +995,12 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
   const missingDescriptions = [];
   const importedDescription = options.fromEnvFile ? `Imported from ${path.basename(options.fromEnvFile)}.` : void 0;
   for (const assignment of uniqueAssignments.values()) {
-    const identity = { target: assignment.target, name: assignment.name };
+    const identity = { name: assignment.name };
     if (!options.includeEmpty && assignment.value.length === 0) {
       result.skippedEmpty.push(identity);
       continue;
     }
-    const existing = current[assignment.target]?.[assignment.name];
+    const existing = current[assignment.name];
     if (options.onlyMissing && existing?.value !== null && existing?.value !== void 0) {
       result.skippedExisting.push(identity);
       continue;
@@ -906,9 +1010,8 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
       missingDescriptions.push(identity);
       continue;
     }
-    const targetUpdate = update[assignment.target] ??= {};
     const optional = options.optional ?? existing?.optional;
-    targetUpdate[assignment.name] = {
+    update[assignment.name] = {
       description,
       value: assignment.value,
       ...optional === void 0 ? {} : { optional }
@@ -916,9 +1019,7 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
     result.updated.push(identity);
   }
   if (missingDescriptions.length > 0) {
-    throw new Error(
-      `--description is required when declaring new envs with -e: ${missingDescriptions.map(({ target, name }) => `${target}/${name}`).join(", ")}`
-    );
+    throw new Error(`--description is required when declaring new envs with -e: ${missingDescriptions.map(({ name }) => name).join(", ")}`);
   }
   if (result.updated.length > 0) {
     await client.projects.env.update(project.id, branchName, update);
@@ -1083,6 +1184,17 @@ async function executeR5dctlCommand(client, json, args) {
     write(result, "API key revoked.\n");
     return;
   }
+  if (first === "ps" && second === "list") {
+    const processes = await client.processes.list(parsePsListArgs(args.slice(2)));
+    write(processes, renderProcessList(processes));
+    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}
+`);
+    return;
+  }
   if (first === "projects" && second === "list" || first === "get" && second === "projects") {
     const projects = await client.projects.list();
     write(projects, renderProjectList(projects));
@@ -1278,6 +1390,12 @@ function resolveCommandExecution(options, rest) {
     throw new Error("Missing command");
   }
   const commandArgs = normalizedRest.slice(1);
+  if (command === "ps" && commandArgs.length === 0) {
+    return {
+      kind: "cli-help",
+      text: PS_HELP_TEXT
+    };
+  }
   if (trailingHelp) {
     const cliOnlyHelp = findCliOnlyCommandHelp(normalizedRest);
     if (cliOnlyHelp) {
@@ -1351,6 +1469,36 @@ function resolveCommandExecution(options, rest) {
     }
     throw new Error("Unknown auth command");
   }
+  if (command === "ps") {
+    const subcommand = commandArgs[0];
+    if (subcommand === "list") {
+      const commandFilters = parsePsListArgs(commandArgs.slice(1));
+      const filters = {
+        ...commandFilters,
+        ...options.project ? { project: options.project } : {},
+        ...options.branch ? { branch: options.branch } : {},
+        ...options.session ? { session: options.session } : {}
+      };
+      const pluginArgs = ["ps", "list"];
+      for (const [flag, value] of [
+        ["--project", filters.project],
+        ["--branch", filters.branch],
+        ["--session", filters.session],
+        ["--worker", filters.worker]
+      ]) {
+        if (value) pluginArgs.push(flag, value);
+      }
+      return { kind: "plugin", pluginArgs };
+    }
+    if (subcommand === "stop") {
+      const runId = requireValue(commandArgs[1], "Missing process run id");
+      if (commandArgs.length > 2) {
+        throw new Error(`Unexpected ps stop value: ${commandArgs[2]}`);
+      }
+      return { kind: "plugin", pluginArgs: ["ps", "stop", runId] };
+    }
+    throw new Error(`Unknown ps command: ${subcommand ?? ""}`.trim());
+  }
   if (command === "get") {
     const target = commandArgs[0];
     if (target === "projects") {
@@ -1530,6 +1678,21 @@ function resolveCommandExecution(options, rest) {
       pluginArgs: ["conversation", sessionId, ...commandArgs]
     };
   }
+  if (command === "shell") {
+    if (!options.project) {
+      throw new Error("--project/-p is required for `shell`");
+    }
+    if (!options.branch) {
+      throw new Error("--branch/-b is required for `shell`");
+    }
+    if (options.json) {
+      throw new Error("--json is not supported for `shell`");
+    }
+    return {
+      kind: "shell",
+      ...parseShellArgs(commandArgs)
+    };
+  }
   if (command === "prompt") {
     const sessionId = options.session;
     if (!sessionId) {
@@ -1653,31 +1816,43 @@ async function runCommand(argv) {
   const { options, rest } = parseGlobalArgs(argv);
   if (options.version) {
     printVersion();
-    return;
+    return 0;
   }
   if (options.help || rest.length === 0) {
     printHelp();
-    return;
+    return 0;
   }
   const config = parseConfig(options.configPath);
-  const client = new R5dctlClient(resolveClientOptions(options, config));
+  const clientOptions = resolveClientOptions(options, config);
+  const client = new R5dctlClient(clientOptions);
   const execution = resolveCommandExecution(options, rest);
   if (execution.kind === "auth-login") {
     await handleAuthLogin(client, options, execution.commandArgs, config);
-    return;
+    return 0;
   }
   if (execution.kind === "auth-api-key-create") {
     await handleAuthApiKeyCreate(client, options, config, execution.commandArgs);
-    return;
+    return 0;
   }
   if (execution.kind === "cli-help") {
     process.stdout.write(execution.text);
-    return;
+    return 0;
+  }
+  if (execution.kind === "shell") {
+    const project = await client.projects.describe(options.project);
+    return await runR5dctlShell({
+      baseUrl: clientOptions.baseUrl ?? "https://r5d.dev",
+      credential: clientOptions.token ?? clientOptions.apiKey ?? "",
+      projectId: project.id,
+      branchName: options.branch,
+      command: execution.command
+    });
   }
   await executeR5dctlCommand(client, options.json, execution.pluginArgs);
   if (execution.clearAuthOnSuccess) {
     writeConfig(options.configPath, clearAuthFromConfig(config, options));
   }
+  return 0;
 }
 function extractApiErrorMessage(error) {
   if (typeof error.body === "object" && error.body !== null) {
@@ -1690,8 +1865,7 @@ function extractApiErrorMessage(error) {
 }
 async function runR5dctlCli(argv) {
   try {
-    await runCommand(argv);
-    return 0;
+    return await runCommand(argv);
   } catch (error) {
     if (error instanceof R5dctlApiError) {
       process.stderr.write(`${extractApiErrorMessage(error)}
@@ -1706,10 +1880,11 @@ async function runR5dctlCli(argv) {
 async function main(argv = process.argv.slice(2)) {
   const exitCode = await runR5dctlCli(argv);
   if (exitCode !== 0) {
-    process.exit(exitCode);
+    process.exitCode = exitCode;
   }
 }
 export {
+  formatProcessAge,
   getCliHelpText,
   getR5dctlVersion,
   main,
@@ -1718,9 +1893,12 @@ export {
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
+  parsePsListArgs,
   parseSetEnvArgs,
+  parseShellArgs,
   readDotenvFile,
   renderConversationResponse,
+  renderProcessList,
   resolveCommandExecution,
   runR5dctlCli,
   summarizeEnvData

package/dist/mjs/package.json

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