@useatlas/create 0.0.5 → 0.0.7

package/templates/nextjs-standalone/src/lib/tools/backends/nsjail.ts

@@ -0,0 +1,213 @@
+/**
+ * Shared nsjail detection, args building, and capability testing.
+ *
+ * These functions are nsjail-platform-generic — they detect whether nsjail
+ * is available and can create namespaces. Both explore and python backends
+ * use them, as does startup.ts (via explore-nsjail.ts re-exports) for
+ * pre-flight checks. python.ts imports directly from this module.
+ */
+
+import * as fs from "fs";
+import { createLogger } from "@atlas/api/lib/logger";
+import { readLimited, MAX_OUTPUT, parsePositiveInt } from "./shared";
+
+const log = createLogger("nsjail-sandbox");
+
+/** Resolve the nsjail binary path, or null if unavailable. */
+export function findNsjailBinary(): string | null {
+  // 1. Explicit path from env
+  const explicit = process.env.ATLAS_NSJAIL_PATH;
+  if (explicit) {
+    try {
+      fs.accessSync(explicit, fs.constants.X_OK);
+      return explicit;
+    } catch (err) {
+      const code =
+        err instanceof Error && "code" in err
+          ? (err as NodeJS.ErrnoException).code
+          : "unknown";
+      log.error(
+        `ATLAS_NSJAIL_PATH="${explicit}" is not executable (${code})`,
+      );
+      return null;
+    }
+  }
+
+  // 2. Search PATH
+  const pathDirs = (process.env.PATH ?? "").split(":");
+  for (const dir of pathDirs) {
+    const candidate = `${dir}/nsjail`;
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      // intentionally ignored: file not found/not executable is the expected case when scanning PATH
+      continue;
+    }
+  }
+
+  return null;
+}
+
+/** Check whether nsjail is available on this system. */
+export function isNsjailAvailable(): boolean {
+  return findNsjailBinary() !== null;
+}
+
+/** Logger interface for buildNsjailArgs — avoids coupling to pino. */
+interface NsjailLogger {
+  warn: (...args: unknown[]) => void;
+}
+
+/**
+ * Build the nsjail CLI args for a single command execution.
+ *
+ * Shared between testNsjailCapabilities (capability check) and
+ * createNsjailBackend (real execution) so both exercise the exact
+ * same namespace config.
+ */
+export function buildNsjailArgs(
+  nsjailPath: string,
+  semanticRoot: string,
+  command: string,
+  nsjailLog: NsjailLogger = log,
+): string[] {
+  const timeLimit = parsePositiveInt(
+    "ATLAS_NSJAIL_TIME_LIMIT",
+    10,
+    "time limit",
+    nsjailLog,
+  );
+  const memoryLimit = parsePositiveInt(
+    "ATLAS_NSJAIL_MEMORY_LIMIT",
+    256,
+    "memory limit",
+    nsjailLog,
+  );
+
+  return [
+    nsjailPath,
+    "--mode",
+    "o",
+
+    // Read-only bind mounts
+    "-R",
+    `${semanticRoot}:/semantic`,
+    "-R",
+    "/bin",
+    "-R",
+    "/usr/bin",
+    "-R",
+    "/lib",
+    "-R",
+    "/lib64",
+    "-R",
+    "/usr/lib",
+
+    // Minimal /dev
+    "-R",
+    "/dev/null",
+    "-R",
+    "/dev/zero",
+    "-R",
+    "/dev/urandom",
+
+    // /proc for correct namespace operation
+    "--proc_path",
+    "/proc",
+
+    // Writable tmpfs for scratch
+    "-T",
+    "/tmp",
+
+    // Working directory
+    "--cwd",
+    "/semantic",
+
+    // Time limit
+    "-t",
+    String(timeLimit),
+
+    // Resource limits
+    "--rlimit_as",
+    String(memoryLimit),
+    "--rlimit_fsize",
+    "10",
+    "--rlimit_nproc",
+    "5",
+    "--rlimit_nofile",
+    "64",
+
+    // Run as nobody
+    "-u",
+    "65534",
+    "-g",
+    "65534",
+
+    // Suppress nsjail info logs but keep error diagnostics
+    "--quiet",
+
+    // Command to execute
+    "--",
+    "/bin/bash",
+    "-c",
+    command,
+  ];
+}
+
+/** Minimal env passed into the jail — no secrets. */
+const JAIL_ENV: Record<string, string> = {
+  PATH: "/bin:/usr/bin",
+  HOME: "/tmp",
+  LANG: "C.UTF-8",
+};
+
+/**
+ * Run a minimal nsjail command to verify namespace support actually works.
+ *
+ * Uses the same buildNsjailArgs as real explore commands to exercise the
+ * exact same namespace config (user, PID, mount, network). Returns
+ * `{ ok: true }` if nsjail can create namespaces on this platform, or
+ * `{ ok: false, error }` with a diagnostic message otherwise.
+ */
+export async function testNsjailCapabilities(
+  nsjailPath: string,
+  semanticRoot: string,
+): Promise<{ ok: boolean; error?: string }> {
+  const TIMEOUT_MS = 5000;
+  try {
+    const args = buildNsjailArgs(nsjailPath, semanticRoot, "echo nsjail-ok");
+    const proc = Bun.spawn(args, {
+      env: JAIL_ENV,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const timer = setTimeout(() => proc.kill(), TIMEOUT_MS);
+    try {
+      const [stdout, stderr] = await Promise.all([
+        readLimited(proc.stdout, MAX_OUTPUT),
+        readLimited(proc.stderr, MAX_OUTPUT),
+      ]);
+      const exitCode = await proc.exited;
+      clearTimeout(timer);
+
+      if (exitCode === 0 && stdout.includes("nsjail-ok")) {
+        return { ok: true };
+      }
+
+      return {
+        ok: false,
+        error: `nsjail exited with code ${exitCode}${stderr ? `: ${stderr.trim()}` : ""}`,
+      };
+    } catch (err) {
+      clearTimeout(timer);
+      throw err;
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/templates/nextjs-standalone/src/lib/tools/backends/shared.ts

@@ -0,0 +1,103 @@
+/**
+ * Shared utilities for sandbox backends.
+ *
+ * Extracted from the explore and python nsjail/sandbox backend files
+ * to eliminate cross-backend duplication.
+ */
+
+import { SENSITIVE_PATTERNS } from "@atlas/api/lib/security";
+
+/** Maximum bytes to read from stdout/stderr (1 MB). */
+export const MAX_OUTPUT = 1024 * 1024;
+
+/**
+ * Read up to `max` bytes from a stream, releasing the reader on completion or error.
+ *
+ * Used by nsjail backends (explore + python) to cap subprocess output
+ * and by testNsjailCapabilities for capability checks.
+ */
+export async function readLimited(
+  stream: ReadableStream,
+  max: number,
+): Promise<string> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > max) {
+        chunks.push(value.slice(0, max - (total - value.byteLength)));
+        break;
+      }
+      chunks.push(value);
+    }
+  } finally {
+    // intentionally ignored: stream cancel errors are non-critical during cleanup
+    await reader.cancel().catch(() => {});
+  }
+  return new TextDecoder().decode(Buffer.concat(chunks));
+}
+
+/** Logger interface accepted by parsePositiveInt — avoids coupling to pino. */
+interface MinimalLogger {
+  warn: (...args: unknown[]) => void;
+}
+
+/**
+ * Parse a positive integer from an env var, returning defaultValue on invalid input.
+ *
+ * Used by both explore and python nsjail backends for resource limit config.
+ */
+export function parsePositiveInt(
+  envVar: string,
+  defaultValue: number,
+  name: string,
+  log: MinimalLogger,
+): number {
+  const raw = process.env[envVar];
+  if (raw === undefined) return defaultValue;
+  const parsed = parseInt(raw, 10);
+  if (isNaN(parsed) || parsed <= 0) {
+    log.warn(
+      { envVar, raw, default: defaultValue },
+      `Invalid ${envVar} for ${name}, using default`,
+    );
+    return defaultValue;
+  }
+  return parsed;
+}
+
+/**
+ * Format an error for logging, with extra detail from @vercel/sandbox
+ * APIError json/text fields when present.
+ *
+ * Used by both explore-sandbox.ts and python-sandbox.ts.
+ */
+export 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 {
+      // intentionally ignored: JSON.stringify can fail on circular references
+      return `${detail} — response: [unserializable object]`;
+    }
+  }
+  if (typeof text === "string" && text) return `${detail} — body: ${text.slice(0, 500)}`;
+  return detail;
+}
+
+/** Scrub sensitive data from error messages before exposing to users. */
+export function safeError(detail: string): string {
+  return SENSITIVE_PATTERNS.test(detail)
+    ? "sandbox API error (details in server logs)"
+    : detail;
+}

