@ricsam/r5dctl 0.0.21 → 0.0.23

package/README.md

@@ -49,6 +49,9 @@ r5dctl delete project <namespace/name|id>
 
 r5dctl -p <project> get branches
 r5dctl -p <project> describe branch <branch>
+r5dctl -p <project> -b <branch> get envs
+r5dctl -p <project> -b <branch> set envs --from-env-file ~/.env --only-missing
+r5dctl -p <project> -b <branch> set envs -e backend/API_KEY=value --description "API credential"
 r5dctl -p <project> get sessions --branch <branch>
 r5dctl -p <project> create session -b <branch> --name "Spec session"
 r5dctl describe session <session-id>
@@ -64,8 +67,14 @@ r5dctl -s <session-id> prompt --mode plan --model max "..."
 r5dctl -s <session-id> answer-questions -a1 "Recipe Collection" -a2 "Both Manual & AI"
 r5dctl -s <session-id> apply-required-envs -e backend/KEY=value -e frontend/KEY=value
 
+r5dctl -p <project> -b <branch> shell
+r5dctl -p <project> -b <branch> shell -c "bun test"
 ```
 
+`shell` connects to the same live worker PTY as the web Shell tab. Without `-c` it attaches the local terminal interactively. With `-c`/`--command`, it runs the supplied shell expression, streams combined PTY output, and exits with the remote command's status. Because command output uses a PTY, stdout and stderr are combined and programs may emit colors or other terminal control sequences.
+
+`get envs` reports names and whether values are set, but never prints the values. Prefer `--from-env-file` for bulk imports so secret values do not appear in shell arguments or history. Dotenv imports target backend envs by default; use `--target frontend` when needed. Empty dotenv values are skipped unless `--include-empty` is passed, and `--only-missing` preserves values that are already set.
+
 Conversation output is human-readable by default and excludes both the system prompt and tool definitions. `--raw` keeps the transcript layout but renders structured message and tool parts as JSON, `--tools` includes the provider-shaped tool definitions, and `--system` includes system prompt messages. The global `--json` flag remains separate and prints the complete API response envelope.
 
 When available, conversation rendering uses the newest complete persisted model-request snapshot on the active conversation branch, so its mode, tier, model, thinking mode, tools, and messages reflect the request that actually ran. Legacy or empty sessions without snapshots fall back to reconstruction from the latest conversation context.

package/dist/cjs/cli.cjs

@@ -36,9 +36,13 @@ __export(cli_exports, {
   parseEnvFlags: () => parseEnvFlags,
   parseGlobalArgs: () => parseGlobalArgs,
   parsePromptArgs: () => parsePromptArgs,
+  parseSetEnvArgs: () => parseSetEnvArgs,
+  parseShellArgs: () => parseShellArgs,
+  readDotenvFile: () => readDotenvFile,
   renderConversationResponse: () => renderConversationResponse,
   resolveCommandExecution: () => resolveCommandExecution,
-  runR5dctlCli: () => runR5dctlCli
+  runR5dctlCli: () => runR5dctlCli,
+  summarizeEnvData: () => summarizeEnvData
 });
 module.exports = __toCommonJS(cli_exports);
 var import_node_fs = __toESM(require("node:fs"), 1);
@@ -46,7 +50,9 @@ var import_node_os = __toESM(require("node:os"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var import_node_child_process = require("node:child_process");
 var import_promises = require("node:timers/promises");
+var import_dotenv = require("dotenv");
 var import_r5d_api = require("@ricsam/r5d-api");
+var import_shell = require("./shell.cjs");
 const CHAT_MODES = /* @__PURE__ */ new Set([
   "ask",
   "plan",
@@ -79,12 +85,21 @@ 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 SHARED_HELP_ENTRIES = [
@@ -103,6 +118,21 @@ const SHARED_HELP_ENTRIES = [
   { section: "projects", usage: "delete project <namespace/name|id>", description: "Delete a project." },
   { section: "branches", usage: "-p <project> get branches", description: "List branches for a project." },
   { section: "branches", usage: "-p <project> describe branch <branch>", description: "Show branch URLs and sessions." },
+  {
+    section: "envs",
+    usage: "-p <project> -b <branch> get envs",
+    description: "List declared envs and whether each has a value, without revealing values."
+  },
+  {
+    section: "envs",
+    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--target <backend|frontend>] [--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]",
+    description: "Set one or more branch envs directly."
+  },
   {
     section: "sessions",
     usage: "-p <project> get sessions [--branch <branch>]",
@@ -151,12 +181,14 @@ 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", "sessions", "agents", "merges"];
+const HELP_SECTION_ORDER = ["auth", "projects", "branches", "envs", "sessions", "shell", "agents", "merges"];
 const HELP_SECTION_TITLES = {
   auth: "Auth",
   projects: "Projects",
   branches: "Branches",
+  envs: "Environment variables",
   sessions: "Sessions",
+  shell: "Shell",
   agents: "Agents",
   merges: "Merges"
 };
@@ -501,10 +533,117 @@ function validateEnvAssignment(value) {
   }
   const target = assignment.slice(0, slashIndex);
   const key = assignment.slice(slashIndex + 1);
-  if (target !== "backend" && target !== "frontend" || key.length === 0) {
+  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`);
   }
 }
