@useatlas/create 0.0.5 → 0.0.7

package/templates/nextjs-standalone/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/nextjs-standalone/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/nextjs-standalone/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/nextjs-standalone/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;
   }

package/templates/nextjs-standalone/src/lib/plugins/settings.ts

@@ -0,0 +1,147 @@
+/**
+ * Plugin settings persistence — enable/disable state and config overrides.
+ *
+ * Stores plugin settings in the internal DB's `plugin_settings` table.
+ * When no internal DB is available, all plugins are enabled and config
+ * is read-only (from env vars / atlas.config.ts only).
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+import { hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
+import type { PluginRegistry } from "./registry";
+
+const log = createLogger("plugin-settings");
+
+export interface PluginSettings {
+  pluginId: string;
+  enabled: boolean;
+  config: Record<string, unknown> | null;
+  updatedAt: string;
+}
+
+/**
+ * Load plugin settings from the internal DB and apply enabled/disabled
+ * state to the registry. Call after plugins are registered.
+ * No-op when no internal DB is available.
+ */
+export async function loadPluginSettings(registry: PluginRegistry): Promise<number> {
+  if (!hasInternalDB()) return 0;
+
+  try {
+    const rows = await internalQuery<{
+      plugin_id: string;
+      enabled: boolean;
+      config: Record<string, unknown> | null;
+    }>("SELECT plugin_id, enabled, config FROM plugin_settings");
+
+    let applied = 0;
+    for (const row of rows) {
+      if (!row.enabled) {
+        if (registry.disable(row.plugin_id)) {
+          applied++;
+        }
+      }
+    }
+
+    if (applied > 0) {
+      log.info({ count: applied }, "Applied plugin settings from internal DB");
+    }
+    return applied;
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Could not load plugin settings (table may not exist yet)",
+    );
+    return 0;
+  }
+}
+
+/**
+ * Save plugin enabled/disabled state to the internal DB.
+ * Uses upsert to handle first-time saves.
+ */
+export async function savePluginEnabled(pluginId: string, enabled: boolean): Promise<void> {
+  if (!hasInternalDB()) {
+    throw new Error("Internal database required to persist plugin settings");
+  }
+
+  await internalQuery(
+    `INSERT INTO plugin_settings (plugin_id, enabled, updated_at)
+     VALUES ($1, $2, now())
+     ON CONFLICT (plugin_id) DO UPDATE SET enabled = $2, updated_at = now()`,
+    [pluginId, enabled],
+  );
+}
+
+/**
+ * Save plugin config overrides to the internal DB.
+ * Uses upsert to handle first-time saves.
+ */
+export async function savePluginConfig(
+  pluginId: string,
+  config: Record<string, unknown>,
+): Promise<void> {
+  if (!hasInternalDB()) {
+    throw new Error("Internal database required to persist plugin settings");
+  }
+
+  await internalQuery(
+    `INSERT INTO plugin_settings (plugin_id, config, updated_at)
+     VALUES ($1, $2::jsonb, now())
+     ON CONFLICT (plugin_id) DO UPDATE SET config = $2::jsonb, updated_at = now()`,
+    [pluginId, JSON.stringify(config)],
+  );
+}
+
+/**
+ * Get plugin config overrides from the internal DB.
+ * Returns null if no overrides are saved.
+ */
+export async function getPluginConfig(
+  pluginId: string,
+): Promise<Record<string, unknown> | null> {
+  if (!hasInternalDB()) return null;
+
+  try {
+    const rows = await internalQuery<{ config: Record<string, unknown> | null }>(
+      "SELECT config FROM plugin_settings WHERE plugin_id = $1",
+      [pluginId],
+    );
+    return rows[0]?.config ?? null;
+  } catch (err) {
+    log.warn(
+      { pluginId, err: err instanceof Error ? err.message : String(err) },
+      "Failed to load plugin config from internal DB",
+    );
+    return null;
+  }
+}
+
+/**
+ * Get all plugin settings from the internal DB.
+ */
+export async function getAllPluginSettings(): Promise<PluginSettings[]> {
+  if (!hasInternalDB()) return [];
+
+  try {
+    const rows = await internalQuery<{
+      plugin_id: string;
+      enabled: boolean;
+      config: Record<string, unknown> | null;
+      updated_at: string;
+    }>("SELECT plugin_id, enabled, config, updated_at FROM plugin_settings");
+
+    return rows.map((r) => ({
+      pluginId: r.plugin_id,
+      enabled: r.enabled,
+      config: r.config,
+      updatedAt: r.updated_at,
+    }));
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Failed to load all plugin settings from internal DB",
+    );
+    return [];
+  }
+}

package/templates/nextjs-standalone/src/lib/plugins/wiring.ts

@@ -27,7 +27,7 @@ interface DatasourceShape {
   connection: {
     create(): Promise<{ query(sql: string, timeoutMs?: number): Promise<unknown>; close(): Promise<void> }> | { query(sql: string, timeoutMs?: number): Promise<unknown>; close(): Promise<void> };
     dbType: string;
-    validate?(query: string): { valid: boolean; reason?: string };
+    validate?(query: string): { valid: boolean; reason?: string } | Promise<{ valid: boolean; reason?: string }>;
     parserDialect?: string;
     forbiddenPatterns?: RegExp[];
   };
@@ -271,15 +271,12 @@ export async function wireInteractionPlugins(
 const SANDBOX_DEFAULT_PRIORITY = 60;
 
 /**
- * Minimal interface for a sandbox execution backend.
- * Structurally identical to ExploreBackend in explore.ts — duplicated here
- * to avoid a circular dependency (explore.ts imports from wiring.ts).
- * Changes to either interface should be mirrored.
+ * Sandbox execution backend interface.
+ * Canonical definition lives in backends/types.ts. Re-exported here for
+ * backward compatibility with plugins that reference SandboxExecBackend.
  */
-export interface SandboxExecBackend {
-  exec(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }>;
-  close?(): Promise<void>;
-}
+import type { ExploreBackend } from "@atlas/api/lib/tools/backends/types";
+export type SandboxExecBackend = ExploreBackend;
 
 interface SandboxShape {
   sandbox: {