@useatlas/create 0.0.6 → 0.0.7

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

@@ -1,8 +1,9 @@
 "use client";
 
-import { useState, useCallback, useRef } from "react";
-import type { Conversation, ConversationWithMessages, Message } from "../lib/types";
+import { useState, useCallback, useRef, useMemo } from "react";
+import type { Conversation, ConversationWithMessages, Message, ShareStatus, ShareMode, ShareExpiryKey, NotebookStateWire, ForkBranchWire } from "../lib/types";
 import type { UIMessage } from "@ai-sdk/react";
+import { createAtlasFetch } from "../lib/fetch-client";
 
 export interface UseConversationsOptions {
   apiUrl: string;
@@ -16,12 +17,19 @@ export interface UseConversationsReturn {
   total: number;
   loading: boolean;
   available: boolean;
+  fetchError: string | null;
   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>;
+  loadConversation: (id: string) => Promise<UIMessage[]>;
+  getConversationData: (id: string) => Promise<ConversationWithMessages>;
+  saveNotebookState: (id: string, state: NotebookStateWire) => Promise<void>;
+  forkConversation: (sourceId: string, forkPointMessageId: string, label?: string) => Promise<{ id: string; branches: ForkBranchWire[]; warning?: string }>;
+  deleteConversation: (id: string) => Promise<void>;
+  starConversation: (id: string, starred: boolean) => Promise<void>;
+  shareConversation: (id: string, opts?: { expiresIn?: ShareExpiryKey; shareMode?: ShareMode }) => Promise<{ token: string; url: string }>;
+  unshareConversation: (id: string) => Promise<void>;
+  getShareStatus: (id: string) => Promise<ShareStatus>;
   refresh: () => Promise<void>;
 }
 
@@ -29,34 +37,40 @@ export function transformMessages(messages: Message[]): UIMessage[] {
   return messages
     .filter((m) => m.role === "user" || m.role === "assistant")
     .map((m) => {
-      const content = typeof m.content === "string"
+      const parts: UIMessage["parts"] = Array.isArray(m.content)
         ? m.content
-        : JSON.stringify(m.content);
+            .filter((p: { type?: string }) => p.type === "text")
+            .map((p: { text?: string }) => ({ type: "text" as const, text: p.text ?? "" }))
+        : [{ type: "text" as const, text: String(m.content) }];
 
       return {
         id: m.id,
         role: m.role as "user" | "assistant",
-        parts: [{ type: "text" as const, text: content }],
+        parts,
       };
     });
 }
 
 export function useConversations(opts: UseConversationsOptions): UseConversationsReturn {
+  const api = useMemo(
+    () => createAtlasFetch(opts),
+    [opts.apiUrl, opts.getHeaders, opts.getCredentials],
+  );
+
   const [conversations, setConversations] = useState<Conversation[]>([]);
   const [total, setTotal] = useState(0);
   const [loading, setLoading] = useState(false);
   const [available, setAvailable] = useState(true);
+  const [fetchError, setFetchError] = useState<string | null>(null);
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const fetchedRef = useRef(false);
 
   const fetchList = useCallback(async () => {
     if (!opts.enabled || !available) return;
     setLoading(true);
+    setFetchError(null);
     try {
-      const res = await fetch(`${opts.apiUrl}/api/v1/conversations?limit=50`, {
-        headers: opts.getHeaders(),
-        credentials: opts.getCredentials(),
-      });
+      const res = await api.raw("GET", "/api/v1/conversations?limit=50");
 
       if (res.status === 404) {
         setAvailable(false);
@@ -64,12 +78,14 @@ export function useConversations(opts: UseConversationsOptions): UseConversation
       }
 
       if (!res.ok) {
+        // intentionally ignored: response may not be JSON
         const errorBody = await res.json().catch(() => null);
         if (errorBody?.code === "not_available") {
           setAvailable(false);
           return;
         }
         console.warn(`fetchList: HTTP ${res.status}`, errorBody);
+        setFetchError("Failed to load conversations. Please reload the page to try again.");
         return;
       }
 
@@ -77,92 +93,92 @@ export function useConversations(opts: UseConversationsOptions): UseConversation
       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);
+    } catch (err: unknown) {
+      console.warn("fetchList error:", err instanceof Error ? err.message : String(err));
+      setFetchError("Failed to load conversations. Please reload the page to try again.");
     } 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;
-      }
+  }, [api, opts.enabled, available]);
 
