@useatlas/create 0.0.1

package/templates/docker/src/lib/tools/__tests__/explore-plugin.test.ts

@@ -0,0 +1,374 @@
+/**
+ * Integration tests for getExploreBackend() sandbox plugin path.
+ *
+ * Validates that the explore module correctly discovers, sorts, and falls
+ * back through sandbox plugins before delegating to built-in backends.
+ *
+ * Uses mock.module() for the plugin registry. Each test gets a fresh
+ * explore module via cache-busting dynamic imports.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, mock } from "bun:test";
+import type { ExploreBackend, ExecResult } from "../../tools/explore";
+
+// ---------------------------------------------------------------------------
+// Mocks — must register before any import of explore.ts
+// ---------------------------------------------------------------------------
+
+// Mock logger (all exports from @atlas/api/lib/logger)
+mock.module("@atlas/api/lib/logger", () => ({
+  createLogger: () => ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+    child: () => ({
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    }),
+  }),
+  getLogger: () => ({
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    debug: () => {},
+    child: () => ({
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    }),
+  }),
+  withRequestContext: <T>(ctx: unknown, fn: () => T) => fn(),
+  getRequestContext: () => undefined,
+  redactPaths: [],
+}));
+
+// Mock tracing (all exports from @atlas/api/lib/tracing)
+mock.module("@atlas/api/lib/tracing", () => ({
+  withSpan: async <T>(_name: string, _attrs: unknown, fn: () => Promise<T>) => fn(),
+}));
+
+// Mock hooks (all exports from @atlas/api/lib/plugins/hooks)
+mock.module("@atlas/api/lib/plugins/hooks", () => ({
+  dispatchHook: async () => {},
+  dispatchMutableHook: async <T extends Record<string, unknown>, K extends string & keyof T>(
+    _hookName: string,
+    context: T,
+    mutateKey: K,
+  ) => context[mutateKey],
+}));
+
+// ---------------------------------------------------------------------------
+// Mutable sandbox plugin list — tests control what getByType("sandbox") returns
+// ---------------------------------------------------------------------------
+
+let mockSandboxPlugins: Array<{
+  id: string;
+  type: string;
+  version: string;
+  sandbox: {
+    create(root: string): Promise<ExploreBackend> | ExploreBackend;
+    priority?: number;
+  };
+  [k: string]: unknown;
+}> = [];
+
+mock.module("@atlas/api/lib/plugins/registry", () => ({
+  plugins: {
+    getByType: (type: string) => {
+      if (type === "sandbox") return mockSandboxPlugins;
+      return [];
+    },
+    getAllHealthy: () => [],
+    get: () => undefined,
+    getStatus: () => undefined,
+    describe: () => [],
+    size: 0,
+    register: () => {},
+    initializeAll: async () => ({ succeeded: [], failed: [] }),
+    healthCheckAll: async () => new Map(),
+    teardownAll: async () => {},
+    _reset: () => {},
+  },
+  PluginRegistry: class {},
+}));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+let importCounter = 0;
+
+/** Import a fresh copy of explore.ts with all module state reset. */
+async function freshExploreModule() {
+  importCounter++;
+  return await import(`@atlas/api/lib/tools/explore?plugin_test=${importCounter}`);
+}
+
+function makeMockBackend(tag: string): ExploreBackend {
+  return {
+    exec: async (command: string): Promise<ExecResult> => ({
+      stdout: `[${tag}] ${command}`,
+      stderr: "",
+      exitCode: 0,
+    }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("explore sandbox plugin integration", () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    mockSandboxPlugins = [];
+    // Ensure built-in backends are not detected
+    delete process.env.ATLAS_RUNTIME;
+    delete process.env.VERCEL;
+    delete process.env.ATLAS_SANDBOX;
+    delete process.env.ATLAS_SANDBOX_URL;
+    delete process.env.ATLAS_NSJAIL_PATH;
+    // Force PATH to not find nsjail
+    process.env.PATH = "/usr/bin:/bin";
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it("selects a registered sandbox plugin over built-in backends", async () => {
+    const backend = makeMockBackend("plugin-a");
+    mockSandboxPlugins = [
+      {
+        id: "plugin-a",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: { create: async () => backend },
+      },
+    ];
+
+    const mod = await freshExploreModule();
+    const result = await mod.explore.execute(
+      { command: "ls" },
+      { toolCallId: "test", messages: [], abortSignal: new AbortController().signal },
+    );
+
+    expect(result).toContain("[plugin-a]");
+  });
+
+  it("higher priority plugin wins when multiple are registered", async () => {
+    mockSandboxPlugins = [
+      {
+        id: "low-priority",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: {
+          create: async () => makeMockBackend("low"),
+          priority: 40,
+        },
+      },
+      {
+        id: "high-priority",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: {
+          create: async () => makeMockBackend("high"),
+          priority: 90,
+        },
+      },
+    ];
+
+    const mod = await freshExploreModule();
+    const result = await mod.explore.execute(
+      { command: "ls" },
+      { toolCallId: "test", messages: [], abortSignal: new AbortController().signal },
+    );
+
+    expect(result).toContain("[high]");
+  });
+
+  it("falls through to next plugin when first create() throws", async () => {
+    mockSandboxPlugins = [
+      {
+        id: "broken-plugin",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: {
+          create: async () => { throw new Error("init failed"); },
+          priority: 90,
+        },
+      },
+      {
+        id: "working-plugin",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: {
+          create: async () => makeMockBackend("working"),
+          priority: 50,
+        },
+      },
+    ];
+
+    const mod = await freshExploreModule();
+    const result = await mod.explore.execute(
+      { command: "ls" },
+      { toolCallId: "test", messages: [], abortSignal: new AbortController().signal },
+    );
+
+    expect(result).toContain("[working]");
+    expect(mod.getActiveSandboxPluginId()).toBe("working-plugin");
+  });
+
+  it("falls back to built-in backends when all plugins fail", async () => {
+    mockSandboxPlugins = [
+      {
+        id: "broken-1",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: {
+          create: async () => { throw new Error("fail 1"); },
+        },
+      },
+      {
+        id: "broken-2",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: {
+          create: async () => { throw new Error("fail 2"); },
+        },
+      },
+    ];
+
+    const mod = await freshExploreModule();
+    // No plugin succeeds, so it should fall through to just-bash.
+    // just-bash may fail in test env too (no semantic/ dir), but the key assertion
+    // is that _activeSandboxPluginId is NOT set.
+    expect(mod.getActiveSandboxPluginId()).toBeNull();
+  });
+
+  it("sets _activeSandboxPluginId on successful plugin selection", async () => {
+    mockSandboxPlugins = [
+      {
+        id: "my-sandbox",
+        type: "sandbox",
+        version: "2.0.0",
+        sandbox: { create: async () => makeMockBackend("my-sandbox") },
+      },
+    ];
+
+    const mod = await freshExploreModule();
+    await mod.explore.execute(
+      { command: "ls" },
+      { toolCallId: "test", messages: [], abortSignal: new AbortController().signal },
+    );
+
+    expect(mod.getActiveSandboxPluginId()).toBe("my-sandbox");
+  });
+
+  it("getExploreBackendType() returns 'plugin' when _activeSandboxPluginId is set", async () => {
+    mockSandboxPlugins = [
+      {
+        id: "test-plugin",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: { create: async () => makeMockBackend("test") },
+      },
+    ];
+
+    const mod = await freshExploreModule();
+    // Before any explore call, plugin is not yet active
+    expect(mod.getExploreBackendType()).not.toBe("plugin");
+
+    // Trigger backend init
+    await mod.explore.execute(
+      { command: "ls" },
+      { toolCallId: "test", messages: [], abortSignal: new AbortController().signal },
+    );
+
+    expect(mod.getExploreBackendType()).toBe("plugin");
+  });
+
+  it("invalidateExploreBackend() clears _activeSandboxPluginId", async () => {
+    mockSandboxPlugins = [
+      {
+        id: "clearable-plugin",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: { create: async () => makeMockBackend("clearable") },
+      },
+    ];
+
+    const mod = await freshExploreModule();
+    await mod.explore.execute(
+      { command: "ls" },
+      { toolCallId: "test", messages: [], abortSignal: new AbortController().signal },
+    );
+
+    expect(mod.getActiveSandboxPluginId()).toBe("clearable-plugin");
+
+    mod.invalidateExploreBackend();
+    expect(mod.getActiveSandboxPluginId()).toBeNull();
+  });
+
+  it("skips plugins when ATLAS_SANDBOX=nsjail is set", async () => {
+    process.env.ATLAS_SANDBOX = "nsjail";
+
+    mockSandboxPlugins = [
+      {
+        id: "should-be-skipped",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: { create: async () => makeMockBackend("skipped") },
+      },
+    ];
+
+    const mod = await freshExploreModule();
+    // Trigger backend init — it should skip plugins and go straight to nsjail
+    // nsjail will fail (not installed in test), but the key assertion is
+    // that the plugin was NOT used
+    await mod.explore.execute(
+      { command: "ls" },
+      { toolCallId: "test", messages: [], abortSignal: new AbortController().signal },
+    );
+
+    expect(mod.getActiveSandboxPluginId()).toBeNull();
+  });
+
+  it("uses default priority (60) when plugin omits priority", async () => {
+    mockSandboxPlugins = [
+      {
+        id: "explicit-low",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: {
+          create: async () => makeMockBackend("explicit-low"),
+          priority: 50,
+        },
+      },
+      {
+        id: "default-priority",
+        type: "sandbox",
+        version: "1.0.0",
+        sandbox: {
+          // No priority — defaults to 60 (SANDBOX_DEFAULT_PRIORITY)
+          create: async () => makeMockBackend("default"),
+        },
+      },
+    ];
+
+    const mod = await freshExploreModule();
+    const result = await mod.explore.execute(
+      { command: "ls" },
+      { toolCallId: "test", messages: [], abortSignal: new AbortController().signal },
+    );
+
+    // Default priority (60) > explicit (50), so default-priority plugin wins
+    expect(result).toContain("[default]");
+    expect(mod.getActiveSandboxPluginId()).toBe("default-priority");
+  });
+});

package/templates/docker/src/lib/tools/__tests__/explore-sdk-compat.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Compile-time drift guard: Plugin SDK <-> API explore types.
+ *
+ * Verifies that PluginExecResult is structurally identical to ExecResult and
+ * PluginExploreBackend is structurally identical to ExploreBackend. If either
+ * side adds a new required field without updating the other, the type-level
+ * assertions will fail at compile time.
+ *
+ * Both types are defined in this file to avoid a cross-package import
+ * (@atlas/api does not depend on @atlas/plugin-sdk by design).
+ */
+import { describe, test, expect } from "bun:test";
+import type { ExecResult, ExploreBackend } from "../explore";
+
+// Structural mirrors of the plugin SDK types — kept in sync manually.
+// If the SDK types change, update these mirrors AND the type assertions below.
+interface SDKExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+interface SDKExploreBackend {
+  exec(command: string): Promise<SDKExecResult>;
+  close?(): Promise<void>;
+}
+
+describe("explore SDK compatibility — structural drift guard", () => {
+  test("ExecResult and SDK mirror have identical shape", () => {
+    // Forward: SDK -> API
+    const sdk: SDKExecResult = { stdout: "out", stderr: "", exitCode: 0 };
+    const _api: ExecResult = sdk;
+    expect(_api.stdout).toBe("out");
+
+    // Backward: API -> SDK
+    const api: ExecResult = { stdout: "data", stderr: "warn", exitCode: 1 };
+    const _sdk: SDKExecResult = api;
+    expect(_sdk.exitCode).toBe(1);
+  });
+
+  test("ExploreBackend and SDK mirror have identical shape", () => {
+    // Forward: SDK -> API
+    const sdk: SDKExploreBackend = {
+      exec: async () => ({ stdout: "", stderr: "", exitCode: 0 }),
+    };
+    const _api: ExploreBackend = sdk;
+    expect(typeof _api.exec).toBe("function");
+
+    // Backward: API -> SDK
+    const api: ExploreBackend = {
+      exec: async () => ({ stdout: "", stderr: "", exitCode: 0 }),
+      close: async () => {},
+    };
+    const _sdk: SDKExploreBackend = api;
+    expect(typeof _sdk.close).toBe("function");
+  });
+
+  // Type-level assertions — fail at compile time if shapes diverge
+  test("type-level: SDKExecResult extends ExecResult", () => {
+    type Check = SDKExecResult extends ExecResult ? true : false;
+    const _: Check = true;
+    expect(_).toBe(true);
+  });
+
+  test("type-level: ExecResult extends SDKExecResult", () => {
+    type Check = ExecResult extends SDKExecResult ? true : false;
+    const _: Check = true;
+    expect(_).toBe(true);
+  });
+
+  test("type-level: SDKExploreBackend extends ExploreBackend", () => {
+    type Check = SDKExploreBackend extends ExploreBackend ? true : false;
+    const _: Check = true;
+    expect(_).toBe(true);
+  });
+
+  test("type-level: ExploreBackend extends SDKExploreBackend", () => {
+    type Check = ExploreBackend extends SDKExploreBackend ? true : false;
+    const _: Check = true;
+    expect(_).toBe(true);
+  });
+});

package/templates/docker/src/lib/tools/__tests__/explore-sidecar.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it, afterEach, spyOn } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mock fetch — intercept HTTP calls to the sidecar
+// ---------------------------------------------------------------------------
+
+let fetchCalls: { url: string; options: RequestInit }[] = [];
+
+const originalFetch = globalThis.fetch;
+
+function mockFetch(
+  handler: (url: string, options: RequestInit) => Response | Promise<Response>,
+) {
+  fetchCalls = [];
+  globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input.toString();
+    const options = init ?? {};
+    fetchCalls.push({ url, options });
+    return handler(url, options);
+  }) as typeof fetch;
+}
+
+function restoreFetch() {
+  globalThis.fetch = originalFetch;
+  fetchCalls = [];
+}
+
+// ---------------------------------------------------------------------------
+// Import after mocks
+// ---------------------------------------------------------------------------
+
+import { createSidecarBackend } from "@atlas/api/lib/tools/explore-sidecar";
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("createSidecarBackend", () => {
+  afterEach(() => {
+    restoreFetch();
+  });
+
+  it("rejects invalid URLs", async () => {
+    await expect(createSidecarBackend("not-a-url")).rejects.toThrow(
+      "Invalid ATLAS_SANDBOX_URL",
+    );
+  });
+
+  it("creates a backend with valid URL", async () => {
+    const backend = await createSidecarBackend("http://localhost:8080");
+    expect(backend).toBeDefined();
+    expect(typeof backend.exec).toBe("function");
+  });
+});
+
+describe("sidecar exec", () => {
+  afterEach(() => {
+    restoreFetch();
+  });
+
+  it("sends POST to /exec with command and timeout", async () => {
+    mockFetch(() =>
+      Response.json({ stdout: "file1.yml\n", stderr: "", exitCode: 0 }),
+    );
+
+    const backend = await createSidecarBackend("http://localhost:8080");
+    const result = await backend.exec("ls");
+
+    expect(result.stdout).toBe("file1.yml\n");
+    expect(result.stderr).toBe("");
+    expect(result.exitCode).toBe(0);
+
+    expect(fetchCalls).toHaveLength(1);
+    expect(fetchCalls[0].url).toBe("http://localhost:8080/exec");
+
+    const body = JSON.parse(fetchCalls[0].options.body as string);
+    expect(body.command).toBe("ls");
+    expect(body.timeout).toBe(10_000);
+  });
+
+  it("returns stderr and non-zero exit code", async () => {
+    mockFetch(() =>
+      Response.json({
+        stdout: "",
+        stderr: "ls: cannot access '/foo': No such file\n",
+        exitCode: 1,
+      }),
+    );
+
+    const backend = await createSidecarBackend("http://localhost:8080");
+    const result = await backend.exec("ls /foo");
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("No such file");
+  });
+
+  it("returns timeout error on AbortError", async () => {
+    mockFetch(() => {
+      throw new DOMException("The operation was aborted", "AbortError");
+    });
+
+    // Suppress log output during test
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+
+    const backend = await createSidecarBackend("http://localhost:8080");
+    const result = await backend.exec("sleep 999");
+
+    expect(result.exitCode).toBe(124);
+    expect(result.stderr).toContain("timed out");
+
+    warnSpy.mockRestore();
+  });
+
+  it("throws on connection refused and invalidates backend", async () => {
+    let invalidated = false;
+
+    // Mock the dynamic import of explore module
+    const exploreModule = await import("@atlas/api/lib/tools/explore");
+    const invalidateSpy = spyOn(
+      exploreModule,
+      "invalidateExploreBackend",
+    ).mockImplementation(() => {
+      invalidated = true;
+    });
+
+    mockFetch(() => {
+      throw new TypeError("fetch failed: ECONNREFUSED");
+    });
+
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    const backend = await createSidecarBackend("http://localhost:8080");
+    await expect(backend.exec("ls")).rejects.toThrow("Sidecar unreachable");
+
+    expect(invalidated).toBe(true);
+
+    errorSpy.mockRestore();
+    invalidateSpy.mockRestore();
+  });
+
+  it("handles HTTP 400 errors gracefully", async () => {
+    mockFetch(
+      () => new Response("Bad Request", { status: 400 }),
+    );
+
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    const backend = await createSidecarBackend("http://localhost:8080");
+    const result = await backend.exec("ls");
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("HTTP 400");
+
+    errorSpy.mockRestore();
+  });
+
+  it("handles HTTP 500 with exec response shape", async () => {
+    mockFetch(
+      () =>
+        new Response(
+          JSON.stringify({
+            error: "Execution failed",
+            stdout: "",
+            stderr: "command not found",
+            exitCode: 127,
+          }),
+          { status: 500, headers: { "Content-Type": "application/json" } },
+        ),
+    );
+
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    const backend = await createSidecarBackend("http://localhost:8080");
+    const result = await backend.exec("nonexistent-cmd");
+
+    expect(result.exitCode).toBe(127);
+    expect(result.stderr).toContain("command not found");
+
+    errorSpy.mockRestore();
+  });
+
+  it("handles malformed JSON response", async () => {
+    mockFetch(
+      () => new Response("not json", { status: 200 }),
+    );
+
+    const errorSpy = spyOn(console, "error").mockImplementation(() => {});
+
+    const backend = await createSidecarBackend("http://localhost:8080");
+    const result = await backend.exec("ls");
+
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("Failed to parse sidecar response");
+
+    errorSpy.mockRestore();
+  });
+
+  it("handles missing fields in response with defaults", async () => {
+    mockFetch(() => Response.json({ exitCode: 0 }));
+
+    const backend = await createSidecarBackend("http://localhost:8080");
+    const result = await backend.exec("ls");
+
+    expect(result.stdout).toBe("");
+    expect(result.stderr).toBe("");
+    expect(result.exitCode).toBe(0);
+  });
+});