@useatlas/create 0.0.5 → 0.0.7

package/templates/nextjs-standalone/src/config/data-table.ts

@@ -0,0 +1,82 @@
+export type DataTableConfig = typeof dataTableConfig;
+
+export const dataTableConfig = {
+  textOperators: [
+    { label: "Contains", value: "iLike" as const },
+    { label: "Does not contain", value: "notILike" as const },
+    { label: "Is", value: "eq" as const },
+    { label: "Is not", value: "ne" as const },
+    { label: "Is empty", value: "isEmpty" as const },
+    { label: "Is not empty", value: "isNotEmpty" as const },
+  ],
+  numericOperators: [
+    { label: "Is", value: "eq" as const },
+    { label: "Is not", value: "ne" as const },
+    { label: "Is less than", value: "lt" as const },
+    { label: "Is less than or equal to", value: "lte" as const },
+    { label: "Is greater than", value: "gt" as const },
+    { label: "Is greater than or equal to", value: "gte" as const },
+    { label: "Is between", value: "isBetween" as const },
+    { label: "Is empty", value: "isEmpty" as const },
+    { label: "Is not empty", value: "isNotEmpty" as const },
+  ],
+  dateOperators: [
+    { label: "Is", value: "eq" as const },
+    { label: "Is not", value: "ne" as const },
+    { label: "Is before", value: "lt" as const },
+    { label: "Is after", value: "gt" as const },
+    { label: "Is on or before", value: "lte" as const },
+    { label: "Is on or after", value: "gte" as const },
+    { label: "Is between", value: "isBetween" as const },
+    { label: "Is relative to today", value: "isRelativeToToday" as const },
+    { label: "Is empty", value: "isEmpty" as const },
+    { label: "Is not empty", value: "isNotEmpty" as const },
+  ],
+  selectOperators: [
+    { label: "Is", value: "eq" as const },
+    { label: "Is not", value: "ne" as const },
+    { label: "Is empty", value: "isEmpty" as const },
+    { label: "Is not empty", value: "isNotEmpty" as const },
+  ],
+  multiSelectOperators: [
+    { label: "Has any of", value: "inArray" as const },
+    { label: "Has none of", value: "notInArray" as const },
+    { label: "Is empty", value: "isEmpty" as const },
+    { label: "Is not empty", value: "isNotEmpty" as const },
+  ],
+  booleanOperators: [
+    { label: "Is", value: "eq" as const },
+    { label: "Is not", value: "ne" as const },
+  ],
+  sortOrders: [
+    { label: "Asc", value: "asc" as const },
+    { label: "Desc", value: "desc" as const },
+  ],
+  filterVariants: [
+    "text",
+    "number",
+    "range",
+    "date",
+    "dateRange",
+    "boolean",
+    "select",
+    "multiSelect",
+  ] as const,
+  operators: [
+    "iLike",
+    "notILike",
+    "eq",
+    "ne",
+    "inArray",
+    "notInArray",
+    "isEmpty",
+    "isNotEmpty",
+    "lt",
+    "lte",
+    "gt",
+    "gte",
+    "isBetween",
+    "isRelativeToToday",
+  ] as const,
+  joinOperators: ["and", "or"] as const,
+};

package/templates/nextjs-standalone/src/env-check.ts

