@useatlas/create 0.0.1

package/templates/docker/src/ui/components/conversations/conversation-sidebar.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import type { Conversation } from "../../lib/types";
+import { ConversationList } from "./conversation-list";
+
+export function ConversationSidebar({
+  conversations,
+  selectedId,
+  loading,
+  onSelect,
+  onDelete,
+  onStar,
+  onNewChat,
+  mobileOpen,
+  onMobileClose,
+}: {
+  conversations: Conversation[];
+  selectedId: string | null;
+  loading: boolean;
+  onSelect: (id: string) => void;
+  onDelete: (id: string) => Promise<boolean>;
+  onStar: (id: string, starred: boolean) => Promise<boolean>;
+  onNewChat: () => void;
+  mobileOpen: boolean;
+  onMobileClose: () => void;
+}) {
+  const sidebar = (
+    <div className="flex h-full flex-col border-r border-zinc-200 bg-zinc-50/50 dark:border-zinc-800 dark:bg-zinc-950/50">
+      <div className="flex items-center justify-between border-b border-zinc-200 px-3 py-3 dark:border-zinc-800">
+        <span className="text-sm font-medium text-zinc-700 dark:text-zinc-300">History</span>
+        <button
+          onClick={onNewChat}
+          className="rounded-lg border border-zinc-200 px-2.5 py-1 text-xs font-medium text-zinc-600 transition-colors hover:border-zinc-400 hover:text-zinc-900 dark:border-zinc-700 dark:text-zinc-400 dark:hover:border-zinc-500 dark:hover:text-zinc-200"
+        >
+          + New
+        </button>
+      </div>
+
+      <div className="flex-1 overflow-y-auto p-2">
+        {loading && conversations.length === 0 ? (
+          <div className="flex items-center justify-center py-8">
+            <span className="inline-block h-4 w-4 animate-spin rounded-full border-2 border-zinc-300 border-t-zinc-600 dark:border-zinc-600 dark:border-t-zinc-300" />
+          </div>
+        ) : (
+          <ConversationList
+            conversations={conversations}
+            selectedId={selectedId}
+            onSelect={onSelect}
+            onDelete={onDelete}
+            onStar={onStar}
+          />
+        )}
+      </div>
+    </div>
+  );
+
+  return (
+    <>
+      {/* Desktop sidebar */}
+      <div className="hidden w-[280px] shrink-0 md:block">
+        {sidebar}
+      </div>
+
+      {/* Mobile overlay */}
+      {mobileOpen && (
+        <>
+          <div
+            className="fixed inset-0 z-40 bg-black/30 md:hidden"
+            onClick={onMobileClose}
+          />
+          <div className="fixed inset-y-0 left-0 z-50 w-[280px] md:hidden">
+            {sidebar}
+          </div>
+        </>
+      )}
+    </>
+  );
+}

package/templates/docker/src/ui/components/conversations/delete-confirmation.tsx

@@ -0,0 +1,27 @@
+"use client";
+
+export function DeleteConfirmation({
+  onConfirm,
+  onCancel,
+}: {
+  onConfirm: () => void;
+  onCancel: () => void;
+}) {
+  return (
+    <div className="flex items-center gap-2 px-3 py-2 text-xs">
+      <span className="text-zinc-500 dark:text-zinc-400">Delete?</span>
+      <button
+        onClick={onCancel}
+        className="rounded px-2 py-0.5 text-zinc-500 transition-colors hover:text-zinc-800 dark:text-zinc-400 dark:hover:text-zinc-200"
+      >
+        Cancel
+      </button>
+      <button
+        onClick={onConfirm}
+        className="rounded bg-red-600 px-2 py-0.5 text-white transition-colors hover:bg-red-500"
+      >
+        Delete
+      </button>
+    </div>
+  );
+}

