@useatlas/create 0.0.5 → 0.0.7

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

@@ -35,9 +35,9 @@ export function getRequestContext(): RequestContext | undefined {
 
 const isDev = process.env.NODE_ENV !== "production";
 
-// Redaction covers top-level fields and one-level nested (*.field) plus
-// array element access ([*].field). fast-redact does not support ** glob
-// wildcards, so deeper nesting would require additional explicit paths.
+// Redaction covers top-level fields, one-level nested (*.field), array
+// element access ([*].field), and known deep structures. fast-redact does
+// not support ** glob wildcards, so deep paths must be listed explicitly.
 export const redactPaths = [
   "connectionString",
   "databaseUrl",
@@ -45,18 +45,33 @@ export const redactPaths = [
   "password",
   "secret",
   "authorization",
+  "url",
   "*.connectionString",
   "*.databaseUrl",
   "*.apiKey",
   "*.password",
   "*.secret",
   "*.authorization",
+  "*.url",
   "[*].connectionString",
   "[*].databaseUrl",
   "[*].apiKey",
   "[*].password",
   "[*].secret",
   "[*].authorization",
+  "[*].url",
+  // Deep structures: datasource config, connection registry, plugin config
+  "datasources.*.url",
+  "datasources.*.connectionString",
+  "datasources.*.password",
+  "config.datasources.*.url",
+  "config.datasources.*.connectionString",
+  "connection.url",
+  "connection.connectionString",
+  "connection.password",
+  "connections.*.url",
+  "connections.*.connectionString",
+  "connections.*.password",
 ];
 
 const rootLogger = pino({
@@ -96,3 +111,20 @@ export function getLogger(): pino.Logger {
 export function createLogger(component: string): pino.Logger {
   return rootLogger.child({ component });
 }
+
+const VALID_LOG_LEVELS = new Set(["trace", "debug", "info", "warn", "error", "fatal"]);
+
+/**
+ * Update the root logger level at runtime.
+ *
+ * Used by the settings hot-reload system to apply ATLAS_LOG_LEVEL changes
+ * in SaaS mode without a server restart. Pino propagates the level change
+ * to all child loggers automatically.
+ *
+ * @returns true if the level was applied, false if the level is invalid.
+ */
+export function setLogLevel(level: string): boolean {
+  if (!VALID_LOG_LEVELS.has(level)) return false;
+  rootLogger.level = level;
+  return true;
+}

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

@@ -0,0 +1,272 @@
+/**
+ * Usage metering helpers.
+ *
+ * Provides event logging and aggregate rollup for per-workspace usage
+ * tracking. Events are recorded to usage_events; summaries are
+ * materialized into usage_summaries on demand.
+ *
+ * Two write strategies:
+ * - `logUsageEvent` is fire-and-forget via `internalExecute` — async
+ *   errors are handled by internalExecute's circuit-breaker `.catch`.
+ * - `aggregateUsageSummary` awaits the query but swallows errors.
+ * In both cases, metering failures never propagate to the caller.
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+import {
+  hasInternalDB,
+  internalExecute,
+  internalQuery,
+} from "@atlas/api/lib/db/internal";
+
+const log = createLogger("metering");
+
+// ---------------------------------------------------------------------------
+// Event types
+// ---------------------------------------------------------------------------
+
+// NOTE: "login" events are not yet emitted — active_users will be 0
+// until auth hooks emit login events. Query and token events are
+// emitted from the agent loop's onFinish callback.
+export type UsageEventType = "query" | "token" | "login";
+
+export interface UsageEvent {
+  workspaceId: string | null;
+  userId: string | null;
+  eventType: UsageEventType;
+  quantity: number;
+  metadata?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Event logging (fire-and-forget)
+// ---------------------------------------------------------------------------
+
+/**
+ * Log a usage event. Fire-and-forget — async errors are handled by
+ * internalExecute's circuit-breaker. No-op if internal DB is not configured.
+ */
+export function logUsageEvent(event: UsageEvent): void {
+  if (!hasInternalDB()) return;
+
+  // Error handling is delegated to internalExecute's .catch handler,
+  // which logs failures with SQL context and trips the circuit breaker
+  // after 5 consecutive failures. No try/catch needed here — hasInternalDB()
+  // guards against the only synchronous throw path (DATABASE_URL unset).
+  internalExecute(
+    `INSERT INTO usage_events (workspace_id, user_id, event_type, quantity, metadata)
+     VALUES ($1, $2, $3, $4, $5)`,
+    [
+      event.workspaceId ?? null,
+      event.userId ?? null,
+      event.eventType,
+      event.quantity,
+      event.metadata ? JSON.stringify(event.metadata) : null,
+    ],
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Aggregation
+// ---------------------------------------------------------------------------
+
+/**
+ * Aggregate usage events into a summary row for the given workspace and period.
+ * Uses atomic upsert (ON CONFLICT ... DO UPDATE) for concurrent safety.
+ *
+ * @param workspaceId - The workspace/org to aggregate for.
+ * @param period - "daily" or "monthly".
+ * @param periodStart - The start of the period (truncated to day/month).
+ */
+export async function aggregateUsageSummary(
+  workspaceId: string,
+  period: "daily" | "monthly",
+  periodStart: Date,
+): Promise<void> {
+  if (!hasInternalDB()) return;
+
+  const periodStartISO = periodStart.toISOString();
+  const interval = period === "daily" ? "1 day" : "1 month";
+
+  try {
+    await internalQuery(
+      `INSERT INTO usage_summaries (workspace_id, period, period_start, query_count, token_count, active_users, storage_bytes)
+       SELECT
+         $1,
+         $2,
+         $3::timestamptz,
+         COALESCE(SUM(CASE WHEN event_type = 'query' THEN quantity ELSE 0 END), 0),
+         COALESCE(SUM(CASE WHEN event_type = 'token' THEN quantity ELSE 0 END), 0),
+         COALESCE(COUNT(DISTINCT CASE WHEN event_type = 'login' THEN user_id END), 0),
+         0
+       FROM usage_events
+       WHERE workspace_id = $1
+         AND created_at >= $3::timestamptz
+         AND created_at < $3::timestamptz + $4::interval
+       ON CONFLICT (workspace_id, period, period_start) DO UPDATE SET
+         query_count = EXCLUDED.query_count,
+         token_count = EXCLUDED.token_count,
+         active_users = EXCLUDED.active_users,
+         updated_at = now()`,
+      [workspaceId, period, periodStartISO, interval],
+    );
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err), workspaceId, period },
+      "Failed to aggregate usage summary",
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Query helpers (for admin API)
+// ---------------------------------------------------------------------------
+
+export interface UsageSummaryRow {
+  id: string;
+  workspace_id: string;
+  period: string;
+  period_start: string;
+  query_count: number;
+  token_count: number;
+  active_users: number;
+  storage_bytes: number;
+  updated_at: string;
+  [key: string]: unknown;
+}
+
+export interface UsageCurrentPeriod {
+  queryCount: number;
+  tokenCount: number;
+  activeUsers: number;
+  periodStart: string;
+  periodEnd: string;
+}
+
+/**
+ * Get the current period summary for a workspace by querying usage_events
+ * directly (real-time, not from pre-aggregated summaries).
+ */
+export async function getCurrentPeriodUsage(
+  workspaceId: string,
+): Promise<UsageCurrentPeriod> {
+  if (!hasInternalDB()) {
+    return { queryCount: 0, tokenCount: 0, activeUsers: 0, periodStart: "", periodEnd: "" };
+  }
+
+  const now = new Date();
+  const periodStart = new Date(now.getFullYear(), now.getMonth(), 1);
+  const periodEnd = new Date(now.getFullYear(), now.getMonth() + 1, 1);
+
+  const rows = await internalQuery<{
+    query_count: number;
+    token_count: number;
+    active_users: number;
+  }>(
+    `SELECT
+       COALESCE(SUM(CASE WHEN event_type = 'query' THEN quantity ELSE 0 END), 0)::int AS query_count,
+       COALESCE(SUM(CASE WHEN event_type = 'token' THEN quantity ELSE 0 END), 0)::int AS token_count,
+       COALESCE(COUNT(DISTINCT CASE WHEN event_type = 'login' THEN user_id END), 0)::int AS active_users
+     FROM usage_events
+     WHERE workspace_id = $1
+       AND created_at >= $2
+       AND created_at < $3`,
+    [workspaceId, periodStart.toISOString(), periodEnd.toISOString()],
+  );
+
+  const row = rows[0];
+  return {
+    queryCount: row?.query_count ?? 0,
+    tokenCount: row?.token_count ?? 0,
+    activeUsers: row?.active_users ?? 0,
+    periodStart: periodStart.toISOString(),
+    periodEnd: periodEnd.toISOString(),
+  };
+}
+
+/**
+ * Get historical usage summaries for a workspace.
+ */
+export async function getUsageHistory(
+  workspaceId: string,
+  period: "daily" | "monthly",
+  startDate?: string,
+  endDate?: string,
+  limit = 90,
+): Promise<UsageSummaryRow[]> {
+  if (!hasInternalDB()) return [];
+
+  const params: unknown[] = [workspaceId, period];
+  const conditions = ["workspace_id = $1", "period = $2"];
+
+  if (startDate) {
+    params.push(startDate);
+    conditions.push(`period_start >= $${params.length}`);
+  }
+  if (endDate) {
+    params.push(endDate);
+    conditions.push(`period_start <= $${params.length}`);
+  }
+
+  params.push(limit);
+  const limitIdx = params.length;
+
+  return internalQuery<UsageSummaryRow>(
+    `SELECT * FROM usage_summaries
+     WHERE ${conditions.join(" AND ")}
+     ORDER BY period_start DESC
+     LIMIT $${limitIdx}`,
+    params,
+  );
+}
+
+/**
+ * Get per-user usage breakdown within a workspace for a time range.
+ */
+export async function getUsageBreakdown(
+  workspaceId: string,
+  startDate?: string,
+  endDate?: string,
+  limit = 100,
+): Promise<Array<{
+  user_id: string;
+  query_count: number;
+  token_count: number;
+  login_count: number;
+}>> {
+  if (!hasInternalDB()) return [];
+
+  const params: unknown[] = [workspaceId];
+  const conditions = ["workspace_id = $1", "user_id IS NOT NULL"];
+
+  if (startDate) {
+    params.push(startDate);
+    conditions.push(`created_at >= $${params.length}`);
+  }
+  if (endDate) {
+    params.push(endDate);
+    conditions.push(`created_at <= $${params.length}`);
+  }
+
+  params.push(limit);
+  const limitIdx = params.length;
+
+  return internalQuery<{
+    user_id: string;
+    query_count: number;
+    token_count: number;
+    login_count: number;
+  }>(
+    `SELECT
+       user_id,
+       SUM(CASE WHEN event_type = 'query' THEN quantity ELSE 0 END)::int AS query_count,
+       SUM(CASE WHEN event_type = 'token' THEN quantity ELSE 0 END)::int AS token_count,
+       SUM(CASE WHEN event_type = 'login' THEN quantity ELSE 0 END)::int AS login_count
+     FROM usage_events
+     WHERE ${conditions.join(" AND ")}
+     GROUP BY user_id
+     ORDER BY query_count DESC
+     LIMIT $${limitIdx}`,
+    params,
+  );
+}

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

@@ -0,0 +1,99 @@
+import { createParser } from "nuqs/server";
+import { z } from "zod";
+
+import { dataTableConfig } from "@/config/data-table";
+
+import type {
+  ExtendedColumnFilter,
+  ExtendedColumnSort,
+} from "@/types/data-table";
+
+const sortingItemSchema = z.object({
+  id: z.string(),
+  desc: z.boolean(),
+});
+
+export const getSortingStateParser = <TData>(
+  columnIds?: string[] | Set<string>,
+) => {
+  const validKeys = columnIds
+    ? columnIds instanceof Set
+      ? columnIds
+      : new Set(columnIds)
+    : null;
+
+  return createParser({
+    parse: (value) => {
+      try {
+        const parsed = JSON.parse(value);
+        const result = z.array(sortingItemSchema).safeParse(parsed);
+
+        if (!result.success) return null;
+
+        if (validKeys && result.data.some((item) => !validKeys.has(item.id))) {
+          return null;
+        }
+
+        return result.data as ExtendedColumnSort<TData>[];
+      } catch {
+        return null;
+      }
+    },
+    serialize: (value) => JSON.stringify(value),
+    eq: (a, b) =>
+      a.length === b.length &&
+      a.every(
+        (item, index) =>
+          item.id === b[index]?.id && item.desc === b[index]?.desc,
+      ),
+  });
+};
+
+const filterItemSchema = z.object({
+  id: z.string(),
+  value: z.union([z.string(), z.array(z.string())]),
+  variant: z.enum(dataTableConfig.filterVariants),
+  operator: z.enum(dataTableConfig.operators),
+  filterId: z.string(),
+});
+
+export type FilterItemSchema = z.infer<typeof filterItemSchema>;
+
+export const getFiltersStateParser = <TData>(
+  columnIds?: string[] | Set<string>,
+) => {
+  const validKeys = columnIds
+    ? columnIds instanceof Set
+      ? columnIds
+      : new Set(columnIds)
+    : null;
+
+  return createParser({
+    parse: (value) => {
+      try {
+        const parsed = JSON.parse(value);
+        const result = z.array(filterItemSchema).safeParse(parsed);
+
+        if (!result.success) return null;
+
+        if (validKeys && result.data.some((item) => !validKeys.has(item.id))) {
+          return null;
+        }
+
+        return result.data as ExtendedColumnFilter<TData>[];
+      } catch {
+        return null;
+      }
+    },
+    serialize: (value) => JSON.stringify(value),
+    eq: (a, b) =>
+      a.length === b.length &&
+      a.every(
+        (filter, index) =>
+          filter.id === b[index]?.id &&
+          filter.value === b[index]?.value &&
+          filter.variant === b[index]?.variant &&
+          filter.operator === b[index]?.operator,
+      ),
+  });
+};

package/templates/docker/src/lib/plugins/hooks.ts

@@ -2,14 +2,16 @@
  * Plugin hook dispatch runtime.
  *
  * Dispatches lifecycle hooks (beforeQuery, afterQuery, beforeExplore,
- * afterExplore, onRequest, onResponse) to all healthy plugins that
- * define matching hook entries. Zero overhead when no plugins are registered.
+ * afterExplore, beforeToolCall, afterToolCall, onRequest, onResponse)
+ * to all healthy plugins that define matching hook entries. Zero overhead
+ * when no plugins are registered.
  *
- * Mutable hooks (beforeQuery, beforeExplore) can return a mutation object
- * to rewrite the SQL/command, or throw to reject the operation. All other
- * hooks are observation-only (void return — handler return values are
- * discarded). Mutations chain in registration order across healthy plugins
- * — unhealthy plugins are silently skipped.
+ * Mutable hooks (beforeQuery, beforeExplore, beforeToolCall, afterToolCall)
+ * can return a mutation object to rewrite the SQL/command/args/result, or
+ * throw to reject the operation. All other hooks are observation-only
+ * (void return — handler return values are discarded). Mutations chain in
+ * registration order across healthy plugins — unhealthy plugins are
+ * silently skipped.
  */
 
 import { plugins } from "./registry";
@@ -23,10 +25,10 @@ interface HookEntry<T> {
   handler: (ctx: T) => Promise<unknown> | unknown;
 }
 
-type HookName = "beforeQuery" | "afterQuery" | "beforeExplore" | "afterExplore" | "onRequest" | "onResponse";
+type HookName = "beforeQuery" | "afterQuery" | "beforeExplore" | "afterExplore" | "beforeToolCall" | "afterToolCall" | "onRequest" | "onResponse";
 
 /** Hook names that support mutation via dispatchMutableHook. */
-type MutableHookName = "beforeQuery" | "beforeExplore";
+type MutableHookName = "beforeQuery" | "beforeExplore" | "beforeToolCall" | "afterToolCall";
 
 /**
  * Dispatch a named hook to all healthy plugins (observation-only —
@@ -80,9 +82,9 @@ export async function dispatchHook<T>(
  * - Matcher errors are caught and logged (skipping the entry), NOT treated
  *   as rejections.
  *
- * @param hookName   - "beforeQuery" or "beforeExplore"
+ * @param hookName   - A mutable hook name (beforeQuery, beforeExplore, beforeToolCall, afterToolCall)
  * @param context    - The initial hook context
- * @param mutateKey  - The context key to mutate (e.g. "sql" or "command")
+ * @param mutateKey  - The context key to mutate (e.g. "sql", "command", "args", "result")
  * @param registry   - Optional plugin registry override. For testing.
  * @returns The final mutated value (or the original if no hooks mutated it).
  */

package/templates/docker/src/lib/plugins/index.ts

@@ -3,10 +3,12 @@
  */
 
 export { plugins, PluginRegistry } from "./registry";
-export type { PluginLike, PluginContextLike, PluginHealthResult, PluginType, PluginStatus, PluginDescription } from "./registry";
+export type { PluginLike, PluginContextLike, PluginHealthResult, PluginType, PluginStatus, PluginDescription, ConfigSchemaField } from "./registry";
 export { wireDatasourcePlugins, wireActionPlugins, wireInteractionPlugins, wireContextPlugins, wireSandboxPlugins } from "./wiring";
 export type { SandboxExecBackend } from "./wiring";
 export { generateMigrationSQL, generateColumnMigrations, applyMigrations, runPluginMigrations, ensureMigrationsTable, getAppliedMigrations, diffSchema, prefixTableName } from "./migrate";
 export type { MigrateDB, MigrationStatement, SchemaDiff } from "./migrate";
 export { dispatchHook } from "./hooks";
 export { getPluginTools, setPluginTools, getContextFragments, setContextFragments } from "./tools";
+export { loadPluginSettings, savePluginEnabled, savePluginConfig, getPluginConfig, getAllPluginSettings } from "./settings";
+export type { PluginSettings } from "./settings";

package/templates/docker/src/lib/plugins/registry.ts

@@ -23,6 +23,21 @@ export interface PluginHealthResult {
 export type PluginType = "datasource" | "context" | "interaction" | "action" | "sandbox";
 export type PluginStatus = "registered" | "initializing" | "healthy" | "unhealthy" | "teardown";
 
+/**
+ * Serializable config field description for admin UI form generation.
+ * Structural mirror of ConfigSchemaField from `@useatlas/plugin-sdk`.
+ */
+export interface ConfigSchemaField {
+  key: string;
+  type: "string" | "number" | "boolean" | "select";
+  label?: string;
+  description?: string;
+  required?: boolean;
+  secret?: boolean;
+  options?: string[];
+  default?: unknown;
+}
+
 /**
  * Structural plugin context (mirrors AtlasPluginContext from the SDK).
  * Built at boot time from Atlas internals, passed to initialize().
@@ -45,9 +60,11 @@ export interface PluginLike {
   readonly types: readonly PluginType[];
   readonly version: string;
   readonly name?: string;
+  readonly config?: unknown;
   initialize?(ctx: PluginContextLike): Promise<void>;
   healthCheck?(): Promise<PluginHealthResult>;
   teardown?(): Promise<void>;
+  getConfigSchema?(): ConfigSchemaField[];
   // Additional properties from specific plugin types are accessed via
   // type-narrowing in wiring.ts using structural checks.
   readonly [key: string]: unknown;
@@ -56,6 +73,7 @@ export interface PluginLike {
 interface PluginEntry {
   plugin: PluginLike;
   status: PluginStatus;
+  enabled: boolean;
 }
 
 export interface PluginDescription {
@@ -64,6 +82,7 @@ export interface PluginDescription {
   version: string;
   name: string;
   status: PluginStatus;
+  enabled: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -83,7 +102,7 @@ export class PluginRegistry {
       throw new Error(`Plugin "${plugin.id}" is already registered`);
     }
     this.idSet.add(plugin.id);
-    this.entries.push({ plugin, status: "registered" });
+    this.entries.push({ plugin, status: "registered", enabled: true });
     log.info({ pluginId: plugin.id, types: plugin.types }, "Plugin registered");
   }
 
@@ -191,22 +210,22 @@ export class PluginRegistry {
     return this.entries.find((e) => e.plugin.id === id)?.status;
   }
 
-  /** Return plugins whose types array includes the given type and are currently healthy. */
+  /** Return plugins whose types array includes the given type, are enabled, and are currently healthy. */
   getByType(type: PluginType): PluginLike[] {
     return this.entries
-      .filter((e) => e.plugin.types.includes(type) && e.status === "healthy")
+      .filter((e) => e.enabled && e.plugin.types.includes(type) && e.status === "healthy")
       .map((e) => e.plugin);
   }
 
-  /** Return all registered plugins regardless of status (for schema migrations at boot). */
+  /** Return all registered plugins regardless of status or enabled state (for schema migrations at boot). */
   getAll(): PluginLike[] {
     return this.entries.map((e) => e.plugin);
   }
 
-  /** Return all healthy plugins regardless of type (for cross-cutting hooks). */
+  /** Return all healthy and enabled plugins regardless of type (for cross-cutting hooks). */
   getAllHealthy(): PluginLike[] {
     return this.entries
-      .filter((e) => e.status === "healthy")
+      .filter((e) => e.enabled && e.status === "healthy")
       .map((e) => e.plugin);
   }
 
@@ -218,9 +237,42 @@ export class PluginRegistry {
       version: e.plugin.version,
       name: e.plugin.name ?? e.plugin.id,
       status: e.status,
+      enabled: e.enabled,
     }));
   }
 
+  /** Enable a plugin so it participates in agent execution. */
+  enable(id: string): boolean {
+    const entry = this.entries.find((e) => e.plugin.id === id);
+    if (!entry) return false;
+    if (entry.status === "teardown") {
+      log.warn({ pluginId: id }, "Cannot enable plugin in teardown state");
+      return false;
+    }
+    entry.enabled = true;
+    log.info({ pluginId: id }, "Plugin enabled");
+    return true;
+  }
+
+  /** Disable a plugin so it is skipped during agent execution. */
+  disable(id: string): boolean {
+    const entry = this.entries.find((e) => e.plugin.id === id);
+    if (!entry) return false;
+    if (entry.status === "teardown") {
+      log.warn({ pluginId: id }, "Cannot disable plugin in teardown state");
+      return false;
+    }
+    entry.enabled = false;
+    log.info({ pluginId: id }, "Plugin disabled");
+    return true;
+  }
+
+  /** Check whether a plugin is currently enabled. */
+  isEnabled(id: string): boolean {
+    const entry = this.entries.find((e) => e.plugin.id === id);
+    return entry?.enabled ?? false;
+  }
+
   get size(): number {
     return this.entries.length;
   }