-      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 loadConversation = useCallback(async (id: string): Promise<UIMessage[]> => {
+    const data = await api.get<ConversationWithMessages>(`/api/v1/conversations/${id}`);
+    return transformMessages(data.messages);
+  }, [api]);
 
-  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 deleteConversation = useCallback(async (id: string): Promise<void> => {
+    await api.del(`/api/v1/conversations/${id}`);
+    setConversations((prev) => prev.filter((c) => c.id !== id));
+    setTotal((prev) => Math.max(0, prev - 1));
+    if (selectedId === id) setSelectedId(null);
+  }, [api, selectedId]);
 
-  const starConversation = useCallback(async (id: string, starred: boolean): Promise<boolean> => {
+  const starConversation = useCallback(async (id: string, starred: boolean): Promise<void> => {
     // 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
+      await api.patch(`/api/v1/conversations/${id}/star`, { starred });
+    } catch (err: unknown) {
       setConversations((prev) =>
         prev.map((c) => (c.id === id ? { ...c, starred: !starred } : c)),
       );
-      return false;
+      throw err;
+    }
+  }, [api]);
+
+  const shareConversation = useCallback(async (id: string, shareOpts?: { expiresIn?: ShareExpiryKey; shareMode?: ShareMode }): Promise<{ token: string; url: string }> => {
+    const data = await api.post<Record<string, unknown>>(`/api/v1/conversations/${id}/share`, shareOpts);
+    if (!data?.token || typeof data.token !== "string") {
+      console.warn(`shareConversation: missing token in response for ${id}`);
+      throw new Error("Share response missing token");
+    }
+    return {
+      token: data.token,
+      url: typeof data.url === "string" ? data.url : `${window.location.origin}/shared/${data.token}`,
+    };
+  }, [api]);
+
+  const unshareConversation = useCallback(async (id: string): Promise<void> => {
+    await api.del(`/api/v1/conversations/${id}/share`);
+  }, [api]);
+
+  const getShareStatus = useCallback(async (id: string): Promise<ShareStatus> => {
+    return api.get<ShareStatus>(`/api/v1/conversations/${id}/share`);
+  }, [api]);
+
+  const getConversationData = useCallback(async (id: string): Promise<ConversationWithMessages> => {
+    return api.get<ConversationWithMessages>(`/api/v1/conversations/${id}`);
+  }, [api]);
+
+  const saveNotebookState = useCallback(async (id: string, state: NotebookStateWire): Promise<void> => {
+    try {
+      await api.patch(`/api/v1/conversations/${id}/notebook-state`, state);
+    } catch (err: unknown) {
+      // Non-fatal — localStorage is still the backup
+      console.warn(
+        "saveNotebookState error:",
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }, [api]);
+
+  const forkConversation = useCallback(async (
+    sourceId: string,
+    forkPointMessageId: string,
+    label?: string,
+  ): Promise<{ id: string; branches: ForkBranchWire[]; warning?: string }> => {
+    const data = await api.post<Record<string, unknown>>(`/api/v1/conversations/${sourceId}/fork`, { forkPointMessageId, label });
+    if (!data.id || typeof data.id !== "string") {
+      throw new Error("Fork response missing conversation ID");
     }
-  }, [opts.apiUrl, opts.getHeaders, opts.getCredentials]);
+    return {
+      id: data.id,
+      branches: (data.branches ?? []) as ForkBranchWire[],
+      warning: typeof data.warning === "string" ? data.warning : undefined,
+    };
+  }, [api]);
 
   const refresh = useCallback(async () => {
     await fetchList();
@@ -173,12 +189,19 @@ export function useConversations(opts: UseConversationsOptions): UseConversation
     total,
     loading,
     available,
+    fetchError,
     selectedId,
     setSelectedId,
     fetchList,
     loadConversation,
+    getConversationData,
+    saveNotebookState,
+    forkConversation,
     deleteConversation,
     starConversation,
+    shareConversation,
+    unshareConversation,
+    getShareStatus,
     refresh,
   };
 }

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

@@ -2,23 +2,147 @@
 
 import { createContext, useSyncExternalStore } from "react";
 
-export const DarkModeContext = createContext(false);
+// ---------------------------------------------------------------------------
+// Theme types & constants
+// ---------------------------------------------------------------------------
+
+import { THEME_STORAGE_KEY } from "./theme-init-script";
+
+export type ThemeMode = "light" | "dark" | "system";
+
+/**
+ * Default brand color — must match `brand.css` `:root { --atlas-brand }` and
+ * the `ATLAS_BRAND_COLOR` default in `packages/api/src/lib/settings.ts`.
+ */
+export const DEFAULT_BRAND_COLOR = "oklch(0.759 0.148 167.71)";
+
+/** Basic oklch format check — prevents obviously invalid values from breaking the theme. */
+export const OKLCH_RE = /^oklch\(\s*[\d.]+\s+[\d.]+\s+[\d.]+\s*(?:\/\s*[\d.%]+\s*)?\)$/;
+
+// ---------------------------------------------------------------------------
+// Shared state — single source of truth for the chosen mode.
+// Listeners are notified on change so useSyncExternalStore re-renders.
+// ---------------------------------------------------------------------------
+
+let _mode: ThemeMode = "system";
+const _listeners = new Set<() => void>();
+
+function notify() {
+  for (const fn of _listeners) fn();
+}
+
+/** Read stored preference (called once on module load in the browser). */
+function init() {
+  try {
+    const stored = localStorage.getItem(THEME_STORAGE_KEY);
+    if (stored === "light" || stored === "dark" || stored === "system") {
+      _mode = stored;
+    }
+  } catch (err) {
+    console.warn("Could not read theme preference from localStorage:", err);
+  }
+}
+
+if (typeof window !== "undefined") init();
+
+// ---------------------------------------------------------------------------
+// Derived boolean: is the effective theme dark?
+// ---------------------------------------------------------------------------
+
+function systemPrefersDark(): boolean {
+  return typeof window !== "undefined" && window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+
+function resolveIsDark(mode: ThemeMode): boolean {
+  if (mode === "dark") return true;
+  if (mode === "light") return false;
+  return systemPrefersDark();
+}
+
+function applyClass(isDark: boolean) {
+  if (typeof document === "undefined") return;
+  document.documentElement.classList.toggle("dark", isDark);
+}
 
-/** SSR-safe snapshot: reads current prefers-color-scheme without hydration flicker. */
-function subscribeToColorScheme(onChange: () => void) {
+// ---------------------------------------------------------------------------
+// External store for isDark (reacts to both mode changes AND system changes)
+// ---------------------------------------------------------------------------
+
+function subscribeIsDark(onChange: () => void) {
+  _listeners.add(onChange);
+
+  // Also listen for system preference changes (relevant when mode === "system").
+  // Apply dark class immediately on OS change so the DOM stays in sync before React re-renders.
   const mq = window.matchMedia("(prefers-color-scheme: dark)");
-  mq.addEventListener("change", onChange);
-  return () => mq.removeEventListener("change", onChange);
+  const handler = () => {
+    applyClass(resolveIsDark(_mode));
+    onChange();
+  };
+  mq.addEventListener("change", handler);
+
+  return () => {
+    _listeners.delete(onChange);
+    mq.removeEventListener("change", handler);
+  };
 }
 
-function getSnapshot() {
-  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+function getSnapshotIsDark() {
+  return resolveIsDark(_mode);
 }
 
-function getServerSnapshot() {
+function getServerSnapshotIsDark() {
   return false;
 }
 
-export function useDarkMode() {
-  return useSyncExternalStore(subscribeToColorScheme, getSnapshot, getServerSnapshot);
+// ---------------------------------------------------------------------------
+// External store for mode
+// ---------------------------------------------------------------------------
+
+function subscribeMode(onChange: () => void) {
+  _listeners.add(onChange);
+  return () => {
+    _listeners.delete(onChange);
+  };
+}
+
+function getSnapshotMode() {
+  return _mode;
+}
+
+function getServerSnapshotMode(): ThemeMode {
+  return "system";
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function setTheme(mode: ThemeMode) {
+  _mode = mode;
+  const isDark = resolveIsDark(mode);
+  applyClass(isDark);
+  try {
+    localStorage.setItem(THEME_STORAGE_KEY, mode);
+  } catch (err) {
+    console.warn("Could not persist theme preference to localStorage:", err);
+  }
+  notify();
+}
+
+/** Apply --atlas-brand on :root so theme tokens update without reload. */
+export function applyBrandColor(color: string) {
+  if (typeof document === "undefined") return;
+  document.documentElement.style.setProperty("--atlas-brand", color);
+}
+
+export const DarkModeContext = createContext(false);
+
+/** Returns whether the effective theme is dark. */
+export function useDarkMode(): boolean {
+  return useSyncExternalStore(subscribeIsDark, getSnapshotIsDark, getServerSnapshotIsDark);
+}
+
+/** Returns the current ThemeMode ("light" | "dark" | "system"). */
+export function useThemeMode(): ThemeMode {
+  return useSyncExternalStore(subscribeMode, getSnapshotMode, getServerSnapshotMode);
 }

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

@@ -0,0 +1,36 @@
+"use client";
+
+import { useAdminFetch, type FetchError } from "@/ui/hooks/use-admin-fetch";
+import type { DeployMode } from "@/ui/lib/types";
+
+interface SettingsResponse {
+  settings: unknown[];
+  manageable: boolean;
+  deployMode: DeployMode;
+}
+
+/**
+ * Returns the resolved deploy mode from the admin settings API.
+ *
+ * Fetches from `/api/v1/admin/settings` and extracts the `deployMode` field.
+ * Defaults to `"self-hosted"` while loading or on error. Exposes the error
+ * so consumers can detect when the fallback is due to a fetch failure
+ * (e.g., expired session) rather than an actual self-hosted deployment.
+ */
+export function useDeployMode(): {
+  deployMode: DeployMode;
+  loading: boolean;
+  error: FetchError | null;
+} {
+  const { data, loading, error } = useAdminFetch<SettingsResponse>("/api/v1/admin/settings");
+
+  if (error) {
+    console.warn("useDeployMode: failed to fetch deploy mode, defaulting to self-hosted:", error);
+  }
+
+  return {
+    deployMode: data?.deployMode ?? "self-hosted",
+    loading,
+    error,
+  };
+}

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

@@ -0,0 +1,49 @@
+"use client";
+
+import { useEffect } from "react";
+import { useRouter } from "next/navigation";
+import { useAtlasConfig } from "@/ui/context";
+
+/**
+ * Returns the user's role from the Better Auth session.
+ * Used by the sidebar for item-level visibility and by page guards.
+ *
+ * Better Auth's public session type doesn't include `role` on the user object
+ * (it's added by the admin/organization plugins at runtime), so we cast through
+ * `Record<string, unknown>` to access it. This is the single source of truth
+ * for role extraction — all call sites should use this hook rather than
+ * duplicating the cast.
+ */
+export function useUserRole(): string | undefined {
+  const { authClient } = useAtlasConfig();
+  const session = authClient.useSession();
+  return (session.data?.user as Record<string, unknown> | undefined)?.role as
+    | string
+    | undefined;
+}
+
+/**
+ * Redirects non-platform-admin users to /admin.
+ *
+ * Call at the top of any page component that should be restricted to
+ * platform admins only. Returns `true` while the role is still loading
+ * or a redirect is in progress — the caller should render nothing (or a
+ * loading spinner) until it returns `false`.
+ */
+export function usePlatformAdminGuard(): { blocked: boolean } {
+  const role = useUserRole();
+  const { authClient } = useAtlasConfig();
+  const isPending = authClient.useSession().isPending;
+  const router = useRouter();
+
+  useEffect(() => {
+    if (isPending) return;
+    if (role !== "platform_admin") {
+      router.replace("/admin");
+    }
+  }, [isPending, role, router]);
+
+  // Block rendering while pending or when the user is not platform_admin
+  const blocked = isPending === true || role !== "platform_admin";
+  return { blocked };
+}

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

@@ -1,63 +1,11 @@
-/** 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)
-  );
-}
+export {
+  ALL_STATUSES,
+  RESOLVED_STATUSES,
+  isActionToolResult,
+} from "@useatlas/types/action";
+export type {
+  ActionDisplayStatus,
+  ResolvedDisplayStatus,
+  ActionToolResultShape,
+  ActionApprovalResponse,
+} from "@useatlas/types/action";