package/templates/docker/src/ui/context.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+
+/**
+ * Duck-typed interface that matches better-auth's client shape.
+ * Components like ManagedAuthCard call signIn/signUp/signOut and useSession().
+ */
+export interface AtlasAuthClient {
+  signIn: {
+    email: (opts: { email: string; password: string }) => Promise<{ error?: { message?: string } | null }>;
+  };
+  signUp: {
+    email: (opts: { email: string; password: string; name: string }) => Promise<{ error?: { message?: string } | null }>;
+  };
+  signOut: () => Promise<unknown>;
+  useSession: () => { data?: { user?: { email?: string } } | null };
+}
+
+export interface AtlasUIConfig {
+  apiUrl: string;
+  isCrossOrigin: boolean;
+  authClient: AtlasAuthClient;
+}
+
+const AtlasUIContext = createContext<AtlasUIConfig | null>(null);
+
+export function useAtlasConfig(): AtlasUIConfig {
+  const ctx = useContext(AtlasUIContext);
+  if (!ctx) throw new Error("useAtlasConfig must be used within <AtlasUIProvider>");
+  return ctx;
+}
+
+export function AtlasUIProvider({
+  config,
+  children,
+}: {
+  config: AtlasUIConfig;
+  children: ReactNode;
+}) {
+  return (
+    <AtlasUIContext.Provider value={config}>
+      {children}
+    </AtlasUIContext.Provider>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  ActionAuth — internal context for passing auth to action cards     */
+/* ------------------------------------------------------------------ */
+
+export interface ActionAuthValue {
+  getHeaders: () => Record<string, string>;
+  getCredentials: () => RequestCredentials;
+}
+
+const ActionAuthContext = createContext<ActionAuthValue | null>(null);
+
+/** Returns auth helpers for action API calls, or null when no provider is present. */
+export function useActionAuth(): ActionAuthValue | null {
+  return useContext(ActionAuthContext);
+}
+
+export function ActionAuthProvider({
+  getHeaders,
+  getCredentials,
+  children,
+}: ActionAuthValue & { children: ReactNode }) {
+  const value = useMemo(
+    () => ({ getHeaders, getCredentials }),
+    [getHeaders, getCredentials],
+  );
+  return (
+    <ActionAuthContext.Provider value={value}>
+      {children}
+    </ActionAuthContext.Provider>
+  );
+}

package/templates/docker/src/ui/hooks/use-admin-fetch.ts

@@ -0,0 +1,104 @@
+"use client";
+
+import { useEffect, useState, useCallback, useRef } from "react";
+import { useAtlasConfig } from "@/ui/context";
+
+export interface FetchError {
+  message: string;
+  status?: number;
+}
+
+/** Map HTTP status codes to user-friendly messages for admin pages. */
+export function friendlyError(err: FetchError): string {
+  if (err.status === 401) return "Not authenticated. Please sign in.";
+  if (err.status === 403)
+    return "Access denied. Admin role required to view this page.";
+  if (err.status === 404) return "This feature is not enabled on this server.";
+  return err.message;
+}
+
+/**
+ * Shared fetch hook for admin pages.
+ * Handles loading/error state, cancellation on unmount, and credentials.
+ */
+export function useAdminFetch<T>(
+  path: string,
+  opts?: {
+    deps?: unknown[];
+    transform?: (json: unknown) => T;
+  },
+) {
+  const { apiUrl, isCrossOrigin } = useAtlasConfig();
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<FetchError | null>(null);
+  const credentials: RequestCredentials = isCrossOrigin ? "include" : "same-origin";
+  const credentialsRef = useRef(credentials);
+  credentialsRef.current = credentials;
+
+  const fetchData = useCallback(async (signal?: AbortSignal) => {
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await fetch(`${apiUrl}${path}`, {
+        credentials: credentialsRef.current,
+        signal,
+      });
+      if (!res.ok) {
+        const e: FetchError = { message: `HTTP ${res.status}`, status: res.status };
+        if (!signal?.aborted) setError(e);
+        return;
+      }
+      const json = await res.json();
+      const result = opts?.transform ? opts.transform(json) : (json as T);
+      if (!signal?.aborted) setData(result);
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "AbortError") return;
+      if (!signal?.aborted) {
+        setError({
+          message: err instanceof Error ? err.message : "Request failed",
+        });
+      }
+    } finally {
+      if (!signal?.aborted) setLoading(false);
+    }
+  }, [apiUrl, path, ...(opts?.deps ?? [])]);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    fetchData(controller.signal);
+    return () => controller.abort();
+  }, [fetchData]);
+
+  const refetch = useCallback(() => {
+    fetchData();
+  }, [fetchData]);
+
+  return { data, loading, error, setError, refetch };
+}
+
+/**
+ * Returns `{ has, start, stop }` for tracking in-progress mutations by ID.
+ */
+export function useInProgressSet() {
+  const [set, setSet] = useState<Set<string>>(new Set());
+  return {
+    has: (id: string) => set.has(id),
+    start: (id: string) => setSet((prev) => new Set(prev).add(id)),
+    stop: (id: string) =>
+      setSet((prev) => {
+        const next = new Set(prev);
+        next.delete(id);
+        return next;
+      }),
+  };
+}
+
+/**
+ * Returns fetch options with correct credentials for admin API calls.
+ */
+export function useAdminFetchOpts() {
+  const { apiUrl, isCrossOrigin } = useAtlasConfig();
+  const credentials: RequestCredentials = isCrossOrigin ? "include" : "same-origin";
+  return { apiUrl, fetchOpts: { credentials } as RequestInit };
+}

