@useatlas/create 0.0.1

package/templates/docker/src/lib/tools/explore-sandbox.ts

@@ -0,0 +1,264 @@
+/**
+ * Vercel Sandbox backend for the explore tool.
+ *
+ * Uses @vercel/sandbox to run commands in an ephemeral microVM.
+ * Only loaded when ATLAS_RUNTIME=vercel or running on the Vercel platform.
+ *
+ * Security: the sandbox runs with networkPolicy "deny-all" (no egress)
+ * and its filesystem is ephemeral — writes do not affect the host.
+ * Files from semantic/ are copied in at creation time.
+ */
+
+import type { ExploreBackend, ExecResult } from "./explore";
+import * as path from "path";
+import * as fs from "fs";
+import { createLogger } from "@atlas/api/lib/logger";
+import { SENSITIVE_PATTERNS } from "@atlas/api/lib/security";
+
+const log = createLogger("explore-sandbox");
+
+function collectSemanticFiles(
+  localDir: string,
+  sandboxDir: string
+): { path: string; content: Buffer }[] {
+  const results: { path: string; content: Buffer }[] = [];
+
+  function walk(dir: string, relative: string) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const localPath = path.join(dir, entry.name);
+      const remotePath = `${relative}/${entry.name}`;
+
+      if (entry.isSymbolicLink()) {
+        // Resolve symlinks — they may point to directories or files
+        try {
+          const realPath = fs.realpathSync(localPath);
+          if (!realPath.startsWith(localDir)) {
+            log.warn(
+              { localPath, realPath },
+              "Skipping symlink escaping semantic root",
+            );
+            continue;
+          }
+          const stat = fs.statSync(localPath);
+          if (stat.isDirectory()) {
+            walk(localPath, remotePath);
+          } else if (stat.isFile()) {
+            results.push({
+              path: remotePath,
+              content: fs.readFileSync(localPath),
+            });
+          }
+        } catch (err) {
+          log.warn(
+            { localPath, err: err instanceof Error ? err.message : String(err) },
+            "Skipping unreadable symlink",
+          );
+        }
+      } else if (entry.isDirectory()) {
+        walk(localPath, remotePath);
+      } else if (entry.isFile()) {
+        try {
+          results.push({
+            path: remotePath,
+            content: fs.readFileSync(localPath),
+          });
+        } catch (err) {
+          log.error(
+            { localPath, err: err instanceof Error ? err.message : String(err) },
+            "Failed to read file",
+          );
+        }
+      }
+    }
+  }
+
+  walk(localDir, sandboxDir);
+  return results;
+}
+
+/** Format an error for logging, with extra detail from @vercel/sandbox APIError json/text fields when present. */
+function sandboxErrorDetail(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+  const detail = err.message;
+  // APIError from @vercel/sandbox carries json/text with the server response.
+  // These properties are not in our type stubs — discovered from runtime errors.
+  const json = (err as unknown as Record<string, unknown>).json;
+  const text = (err as unknown as Record<string, unknown>).text;
+  if (json) {
+    try {
+      return `${detail} — response: ${JSON.stringify(json)}`;
+    } catch {
+      return `${detail} — response: [unserializable object]`;
+    }
+  }
+  if (typeof text === "string" && text) return `${detail} — body: ${text.slice(0, 500)}`;
+  return detail;
+}
+
+// Prefix for sandbox file paths: the SDK resolves relative paths under /vercel/sandbox/.
+const SANDBOX_SEMANTIC_REL = "semantic";
+// Must match the absolute resolution of SANDBOX_SEMANTIC_REL (used as runCommand cwd).
+const SANDBOX_SEMANTIC_CWD = "/vercel/sandbox/semantic";
+
+export async function createSandboxBackend(
+  semanticRoot: string
+): Promise<ExploreBackend> {
+  // 1. Import the optional dependency
+  let Sandbox: (typeof import("@vercel/sandbox"))["Sandbox"];
+  try {
+    ({ Sandbox } = await import("@vercel/sandbox"));
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    log.error({ err: detail }, "Failed to import @vercel/sandbox");
+    throw new Error(
+      "Vercel Sandbox runtime selected but @vercel/sandbox is not installed. " +
+        "Run 'bun add @vercel/sandbox' or set ATLAS_RUNTIME to a different backend.",
+      { cause: err }
+    );
+  }
+
+  // 2. Create the sandbox
+  let sandbox: InstanceType<typeof Sandbox>;
+  try {
+    sandbox = await Sandbox.create({
+      runtime: "node24",
+      networkPolicy: "deny-all",
+    });
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    log.error({ err: detail }, "Sandbox.create() failed");
+    throw new Error(
+      `Failed to create Vercel Sandbox: ${detail}. ` +
+        "Check your Vercel deployment configuration and sandbox quotas.",
+      { cause: err }
+    );
+  }
+
+  try {
+    // 3. Collect semantic layer files
+    // Use relative paths so the SDK writes under /vercel/sandbox/ (the writable
+    // base directory). Absolute root paths like /semantic cause the Sandbox API
+    // to return HTTP 400 — the SDK resolves relative paths to /vercel/sandbox/.
+    let files: { path: string; content: Buffer }[];
+    try {
+      files = collectSemanticFiles(semanticRoot, SANDBOX_SEMANTIC_REL);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      log.error({ err: detail }, "Failed to collect semantic layer files");
+      throw new Error(
+        `Cannot read semantic layer at ${semanticRoot}: ${detail}. ` +
+          "Ensure the semantic/ directory exists and is readable.",
+        { cause: err }
+      );
+    }
+
+    if (files.length === 0) {
+      log.error(
+        { semanticRoot },
+        "No semantic layer files found — sandbox will have empty semantic directory",
+      );
+      throw new Error(
+        "No semantic layer files found. " +
+          "Run 'bun run atlas -- init' to generate a semantic layer, then redeploy."
+      );
+    }
+
+    // 4. Copy semantic files into the sandbox filesystem
+    // Create directories first (mkDir is not recursive), then upload files.
+    const dirs = new Set<string>();
+    for (const f of files) {
+      let dir = path.posix.dirname(f.path);
+      while (dir !== "/" && dir !== ".") {
+        dirs.add(dir);
+        dir = path.posix.dirname(dir);
+      }
+    }
+
+    for (const dir of [...dirs].sort()) {
+      try {
+        await sandbox.mkDir(dir);
+      } catch (err) {
+        const detail = sandboxErrorDetail(err);
+        log.error({ err: detail, dir }, "Failed to create directory in sandbox");
+        const safeDetail = SENSITIVE_PATTERNS.test(detail)
+          ? "sandbox API error (details in server logs)"
+          : detail;
+        throw new Error(
+          `Failed to create directory "${dir}" in sandbox: ${safeDetail}.`,
+          { cause: err },
+        );
+      }
+    }
+
+    try {
+      await sandbox.writeFiles(files);
+    } catch (err) {
+      const detail = sandboxErrorDetail(err);
+      log.error({ err: detail, fileCount: files.length }, "Failed to write files into sandbox");
+      const safeDetail = SENSITIVE_PATTERNS.test(detail)
+        ? "sandbox API error (details in server logs)"
+        : detail;
+      throw new Error(
+        `Failed to upload ${files.length} semantic files to sandbox: ${safeDetail}.`,
+        { cause: err }
+      );
+    }
+  } catch (err) {
+    // Clean up the sandbox before re-throwing
+    try {
+      await sandbox.stop();
+    } catch (stopErr) {
+      log.warn(
+        { err: stopErr instanceof Error ? stopErr.message : String(stopErr) },
+        "Failed to stop sandbox during error cleanup",
+      );
+    }
+    throw err;
+  }
+
+  return {
+    exec: async (command: string): Promise<ExecResult> => {
+      try {
+        const result = await sandbox.runCommand({
+          cmd: "sh",
+          args: ["-c", command],
+          cwd: SANDBOX_SEMANTIC_CWD,
+        });
+        return {
+          stdout: await result.stdout(),
+          stderr: await result.stderr(),
+          exitCode: result.exitCode,
+        };
+      } catch (err) {
+        const detail = sandboxErrorDetail(err);
+        log.error({ err: detail }, "Sandbox command failed");
+        // Stop the broken sandbox before invalidating the cache
+        try {
+          await sandbox.stop();
+        } catch (stopErr) {
+          log.warn(
+            { err: stopErr instanceof Error ? stopErr.message : String(stopErr) },
+            "Failed to stop sandbox during error cleanup",
+          );
+        }
+        // Invalidate cached backend so next call creates a fresh sandbox
+        const { invalidateExploreBackend } = await import("./explore");
+        invalidateExploreBackend();
+        throw new Error(
+          `Sandbox infrastructure error: ${detail}. Will retry with a fresh sandbox.`,
+          { cause: err }
+        );
+      }
+    },
+    close: async () => {
+      try {
+        await sandbox.stop();
+      } catch (err) {
+        log.warn(
+          { err: err instanceof Error ? err.message : String(err) },
+          "Failed to stop sandbox during close",
+        );
+      }
+    },
+  };
+}

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

