@enactprotocol/cli 1.2.13 → 2.0.0

package/src/commands/env/index.ts

@@ -0,0 +1,392 @@
+/**
+ * enact env command
+ *
+ * Manage environment variables and secrets.
+ */
+
+import {
+  deleteEnv,
+  deleteSecret,
+  getEnv,
+  listEnv,
+  listSecrets,
+  secretExists,
+  setEnv,
+  setSecret,
+} from "@enactprotocol/secrets";
+import type { Command } from "commander";
+import type { CommandContext, GlobalOptions } from "../../types";
+import {
+  type TableColumn,
+  dim,
+  error,
+  formatError,
+  header,
+  info,
+  json,
+  keyValue,
+  newline,
+  password,
+  success,
+  table,
+} from "../../utils";
+
+interface EnvSetOptions extends GlobalOptions {
+  secret?: boolean;
+  namespace?: string;
+  local?: boolean;
+}
+
+interface EnvGetOptions extends GlobalOptions {
+  secret?: boolean;
+  namespace?: string;
+}
+
+interface EnvListOptions extends GlobalOptions {
+  secret?: boolean;
+  namespace?: string;
+  local?: boolean;
+  global?: boolean;
+}
+
+interface EnvDeleteOptions extends GlobalOptions {
+  secret?: boolean;
+  namespace?: string;
+  local?: boolean;
+}
+
+/**
+ * Set environment variable or secret
+ */
+async function envSetHandler(
+  key: string,
+  value: string | undefined,
+  options: EnvSetOptions,
+  ctx: CommandContext
+): Promise<void> {
+  if (options.secret) {
+    // Setting a secret in the keyring
+    if (!options.namespace) {
+      error("--namespace is required when setting a secret");
+      dim("Example: enact env set API_KEY --secret --namespace alice/api");
+      process.exit(1);
+    }
+
+    // If no value provided, prompt for it
+    let secretValue = value;
+    if (!secretValue) {
+      if (!ctx.isInteractive) {
+        error("Value is required in non-interactive mode");
+        process.exit(1);
+      }
+      const prompted = await password(`Enter value for ${key}:`);
+      if (!prompted) {
+        error("No value provided");
+        process.exit(1);
+      }
+      secretValue = prompted;
+    }
+
+    await setSecret(options.namespace, key, secretValue);
+
+    if (options.json) {
+      json({ set: true, key, namespace: options.namespace, type: "secret" });
+      return;
+    }
+
+    success(`Secret ${key} set for namespace ${options.namespace}`);
+  } else {
+    // Setting an environment variable in .env file
+    if (!value) {
+      error("Value is required for environment variables");
+      dim("Example: enact env set API_URL https://api.example.com");
+      process.exit(1);
+    }
+
+    const scope = options.local ? "local" : "global";
+    setEnv(key, value, scope, ctx.cwd);
+
+    if (options.json) {
+      json({ set: true, key, value, scope, type: "env" });
+      return;
+    }
+
+    success(`Environment variable ${key} set (${scope})`);
+  }
+}
+
+/**
+ * Get environment variable or check secret existence
+ */
+async function envGetHandler(
+  key: string,
+  options: EnvGetOptions,
+  ctx: CommandContext
+): Promise<void> {
+  if (options.secret) {
+    // Check if secret exists (never show value)
+    if (!options.namespace) {
+      error("--namespace is required when getting a secret");
+      process.exit(1);
+    }
+
+    const exists = await secretExists(options.namespace, key);
+
+    if (options.json) {
+      json({ key, namespace: options.namespace, exists, type: "secret" });
+      return;
+    }
+
+    if (exists) {
+      success(`Secret ${key} exists for namespace ${options.namespace}`);
+    } else {
+      info(`Secret ${key} not found for namespace ${options.namespace}`);
+    }
+  } else {
+    // Get environment variable
+    const result = getEnv(key, undefined, ctx.cwd);
+
+    if (options.json) {
+      json(result ? { ...result, type: "env" } : { key, found: false, type: "env" });
+      return;
+    }
+
+    if (result) {
+      keyValue("Key", key);
+      keyValue("Value", result.value);
+      keyValue("Source", result.source);
+      if (result.filePath) {
+        keyValue("File", result.filePath);
+      }
+    } else {
+      info(`Environment variable ${key} not found`);
+    }
+  }
+}
+
+/**
+ * List environment variables or secrets
+ */
+async function envListHandler(options: EnvListOptions, ctx: CommandContext): Promise<void> {
+  if (options.secret) {
+    // List secrets for a namespace
+    if (!options.namespace) {
+      error("--namespace is required when listing secrets");
+      process.exit(1);
+    }
+
+    const secrets = await listSecrets(options.namespace);
+
+    if (options.json) {
+      json({ namespace: options.namespace, secrets, type: "secrets" });
+      return;
+    }
+
+    if (secrets.length === 0) {
+      info(`No secrets found for namespace ${options.namespace}`);
+      return;
+    }
+
+    header(`Secrets for ${options.namespace}`);
+    newline();
+    for (const name of secrets) {
+      dim(`  • ${name}`);
+    }
+    newline();
+    dim(`Total: ${secrets.length} secret(s)`);
+  } else {
+    // List environment variables
+    let scope: "local" | "global" | "all" = "all";
+    if (options.local && !options.global) {
+      scope = "local";
+    } else if (options.global && !options.local) {
+      scope = "global";
+    }
+
+    const envVars = listEnv(scope, ctx.cwd);
+
+    if (options.json) {
+      json({ scope, variables: envVars, type: "env" });
+      return;
+    }
+
+    if (envVars.length === 0) {
+      info("No environment variables found");
+      dim("Set variables with 'enact env set KEY VALUE'");
+      return;
+    }
+
+    header("Environment Variables");
+    newline();
+
+    const columns: TableColumn[] = [
+      { key: "key", header: "Key", width: 25 },
+      { key: "value", header: "Value", width: 40 },
+      { key: "source", header: "Source", width: 10 },
+    ];
+
+    // Transform to table-compatible format
+    const tableData = envVars.map((v) => ({
+      key: v.key,
+      value: v.value.length > 40 ? `${v.value.slice(0, 37)}...` : v.value,
+      source: v.source,
+    }));
+
+    table(tableData, columns);
+    newline();
+    dim(`Total: ${envVars.length} variable(s)`);
+  }
+}
+
+/**
+ * Delete environment variable or secret
+ */
+async function envDeleteHandler(
+  key: string,
+  options: EnvDeleteOptions,
+  ctx: CommandContext
+): Promise<void> {
+  if (options.secret) {
+    // Delete secret from keyring
+    if (!options.namespace) {
+      error("--namespace is required when deleting a secret");
+      process.exit(1);
+    }
+
+    const deleted = await deleteSecret(options.namespace, key);
+
+    if (options.json) {
+      json({ deleted, key, namespace: options.namespace, type: "secret" });
+      return;
+    }
+
+    if (deleted) {
+      success(`Secret ${key} deleted from namespace ${options.namespace}`);
+    } else {
+      info(`Secret ${key} not found for namespace ${options.namespace}`);
+    }
+  } else {
+    // Delete environment variable
+    const scope = options.local ? "local" : "global";
+    const deleted = deleteEnv(key, scope, ctx.cwd);
+
+    if (options.json) {
+      json({ deleted, key, scope, type: "env" });
+      return;
+    }
+
+    if (deleted) {
+      success(`Environment variable ${key} deleted (${scope})`);
+    } else {
+      info(`Environment variable ${key} not found (${scope})`);
+    }
+  }
+}
+
+/**
+ * Configure the env command
+ */
+export function configureEnvCommand(program: Command): void {
+  const env = program.command("env").description("Manage environment variables and secrets");
+
+  // env set
+  env
+    .command("set")
+    .description("Set an environment variable or secret")
+    .argument("<key>", "Variable name")
+    .argument("[value]", "Variable value (prompted if secret and not provided)")
+    .option("-s, --secret", "Store as secret in OS keyring")
+    .option("-n, --namespace <namespace>", "Namespace for secret (required with --secret)")
+    .option("-l, --local", "Set in project .enact/.env instead of global")
+    .option("--json", "Output as JSON")
+    .action(async (key: string, value: string | undefined, options: EnvSetOptions) => {
+      const ctx: CommandContext = {
+        cwd: process.cwd(),
+        options,
+        isCI: Boolean(process.env.CI),
+        isInteractive: process.stdout.isTTY ?? false,
+      };
+
+      try {
+        await envSetHandler(key, value, options, ctx);
+      } catch (err) {
+        error(formatError(err));
+        process.exit(1);
+      }
+    });
+
+  // env get
+  env
+    .command("get")
+    .description("Get an environment variable or check if a secret exists")
+    .argument("<key>", "Variable name")
+    .option("-s, --secret", "Check secret in OS keyring (never shows value)")
+    .option("-n, --namespace <namespace>", "Namespace for secret (required with --secret)")
+    .option("--json", "Output as JSON")
+    .action(async (key: string, options: EnvGetOptions) => {
+      const ctx: CommandContext = {
+        cwd: process.cwd(),
+        options,
+        isCI: Boolean(process.env.CI),
+        isInteractive: process.stdout.isTTY ?? false,
+      };
+
+      try {
+        await envGetHandler(key, options, ctx);
+      } catch (err) {
+        error(formatError(err));
+        process.exit(1);
+      }
+    });
+
+  // env list
+  env
+    .command("list")
+    .description("List environment variables or secrets")
+    .option("-s, --secret", "List secrets from OS keyring")
+    .option("-n, --namespace <namespace>", "Namespace for secrets (required with --secret)")
+    .option("-l, --local", "Show only project .enact/.env variables")
+    .option("-g, --global", "Show only global ~/.enact/.env variables")
+    .option("--json", "Output as JSON")
+    .action(async (options: EnvListOptions) => {
+      const ctx: CommandContext = {
+        cwd: process.cwd(),
+        options,
+        isCI: Boolean(process.env.CI),
+        isInteractive: process.stdout.isTTY ?? false,
+      };
+
+      try {
+        await envListHandler(options, ctx);
+      } catch (err) {
+        error(formatError(err));
+        process.exit(1);
+      }
+    });
+
+  // env delete
+  env
+    .command("delete")
+    .alias("rm")
+    .description("Delete an environment variable or secret")
+    .argument("<key>", "Variable name")
+    .option("-s, --secret", "Delete secret from OS keyring")
+    .option("-n, --namespace <namespace>", "Namespace for secret (required with --secret)")
+    .option("-l, --local", "Delete from project .enact/.env instead of global")
+    .option("--json", "Output as JSON")
+    .action(async (key: string, options: EnvDeleteOptions) => {
+      const ctx: CommandContext = {
+        cwd: process.cwd(),
+        options,
+        isCI: Boolean(process.env.CI),
+        isInteractive: process.stdout.isTTY ?? false,
+      };
+
+      try {
+        await envDeleteHandler(key, options, ctx);
+      } catch (err) {
+        error(formatError(err));
+        process.exit(1);
+      }
+    });
+}

