@ricsam/r5dctl 0.0.21 → 0.0.23

package/dist/mjs/cli.mjs

@@ -3,10 +3,12 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
+import { parse as parseDotenv } from "dotenv";
 import {
   R5dctlApiError,
   R5dctlClient
 } from "@ricsam/r5d-api";
+import { runR5dctlShell } from "./shell.mjs";
 const CHAT_MODES = /* @__PURE__ */ new Set([
   "ask",
   "plan",
@@ -39,12 +41,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 = [
@@ -63,6 +74,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>]",
@@ -111,12 +137,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"
 };
@@ -461,10 +489,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 os.homedir();
+  if (filePath.startsWith("~/")) return path.join(os.homedir(), filePath.slice(2));
+  return path.resolve(filePath);
+}
+function readDotenvFile(filePath) {
+  const resolvedPath = resolveLocalPath(filePath);
+  return parseDotenv(fs.readFileSync(resolvedPath));
+}
 function parseEnvFlags(args) {
   const envs = [];
   for (let i = 0; i < args.length; i += 1) {
@@ -558,6 +693,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") {
     spawn("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -699,6 +861,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 ${path.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}`,
@@ -900,6 +1164,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");
@@ -1137,8 +1419,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") {
@@ -1258,6 +1568,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) {
@@ -1381,31 +1706,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) {
@@ -1418,8 +1755,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)}
@@ -1434,7 +1770,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;
   }
 }
 export {
@@ -1446,7 +1782,11 @@ export {
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
+  parseSetEnvArgs,
+  parseShellArgs,
+  readDotenvFile,
   renderConversationResponse,
   resolveCommandExecution,
-  runR5dctlCli
+  runR5dctlCli,
+  summarizeEnvData
 };

package/dist/mjs/package.json

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