@enactprotocol/execution 2.2.4 → 2.3.1

package/src/router.ts

@@ -0,0 +1,143 @@
+/**
+ * Execution Router
+ *
+ * Config-driven backend selection for tool execution.
+ * Selects the appropriate execution provider based on:
+ *   - CLI flags (--local overrides everything)
+ *   - trusted_scopes (matching scopes bypass containers)
+ *   - default backend preference
+ *   - fallback if default is unavailable
+ */
+
+import type { ExecutionBackend } from "@enactprotocol/shared";
+import type { ExecutionProvider } from "@enactprotocol/shared";
+
+/**
+ * Configuration for execution routing
+ */
+export interface ExecutionRoutingConfig {
+  /** Default execution backend */
+  default?: ExecutionBackend | undefined;
+  /** Fallback backend if default is unavailable */
+  fallback?: ExecutionBackend | undefined;
+  /** Package scopes that bypass container isolation (e.g., ["@my-org/*"]) */
+  trusted_scopes?: string[] | undefined;
+}
+
+/**
+ * Options passed when selecting a provider
+ */
+export interface ProviderSelectionOptions {
+  /** Force local execution (--local flag) */
+  forceLocal?: boolean | undefined;
+  /** Force remote execution (--remote flag) */
+  forceRemote?: boolean | undefined;
+}
+
+/**
+ * Routes execution to the appropriate provider based on config and tool identity.
+ */
+export class ExecutionRouter {
+  private providers = new Map<string, ExecutionProvider>();
+  private config: ExecutionRoutingConfig;
+
+  constructor(config: ExecutionRoutingConfig = {}) {
+    this.config = config;
+  }
+
+  /**
+   * Register an execution provider by name
+   */
+  registerProvider(name: string, provider: ExecutionProvider): void {
+    this.providers.set(name, provider);
+  }
+
+  /**
+   * Select the appropriate provider for a given tool
+   */
+  async selectProvider(
+    toolName: string,
+    options: ProviderSelectionOptions = {}
+  ): Promise<ExecutionProvider> {
+    // 1. CLI flag overrides
+    if (options.forceLocal) {
+      const local = this.providers.get("local");
+      if (local) return local;
+    }
+
+    if (options.forceRemote) {
+      const remote = this.providers.get("remote");
+      if (remote && (await remote.isAvailable())) return remote;
+    }
+
+    // 2. Trusted scopes bypass containers
+    if (this.isTrustedScope(toolName)) {
+      const local = this.providers.get("local");
+      if (local) return local;
+    }
+
+    // 3. Try the configured default backend
+    const defaultBackend = this.config.default ?? "container";
+    const defaultProvider = await this.resolveBackend(defaultBackend);
+    if (defaultProvider) return defaultProvider;
+
+    // 4. Try the configured fallback backend
+    if (this.config.fallback) {
+      const fallbackProvider = await this.resolveBackend(this.config.fallback);
+      if (fallbackProvider) return fallbackProvider;
+    }
+
+    // 5. Last resort: local execution
+    const local = this.providers.get("local");
+    if (local) return local;
+
+    throw new Error(
+      "No execution provider available. Install Docker or configure a remote backend."
+    );
+  }
+
+  /**
+   * Check if a tool name matches any trusted scope pattern
+   */
+  private isTrustedScope(toolName: string): boolean {
+    if (!this.config.trusted_scopes?.length) return false;
+
+    for (const pattern of this.config.trusted_scopes) {
+      if (pattern.endsWith("/*")) {
+        // Wildcard: "@my-org/*" matches "@my-org/anything"
+        const prefix = pattern.slice(0, -2);
+        if (toolName.startsWith(`${prefix}/`)) return true;
+      } else if (pattern === toolName) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Resolve a backend name to an available provider.
+   * "container" is an alias that tries docker, then dagger.
+   */
+  private async resolveBackend(backend: ExecutionBackend): Promise<ExecutionProvider | null> {
+    if (backend === "container") {
+      // Try dagger first (full feature support), then docker as fallback
+      for (const name of ["dagger", "docker"]) {
+        const provider = this.providers.get(name);
+        if (provider && (await provider.isAvailable())) return provider;
+      }
+      return null;
+    }
+
+    const provider = this.providers.get(backend);
+    if (provider && (await provider.isAvailable())) return provider;
+    return null;
+  }
+}
+
+/**
+ * Create an execution router with the given config
+ */
+export function createRouter(config: ExecutionRoutingConfig = {}): ExecutionRouter {
+  return new ExecutionRouter(config);
+}

package/tests/docker-provider.test.ts

@@ -0,0 +1,207 @@
+/**
+ * Tests for the Docker execution provider.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { DockerExecutionProvider } from "../src/docker-provider";
+
+describe("DockerExecutionProvider", () => {
+  describe("instantiation", () => {
+    test("creates with default config", () => {
+      const provider = new DockerExecutionProvider();
+      expect(provider.name).toBe("docker");
+    });
+
+    test("creates with custom config", () => {
+      const provider = new DockerExecutionProvider({
+        defaultTimeout: 60000,
+        verbose: true,
+        preferredRuntime: "podman",
+      });
+      expect(provider.name).toBe("docker");
+    });
+  });
+
+  describe("interface compliance", () => {
+    test("implements all ExecutionProvider methods", () => {
+      const provider = new DockerExecutionProvider();
+
+      expect(typeof provider.initialize).toBe("function");
+      expect(typeof provider.isAvailable).toBe("function");
+      expect(typeof provider.getHealth).toBe("function");
+      expect(typeof provider.execute).toBe("function");
+      expect(typeof provider.exec).toBe("function");
+      expect(typeof provider.executeAction).toBe("function");
+      expect(typeof provider.shutdown).toBe("function");
+    });
+
+    test("initialize resolves without error", async () => {
+      const provider = new DockerExecutionProvider();
+      await expect(provider.initialize()).resolves.toBeUndefined();
+    });
+
+    test("shutdown resolves without error", async () => {
+      const provider = new DockerExecutionProvider();
+      await expect(provider.shutdown()).resolves.toBeUndefined();
+    });
+
+    test("isAvailable returns a boolean", async () => {
+      const provider = new DockerExecutionProvider();
+      const result = await provider.isAvailable();
+      expect(typeof result).toBe("boolean");
+    });
+
+    test("getHealth returns valid health object", async () => {
+      const provider = new DockerExecutionProvider();
+      const health = await provider.getHealth();
+      expect(typeof health.healthy).toBe("boolean");
+      expect(typeof health.runtime).toBe("string");
+      expect(typeof health.consecutiveFailures).toBe("number");
+    });
+  });
+
+  describe("execute", () => {
+    test("returns error when no command in manifest", async () => {
+      const provider = new DockerExecutionProvider();
+      await provider.initialize();
+
+      const result = await provider.execute(
+        {
+          enact: "2.0.0",
+          name: "@test/tool",
+          description: "test",
+          version: "1.0.0",
+        },
+        { params: {} }
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("COMMAND_ERROR");
+      expect(result.error?.message).toContain("No command specified");
+    });
+
+    test("returns error when no runtime available", async () => {
+      // Use an impossible runtime to force unavailability
+      const provider = new DockerExecutionProvider({
+        preferredRuntime: "nerdctl", // may not be installed
+      });
+
+      // Don't initialize — runtime stays null
+      const result = await provider.execute(
+        {
+          enact: "2.0.0",
+          name: "@test/tool",
+          description: "test",
+          version: "1.0.0",
+          command: "echo hello",
+        },
+        { params: {} }
+      );
+
+      // Without initialize, runtime is null
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("CONTAINER_ERROR");
+    });
+  });
+
+  describe("executeAction", () => {
+    test("validates inputs against action schema", async () => {
+      const provider = new DockerExecutionProvider();
+      await provider.initialize();
+
+      const result = await provider.executeAction(
+        {
+          enact: "2.0.0",
+          name: "@test/tool",
+          description: "test",
+          version: "1.0.0",
+        },
+        {
+          actions: {
+            greet: {
+              description: "Greet",
+              command: ["echo", "hello", "{{name}}"],
+              inputSchema: {
+                type: "object" as const,
+                properties: {
+                  name: { type: "string" as const },
+                },
+                required: ["name"],
+              },
+            },
+          },
+        },
+        "greet",
+        {
+          description: "Greet",
+          command: ["echo", "hello", "{{name}}"],
+          inputSchema: {
+            type: "object" as const,
+            properties: {
+              name: { type: "string" as const },
+            },
+            required: ["name"],
+          },
+        },
+        { params: {} } // Missing required 'name'
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("VALIDATION_ERROR");
+    });
+
+    test("returns error for empty command array", async () => {
+      const provider = new DockerExecutionProvider();
+      await provider.initialize();
+
+      // Skip this test if no runtime
+      if (!(await provider.isAvailable())) return;
+
+      const result = await provider.executeAction(
+        {
+          enact: "2.0.0",
+          name: "@test/tool",
+          description: "test",
+          version: "1.0.0",
+        },
+        {
+          actions: {
+            empty: {
+              description: "Empty",
+              command: "",
+            },
+          },
+        },
+        "empty",
+        { description: "Empty", command: "" },
+        { params: {} }
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("COMMAND_ERROR");
+    });
+  });
+
+  describe("metadata", () => {
+    test("error results include correct metadata", async () => {
+      const provider = new DockerExecutionProvider();
+
+      const result = await provider.execute(
+        {
+          enact: "2.0.0",
+          name: "@test/my-tool",
+          description: "test",
+          version: "1.0.0",
+        },
+        { params: {} }
+      );
+
+      expect(result.metadata).toBeDefined();
+      expect(result.metadata.toolName).toBe("@test/my-tool");
+      expect(result.metadata.startTime).toBeInstanceOf(Date);
+      expect(result.metadata.endTime).toBeInstanceOf(Date);
+      expect(typeof result.metadata.durationMs).toBe("number");
+      expect(result.metadata.executionId).toMatch(/^docker-/);
+    });
+  });
+});

package/tests/local-provider.test.ts

@@ -0,0 +1,256 @@
+/**
+ * Tests for the Local execution provider.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  LocalExecutionProvider,
+  hasContainerfile,
+  selectExecutionMode,
+} from "../src/local-provider";
+
+const FIXTURES_DIR = join(import.meta.dir, "fixtures", "local-provider");
+
+describe("LocalExecutionProvider", () => {
+  describe("instantiation", () => {
+    test("creates with default config", () => {
+      const provider = new LocalExecutionProvider();
+      expect(provider.name).toBe("local");
+    });
+
+    test("creates with custom config", () => {
+      const provider = new LocalExecutionProvider({
+        defaultTimeout: 60000,
+        verbose: true,
+        workdir: "/tmp/test",
+      });
+      expect(provider.name).toBe("local");
+    });
+  });
+
+  describe("interface compliance", () => {
+    test("implements all ExecutionProvider methods", () => {
+      const provider = new LocalExecutionProvider();
+      expect(typeof provider.initialize).toBe("function");
+      expect(typeof provider.isAvailable).toBe("function");
+      expect(typeof provider.getHealth).toBe("function");
+      expect(typeof provider.execute).toBe("function");
+      expect(typeof provider.exec).toBe("function");
+      expect(typeof provider.executeAction).toBe("function");
+      expect(typeof provider.shutdown).toBe("function");
+    });
+
+    test("initialize resolves without error", async () => {
+      const provider = new LocalExecutionProvider();
+      await expect(provider.initialize()).resolves.toBeUndefined();
+    });
+
+    test("shutdown resolves without error", async () => {
+      const provider = new LocalExecutionProvider();
+      await expect(provider.shutdown()).resolves.toBeUndefined();
+    });
+
+    test("isAvailable always returns true", async () => {
+      const provider = new LocalExecutionProvider();
+      expect(await provider.isAvailable()).toBe(true);
+    });
+
+    test("getHealth returns healthy", async () => {
+      const provider = new LocalExecutionProvider();
+      const health = await provider.getHealth();
+      expect(health.healthy).toBe(true);
+      expect(health.consecutiveFailures).toBe(0);
+    });
+  });
+
+  describe("execute", () => {
+    test("runs a simple echo command", async () => {
+      const provider = new LocalExecutionProvider();
+      const result = await provider.execute(
+        { name: "@test/echo", description: "test", command: "echo hello" },
+        { params: {} }
+      );
+      expect(result.success).toBe(true);
+      expect(result.output.stdout.trim()).toBe("hello");
+      expect(result.output.exitCode).toBe(0);
+    });
+
+    test("returns error when no command in manifest", async () => {
+      const provider = new LocalExecutionProvider();
+      const result = await provider.execute(
+        { name: "@test/no-cmd", description: "test" },
+        { params: {} }
+      );
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("COMMAND_ERROR");
+      expect(result.error?.message).toContain("No command");
+    });
+
+    test("reports failure for command with non-zero exit", async () => {
+      const provider = new LocalExecutionProvider();
+      const result = await provider.execute(
+        { name: "@test/fail", description: "test", command: "false" },
+        { params: {} }
+      );
+      expect(result.success).toBe(false);
+      expect(result.output.exitCode).not.toBe(0);
+    });
+
+    test("returns COMMAND_ERROR for non-existent command", async () => {
+      const provider = new LocalExecutionProvider();
+      const result = await provider.execute(
+        { name: "@test/bad", description: "test", command: "nonexistent_command_xyz" },
+        { params: {} }
+      );
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("COMMAND_ERROR");
+    });
+  });
+
+  describe("exec", () => {
+    test("runs a raw command string", async () => {
+      const provider = new LocalExecutionProvider();
+      const result = await provider.exec({ name: "@test/tool", description: "test" }, "echo world");
+      expect(result.success).toBe(true);
+      expect(result.output.stdout.trim()).toBe("world");
+    });
+  });
+
+  describe("executeAction", () => {
+    test("validates inputs against action schema", async () => {
+      const provider = new LocalExecutionProvider();
+      const result = await provider.executeAction(
+        { name: "@test/tool", description: "test" },
+        {
+          actions: {
+            greet: {
+              description: "Greet someone",
+              command: ["echo", "{{name}}"],
+              inputSchema: {
+                type: "object" as const,
+                properties: { name: { type: "string" as const } },
+                required: ["name"],
+              },
+            },
+          },
+        },
+        "greet",
+        {
+          description: "Greet someone",
+          command: ["echo", "{{name}}"],
+          inputSchema: {
+            type: "object" as const,
+            properties: { name: { type: "string" as const } },
+            required: ["name"],
+          },
+        },
+        { params: {} } // Missing required 'name'
+      );
+      expect(result.success).toBe(false);
+      expect(result.error?.code).toBe("VALIDATION_ERROR");
+    });
+
+    test("executes action with valid inputs", async () => {
+      const provider = new LocalExecutionProvider();
+      const result = await provider.executeAction(
+        { name: "@test/tool", description: "test" },
+        {
+          actions: {
+            greet: {
+              description: "Greet someone",
+              command: ["echo", "{{name}}"],
+              inputSchema: {
+                type: "object" as const,
+                properties: { name: { type: "string" as const } },
+                required: ["name"],
+              },
+            },
+          },
+        },
+        "greet",
+        {
+          description: "Greet someone",
+          command: ["echo", "{{name}}"],
+          inputSchema: {
+            type: "object" as const,
+            properties: { name: { type: "string" as const } },
+            required: ["name"],
+          },
+        },
+        { params: { name: "Alice" } }
+      );
+      expect(result.success).toBe(true);
+      expect(result.output.stdout.trim()).toBe("Alice");
+    });
+  });
+
+  describe("metadata", () => {
+    test("results include timing metadata", async () => {
+      const provider = new LocalExecutionProvider();
+      const before = new Date();
+      const result = await provider.execute(
+        { name: "@test/tool", description: "test", command: "echo timing" },
+        { params: {} }
+      );
+      const after = new Date();
+
+      expect(result.metadata.startTime.getTime()).toBeGreaterThanOrEqual(before.getTime());
+      expect(result.metadata.endTime.getTime()).toBeLessThanOrEqual(after.getTime());
+      expect(result.metadata.durationMs).toBeGreaterThanOrEqual(0);
+      expect(result.metadata.containerImage).toBe("local");
+      expect(result.metadata.executionId).toMatch(/^local-/);
+    });
+  });
+});
+
+describe("hasContainerfile", () => {
+  test("returns false for directory without container file", () => {
+    const dir = join(FIXTURES_DIR, "no-containerfile");
+    mkdirSync(dir, { recursive: true });
+    expect(hasContainerfile(dir)).toBe(false);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("returns true for directory with Containerfile", () => {
+    const dir = join(FIXTURES_DIR, "with-containerfile");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "Containerfile"), "FROM alpine");
+    expect(hasContainerfile(dir)).toBe(true);
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("returns true for directory with Dockerfile", () => {
+    const dir = join(FIXTURES_DIR, "with-dockerfile");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "Dockerfile"), "FROM alpine");
+    expect(hasContainerfile(dir)).toBe(true);
+    rmSync(dir, { recursive: true, force: true });
+  });
+});
+
+describe("selectExecutionMode", () => {
+  test("returns local when --local flag is set", () => {
+    expect(selectExecutionMode("/tmp", { local: true })).toBe("local");
+  });
+
+  test("returns container when --container flag is set", () => {
+    expect(selectExecutionMode("/tmp", { container: true })).toBe("container");
+  });
+
+  test("returns local when no Containerfile exists", () => {
+    const dir = join(FIXTURES_DIR, "no-cf-mode");
+    mkdirSync(dir, { recursive: true });
+    expect(selectExecutionMode(dir, {})).toBe("local");
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("returns container when Containerfile exists", () => {
+    const dir = join(FIXTURES_DIR, "cf-mode");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "Containerfile"), "FROM alpine");
+    expect(selectExecutionMode(dir, {})).toBe("container");
+    rmSync(dir, { recursive: true, force: true });
+  });
+});