package/src/commands/exec/README.md

@@ -0,0 +1,110 @@
+# enact exec
+
+Execute an arbitrary command in a tool's container environment.
+
+## Synopsis
+
+```bash
+enact exec <tool> "<command>" [options]
+```
+
+## Description
+
+The `exec` command allows you to run any command inside a tool's container environment, not just the manifest-defined command. This is useful for:
+
+- Debugging and inspecting tool containers
+- Running one-off commands in a tool's environment
+- Testing commands before adding them to a manifest
+- Exploring tool dependencies and file structure
+
+The container environment includes:
+- The same base image defined in the manifest
+- All environment variables and secrets
+- The tool's source directory mounted
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<tool>` | Tool to run in. Can be a tool name, path, or `.` for current directory |
+| `<command>` | Command to execute. Quote complex commands with spaces or special characters |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-t, --timeout <duration>` | Execution timeout (e.g., `30s`, `5m`, `1h`) |
+| `-v, --verbose` | Show detailed output including stderr and timing |
+| `--json` | Output result as JSON |
+
+## Examples
+
+### Basic usage
+
+```bash
+# View the tool's manifest
+enact exec alice/utils/greeter "cat enact.md"
+
+# List files in the container
+enact exec alice/utils/greeter "ls -la"
+
+# Check installed packages
+enact exec python-tool "pip list"
+```
+
+### Debugging
+
+```bash
+# Interactive shell exploration
+enact exec my-tool "sh -c 'echo $PATH && which python'"
+
+# Check environment variables
+enact exec my-tool "env | sort"
+
+# Test a command before adding to manifest
+enact exec my-tool "python --version"
+```
+
+### With options
+
+```bash
+# Long-running command with timeout
+enact exec my-tool "sleep 10 && echo done" --timeout 30s
+
+# Verbose output for debugging
+enact exec my-tool "some-command" --verbose
+
+# JSON output for scripting
+enact exec my-tool "cat config.json" --json
+```
+
+## Differences from `enact run`
+
+| Feature | `enact run` | `enact exec` |
+|---------|-------------|--------------|
+| Command | Manifest-defined | User-specified |
+| Input validation | Yes (via inputSchema) | No |
+| Parameter interpolation | Yes (`${param}`) | No |
+| Use case | Production execution | Debugging/exploration |
+
+## Security Note
+
+The `exec` command runs with the same isolation as `run`:
+- Commands execute inside the container
+- Secrets are injected as environment variables
+- Network access follows manifest settings
+
+However, since you can run arbitrary commands, be careful when using `exec` with untrusted tools.
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| `0` | Successful execution |
+| `1` | Execution failed or error |
+| `3` | Tool not found |
+
+## See Also
+
+- [enact run](../run/README.md) - Execute a tool's manifest-defined command
+- [enact install](../install/README.md) - Install tools