package/templates/docker/src/ui/hooks/use-conversations.ts

@@ -0,0 +1,184 @@
+"use client";
+
+import { useState, useCallback, useRef } from "react";
+import type { Conversation, ConversationWithMessages, Message } from "../lib/types";
+import type { UIMessage } from "@ai-sdk/react";
+
+export interface UseConversationsOptions {
+  apiUrl: string;
+  enabled: boolean;
+  getHeaders: () => Record<string, string>;
+  getCredentials: () => RequestCredentials;
+}
+
+export interface UseConversationsReturn {
+  conversations: Conversation[];
+  total: number;
+  loading: boolean;
+  available: boolean;
+  selectedId: string | null;
+  setSelectedId: (id: string | null) => void;
+  fetchList: () => Promise<void>;
+  loadConversation: (id: string) => Promise<UIMessage[] | null>;
+  deleteConversation: (id: string) => Promise<boolean>;
+  starConversation: (id: string, starred: boolean) => Promise<boolean>;
+  refresh: () => Promise<void>;
+}
+
+export function transformMessages(messages: Message[]): UIMessage[] {
+  return messages
+    .filter((m) => m.role === "user" || m.role === "assistant")
+    .map((m) => {
+      const content = typeof m.content === "string"
+        ? m.content
+        : JSON.stringify(m.content);
+
+      return {
+        id: m.id,
+        role: m.role as "user" | "assistant",
+        parts: [{ type: "text" as const, text: content }],
+      };
+    });
+}
+
+export function useConversations(opts: UseConversationsOptions): UseConversationsReturn {
+  const [conversations, setConversations] = useState<Conversation[]>([]);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(false);
+  const [available, setAvailable] = useState(true);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const fetchedRef = useRef(false);
+
+  const fetchList = useCallback(async () => {
+    if (!opts.enabled || !available) return;
+    setLoading(true);
+    try {
+      const res = await fetch(`${opts.apiUrl}/api/v1/conversations?limit=50`, {
+        headers: opts.getHeaders(),
+        credentials: opts.getCredentials(),
+      });
+
+      if (res.status === 404) {
+        setAvailable(false);
+        return;
+      }
+
+      if (!res.ok) {
+        const body = await res.json().catch(() => null);
+        if (body?.code === "not_available") {
+          setAvailable(false);
+          return;
+        }
+        console.warn(`fetchList: HTTP ${res.status}`, body);
+        return;
+      }
+
+      const data = await res.json();
+      setConversations(data.conversations ?? []);
+      setTotal(data.total ?? 0);
+      fetchedRef.current = true;
+    } catch (err) {
+      console.warn("fetchList error:", err);
+      // Network error on first attempt — permanently disable conversations for this session. A page reload resets this.
+      if (!fetchedRef.current) setAvailable(false);
+    } finally {
+      setLoading(false);
+    }
+  }, [opts.apiUrl, opts.enabled, opts.getHeaders, opts.getCredentials, available]);
+
+  const loadConversation = useCallback(async (id: string): Promise<UIMessage[] | null> => {
+    try {
+      const res = await fetch(`${opts.apiUrl}/api/v1/conversations/${id}`, {
+        headers: opts.getHeaders(),
+        credentials: opts.getCredentials(),
+      });
+
+      if (!res.ok) {
+        console.warn(`loadConversation: HTTP ${res.status} for ${id}`);
+        return null;
+      }
+
+      const data: ConversationWithMessages = await res.json();
+      return transformMessages(data.messages);
+    } catch (err) {
+      console.warn("loadConversation error:", err);
+      return null;
+    }
+  }, [opts.apiUrl, opts.getHeaders, opts.getCredentials]);
+
+  const deleteConversation = useCallback(async (id: string): Promise<boolean> => {
+    try {
+      const res = await fetch(`${opts.apiUrl}/api/v1/conversations/${id}`, {
+        method: "DELETE",
+        headers: opts.getHeaders(),
+        credentials: opts.getCredentials(),
+      });
+
+      if (!res.ok) {
+        console.warn(`deleteConversation: HTTP ${res.status} for ${id}`);
+        return false;
+      }
+
+      setConversations((prev) => prev.filter((c) => c.id !== id));
+      setTotal((prev) => Math.max(0, prev - 1));
+
+      if (selectedId === id) setSelectedId(null);
+
+      return true;
+    } catch (err) {
+      console.warn("deleteConversation error:", err);
+      return false;
+    }
+  }, [opts.apiUrl, opts.getHeaders, opts.getCredentials, selectedId]);
+
+  const starConversation = useCallback(async (id: string, starred: boolean): Promise<boolean> => {
+    // Optimistic update
+    setConversations((prev) =>
+      prev.map((c) => (c.id === id ? { ...c, starred } : c)),
+    );
+    try {
+      const res = await fetch(`${opts.apiUrl}/api/v1/conversations/${id}/star`, {
+        method: "PATCH",
+        headers: { ...opts.getHeaders(), "Content-Type": "application/json" },
+        credentials: opts.getCredentials(),
+        body: JSON.stringify({ starred }),
+      });
+
+      if (!res.ok) {
+        console.warn(`starConversation: HTTP ${res.status} for ${id}`);
+        // Rollback
+        setConversations((prev) =>
+          prev.map((c) => (c.id === id ? { ...c, starred: !starred } : c)),
+        );
+        return false;
+      }
+
+      return true;
+    } catch (err) {
+      console.warn("starConversation error:", err);
+      // Rollback
+      setConversations((prev) =>
+        prev.map((c) => (c.id === id ? { ...c, starred: !starred } : c)),
+      );
+      return false;
+    }
+  }, [opts.apiUrl, opts.getHeaders, opts.getCredentials]);
+
+  const refresh = useCallback(async () => {
+    await fetchList();
+  }, [fetchList]);
+
+  return {
+    conversations,
+    total,
+    loading,
+    available,
+    selectedId,
+    setSelectedId,
+    fetchList,
+    loadConversation,
+    deleteConversation,
+    starConversation,
+    refresh,
+  };
+}