package/templates/nextjs-standalone/src/lib/tools/backends/types.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared types for sandbox backends.
+ *
+ * Canonical definitions for the explore backend interface. Explore tool
+ * backends import from here; plugins/wiring.ts uses ExploreBackend as
+ * the type for sandbox plugin backends.
+ */
+
+export interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Shell backend for the explore tool.
+ *
+ * Implementations MUST provide read-only filesystem access scoped to the
+ * semantic layer directory. Commands execute within /semantic as the working
+ * directory. Writes should be silently discarded or cause errors, never
+ * modify the host filesystem.
+ */
+export interface ExploreBackend {
+  exec(command: string): Promise<ExecResult>;
+  close?(): Promise<void>;
+}

package/templates/nextjs-standalone/src/lib/tools/explore-nsjail.ts

@@ -10,238 +10,17 @@
  * to .env or any host secrets. Process runs as nobody (65534:65534).
  */
 
-import type { ExploreBackend, ExecResult } from "./explore";
+import type { ExploreBackend, ExecResult } from "./backends/types";
+import { readLimited, MAX_OUTPUT } from "./backends/shared";
+import { findNsjailBinary, buildNsjailArgs } from "./backends/nsjail";
 import { createLogger } from "@atlas/api/lib/logger";
 import * as fs from "fs";
 
 const log = createLogger("nsjail-sandbox");
 