package/src/commands/exec/index.ts

@@ -0,0 +1,195 @@
+/**
+ * enact exec command
+ *
+ * Execute an arbitrary command in a tool's container environment.
+ * Unlike `run`, this allows running any command, not just the manifest-defined one.
+ */
+
+import { DaggerExecutionProvider, type ExecutionResult } from "@enactprotocol/execution";
+import { resolveSecrets, resolveToolEnv } from "@enactprotocol/secrets";
+import { resolveToolAuto } from "@enactprotocol/shared";
+import type { Command } from "commander";
+import type { CommandContext, GlobalOptions } from "../../types";
+import { dim, error, formatError, json, newline, suggest, symbols, withSpinner } from "../../utils";
+
+interface ExecOptions extends GlobalOptions {
+  timeout?: string;
+}
+
+/**
+ * Display execution result
+ */
+function displayResult(result: ExecutionResult, options: ExecOptions): void {
+  if (options.json) {
+    json(result);
+    return;
+  }
+
+  if (result.success) {
+    if (result.output?.stdout) {
+      process.stdout.write(result.output.stdout);
+      if (!result.output.stdout.endsWith("\n")) {
+        newline();
+      }
+    }
+
+    if (options.verbose && result.output?.stderr) {
+      dim(`stderr: ${result.output.stderr}`);
+    }
+
+    if (options.verbose && result.metadata) {
+      newline();
+      dim(`Duration: ${result.metadata.durationMs}ms`);
+      dim(`Exit code: ${result.output?.exitCode ?? 0}`);
+    }
+  } else {
+    error(`Execution failed: ${result.error?.message ?? "Unknown error"}`);
+
+    if (result.output?.stderr) {
+      newline();
+      dim("stderr:");
+      dim(result.output.stderr);
+    }
+  }
+}
+
+/**
+ * Parse timeout string (e.g., "30s", "5m", "1h")
+ */
+function parseTimeout(timeout: string): number {
+  const match = timeout.match(/^(\d+)(s|m|h)?$/);
+  if (!match) {
+    throw new Error(`Invalid timeout format: ${timeout}. Use format like "30s", "5m", or "1h".`);
+  }
+
+  const value = Number.parseInt(match[1] ?? "0", 10);
+  const unit = match[2] || "s";
+
+  switch (unit) {
+    case "h":
+      return value * 60 * 60 * 1000;
+    case "m":
+      return value * 60 * 1000;
+    default:
+      return value * 1000;
+  }
+}
+
+/**
+ * Exec command handler
+ */
+async function execHandler(
+  tool: string,
+  command: string,
+  options: ExecOptions,
+  ctx: CommandContext
+): Promise<void> {
+  // Resolve the tool
+  const resolution = await withSpinner(
+    `Resolving tool: ${tool}`,
+    async () => resolveToolAuto(tool, { startDir: ctx.cwd }),
+    `${symbols.success} Resolved: ${tool}`
+  );
+
+  if (!resolution) {
+    error(`Tool not found: ${tool}`);
+    suggest(`Try 'enact install ${tool}' first, or check the tool name.`);
+    process.exit(1);
+  }
+
+  const manifest = resolution.manifest;
+
+  // Resolve environment variables (non-secrets)
+  const { resolved: envResolved } = resolveToolEnv(manifest.env ?? {}, ctx.cwd);
+  const envVars: Record<string, string> = {};
+  for (const [key, envRes] of envResolved) {
+    envVars[key] = envRes.value;
+  }
+
+  // Resolve secrets
+  const secretDeclarations = Object.entries(manifest.env ?? {})
+    .filter(([_, v]) => v.secret)
+    .map(([k]) => k);
+
+  if (secretDeclarations.length > 0) {
+    const namespace = manifest.name.split("/").slice(0, -1).join("/") || manifest.name;
+    const secretResults = await resolveSecrets(namespace, secretDeclarations);
+
+    for (const [key, result] of secretResults) {
+      if (result.found && result.value) {
+        envVars[key] = result.value;
+      }
+    }
+  }
+
+  // Execute the custom command
+  const providerConfig: { defaultTimeout?: number; verbose?: boolean } = {};
+  if (options.timeout) {
+    providerConfig.defaultTimeout = parseTimeout(options.timeout);
+  }
+  if (options.verbose) {
+    providerConfig.verbose = true;
+  }
+
+  const provider = new DaggerExecutionProvider(providerConfig);
+
+  try {
+    await provider.initialize();
+
+    // Create a modified manifest with the custom command
+    const execManifest = {
+      ...manifest,
+      command,
+    };
+
+    const result = await withSpinner(
+      `Executing in ${manifest.name}...`,
+      async () =>
+        provider.execute(execManifest, {
+          params: {},
+          envOverrides: envVars,
+        }),
+      options.verbose ? `${symbols.success} Execution complete` : undefined
+    );
+
+    displayResult(result, options);
+
+    if (!result.success) {
+      process.exit(1);
+    }
+  } finally {
+    // Provider cleanup handled by Dagger
+  }
+}
+
+/**
+ * Configure the exec command
+ */
+export function configureExecCommand(program: Command): void {
+  program
+    .command("exec")
+    .description("Execute an arbitrary command in a tool's container environment")
+    .argument("<tool>", "Tool to run in (name, path, or '.' for current directory)")
+    .argument("<command>", "Command to execute (quote complex commands)")
+    .option("-t, --timeout <duration>", "Execution timeout (e.g., 30s, 5m)")
+    .option("-v, --verbose", "Show detailed output")
+    .option("--json", "Output result as JSON")
+    .action(async (tool: string, command: string, options: ExecOptions) => {
+      const ctx: CommandContext = {
+        cwd: process.cwd(),
+        options,
+        isCI: Boolean(process.env.CI),
+        isInteractive: process.stdout.isTTY ?? false,
+      };
+
+      try {
+        await execHandler(tool, command, options, ctx);
+      } catch (err) {
+        error(formatError(err));
+        if (options.verbose && err instanceof Error && err.stack) {
+          dim(err.stack);
+        }
+        process.exit(1);
+      }
+    });
+}