package/templates/docker/src/ui/hooks/use-dark-mode.ts

@@ -0,0 +1,17 @@
+"use client";
+
+import { createContext, useState, useEffect } from "react";
+
+export const DarkModeContext = createContext(false);
+
+export function useDarkMode() {
+  const [dark, setDark] = useState(false);
+  useEffect(() => {
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    setDark(mq.matches);
+    const handler = (e: MediaQueryListEvent) => setDark(e.matches);
+    mq.addEventListener("change", handler);
+    return () => mq.removeEventListener("change", handler);
+  }, []);
+  return dark;
+}

package/templates/docker/src/ui/lib/action-types.ts

@@ -0,0 +1,63 @@
+/** Status lifecycle for action tools that require user approval. */
+export type ActionStatus =
+  | "pending_approval"
+  | "approved"
+  | "executed"
+  | "auto_approved"
+  | "denied"
+  | "failed"
+  | "rolled_back"
+  | "timed_out";
+
+/** A status that is terminal (no longer pending). */
+export type ResolvedStatus = Exclude<ActionStatus, "pending_approval">;
+
+/** Single source of truth for every ActionStatus value. */
+export const ALL_STATUSES = [
+  "pending_approval",
+  "approved",
+  "executed",
+  "auto_approved",
+  "denied",
+  "failed",
+  "rolled_back",
+  "timed_out",
+] as const satisfies readonly ActionStatus[];
+
+/** All statuses that are terminal (no longer pending). */
+export const RESOLVED_STATUSES: ReadonlySet<ActionStatus> = new Set<ActionStatus>(
+  ALL_STATUSES.filter((s): s is ResolvedStatus => s !== "pending_approval"),
+);
+
+/** Shape returned by action tools in the tool result. */
+export interface ActionToolResultShape {
+  status: ActionStatus;
+  actionId: string;
+  summary?: string;
+  details?: Record<string, unknown>;
+  result?: unknown;
+  reason?: string;
+  error?: string;
+}
+
+/** API response when approving or denying an action. */
+export interface ActionApprovalResponse {
+  actionId: string;
+  status: ActionStatus;
+  result?: unknown;
+  error?: string;
+}
+
+/** All valid ActionStatus values (derived from ALL_STATUSES). */
+const VALID_STATUSES: ReadonlySet<ActionStatus> = new Set<ActionStatus>(ALL_STATUSES);
+
+/** Type guard: returns true if `result` looks like an action tool result. */
+export function isActionToolResult(result: unknown): result is ActionToolResultShape {
+  if (result == null || typeof result !== "object") return false;
+  const r = result as Record<string, unknown>;
+  return (
+    typeof r.actionId === "string" &&
+    typeof r.status === "string" &&
+    VALID_STATUSES.has(r.status as ActionStatus)
+  );
+}