@@ -0,0 +1,163 @@
+/**
+ * Sidecar backend for the explore tool.
+ *
+ * Calls a separate HTTP service (the sandbox sidecar) to execute shell
+ * commands against the semantic layer. Isolation is provided by the
+ * container boundary — the sidecar has no secrets, no database drivers,
+ * and a minimal filesystem (bash, coreutils, semantic/ files).
+ * Communication occurs only via HTTP.
+ *
+ * Configured via ATLAS_SANDBOX_URL (e.g. http://sandbox-sidecar:8080).
+ */
+
+import type { ExploreBackend, ExecResult } from "./explore";
+import type { SidecarExecResponse } from "@atlas/api/lib/sidecar-types";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("explore-sidecar");
+
+/** Default timeout for sidecar requests (ms). */
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** HTTP-level timeout — slightly longer than the command timeout to allow for overhead. */
+const HTTP_OVERHEAD_MS = 5_000;
+
+export async function createSidecarBackend(
+  sidecarUrl: string,
+): Promise<ExploreBackend> {
+  const authToken = process.env.SIDECAR_AUTH_TOKEN;
+
+  let baseUrl: URL;
+  try {
+    baseUrl = new URL(sidecarUrl);
+  } catch {
+    throw new Error(
+      `Invalid ATLAS_SANDBOX_URL: "${sidecarUrl}". Expected a valid URL (e.g. http://sandbox-sidecar:8080).`,
+    );
+  }
+
+  const execUrl = new URL("/exec", baseUrl).toString();
+
+  return {
+    exec: async (command: string): Promise<ExecResult> => {
+      const timeout = DEFAULT_TIMEOUT_MS;
+
+      let response: Response;
+      try {
+        response = await fetch(execUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+          },
+          body: JSON.stringify({ command, timeout }),
+          signal: AbortSignal.timeout(timeout + HTTP_OVERHEAD_MS),
+        });
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+
+        // Connection refused or timeout — sidecar may be down
+        if (
+          detail.includes("ECONNREFUSED") ||
+          detail.includes("fetch failed") ||
+          detail.includes("Failed to connect")
+        ) {
+          log.error({ err: detail, url: execUrl }, "Sidecar connection failed");
+          // Invalidate backend cache so the next call re-evaluates the backend priority chain.
+          // If the sidecar stays down, the system falls back to just-bash.
+          const { invalidateExploreBackend } = await import("./explore");
+          invalidateExploreBackend();
+          throw new Error(
+            `Sidecar unreachable at ${baseUrl.origin}: ${detail}. ` +
+            "Check that the sandbox-sidecar service is running.",
+            { cause: err },
+          );
+        }
+
+        if (detail.includes("TimeoutError") || detail.includes("timed out") || detail.includes("aborted")) {
+          log.warn({ command, timeout }, "Sidecar request timed out");
+          return {
+            stdout: "",
+            stderr: `Command timed out after ${timeout}ms`,
+            exitCode: 124, // Conventional timeout exit code (matches GNU timeout(1))
+          };
+        }
+
+        log.error({ err: detail, command }, "Sidecar request failed");
+        throw new Error(`Sidecar request failed: ${detail}`, { cause: err });
+      }
+
+      // Handle HTTP-level errors from the sidecar
+      if (!response.ok) {
+        let errorBody: string;
+        try {
+          errorBody = await response.text();
+        } catch {
+          errorBody = `HTTP ${response.status}`;
+        }
+
+        log.error(
+          { status: response.status, body: errorBody.slice(0, 500) },
+          "Sidecar returned HTTP error",
+        );
+
+        // 500 with exec response shape — the sidecar wraps execution errors
+        if (response.status === 500) {
+          try {
+            const parsed = JSON.parse(errorBody);
+            if (typeof parsed.exitCode === "number") {
+              return {
+                stdout: parsed.stdout ?? "",
+                stderr: parsed.stderr ?? errorBody,
+                exitCode: parsed.exitCode,
+              };
+            }
+          } catch (parseErr) {
+            // Sidecar returned non-JSON 500 body — fall through to generic error
+            log.debug(
+              { status: response.status, parseError: parseErr instanceof Error ? parseErr.message : String(parseErr) },
+              "HTTP 500 body is not valid exec JSON — using generic error",
+            );
+          }
+        }
+
+        return {
+          stdout: "",
+          stderr: `Sidecar error (HTTP ${response.status}): ${errorBody.slice(0, 500)}`,
+          exitCode: 1,
+        };
+      }
+
+      // Parse the exec response
+      let parsed: unknown;
+      try {
+        parsed = await response.json();
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        log.error({ err: detail }, "Failed to parse sidecar response");
+        return {
+          stdout: "",
+          stderr: `Failed to parse sidecar response: ${detail}`,
+          exitCode: 1,
+        };
+      }
+
+      if (typeof parsed !== "object" || parsed === null || typeof (parsed as Record<string, unknown>).exitCode !== "number") {
+        log.error({ body: JSON.stringify(parsed).slice(0, 500) }, "Sidecar returned unexpected response shape");
+        return {
+          stdout: "",
+          stderr: "Sidecar returned an unexpected response format. Check ATLAS_SANDBOX_URL configuration.",
+          exitCode: 1,
+        };
+      }
+
+      const result = parsed as SidecarExecResponse;
+
+      return {
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        exitCode: result.exitCode,
+      };
+    },
+  };
+}