+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),
+    value: value.slice(equalsIndex + 1)
+  };
+}
+function parseSetEnvArgs(args) {
+  const parsed = {
+    assignments: [],
+    target: "backend",
+    onlyMissing: false,
+    includeEmpty: false
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    if (arg === "-e" || arg === "--env") {
+      const value = requireValue(args[index + 1], `Missing value for ${arg}`);
+      validateEnvAssignment(value);
+      parsed.assignments.push(value);
+      index += 1;
+      continue;
+    }
+    const inlineEnv = parseLongOptionWithEquals(arg, "--env");
+    if (inlineEnv !== void 0) {
+      validateEnvAssignment(inlineEnv);
+      parsed.assignments.push(inlineEnv);
+      continue;
+    }
+    if (arg === "--from-env-file") {
+      parsed.fromEnvFile = requireValue(args[index + 1], "Missing value for --from-env-file");
+      index += 1;
+      continue;
+    }
+    const inlineFile = parseLongOptionWithEquals(arg, "--from-env-file");
+    if (inlineFile !== void 0) {
+      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;
+      continue;
+    }
+    const inlineDescription = parseLongOptionWithEquals(arg, "--description");
+    if (inlineDescription !== void 0) {
+      parsed.description = requireValue(inlineDescription, "Missing value for --description");
+      continue;
+    }
+    if (arg === "--optional") {
+      if (parsed.optional === false) throw new Error("Use only one of --optional or --required");
+      parsed.optional = true;
+      continue;
+    }
+    if (arg === "--required") {
+      if (parsed.optional === true) throw new Error("Use only one of --optional or --required");
+      parsed.optional = false;
+      continue;
+    }
+    if (arg === "--only-missing") {
+      parsed.onlyMissing = true;
+      continue;
+    }
+    if (arg === "--include-empty") {
+      parsed.includeEmpty = true;
+      continue;
+    }
+    throw new Error(arg.startsWith("-") ? `Unknown set envs flag: ${arg}` : `Unexpected set envs value: ${arg}`);
+  }
+  if (parsed.assignments.length > 0 && parsed.fromEnvFile) {
+    throw new Error("Use either -e/--env or --from-env-file, not both");
+  }
+  if (parsed.assignments.length === 0 && !parsed.fromEnvFile) {
+    throw new Error("Provide at least one -e/--env assignment or --from-env-file <path>");
+  }
+  return parsed;
+}
+function resolveLocalPath(filePath) {
+  if (filePath === "~") return import_node_os.default.homedir();
+  if (filePath.startsWith("~/")) return import_node_path.default.join(import_node_os.default.homedir(), filePath.slice(2));
+  return import_node_path.default.resolve(filePath);
+}
+function readDotenvFile(filePath) {
+  const resolvedPath = resolveLocalPath(filePath);
+  return (0, import_dotenv.parse)(import_node_fs.default.readFileSync(resolvedPath));
+}
 function parseEnvFlags(args) {
   const envs = [];
   for (let i = 0; i < args.length; i += 1) {
@@ -598,6 +737,33 @@ 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 };
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     (0, import_node_child_process.spawn)("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -739,6 +905,108 @@ function renderSessionList(sessions) {
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\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;
+}
+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}`);
+    }
+  }
+  return lines.length > 0 ? `${lines.join("\n")}
+` : "No environment variables declared.\n";
+}
+function renderEnvSetResult(result) {
+  const lines = [
+    `Updated ${result.updated.length} environment variable${result.updated.length === 1 ? "" : "s"} for ${result.project}/${result.branch}.`
+  ];
+  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}`));
+  }
+  return `${lines.join("\n")}
+`;
+}
+async function setBranchEnvs(client, projectRef, branchName, args) {
+  const options = parseSetEnvArgs(args);
+  const project = await client.projects.describe(projectRef);
+  const current = await client.projects.env.get(project.id, branchName);
+  const assignments = options.fromEnvFile ? Object.entries(readDotenvFile(options.fromEnvFile)).map(([name, value]) => {
+    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 };
+  }) : options.assignments.map(parseEnvAssignment);
+  const uniqueAssignments = /* @__PURE__ */ new Map();
+  for (const assignment of assignments) uniqueAssignments.set(`${assignment.target}/${assignment.name}`, assignment);
+  const update = {};
+  const result = {
+    success: true,
+    project: project.path,
+    branch: branchName,
+    updated: [],
+    skippedExisting: [],
+    skippedEmpty: []
+  };
+  const missingDescriptions = [];
+  const importedDescription = options.fromEnvFile ? `Imported from ${import_node_path.default.basename(options.fromEnvFile)}.` : void 0;
+  for (const assignment of uniqueAssignments.values()) {
+    const identity = { target: assignment.target, name: assignment.name };
+    if (!options.includeEmpty && assignment.value.length === 0) {
+      result.skippedEmpty.push(identity);
+      continue;
+    }
+    const existing = current[assignment.target]?.[assignment.name];
+    if (options.onlyMissing && existing?.value !== null && existing?.value !== void 0) {
+      result.skippedExisting.push(identity);
+      continue;
+    }
+    const description = options.description ?? existing?.description ?? importedDescription;
+    if (!description) {
+      missingDescriptions.push(identity);
+      continue;
+    }
+    const targetUpdate = update[assignment.target] ??= {};
+    const optional = options.optional ?? existing?.optional;
+    targetUpdate[assignment.name] = {
+      description,
+      value: assignment.value,
+      ...optional === void 0 ? {} : { optional }
+    };
+    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(", ")}`
+    );
+  }
+  if (result.updated.length > 0) {
+    await client.projects.env.update(project.id, branchName, update);
+  }
+  return result;
+}
 function renderAgentStart(agent) {
   return [
     `Agent: ${agent.sessionId}`,
@@ -940,6 +1208,24 @@ Sessions: ${result.sessions.length}
 `);
     return;
   }