package/templates/docker/src/ui/lib/helpers.ts

@@ -0,0 +1,104 @@
+/** Extract tool invocation input from a ToolUIPart. Returns empty object if unavailable. */
+export function getToolArgs(part: unknown): Record<string, unknown> {
+  if (part == null || typeof part !== "object") return {};
+  const input = (part as Record<string, unknown>).input;
+  if (input == null || typeof input !== "object") return {};
+  return input as Record<string, unknown>;
+}
+
+/** Extract tool output from a ToolUIPart. Returns null if not yet available. */
+export function getToolResult(part: unknown): unknown {
+  if (part == null || typeof part !== "object") return null;
+  return (part as Record<string, unknown>).output ?? null;
+}
+
+/** True when the tool invocation has finished successfully (state is "output-available"). */
+export function isToolComplete(part: unknown): boolean {
+  if (part == null || typeof part !== "object") return false;
+  return (part as Record<string, unknown>).state === "output-available";
+}
+
+/** Parse a CSV string into headers + rows. Handles basic quoting and escaped quotes (""). */
+export function parseCSV(csv: string): { headers: string[]; rows: string[][] } {
+  if (!csv || !csv.trim()) return { headers: [], rows: [] };
+
+  const lines = csv.trim().split("\n");
+  if (lines.length === 0) return { headers: [], rows: [] };
+
+  function parseLine(line: string): string[] {
+    const result: string[] = [];
+    let current = "";
+    let inQuotes = false;
+    for (let k = 0; k < line.length; k++) {
+      const char = line[k];
+      if (char === '"') {
+        if (inQuotes && line[k + 1] === '"') {
+          current += '"';
+          k++;
+        } else {
+          inQuotes = !inQuotes;
+        }
+      } else if (char === "," && !inQuotes) {
+        result.push(current.trim());
+        current = "";
+      } else {
+        current += char;
+      }
+    }
+    result.push(current.trim());
+    return result;
+  }
+
+  return {
+    headers: parseLine(lines[0]),
+    rows: lines
+      .slice(1)
+      .filter((l) => l.trim())
+      .map(parseLine),
+  };
+}
+
+/** Serialize columns + rows to a CSV string. Handles commas, quotes, and newlines in values. */
+export function toCsvString(columns: string[], rows: Record<string, unknown>[]): string {
+  const escape = (v: unknown) => {
+    const s = v == null ? "" : String(v);
+    return s.includes(",") || s.includes('"') || s.includes("\n")
+      ? `"${s.replace(/"/g, '""')}"`
+      : s;
+  };
+  const header = columns.map(escape).join(",");
+  const body = rows.map((row) => columns.map((col) => escape(row[col])).join(","));
+  return [header, ...body].join("\n");
+}
+
+/** Trigger a CSV download in the browser. */
+export function downloadCSV(csv: string, filename = "atlas-results.csv") {
+  let url: string | null = null;
+  try {
+    const blob = new Blob([csv], { type: "text/csv" });
+    url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = filename;
+    a.click();
+  } catch (err) {
+    console.error("CSV download failed:", err);
+    window.alert("CSV download failed");
+  } finally {
+    if (url) {
+      const blobUrl = url;
+      setTimeout(() => URL.revokeObjectURL(blobUrl), 10_000);
+    }
+  }
+}
+
+/** Format a cell value: null as em-dash, numbers with locale formatting, else stringified. */
+export function formatCell(value: unknown): string {
+  if (value == null) return "\u2014";
+  if (typeof value === "number") {
+    return Number.isInteger(value)
+      ? value.toLocaleString()
+      : value.toLocaleString(undefined, { maximumFractionDigits: 2 });
+  }
+  return String(value);
+}