@@ -0,0 +1,74 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as p from "@clack/prompts";
+
+/** Commands that require a configured .env file for normal operation. */
+export const ENV_COMMANDS = new Set([
+  "init",
+  "diff",
+  "query",
+  "doctor",
+  "validate",
+  "mcp",
+  "migrate",
+]);
+
+/**
+ * Check for missing .env file and offer to copy from .env.example.
+ * Skips silently if neither file exists (embedded deploy).
+ * In non-TTY environments, logs a warning instead of prompting.
+ *
+ * This is an advisory check — filesystem errors are caught and logged
+ * as warnings so the CLI command can still proceed.
+ */
+export async function checkEnvFile(command: string | undefined): Promise<void> {
+  if (!command || !ENV_COMMANDS.has(command)) return;
+
+  let envPath: string;
+  let examplePath: string;
+
+  try {
+    envPath = path.join(process.cwd(), ".env");
+    examplePath = path.join(process.cwd(), ".env.example");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    p.log.warn(`Could not check for .env file: ${msg}`);
+    return;
+  }
+
+  if (fs.existsSync(envPath)) return;
+  if (!fs.existsSync(examplePath)) return;
+
+  // Non-interactive (CI, piped): warn but don't block execution
+  if (!process.stdin.isTTY) {
+    p.log.warn(
+      "No .env file found. Copy .env.example to .env and configure it.",
+    );
+    return;
+  }
+
+  const shouldCopy = await p.confirm({
+    message: "No .env file found. Copy from .env.example?",
+    initialValue: true,
+  });
+
+  if (p.isCancel(shouldCopy)) {
+    p.cancel("Operation cancelled.");
+    process.exit(0);
+  }
+
+  if (shouldCopy) {
+    try {
+      // COPYFILE_EXCL prevents overwriting if .env was created concurrently
+      fs.copyFileSync(examplePath, envPath, fs.constants.COPYFILE_EXCL);
+      p.log.success(
+        "Created .env — edit it with your database URL and API key.",
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      p.log.warn(
+        `Could not copy .env.example to .env: ${msg}\nCopy it manually: cp .env.example .env`,
+      );
+    }
+  }
+}

package/templates/nextjs-standalone/src/hooks/use-callback-ref.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+
+/**
+ * @see https://github.com/radix-ui/primitives/blob/main/packages/react/use-callback-ref/src/useCallbackRef.tsx
+ */
+
+/**
+ * A custom hook that converts a callback to a ref to avoid triggering re-renders when passed as a
+ * prop or avoid re-executing effects when passed as a dependency
+ */
+function useCallbackRef<T extends (...args: never[]) => unknown>(
+  callback: T | undefined,
+): T {
+  const callbackRef = React.useRef(callback);
+
+  React.useEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  // https://github.com/facebook/react/issues/19240
+  return React.useMemo(
+    () => ((...args) => callbackRef.current?.(...args)) as T,
+    [],
+  );
+}
+
+export { useCallbackRef };

package/templates/nextjs-standalone/src/hooks/use-data-table.ts

@@ -0,0 +1,316 @@
+import {
+  type ColumnFiltersState,
+  getCoreRowModel,
+  getFacetedMinMaxValues,
+  getFacetedRowModel,
+  getFacetedUniqueValues,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  type PaginationState,
+  type RowSelectionState,
+  type SortingState,
+  type TableOptions,
+  type TableState,
+  type Updater,
+  useReactTable,
+  type VisibilityState,
+} from "@tanstack/react-table";
+import {
+  parseAsArrayOf,
+  parseAsInteger,
+  parseAsString,
+  type SingleParser,
+  type UseQueryStateOptions,
+  useQueryState,
+  useQueryStates,
+} from "nuqs";
+import * as React from "react";
+
+import { useDebouncedCallback } from "@/hooks/use-debounced-callback";
+import { getSortingStateParser } from "@/lib/parsers";
+import type { ExtendedColumnSort, QueryKeys } from "@/types/data-table";
+
+const PAGE_KEY = "page";
+const PER_PAGE_KEY = "perPage";
+const SORT_KEY = "sort";
+const FILTERS_KEY = "filters";
+const JOIN_OPERATOR_KEY = "joinOperator";
+const ARRAY_SEPARATOR = ",";
+const DEBOUNCE_MS = 300;
+const THROTTLE_MS = 50;
+
+interface UseDataTableProps<TData>
+  extends Omit<
+      TableOptions<TData>,
+      | "state"
+      | "pageCount"
+      | "getCoreRowModel"
+      | "manualFiltering"
+      | "manualPagination"
+      | "manualSorting"
+    >,
+    Required<Pick<TableOptions<TData>, "pageCount">> {
+  initialState?: Omit<Partial<TableState>, "sorting"> & {
+    sorting?: ExtendedColumnSort<TData>[];
+  };
+  queryKeys?: Partial<QueryKeys>;
+  history?: "push" | "replace";
+  debounceMs?: number;
+  throttleMs?: number;
+  clearOnDefault?: boolean;
+  enableAdvancedFilter?: boolean;
+  scroll?: boolean;
+  shallow?: boolean;
+  startTransition?: React.TransitionStartFunction;
+}
+
+export function useDataTable<TData>(props: UseDataTableProps<TData>) {
+  const {
+    columns,
+    pageCount = -1,
+    initialState,
+    queryKeys,
+    history = "replace",
+    debounceMs = DEBOUNCE_MS,
+    throttleMs = THROTTLE_MS,
+    clearOnDefault = false,
+    enableAdvancedFilter = false,
+    scroll = false,
+    shallow = true,
+    startTransition,
+    ...tableProps
+  } = props;
+  const pageKey = queryKeys?.page ?? PAGE_KEY;
+  const perPageKey = queryKeys?.perPage ?? PER_PAGE_KEY;
+  const sortKey = queryKeys?.sort ?? SORT_KEY;
+  const filtersKey = queryKeys?.filters ?? FILTERS_KEY;
+  const joinOperatorKey = queryKeys?.joinOperator ?? JOIN_OPERATOR_KEY;
+
+  const queryStateOptions = React.useMemo<
+    Omit<UseQueryStateOptions<string>, "parse">
+  >(
+    () => ({
+      history,
+      scroll,
+      shallow,
+      throttleMs,
+      debounceMs,
+      clearOnDefault,
+      startTransition,
+    }),
+    [
+      history,
+      scroll,
+      shallow,
+      throttleMs,
+      debounceMs,
+      clearOnDefault,
+      startTransition,
+    ],
+  );
+
+  const [rowSelection, setRowSelection] = React.useState<RowSelectionState>(
+    initialState?.rowSelection ?? {},
+  );
+  const [columnVisibility, setColumnVisibility] =
+    React.useState<VisibilityState>(initialState?.columnVisibility ?? {});
+
+  const [page, setPage] = useQueryState(
+    pageKey,
+    parseAsInteger.withOptions(queryStateOptions).withDefault(1),
+  );
+  const [perPage, setPerPage] = useQueryState(
+    perPageKey,
+    parseAsInteger
+      .withOptions(queryStateOptions)
+      .withDefault(initialState?.pagination?.pageSize ?? 10),
+  );
+
+  const pagination: PaginationState = React.useMemo(() => {
+    return {
+      pageIndex: page - 1, // zero-based index -> one-based index
+      pageSize: perPage,
+    };
+  }, [page, perPage]);
+
+  const onPaginationChange = React.useCallback(
+    (updaterOrValue: Updater<PaginationState>) => {
+      if (typeof updaterOrValue === "function") {
+        const newPagination = updaterOrValue(pagination);
+        void setPage(newPagination.pageIndex + 1);
+        void setPerPage(newPagination.pageSize);
+      } else {
+        void setPage(updaterOrValue.pageIndex + 1);
+        void setPerPage(updaterOrValue.pageSize);
+      }
+    },
+    [pagination, setPage, setPerPage],
+  );
+
+  const columnIds = React.useMemo(() => {
+    return new Set(
+      columns.map((column) => column.id).filter(Boolean) as string[],
+    );
+  }, [columns]);
+
+  const [sorting, setSorting] = useQueryState(
+    sortKey,
+    getSortingStateParser<TData>(columnIds)
+      .withOptions(queryStateOptions)
+      .withDefault(initialState?.sorting ?? []),
+  );
+
+  const onSortingChange = React.useCallback(
+    (updaterOrValue: Updater<SortingState>) => {
+      if (typeof updaterOrValue === "function") {
+        const newSorting = updaterOrValue(sorting);
+        setSorting(newSorting as ExtendedColumnSort<TData>[]);
+      } else {
+        setSorting(updaterOrValue as ExtendedColumnSort<TData>[]);
+      }
+    },
+    [sorting, setSorting],
+  );
+
+  const filterableColumns = React.useMemo(() => {
+    if (enableAdvancedFilter) return [];
+
+    return columns.filter((column) => column.enableColumnFilter);
+  }, [columns, enableAdvancedFilter]);
+
+  const filterParsers = React.useMemo(() => {
+    if (enableAdvancedFilter) return {};
+
+    return filterableColumns.reduce<
+      Record<string, SingleParser<string> | SingleParser<string[]>>
+    >((acc, column) => {
+      if (column.meta?.options) {
+        acc[column.id ?? ""] = parseAsArrayOf(
+          parseAsString,
+          ARRAY_SEPARATOR,
+        ).withOptions(queryStateOptions);
+      } else {
+        acc[column.id ?? ""] = parseAsString.withOptions(queryStateOptions);
+      }
+      return acc;
+    }, {});
+  }, [filterableColumns, queryStateOptions, enableAdvancedFilter]);
+
+  const [filterValues, setFilterValues] = useQueryStates(filterParsers);
+
+  const debouncedSetFilterValues = useDebouncedCallback(
+    (values: typeof filterValues) => {
+      void setPage(1);
+      void setFilterValues(values);
+    },
+    debounceMs,
+  );
+
+  const initialColumnFilters: ColumnFiltersState = React.useMemo(() => {
+    if (enableAdvancedFilter) return [];
+
+    return Object.entries(filterValues).reduce<ColumnFiltersState>(
+      (filters, [key, value]) => {
+        if (value !== null) {
+          const processedValue = Array.isArray(value)
+            ? value
+            : typeof value === "string" && /[^a-zA-Z0-9]/.test(value)
+              ? value.split(/[^a-zA-Z0-9]+/).filter(Boolean)
+              : [value];
+
+          filters.push({
+            id: key,
+            value: processedValue,
+          });
+        }
+        return filters;
+      },
+      [],
+    );
+  }, [filterValues, enableAdvancedFilter]);
+
+  const [columnFilters, setColumnFilters] =
+    React.useState<ColumnFiltersState>(initialColumnFilters);
+
+  const onColumnFiltersChange = React.useCallback(
+    (updaterOrValue: Updater<ColumnFiltersState>) => {
+      if (enableAdvancedFilter) return;
+
+      setColumnFilters((prev) => {
+        const next =
+          typeof updaterOrValue === "function"
+            ? updaterOrValue(prev)
+            : updaterOrValue;
+
+        const filterUpdates = next.reduce<
+          Record<string, string | string[] | null>
+        >((acc, filter) => {
+          if (filterableColumns.find((column) => column.id === filter.id)) {
+            acc[filter.id] = filter.value as string | string[];
+          }
+          return acc;
+        }, {});
+
+        for (const prevFilter of prev) {
+          if (!next.some((filter) => filter.id === prevFilter.id)) {
+            filterUpdates[prevFilter.id] = null;
+          }
+        }
+
+        debouncedSetFilterValues(filterUpdates);
+        return next;
+      });
+    },
+    [debouncedSetFilterValues, filterableColumns, enableAdvancedFilter],
+  );
+
+  const table = useReactTable({
+    ...tableProps,
+    columns,
+    initialState,
+    pageCount,
+    state: {
+      pagination,
+      sorting,
+      columnVisibility,
+      rowSelection,
+      columnFilters,
+    },
+    defaultColumn: {
+      ...tableProps.defaultColumn,
+      enableColumnFilter: false,
+    },
+    enableRowSelection: true,
+    onRowSelectionChange: setRowSelection,
+    onPaginationChange,
+    onSortingChange,
+    onColumnFiltersChange,
+    onColumnVisibilityChange: setColumnVisibility,
+    getCoreRowModel: getCoreRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getFacetedRowModel: getFacetedRowModel(),
+    getFacetedUniqueValues: getFacetedUniqueValues(),
+    getFacetedMinMaxValues: getFacetedMinMaxValues(),
+    manualPagination: true,
+    manualSorting: true,
+    manualFiltering: true,
+    meta: {
+      ...tableProps.meta,
+      queryKeys: {
+        page: pageKey,
+        perPage: perPageKey,
+        sort: sortKey,
+        filters: filtersKey,
+        joinOperator: joinOperatorKey,
+      },
+    },
+  });
+
+  return React.useMemo(
+    () => ({ table, shallow, debounceMs, throttleMs }),
+    [table, shallow, debounceMs, throttleMs],
+  );
+}

package/templates/nextjs-standalone/src/hooks/use-debounced-callback.ts

@@ -0,0 +1,28 @@
+import * as React from "react";
+
+import { useCallbackRef } from "@/hooks/use-callback-ref";
+
+export function useDebouncedCallback<T extends (...args: never[]) => unknown>(
+  callback: T,
+  delay: number,
+) {
+  const handleCallback = useCallbackRef(callback);
+  const debounceTimerRef = React.useRef(0);
+  React.useEffect(
+    () => () => window.clearTimeout(debounceTimerRef.current),
+    [],
+  );
+
+  const setValue = React.useCallback(
+    (...args: Parameters<T>) => {
+      window.clearTimeout(debounceTimerRef.current);
+      debounceTimerRef.current = window.setTimeout(
+        () => handleCallback(...args),
+        delay,
+      );
+    },
+    [handleCallback, delay],
+  );
+
+  return setValue;
+}

package/templates/nextjs-standalone/src/lib/action-types.ts

@@ -1,26 +1,17 @@
 /**
  * Action types for Atlas.
  *
- * ActionApprovalMode determines how an action request is handled.
- * ActionStatus tracks the lifecycle of an action request.
+ * ActionApprovalMode is re-exported from @useatlas/types/action.
+ * ActionStatus tracks the server-internal lifecycle of an action request.
  * ActionRequest and ActionToolResult provide the tool-level interface.
  * AtlasAction extends the structural tool interface with action metadata.
  * ActionLogEntry represents the persisted audit row.
  */
 
-export const ACTION_APPROVAL_MODES = ["auto", "manual", "admin-only"] as const;
-export type ActionApprovalMode = (typeof ACTION_APPROVAL_MODES)[number];
+export { ACTION_APPROVAL_MODES, ACTION_STATUSES } from "@useatlas/types/action";
+export type { ActionApprovalMode, ActionStatus, ActionLogEntry, RollbackInfo } from "@useatlas/types/action";
 
-export const ACTION_STATUSES = [
-  "pending",
-  "approved",
-  "denied",
-  "executed",
-  "failed",
-  "timed_out", // Reserved — not yet implemented
-  "auto_approved",
-] as const;
-export type ActionStatus = (typeof ACTION_STATUSES)[number];
+import type { ActionApprovalMode } from "@useatlas/types/action";
 
 /** Describes the action the agent wants to perform. */
 export interface ActionRequest {
@@ -32,19 +23,14 @@ export interface ActionRequest {
   reversible: boolean;
 }
 
-/** Information needed to undo an executed action. */
-export interface RollbackInfo {
-  method: string;
-  params: Record<string, unknown>;
-}
-
 /** Discriminated union returned by action tools to the agent loop. */
 export type ActionToolResult =
   | { status: "pending_approval"; actionId: string; summary: string }
   | { status: "executed"; actionId: string; result: unknown }
   | { status: "denied"; actionId: string; reason?: string }
   | { status: "auto_approved"; actionId: string; result: unknown }
-  | { status: "error"; actionId?: string; error: string };
+  | { status: "failed"; actionId?: string; error: string }
+  | { status: "timed_out"; actionId: string; error: string };
 
 /**
  * Structural superset of AtlasTool with action-specific metadata.
@@ -73,23 +59,3 @@ export function isAction(tool: { readonly name: string }): tool is AtlasAction {
   );
 }
 
-/** Database row shape for the action_log table. */
-export interface ActionLogEntry {
-  id: string;
-  requested_at: string;
-  resolved_at: string | null;
-  executed_at: string | null;
-  requested_by: string | null;
-  approved_by: string | null;
-  auth_mode: string;
-  action_type: string;
-  target: string;
-  summary: string;
-  payload: Record<string, unknown>;
-  status: ActionStatus;
-  result: unknown;
-  error: string | null;
-  rollback_info: RollbackInfo | null;
-  conversation_id: string | null;
-  request_id: string | null;
-}

package/templates/nextjs-standalone/src/lib/agent-query.ts

@@ -36,7 +36,7 @@ export interface AgentQueryResult {
 export async function executeAgentQuery(
   question: string,
   requestId?: string,
-  options?: { priorMessages?: Array<{ role: "user" | "assistant"; content: string }> },
+  options?: { priorMessages?: Array<{ role: "user" | "assistant"; content: string }>; conversationId?: string },
 ): Promise<AgentQueryResult> {
   const id = requestId ?? crypto.randomUUID();
 
@@ -64,7 +64,8 @@ export async function executeAgentQuery(
         const { buildRegistry } = await import(
           "@atlas/api/lib/tools/registry"
         );
-        toolRegistry = await buildRegistry({ includeActions });
+        const result = await buildRegistry({ includeActions });
+        toolRegistry = result.registry;
       } catch (err) {
         log.error(
           { err: err instanceof Error ? err : new Error(String(err)) },
@@ -76,6 +77,7 @@ export async function executeAgentQuery(
     const result = await runAgent({
       messages,
       ...(toolRegistry && { tools: toolRegistry }),
+      ...(options?.conversationId && { conversationId: options.conversationId }),
     });
 
     const [text, steps, totalUsage] = await Promise.all([