@useatlas/create 0.0.1

package/templates/docker/src/lib/tracing.ts

@@ -0,0 +1,40 @@
+/**
+ * Lightweight tracing helper.
+ *
+ * Wraps async functions in OpenTelemetry spans. When the OTel SDK is not
+ * initialized (no OTEL_EXPORTER_OTLP_ENDPOINT), @opentelemetry/api returns
+ * a no-op tracer — zero overhead, no conditional imports needed.
+ */
+
+import { trace, SpanStatusCode, type Attributes } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("atlas");
+
+/**
+ * Execute `fn` inside an OTel span. Sets span status and records exceptions
+ * on failure. When OTel is not initialized the span is a no-op.
+ */
+export async function withSpan<T>(
+  name: string,
+  attributes: Attributes,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return tracer.startActiveSpan(name, { attributes }, async (span) => {
+    try {
+      const result = await fn();
+      span.setStatus({ code: SpanStatusCode.OK });
+      return result;
+    } catch (err) {
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: err instanceof Error ? err.message : String(err),
+      });
+      span.recordException(
+        err instanceof Error ? err : new Error(String(err)),
+      );
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+}

package/templates/docker/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/templates/docker/src/test-setup.ts

@@ -0,0 +1,38 @@
+/**
+ * Global test preload — strips ATLAS_*, BETTER_AUTH_*, DATABASE_URL, and
+ * provider API keys (ANTHROPIC_API_KEY, etc.) before any test file loads,
+ * preventing the developer's real .env from leaking into tests.
+ *
+ * Individual tests set the vars they need in beforeEach; this preload ensures a
+ * clean baseline. Original values are restored in a top-level afterAll so the
+ * process isn't permanently modified.
+ */
+
+import { afterAll } from "bun:test";
+
+const prefixes = ["ATLAS_", "BETTER_AUTH_"];
+const exactVars = [
+  "DATABASE_URL",
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_SESSION_TOKEN",
+];
+
+// Snapshot current values so we can restore them after the entire suite
+const snapshot: Record<string, string> = {};
+
+for (const key of Object.keys(process.env)) {
+  if (prefixes.some((p) => key.startsWith(p)) || exactVars.includes(key)) {
+    snapshot[key] = process.env[key]!;
+    delete process.env[key];
+  }
+}
+
+afterAll(() => {
+  // Restore snapshotted vars
+  for (const [key, value] of Object.entries(snapshot)) {
+    process.env[key] = value;
+  }
+});

package/templates/docker/src/types/vercel-sandbox.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Minimal type declarations for @vercel/sandbox ^1.x (optional dependency).
+ * These declarations provide type safety on environments where the optional
+ * package is not installed (e.g., self-hosted Docker deployments).
+ * When @vercel/sandbox is installed, its own types take precedence.
+ *
+ * Last synced with: @vercel/sandbox@1.x SDK reference
+ */
+declare module "@vercel/sandbox" {
+  interface SandboxCreateOptions {
+    runtime?: string;
+    /**
+     * Network policy for the sandbox. Atlas MUST use "deny-all"
+     * to prevent the explore tool from making network requests.
+     * Actual SDK also accepts an object form for fine-grained rules.
+     */
+    networkPolicy?: "deny-all" | "allow-all" | (string & {});
+    ports?: number[];
+    timeout?: number;
+  }
+
+  interface WriteFileEntry {
+    path: string;
+    content: Buffer;
+  }
+
+  interface RunCommandParams {
+    cmd: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    sudo?: boolean;
+  }
+
+  /** Subset of actual CommandFinished class — see SDK docs for full API. */
+  interface CommandFinished {
+    exitCode: number;
+    stdout(): Promise<string>;
+    stderr(): Promise<string>;
+  }
+
+  class Sandbox {
+    static create(opts?: SandboxCreateOptions): Promise<Sandbox>;
+    mkDir(path: string): Promise<void>;
+    writeFiles(files: WriteFileEntry[]): Promise<void>;
+    runCommand(params: RunCommandParams): Promise<CommandFinished>;
+    runCommand(
+      command: string,
+      args?: string[],
+      opts?: { signal?: AbortSignal }
+    ): Promise<CommandFinished>;
+    stop(): Promise<Sandbox>;
+  }
+}

package/templates/docker/src/ui/components/actions/action-approval-card.tsx

@@ -0,0 +1,295 @@
+"use client";
+
+import { useState } from "react";
+import { getToolArgs, getToolResult, isToolComplete } from "../../lib/helpers";
+import {
+  isActionToolResult,
+  RESOLVED_STATUSES,
+  type ActionStatus,
+  type ResolvedStatus,
+  type ActionApprovalResponse,
+  type ActionToolResultShape,
+} from "../../lib/action-types";
+import { useAtlasConfig } from "../../context";
+import { useActionAuth } from "../../context";
+import { LoadingCard } from "../chat/loading-card";
+import { ActionStatusBadge } from "./action-status-badge";
+
+/* ------------------------------------------------------------------ */
+/*  Safe JSON.stringify helper                                         */
+/* ------------------------------------------------------------------ */
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return "[Unable to display]";
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/*  Card state machine                                                 */
+/* ------------------------------------------------------------------ */
+
+type CardState =
+  | { phase: "idle" }
+  | { phase: "submitting"; action: "approve" | "deny" }
+  | { phase: "resolved"; status: ResolvedStatus; result?: unknown }
+  | { phase: "error"; message: string };
+
+/* ------------------------------------------------------------------ */
+/*  Border color by status                                             */
+/* ------------------------------------------------------------------ */
+
+function borderColor(status: ActionStatus): string {
+  switch (status) {
+    case "pending_approval":
+      return "border-yellow-300 dark:border-yellow-900/50";
+    case "approved":
+    case "executed":
+    case "auto_approved":
+      return "border-green-300 dark:border-green-900/50";
+    case "denied":
+    case "failed":
+      return "border-red-300 dark:border-red-900/50";
+    default:
+      return "border-zinc-200 dark:border-zinc-700";
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/*  Component                                                          */
+/* ------------------------------------------------------------------ */
+
+export function ActionApprovalCard({ part }: { part: unknown }) {
+  const { apiUrl } = useAtlasConfig();
+  const actionAuth = useActionAuth();
+  const args = getToolArgs(part);
+  const rawResult = getToolResult(part);
+  const done = isToolComplete(part);
+
+  const [cardState, setCardState] = useState<CardState>({ phase: "idle" });
+  const [open, setOpen] = useState(false);
+  const [denyReason, setDenyReason] = useState("");
+  const [showDenyInput, setShowDenyInput] = useState(false);
+
+  if (!done) return <LoadingCard label="Requesting action approval..." />;
+
+  if (!isActionToolResult(rawResult)) {
+    return (
+      <div className="my-2 rounded-lg border border-yellow-300 bg-yellow-50 px-3 py-2 text-xs text-yellow-700 dark:border-yellow-900/50 dark:bg-yellow-950/20 dark:text-yellow-400">
+        Action result (unexpected format)
+      </div>
+    );
+  }
+
+  const toolResult: ActionToolResultShape = rawResult;
+
+  // Effective status: local optimistic update wins over server result
+  const effectiveStatus: ActionStatus =
+    cardState.phase === "resolved" ? cardState.status : toolResult.status;
+
+  const isPending = effectiveStatus === "pending_approval" && cardState.phase !== "submitting";
+  const isSubmitting = cardState.phase === "submitting";
+  const resolvedResult = cardState.phase === "resolved" ? cardState.result : toolResult.result;
+
+  /* ---------------------------------------------------------------- */
+  /*  API helpers                                                      */
+  /* ---------------------------------------------------------------- */
+
+  async function callAction(endpoint: "approve" | "deny", body?: Record<string, unknown>) {
+    if (!actionAuth) {
+      console.warn("ActionApprovalCard: No ActionAuthProvider found. API calls will be sent without authentication.");
+    }
+
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      ...(actionAuth?.getHeaders() ?? {}),
+    };
+    const credentials = actionAuth?.getCredentials() ?? "same-origin";
+
+    const res = await fetch(
+      `${apiUrl}/api/v1/actions/${toolResult.actionId}/${endpoint}`,
+      {
+        method: "POST",
+        headers,
+        credentials,
+        body: body ? JSON.stringify(body) : undefined,
+      },
+    );
+
+    if (res.status === 409) {
+      // Already resolved — read current status from response
+      let data: ActionApprovalResponse;
+      try {
+        data = (await res.json()) as ActionApprovalResponse;
+      } catch {
+        throw new Error("Action was already resolved, but the response could not be read. Refresh the page.");
+      }
+      const status = typeof data.status === "string" ? data.status as ResolvedStatus : "failed" as ResolvedStatus;
+      const label = status.replace(/_/g, " ");
+      throw new Error(`This action was already ${label} by another user or policy.`);
+    }
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "Unknown error");
+      throw new Error(`Server responded ${res.status}: ${text}`);
+    }
+
+    let data: ActionApprovalResponse;
+    try {
+      data = (await res.json()) as ActionApprovalResponse;
+    } catch {
+      throw new Error("Action succeeded, but the response could not be read. Refresh the page.");
+    }
+    if (typeof data.status !== "string") {
+      throw new Error("Action succeeded, but the server returned an invalid status. Refresh the page.");
+    }
+    setCardState({ phase: "resolved", status: data.status as ResolvedStatus, result: data.result });
+  }
+
+  async function handleApprove() {
+    setCardState({ phase: "submitting", action: "approve" });
+    try {
+      await callAction("approve");
+    } catch (err) {
+      console.error("Action approval failed:", err);
+      const message =
+        err instanceof TypeError
+          ? "Network error — could not reach the server."
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      setCardState({ phase: "error", message });
+    }
+  }
+
+  async function handleDeny() {
+    setCardState({ phase: "submitting", action: "deny" });
+    try {
+      await callAction("deny", denyReason.trim() ? { reason: denyReason.trim() } : undefined);
+    } catch (err) {
+      console.error("Action approval failed:", err);
+      const message =
+        err instanceof TypeError
+          ? "Network error — could not reach the server."
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      setCardState({ phase: "error", message });
+    }
+  }
+
+  /* ---------------------------------------------------------------- */
+  /*  Render                                                           */
+  /* ---------------------------------------------------------------- */
+
+  return (
+    <div className={`my-2 overflow-hidden rounded-lg border ${borderColor(effectiveStatus)} bg-zinc-50 dark:bg-zinc-900`}>
+      {/* Header */}
+      <button
+        onClick={() => setOpen(!open)}
+        className="flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors hover:bg-zinc-100/60 dark:hover:bg-zinc-800/60"
+      >
+        <ActionStatusBadge status={effectiveStatus} />
+        <span className="flex-1 truncate text-zinc-500 dark:text-zinc-400">
+          {toolResult.summary ?? String(args.description ?? "Action")}
+        </span>
+        <span className="text-zinc-400 dark:text-zinc-600">{open ? "\u25BE" : "\u25B8"}</span>
+      </button>
+
+      {/* Expanded details */}
+      {open && (
+        <div className="border-t border-zinc-100 px-3 py-2 dark:border-zinc-800">
+          {toolResult.details && (
+            <pre className="mb-2 max-h-48 overflow-auto rounded bg-zinc-100 p-2 text-xs text-zinc-600 dark:bg-zinc-800 dark:text-zinc-400">
+              {safeStringify(toolResult.details)}
+            </pre>
+          )}
+          {resolvedResult != null && (
+            <div className="mb-2 rounded bg-green-50 p-2 text-xs text-green-700 dark:bg-green-900/20 dark:text-green-400">
+              <span className="font-medium">Result: </span>
+              {typeof resolvedResult === "string"
+                ? resolvedResult
+                : safeStringify(resolvedResult)}
+            </div>
+          )}
+          {toolResult.error && (
+            <div className="mb-2 rounded bg-red-50 p-2 text-xs text-red-700 dark:bg-red-900/20 dark:text-red-400">
+              <span className="font-medium">Error: </span>
+              {toolResult.error}
+            </div>
+          )}
+          {toolResult.reason && RESOLVED_STATUSES.has(effectiveStatus) && (
+            <div className="mb-2 text-xs text-zinc-500 dark:text-zinc-400">
+              <span className="font-medium">Reason: </span>
+              {toolResult.reason}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Approval buttons — only when pending */}
+      {(isPending || isSubmitting || cardState.phase === "error") && (
+        <div className="border-t border-zinc-100 px-3 py-2 dark:border-zinc-800">
+          {cardState.phase === "error" && (
+            <p className="mb-2 text-xs text-red-600 dark:text-red-400">{cardState.message}</p>
+          )}
+
+          <div className="flex items-center gap-2">
+            <button
+              onClick={handleApprove}
+              disabled={isSubmitting}
+              className="inline-flex items-center gap-1.5 rounded bg-blue-600 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-blue-500 disabled:opacity-40"
+            >
+              {isSubmitting && cardState.action === "approve" && (
+                <span className="inline-block h-3 w-3 animate-spin rounded-full border-2 border-white/30 border-t-white" />
+              )}
+              Approve
+            </button>
+
+            {!showDenyInput ? (
+              <button
+                onClick={() => setShowDenyInput(true)}
+                disabled={isSubmitting}
+                className="rounded border border-zinc-300 px-3 py-1.5 text-xs font-medium text-zinc-600 transition-colors hover:border-zinc-400 hover:text-zinc-800 disabled:opacity-40 dark:border-zinc-600 dark:text-zinc-400 dark:hover:border-zinc-500 dark:hover:text-zinc-200"
+              >
+                Deny
+              </button>
+            ) : (
+              <div className="flex flex-1 items-center gap-2">
+                <input
+                  value={denyReason}
+                  onChange={(e) => setDenyReason(e.target.value)}
+                  placeholder="Reason (optional)"
+                  className="flex-1 rounded border border-zinc-200 bg-white px-2 py-1 text-xs text-zinc-900 placeholder-zinc-400 outline-none focus:border-red-400 dark:border-zinc-700 dark:bg-zinc-800 dark:text-zinc-100 dark:placeholder-zinc-600"
+                  disabled={isSubmitting}
+                />
+                <button
+                  onClick={handleDeny}
+                  disabled={isSubmitting}
+                  className="inline-flex items-center gap-1.5 rounded bg-red-600 px-3 py-1.5 text-xs font-medium text-white transition-colors hover:bg-red-500 disabled:opacity-40"
+                >
+                  {isSubmitting && cardState.action === "deny" && (
+                    <span className="inline-block h-3 w-3 animate-spin rounded-full border-2 border-white/30 border-t-white" />
+                  )}
+                  Confirm Deny
+                </button>
+                <button
+                  onClick={() => {
+                    setShowDenyInput(false);
+                    setDenyReason("");
+                  }}
+                  disabled={isSubmitting}
+                  className="text-xs text-zinc-400 hover:text-zinc-600 disabled:opacity-40 dark:hover:text-zinc-300"
+                >
+                  Cancel
+                </button>
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/docker/src/ui/components/actions/action-status-badge.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import type { ActionStatus } from "../../lib/action-types";
+
+const STATUS_CONFIG: Record<ActionStatus, { label: string; classes: string }> = {
+  pending_approval: {
+    label: "Pending Approval",
+    classes: "bg-yellow-100 text-yellow-700 dark:bg-yellow-600/20 dark:text-yellow-400",
+  },
+  approved: {
+    label: "Approved",
+    classes: "bg-green-100 text-green-700 dark:bg-green-600/20 dark:text-green-400",
+  },
+  executed: {
+    label: "Executed",
+    classes: "bg-green-100 text-green-700 dark:bg-green-600/20 dark:text-green-400",
+  },
+  auto_approved: {
+    label: "Auto-approved",
+    classes: "bg-green-100 text-green-700 dark:bg-green-600/20 dark:text-green-400",
+  },
+  denied: {
+    label: "Denied",
+    classes: "bg-red-100 text-red-700 dark:bg-red-600/20 dark:text-red-400",
+  },
+  failed: {
+    label: "Failed",
+    classes: "bg-red-100 text-red-700 dark:bg-red-600/20 dark:text-red-400",
+  },
+  rolled_back: {
+    label: "Rolled Back",
+    classes: "bg-zinc-100 text-zinc-700 dark:bg-zinc-600/20 dark:text-zinc-400",
+  },
+  timed_out: {
+    label: "Timed Out",
+    classes: "bg-zinc-100 text-zinc-700 dark:bg-zinc-600/20 dark:text-zinc-400",
+  },
+};
+
+export function ActionStatusBadge({ status }: { status: ActionStatus }) {
+  const config = STATUS_CONFIG[status] ?? {
+    label: status.replace(/_/g, " "),
+    classes: "bg-zinc-100 text-zinc-700 dark:bg-zinc-600/20 dark:text-zinc-400",
+  };
+  return (
+    <span className={`rounded px-1.5 py-0.5 text-xs font-medium ${config.classes}`}>
+      {config.label}
+    </span>
+  );
+}

package/templates/docker/src/ui/components/admin/admin-layout.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { SidebarProvider, SidebarInset, SidebarTrigger } from "@/components/ui/sidebar";
+import { Separator } from "@/components/ui/separator";
+import { AdminSidebar } from "./admin-sidebar";
+
+// TODO: Add real role gating once admin API enforces auth.
+// For now, all users can access the admin console — the admin API
+// endpoints will reject unauthorized requests server-side.
+
+export function AdminLayout({ children }: { children: ReactNode }) {
+  return (
+    <SidebarProvider>
+      <AdminSidebar />
+      <SidebarInset>
+        <header className="flex h-12 shrink-0 items-center gap-2 border-b px-4">
+          <SidebarTrigger className="-ml-1" />
+          <Separator orientation="vertical" className="mr-2 h-4" />
+          <span className="text-sm font-medium text-muted-foreground">Admin Console</span>
+        </header>
+        <div className="flex-1 overflow-auto">{children}</div>
+      </SidebarInset>
+    </SidebarProvider>
+  );
+}

package/templates/docker/src/ui/components/admin/admin-sidebar.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import {
+  LayoutDashboard,
+  Database,
+  Cable,
+  ScrollText,
+  Puzzle,
+  CalendarClock,
+  Zap,
+  ArrowLeft,
+} from "lucide-react";
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarFooter,
+  SidebarSeparator,
+} from "@/components/ui/sidebar";
+
+const navItems = [
+  { href: "/admin", label: "Overview", icon: LayoutDashboard, exact: true },
+  { href: "/admin/semantic", label: "Semantic Layer", icon: Database },
+  { href: "/admin/connections", label: "Connections", icon: Cable },
+  { href: "/admin/audit", label: "Audit", icon: ScrollText },
+  { href: "/admin/plugins", label: "Plugins", icon: Puzzle },
+  { href: "/admin/scheduled-tasks", label: "Scheduled Tasks", icon: CalendarClock },
+  { href: "/admin/actions", label: "Actions", icon: Zap },
+];
+
+export function AdminSidebar() {
+  const pathname = usePathname();
+
+  function isActive(item: (typeof navItems)[number]) {
+    if (item.exact) return pathname === item.href;
+    return pathname.startsWith(item.href);
+  }
+
+  return (
+    <Sidebar>
+      <SidebarHeader className="px-3 pt-4 pb-2">
+        <div className="flex items-center gap-2.5">
+          <svg viewBox="0 0 256 256" fill="none" className="size-6 shrink-0" aria-hidden="true">
+            <path d="M128 24 L232 208 L24 208 Z" stroke="#23CE9E" strokeWidth="14" fill="none" strokeLinejoin="round" />
+            <circle cx="128" cy="28" r="16" fill="#23CE9E" />
+          </svg>
+          <div>
+            <p className="text-sm font-semibold leading-none tracking-tight">Atlas</p>
+            <p className="text-xs text-muted-foreground">Admin Console</p>
+          </div>
+        </div>
+      </SidebarHeader>
+      <SidebarSeparator />
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarGroupLabel>Navigation</SidebarGroupLabel>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              {navItems.map((item) => (
+                <SidebarMenuItem key={item.href}>
+                  <SidebarMenuButton asChild isActive={isActive(item)} tooltip={item.label}>
+                    <Link href={item.href}>
+                      <item.icon className="size-4" />
+                      <span>{item.label}</span>
+                    </Link>
+                  </SidebarMenuButton>
+                </SidebarMenuItem>
+              ))}
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+      </SidebarContent>
+      <SidebarFooter>
+        <SidebarSeparator />
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton asChild tooltip="Back to Chat">
+              <Link href="/">
+                <ArrowLeft className="size-4" />
+                <span>Back to Chat</span>
+              </Link>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarFooter>
+    </Sidebar>
+  );
+}

package/templates/docker/src/ui/components/admin/empty-state.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+
+export function EmptyState({
+  icon: Icon,
+  message,
+  children,
+}: {
+  icon: LucideIcon;
+  message: string;
+  children?: ReactNode;
+}) {
+  return (
+    <div className="flex h-64 items-center justify-center text-muted-foreground">
+      <div className="text-center">
+        <Icon className="mx-auto size-10 opacity-50" />
+        <p className="mt-3 text-sm">{message}</p>
+        {children}
+      </div>
+    </div>
+  );
+}