@enactprotocol/shared 1.2.13 → 2.0.0

package/src/execution/command.ts

@@ -0,0 +1,314 @@
+/**
+ * Command interpolation and parsing
+ *
+ * Handles ${parameter} substitution in command templates with proper escaping.
+ */
+
+import type { CommandToken, InterpolationOptions, ParsedCommand } from "./types";
+
+/**
+ * Pattern to match ${parameter} in command strings
+ */
+const PARAM_PATTERN = /\$\{([^}]+)\}/g;
+
+/**
+ * Parse a command template into tokens
+ *
+ * @param command - Command template with ${parameter} placeholders
+ * @returns Parsed command with tokens and parameter list
+ */
+export function parseCommand(command: string): ParsedCommand {
+  const tokens: CommandToken[] = [];
+  const parameters: string[] = [];
+
+  let lastIndex = 0;
+  let match: RegExpExecArray | null = null;
+
+  // Reset regex state
+  PARAM_PATTERN.lastIndex = 0;
+
+  match = PARAM_PATTERN.exec(command);
+  while (match !== null) {
+    // Add literal text before this match
+    if (match.index > lastIndex) {
+      tokens.push({
+        type: "literal",
+        value: command.slice(lastIndex, match.index),
+      });
+    }
+
+    // Add the parameter token
+    const paramName = match[1];
+    if (paramName) {
+      tokens.push({
+        type: "parameter",
+        name: paramName,
+      });
+
+      if (!parameters.includes(paramName)) {
+        parameters.push(paramName);
+      }
+    }
+
+    lastIndex = match.index + match[0].length;
+    match = PARAM_PATTERN.exec(command);
+  }
+
+  // Add any remaining literal text
+  if (lastIndex < command.length) {
+    tokens.push({
+      type: "literal",
+      value: command.slice(lastIndex),
+    });
+  }
+
+  return {
+    original: command,
+    tokens,
+    parameters,
+  };
+}
+
+/**
+ * Shell-escape a value for safe inclusion in a command
+ *
+ * Uses single quotes and handles embedded single quotes.
+ * Example: "it's a test" becomes "'it'\"'\"'s a test'"
+ *
+ * @param value - Value to escape
+ * @returns Shell-safe escaped string
+ */
+export function shellEscape(value: string): string {
+  // If the value is empty, return empty quoted string
+  if (value === "") {
+    return "''";
+  }
+
+  // If value contains no special characters, return as-is
+  if (/^[a-zA-Z0-9._\-/]+$/.test(value)) {
+    return value;
+  }
+
+  // Use single quotes, escaping any embedded single quotes
+  // The technique: end quote, add escaped quote, start new quote
+  // 'it'"'"'s' means: 'it' + "'" + 's'
+  return `'${value.replace(/'/g, "'\"'\"'")}'`;
+}
+
+/**
+ * Convert a value to string for command interpolation
+ *
+ * Handles different types:
+ * - string: as-is
+ * - number: toString()
+ * - boolean: "true" or "false"
+ * - object/array: JSON.stringify
+ * - null/undefined: empty string
+ *
+ * @param value - Value to convert
+ * @param jsonifyObjects - Whether to JSON-stringify objects
+ * @returns String representation
+ */
+export function valueToString(value: unknown, jsonifyObjects = true): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+
+  if (jsonifyObjects && (typeof value === "object" || Array.isArray(value))) {
+    return JSON.stringify(value);
+  }
+
+  return String(value);
+}
+
+/**
+ * Interpolate a command template with parameter values
+ *
+ * @param command - Command template or parsed command
+ * @param params - Parameter values
+ * @param options - Interpolation options
+ * @returns Interpolated command string
+ * @throws Error if required parameter is missing and onMissing is "error"
+ */
+export function interpolateCommand(
+  command: string | ParsedCommand,
+  params: Record<string, unknown>,
+  options: InterpolationOptions = {}
+): string {
+  const { escape: shouldEscape = true, jsonifyObjects = true, onMissing = "error" } = options;
+
+  const parsed = typeof command === "string" ? parseCommand(command) : command;
+
+  const parts: string[] = [];
+
+  for (const token of parsed.tokens) {
+    if (token.type === "literal") {
+      parts.push(token.value);
+    } else {
+      const paramName = token.name;
+      const value = params[paramName];
+
+      if (value === undefined) {
+        switch (onMissing) {
+          case "error":
+            throw new Error(`Missing required parameter: ${paramName}`);
+          case "empty":
+            parts.push("");
+            break;
+          case "keep":
+            parts.push(`\${${paramName}}`);
+            break;
+        }
+      } else {
+        const stringValue = valueToString(value, jsonifyObjects);
+        parts.push(shouldEscape ? shellEscape(stringValue) : stringValue);
+      }
+    }
+  }
+
+  return parts.join("");
+}
+
+/**
+ * Parse a command string respecting quotes
+ *
+ * Splits a command into arguments, respecting single and double quotes.
+ *
+ * @param command - Command string to parse
+ * @returns Array of command arguments
+ */
+export function parseCommandArgs(command: string): string[] {
+  const args: string[] = [];
+  let current = "";
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let escapeNext = false;
+
+  for (let i = 0; i < command.length; i++) {
+    const char = command[i] as string;
+
+    if (escapeNext) {
+      current += char;
+      escapeNext = false;
+      continue;
+    }
+
+    if (char === "\\") {
+      escapeNext = true;
+      continue;
+    }
+
+    if (char === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+      continue;
+    }
+
+    if (char === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+      continue;
+    }
+
+    if (char === " " && !inSingleQuote && !inDoubleQuote) {
+      if (current.length > 0) {
+        args.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  // Add the last argument
+  if (current.length > 0) {
+    args.push(current);
+  }
+
+  return args;
+}
+
+/**
+ * Wrap a command with sh -c for execution
+ *
+ * Useful when the command contains shell features like pipes, redirects, etc.
+ *
+ * @param command - Command to wrap
+ * @returns Arguments for sh -c execution
+ */
+export function wrapWithShell(command: string): string[] {
+  return ["sh", "-c", command];
+}
+
+/**
+ * Check if a command needs shell wrapping
+ *
+ * Returns true if the command contains shell special characters.
+ *
+ * @param command - Command to check
+ * @returns Whether the command needs sh -c wrapping
+ */
+export function needsShellWrap(command: string): boolean {
+  // Check for shell operators and features
+  return /[|&;<>()$`\\"\n*?[\]#~=%]/.test(command);
+}
+
+/**
+ * Prepare a command for execution
+ *
+ * Parses the command and determines if it needs shell wrapping.
+ *
+ * @param command - Command template
+ * @param params - Parameter values for interpolation
+ * @param options - Interpolation options
+ * @returns Command ready for execution [program, ...args]
+ */
+export function prepareCommand(
+  command: string,
+  params: Record<string, unknown>,
+  options: InterpolationOptions = {}
+): string[] {
+  // Interpolate parameters
+  const interpolated = interpolateCommand(command, params, options);
+
+  // Check if we need shell wrapping
+  if (needsShellWrap(interpolated)) {
+    return wrapWithShell(interpolated);
+  }
+
+  // Parse into arguments
+  return parseCommandArgs(interpolated);
+}
+
+/**
+ * Validate that all required parameters are provided
+ *
+ * @param command - Parsed command
+ * @param params - Provided parameters
+ * @returns Array of missing parameter names
+ */
+export function getMissingParams(
+  command: string | ParsedCommand,
+  params: Record<string, unknown>
+): string[] {
+  const parsed = typeof command === "string" ? parseCommand(command) : command;
+
+  return parsed.parameters.filter((param) => params[param] === undefined);
+}
+
+/**
+ * Get all parameters in a command template
+ *
+ * @param command - Command template
+ * @returns Array of parameter names
+ */
+export function getCommandParams(command: string): string[] {
+  return parseCommand(command).parameters;
+}

package/src/execution/index.ts

@@ -0,0 +1,73 @@
+/**
+ * Execution Engine Module
+ *
+ * Provides containerized tool execution using the Dagger SDK.
+ * This is the main entry point for Phase 3 of Enact CLI 2.0.
+ */
+
+// Types
+export type {
+  // Input/Output types
+  ExecutionInput,
+  FileInput,
+  ExecutionOutput,
+  ExecutionResult,
+  ExecutionMetadata,
+  ExecutionError,
+  ExecutionErrorCode,
+  // Options
+  ExecutionOptions,
+  RetryConfig,
+  // Runtime types
+  ContainerRuntime,
+  RuntimeDetection,
+  RuntimeStatus,
+  // Engine health
+  EngineHealth,
+  EngineState,
+  // Provider interface
+  ExecutionProvider,
+  // Command types
+  ParsedCommand,
+  CommandToken,
+  InterpolationOptions,
+  // Validation types
+  InputValidationResult,
+  InputValidationError,
+  // Dry run
+  DryRunResult,
+} from "./types.js";
+
+// Constants
+export { DEFAULT_RETRY_CONFIG } from "./types.js";
+
+// Runtime detection
+export {
+  detectRuntime,
+  clearRuntimeCache,
+  isRuntimeAvailable,
+  getAvailableRuntimes,
+  RuntimeStatusTracker,
+  createRuntimeTracker,
+} from "./runtime.js";
+
+// Command interpolation
+export {
+  parseCommand,
+  interpolateCommand,
+  shellEscape,
+  parseCommandArgs,
+  prepareCommand,
+  getMissingParams,
+} from "./command.js";
+
+// Input validation
+export {
+  validateInputs,
+  applyDefaults,
+  getRequiredParams,
+  getParamInfo,
+} from "./validation.js";
+
+// NOTE: Dagger provider moved to @enactprotocol/execution package
+// This keeps @enactprotocol/shared browser-safe (no Dagger SDK dependency)

package/src/execution/runtime.ts

@@ -0,0 +1,308 @@
+/**
+ * Container runtime detection
+ *
+ * Auto-detects available container runtimes (docker, podman, nerdctl)
+ * and provides runtime status monitoring.
+ */
+
+import { spawnSync } from "node:child_process";
+import type { ContainerRuntime, RuntimeDetection, RuntimeStatus } from "./types";
+
+/**
+ * Order of preference for container runtime detection
+ */
+const RUNTIME_PREFERENCE: ContainerRuntime[] = ["docker", "podman", "nerdctl"];
+
+/**
+ * Runtime-specific version commands
+ */
+const VERSION_COMMANDS: Record<ContainerRuntime, string[]> = {
+  docker: ["docker", "--version"],
+  podman: ["podman", "--version"],
+  nerdctl: ["nerdctl", "--version"],
+};
+
+/**
+ * Cached detection result
+ */
+let cachedDetection: RuntimeDetection | null = null;
+let cachedDetectionTime = 0;
+const CACHE_TTL_MS = 60000; // 1 minute
+
+/**
+ * Check if a command is available in PATH
+ */
+function commandExists(command: string): boolean {
+  try {
+    const result = spawnSync("which", [command], {
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+    return result.status === 0 && result.stdout.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the version of a container runtime
+ */
+function getRuntimeVersion(runtime: ContainerRuntime): string | undefined {
+  try {
+    const versionCmd = VERSION_COMMANDS[runtime];
+    const cmd = versionCmd[0];
+    if (!cmd) return undefined;
+    const args = versionCmd.slice(1);
+    const result = spawnSync(cmd, args, {
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+
+    if (result.status === 0) {
+      // Parse version from output
+      // Docker: "Docker version 24.0.6, build ed223bc"
+      // Podman: "podman version 4.5.1"
+      // nerdctl: "nerdctl version 1.5.0"
+      const match = result.stdout.match(/(\d+\.\d+\.\d+)/);
+      return match?.[1];
+    }
+  } catch {
+    // Ignore errors
+  }
+  return undefined;
+}
+
+/**
+ * Get the path to a runtime binary
+ */
+function getRuntimePath(runtime: ContainerRuntime): string | undefined {
+  try {
+    const result = spawnSync("which", [runtime], {
+      encoding: "utf-8",
+      timeout: 5000,
+    });
+    if (result.status === 0) {
+      return result.stdout.trim();
+    }
+  } catch {
+    // Ignore errors
+  }
+  return undefined;
+}
+
+/**
+ * Detect available container runtime
+ *
+ * Checks for docker, podman, and nerdctl in order of preference.
+ * Results are cached for 1 minute.
+ *
+ * @returns Detection result with runtime info or error
+ */
+export function detectRuntime(): RuntimeDetection {
+  // Return cached result if still valid
+  const now = Date.now();
+  if (cachedDetection && now - cachedDetectionTime < CACHE_TTL_MS) {
+    return cachedDetection;
+  }
+
+  for (const runtime of RUNTIME_PREFERENCE) {
+    if (commandExists(runtime)) {
+      const version = getRuntimeVersion(runtime);
+      const path = getRuntimePath(runtime);
+
+      const result: RuntimeDetection = {
+        found: true,
+        runtime,
+      };
+      if (path) result.path = path;
+      if (version) result.version = version;
+
+      cachedDetection = result;
+      cachedDetectionTime = now;
+      return result;
+    }
+  }
+
+  const notFoundResult: RuntimeDetection = {
+    found: false,
+    error: getInstallInstructions(),
+  };
+  cachedDetection = notFoundResult;
+  cachedDetectionTime = now;
+  return notFoundResult;
+}
+
+/**
+ * Get helpful installation instructions when no runtime is found
+ */
+function getInstallInstructions(): string {
+  const platform = process.platform;
+
+  if (platform === "darwin") {
+    return (
+      "No container runtime found. Install Docker Desktop:\n" +
+      "  brew install --cask docker\n" +
+      "Or install Podman:\n" +
+      "  brew install podman"
+    );
+  }
+
+  if (platform === "linux") {
+    return (
+      "No container runtime found. Install Docker:\n" +
+      "  curl -fsSL https://get.docker.com | sh\n" +
+      "Or install Podman:\n" +
+      "  sudo apt install podman  # Debian/Ubuntu\n" +
+      "  sudo dnf install podman  # Fedora/RHEL"
+    );
+  }
+
+  if (platform === "win32") {
+    return (
+      "No container runtime found. Install Docker Desktop:\n" +
+      "  winget install Docker.DockerDesktop\n" +
+      "Or download from: https://www.docker.com/products/docker-desktop"
+    );
+  }
+
+  return "No container runtime found. Please install Docker, Podman, or nerdctl.";
+}
+
+/**
+ * Clear the cached detection result
+ * Useful after installing a runtime
+ */
+export function clearRuntimeCache(): void {
+  cachedDetection = null;
+  cachedDetectionTime = 0;
+}
+
+/**
+ * Force detection of a specific runtime
+ *
+ * @param runtime - The runtime to check
+ * @returns Whether the runtime is available
+ */
+export function isRuntimeAvailable(runtime: ContainerRuntime): boolean {
+  return commandExists(runtime);
+}
+
+/**
+ * Get all available runtimes
+ *
+ * @returns Array of available runtimes
+ */
+export function getAvailableRuntimes(): ContainerRuntime[] {
+  return RUNTIME_PREFERENCE.filter((runtime) => commandExists(runtime));
+}
+
+/**
+ * Runtime status tracker for health monitoring
+ */
+export class RuntimeStatusTracker {
+  private status: RuntimeStatus;
+  private healthCheckInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(runtime: ContainerRuntime) {
+    this.status = {
+      available: true,
+      runtime,
+      engineHealthy: true,
+      lastHealthCheck: new Date(),
+      failureCount: 0,
+    };
+  }
+
+  /**
+   * Record a successful operation
+   */
+  recordSuccess(): void {
+    this.status.failureCount = 0;
+    this.status.engineHealthy = true;
+    this.status.lastHealthCheck = new Date();
+  }
+
+  /**
+   * Record a failed operation
+   *
+   * @returns Whether the engine should be reset (3+ consecutive failures)
+   */
+  recordFailure(): boolean {
+    this.status.failureCount++;
+    this.status.lastHealthCheck = new Date();
+
+    if (this.status.failureCount >= 3) {
+      this.status.engineHealthy = false;
+      return true; // Engine needs reset
+    }
+
+    return false;
+  }
+
+  /**
+   * Get current status
+   */
+  getStatus(): RuntimeStatus {
+    return { ...this.status };
+  }
+
+  /**
+   * Check if engine needs reset
+   */
+  needsReset(): boolean {
+    return this.status.failureCount >= 3;
+  }
+
+  /**
+   * Reset failure count after engine restart
+   */
+  resetFailureCount(): void {
+    this.status.failureCount = 0;
+    this.status.engineHealthy = true;
+  }
+
+  /**
+   * Start periodic health checks
+   *
+   * @param intervalMs - Check interval in milliseconds (default: 60000)
+   * @param onUnhealthy - Callback when engine becomes unhealthy
+   */
+  startHealthChecks(intervalMs = 60000, onUnhealthy?: (status: RuntimeStatus) => void): void {
+    if (this.healthCheckInterval) {
+      clearInterval(this.healthCheckInterval);
+    }
+
+    this.healthCheckInterval = setInterval(() => {
+      const detection = detectRuntime();
+      this.status.available = detection.found;
+      this.status.lastHealthCheck = new Date();
+
+      if (!detection.found || !this.status.engineHealthy) {
+        onUnhealthy?.(this.status);
+      }
+    }, intervalMs);
+  }
+
+  /**
+   * Stop periodic health checks
+   */
+  stopHealthChecks(): void {
+    if (this.healthCheckInterval) {
+      clearInterval(this.healthCheckInterval);
+      this.healthCheckInterval = null;
+    }
+  }
+}
+
+/**
+ * Create a runtime status tracker for the detected runtime
+ *
+ * @returns Status tracker or null if no runtime found
+ */
+export function createRuntimeTracker(): RuntimeStatusTracker | null {
+  const detection = detectRuntime();
+  if (!detection.found || !detection.runtime) {
+    return null;
+  }
+  return new RuntimeStatusTracker(detection.runtime);
+}