+  if (first === "get" && second === "envs") {
+    const projectRef = requireValue(args[2], "Missing project reference");
+    const branchName = requireValue(args[3], "Missing branch name");
+    const project = await client.projects.describe(projectRef);
+    const envs = summarizeEnvData(await client.projects.env.get(project.id, branchName));
+    write({ project: project.path, branch: branchName, envs }, renderEnvSummary(envs));
+    return;
+  }
+  if (first === "set" && second === "envs") {
+    const result = await setBranchEnvs(
+      client,
+      requireValue(args[2], "Missing project reference"),
+      requireValue(args[3], "Missing branch name"),
+      args.slice(4)
+    );
+    write(result, renderEnvSetResult(result));
+    return;
+  }
   if (first === "projects" && second === "sessions" && third === "list" || first === "get" && second === "sessions") {
     const offset = first === "get" ? 2 : 3;
     const projectRef = requireValue(args[offset], "Missing project reference");
@@ -1177,8 +1463,36 @@ function resolveCommandExecution(options, rest) {
         pluginArgs
       };
     }
+    if (target === "envs") {
+      if (!options.project) {
+        throw new Error("--project/-p is required for `get envs`");
+      }
+      if (!options.branch) {
+        throw new Error("--branch/-b is required for `get envs`");
+      }
+      return {
+        kind: "plugin",
+        pluginArgs: ["get", "envs", options.project, options.branch]
+      };
+    }
     throw new Error("Unknown get command");
   }
+  if (command === "set") {
+    const target = commandArgs[0];
+    if (target !== "envs") {
+      throw new Error("Unknown set command");
+    }
+    if (!options.project) {
+      throw new Error("--project/-p is required for `set envs`");
+    }
+    if (!options.branch) {
+      throw new Error("--branch/-b is required for `set envs`");
+    }
+    return {
+      kind: "plugin",
+      pluginArgs: ["set", "envs", options.project, options.branch, ...commandArgs.slice(1)]
+    };
+  }
   if (command === "describe") {
     const target = commandArgs[0];
     if (target === "project") {
@@ -1298,6 +1612,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) {
@@ -1421,31 +1750,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 import_r5d_api.R5dctlClient(resolveClientOptions(options, config));
+  const clientOptions = resolveClientOptions(options, config);
+  const client = new import_r5d_api.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 (0, import_shell.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) {
@@ -1458,8 +1799,7 @@ function extractApiErrorMessage(error) {
 }
 async function runR5dctlCli(argv) {
   try {
-    await runCommand(argv);
-    return 0;
+    return await runCommand(argv);
   } catch (error) {
     if (error instanceof import_r5d_api.R5dctlApiError) {
       process.stderr.write(`${extractApiErrorMessage(error)}
@@ -1474,7 +1814,7 @@ 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;
   }
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -1487,7 +1827,11 @@ async function main(argv = process.argv.slice(2)) {
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
+  parseSetEnvArgs,
+  parseShellArgs,
+  readDotenvFile,
   renderConversationResponse,
   resolveCommandExecution,
-  runR5dctlCli
+  runR5dctlCli,
+  summarizeEnvData
 });

package/dist/cjs/package.json

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