-/** Maximum bytes to read from stdout/stderr (1 MB). */
-const MAX_OUTPUT = 1024 * 1024;
-
-/** Read up to `max` bytes from a stream, releasing the reader on completion or error. */
-async function readLimited(
-  stream: ReadableStream,
-  max: number,
-): Promise<string> {
-  const reader = stream.getReader();
-  const chunks: Uint8Array[] = [];
-  let total = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      total += value.byteLength;
-      if (total > max) {
-        chunks.push(value.slice(0, max - (total - value.byteLength)));
-        break;
-      }
-      chunks.push(value);
-    }
-  } finally {
-    await reader.cancel().catch(() => {});
-  }
-  return new TextDecoder().decode(Buffer.concat(chunks));
-}
-
-/** Parse a positive integer from an env var, returning defaultValue on invalid input. */
-function parsePositiveInt(
-  envVar: string,
-  defaultValue: number,
-  name: string,
-): number {
-  const raw = process.env[envVar];
-  if (raw === undefined) return defaultValue;
-  const parsed = parseInt(raw, 10);
-  if (isNaN(parsed) || parsed <= 0) {
-    log.warn(
-      `Invalid ${envVar}="${raw}" for ${name}, using default: ${defaultValue}`,
-    );
-    return defaultValue;
-  }
-  return parsed;
-}
-
-/** Resolve the nsjail binary path, or null if unavailable. */
-export function findNsjailBinary(): string | null {
-  // 1. Explicit path from env
-  const explicit = process.env.ATLAS_NSJAIL_PATH;
-  if (explicit) {
-    try {
-      fs.accessSync(explicit, fs.constants.X_OK);
-      return explicit;
-    } catch (err) {
-      const code =
-        err instanceof Error && "code" in err
-          ? (err as NodeJS.ErrnoException).code
-          : "unknown";
-      log.error(
-        `ATLAS_NSJAIL_PATH="${explicit}" is not executable (${code})`,
-      );
-      return null;
-    }
-  }
-
-  // 2. Search PATH
-  const pathDirs = (process.env.PATH ?? "").split(":");
-  for (const dir of pathDirs) {
-    const candidate = `${dir}/nsjail`;
-    try {
-      fs.accessSync(candidate, fs.constants.X_OK);
-      return candidate;
-    } catch {
-      continue;
-    }
-  }
-
-  return null;
-}
-
-/** Check whether nsjail is available on this system. */
-export function isNsjailAvailable(): boolean {
-  return findNsjailBinary() !== null;
-}
-
-/**
- * Run a minimal nsjail command to verify namespace support actually works.
- *
- * Exercises the exact same namespace config (user, PID, mount, network)
- * that real explore commands use. Returns `{ ok: true }` if nsjail can
- * create namespaces on this platform, or `{ ok: false, error }` with
- * a diagnostic message otherwise.
- */
-export async function testNsjailCapabilities(
-  nsjailPath: string,
-  semanticRoot: string,
-): Promise<{ ok: boolean; error?: string }> {
-  const TIMEOUT_MS = 5000;
-  try {
-    const args = buildNsjailArgs(nsjailPath, semanticRoot, "echo nsjail-ok");
-    const proc = Bun.spawn(args, {
-      env: JAIL_ENV,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-
-    const timer = setTimeout(() => proc.kill(), TIMEOUT_MS);
-    try {
-      const [stdout, stderr] = await Promise.all([
-        readLimited(proc.stdout, MAX_OUTPUT),
-        readLimited(proc.stderr, MAX_OUTPUT),
-      ]);
-      const exitCode = await proc.exited;
-      clearTimeout(timer);
-
-      if (exitCode === 0 && stdout.includes("nsjail-ok")) {
-        return { ok: true };
-      }
-
-      return {
-        ok: false,
-        error: `nsjail exited with code ${exitCode}${stderr ? `: ${stderr.trim()}` : ""}`,
-      };
-    } catch (err) {
-      clearTimeout(timer);
-      throw err;
-    }
-  } catch (err) {
-    return {
-      ok: false,
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-/** Build the nsjail CLI args for a single command execution. */
-function buildNsjailArgs(
-  nsjailPath: string,
-  semanticRoot: string,
-  command: string,
-): string[] {
-  const timeLimit = parsePositiveInt(
-    "ATLAS_NSJAIL_TIME_LIMIT",
-    10,
-    "time limit",
-  );
-  const memoryLimit = parsePositiveInt(
-    "ATLAS_NSJAIL_MEMORY_LIMIT",
-    256,
-    "memory limit",
-  );
-
-  return [
-    nsjailPath,
-    "--mode",
-    "o",
-
-    // Read-only bind mounts
-    "-R",
-    `${semanticRoot}:/semantic`,
-    "-R",
-    "/bin",
-    "-R",
-    "/usr/bin",
-    "-R",
-    "/lib",
-    "-R",
-    "/lib64",
-    "-R",
-    "/usr/lib",
-
-    // Minimal /dev
-    "-R",
-    "/dev/null",
-    "-R",
-    "/dev/zero",
-    "-R",
-    "/dev/urandom",
-
-    // /proc for correct namespace operation
-    "--proc_path",
-    "/proc",
-
-    // Writable tmpfs for scratch
-    "-T",
-    "/tmp",
-
-    // Working directory
-    "--cwd",
-    "/semantic",
-
-    // Network namespace is enabled by default in nsjail (no network access).
-    // Older versions used --clone_newnet to opt in; current versions use
-    // --disable_clone_newnet to opt out. No flag needed.
-
-    // Time limit
-    "-t",
-    String(timeLimit),
-
-    // Resource limits
-    "--rlimit_as",
-    String(memoryLimit),
-    "--rlimit_fsize",
-    "10",
-    "--rlimit_nproc",
-    "5",
-    "--rlimit_nofile",
-    "64",
-
-    // Run as nobody
-    "-u",
-    "65534",
-    "-g",
-    "65534",
-
-    // Suppress nsjail info logs but keep error diagnostics
-    "--quiet",
-
-    // Command to execute
-    "--",
-    "/bin/bash",
-    "-c",
-    command,
-  ];
-}
+// Re-export nsjail detection utilities for backward compatibility.
+// startup.ts dynamically imports these from this module path.
+export { findNsjailBinary, isNsjailAvailable, testNsjailCapabilities } from "./backends/nsjail";
 
 /** Minimal env passed into the jail — no secrets. */
 const JAIL_ENV: Record<string, string> = {
@@ -288,7 +67,7 @@ export async function createNsjailBackend(
     exec: async (command: string): Promise<ExecResult> => {
       let proc;
       try {
-        const args = buildNsjailArgs(nsjailPath, semanticRoot, command);
+        const args = buildNsjailArgs(nsjailPath, semanticRoot, command, log);
         proc = Bun.spawn(args, {
           env: JAIL_ENV,
           stdout: "pipe",

package/templates/nextjs-standalone/src/lib/tools/explore-sandbox.ts

@@ -9,11 +9,11 @@
  * Files from semantic/ are copied in at creation time.
  */
 
-import type { ExploreBackend, ExecResult } from "./explore";
+import type { ExploreBackend, ExecResult } from "./backends/types";
+import { sandboxErrorDetail, safeError } from "./backends/shared";
 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");
 
@@ -76,25 +76,6 @@ function collectSemanticFiles(
   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).
@@ -180,11 +161,8 @@ export async function createSandboxBackend(
       } 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}.`,
+          `Failed to create directory "${dir}" in sandbox: ${safeError(detail)}.`,
           { cause: err },
         );
       }
@@ -195,11 +173,8 @@ export async function createSandboxBackend(
     } 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}.`,
+        `Failed to upload ${files.length} semantic files to sandbox: ${safeError(detail)}.`,
         { cause: err }
       );
     }

package/templates/nextjs-standalone/src/lib/tools/explore-sidecar.ts

@@ -10,7 +10,7 @@
  * Configured via ATLAS_SANDBOX_URL (e.g. http://sandbox-sidecar:8080).
  */
 
-import type { ExploreBackend, ExecResult } from "./explore";
+import type { ExploreBackend, ExecResult } from "./backends/types";
 import type { SidecarExecResponse } from "@atlas/api/lib/sidecar-types";
 import { createLogger } from "@atlas/api/lib/logger";
 
@@ -24,9 +24,25 @@ const HTTP_OVERHEAD_MS = 5_000;
 
 export async function createSidecarBackend(
   sidecarUrl: string,
+  options?: { semanticRoot?: string },
 ): Promise<ExploreBackend> {
   const authToken = process.env.SIDECAR_AUTH_TOKEN;
 
+  // Compute sidecar cwd for org-scoped directories.
+  // The sidecar mounts the host's semantic/ at /semantic. If the semantic
+  // root is semantic/.orgs/org123, the sidecar cwd is .orgs/org123
+  // (relative to /semantic in the container).
+  let sidecarCwd: string | undefined;
+  if (options?.semanticRoot) {
+    const { getSemanticRoot } = await import("@atlas/api/lib/semantic/sync");
+    const base = getSemanticRoot(); // base semantic root (no org)
+    const path = await import("path");
+    const rel = path.relative(base, options.semanticRoot);
+    if (rel && rel !== "." && !rel.startsWith("..")) {
+      sidecarCwd = rel;
+    }
+  }
+
   let baseUrl: URL;
   try {
     baseUrl = new URL(sidecarUrl);
@@ -75,7 +91,7 @@ export async function createSidecarBackend(
             "Content-Type": "application/json",
             ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
           },
-          body: JSON.stringify({ command, timeout }),
+          body: JSON.stringify({ command, timeout, ...(sidecarCwd ? { cwd: sidecarCwd } : {}) }),
           signal: AbortSignal.timeout(timeout + HTTP_OVERHEAD_MS),
         });
       } catch (err) {