@useatlas/create 0.0.1

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

@@ -0,0 +1,162 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+import { plugins } from "./registry";
+import type { PluginRegistry } from "./registry";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("plugins:hooks");
+
+interface HookEntry<T> {
+  matcher?: (ctx: T) => boolean;
+  handler: (ctx: T) => Promise<unknown> | unknown;
+}
+
+type HookName = "beforeQuery" | "afterQuery" | "beforeExplore" | "afterExplore" | "onRequest" | "onResponse";
+
+/** Hook names that support mutation via dispatchMutableHook. */
+type MutableHookName = "beforeQuery" | "beforeExplore";
+
+/**
+ * Dispatch a named hook to all healthy plugins (observation-only —
+ * handler return values are discarded).
+ *
+ * - Skips entirely when no plugins are registered (zero overhead).
+ * - Respects `matcher` filters on individual hook entries.
+ * - Catches and logs errors from hook handlers — never crashes the caller.
+ *
+ * @param registry - Optional plugin registry override (default: global singleton). For testing.
+ */
+export async function dispatchHook<T>(
+  hookName: HookName,
+  context: T,
+  registry?: PluginRegistry,
+): Promise<void> {
+  const reg = registry ?? plugins;
+  if (reg.size === 0) return;
+
+  const healthyPlugins = reg.getAllHealthy();
+  if (healthyPlugins.length === 0) return;
+
+  for (const plugin of healthyPlugins) {
+    const hooks = (plugin as Record<string, unknown>).hooks as Record<string, HookEntry<T>[]> | undefined;
+    if (!hooks?.[hookName]) continue;
+
+    for (const entry of hooks[hookName]) {
+      try {
+        if (entry.matcher && !entry.matcher(context)) continue;
+        await entry.handler(context);
+      } catch (err) {
+        log.warn(
+          { pluginId: plugin.id, hookName, err: err instanceof Error ? err : new Error(String(err)) },
+          "Plugin hook failed",
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Dispatch a mutable hook and return the final mutated value.
+ *
+ * - Chains mutations in plugin registration order across healthy plugins.
+ * - Each hook handler receives a context with the latest mutated value applied.
+ * - Handlers that return `void`/`undefined` pass through without mutation.
+ * - Handlers that return a mutation object (e.g. `{ sql }`) update the value
+ *   for subsequent hooks.
+ * - If any handler **throws**, the error propagates immediately — the caller
+ *   should treat this as a rejection (e.g. deny the query).
+ * - Matcher errors are caught and logged (skipping the entry), NOT treated
+ *   as rejections.
+ *
+ * @param hookName   - "beforeQuery" or "beforeExplore"
+ * @param context    - The initial hook context
+ * @param mutateKey  - The context key to mutate (e.g. "sql" or "command")
+ * @param registry   - Optional plugin registry override. For testing.
+ * @returns The final mutated value (or the original if no hooks mutated it).
+ */
+export async function dispatchMutableHook<
+  T extends Record<string, unknown>,
+  K extends string & keyof T,
+>(
+  hookName: MutableHookName,
+  context: T,
+  mutateKey: K,
+  registry?: PluginRegistry,
+): Promise<T[K]> {
+  const reg = registry ?? plugins;
+  let currentValue = context[mutateKey];
+
+  if (reg.size === 0) return currentValue;
+
+  const healthyPlugins = reg.getAllHealthy();
+  if (healthyPlugins.length === 0) return currentValue;
+
+  // Build a mutable copy of the context so each hook sees the latest value
+  const mutableCtx = { ...context };
+
+  for (const plugin of healthyPlugins) {
+    const hooks = (plugin as Record<string, unknown>).hooks as Record<string, HookEntry<T>[]> | undefined;
+    if (!hooks?.[hookName]) continue;
+
+    for (const entry of hooks[hookName]) {
+      // Matcher errors are bugs, not rejections — catch and skip
+      if (entry.matcher) {
+        let matched: boolean;
+        try {
+          matched = entry.matcher(mutableCtx);
+        } catch (matcherErr) {
+          log.error(
+            { pluginId: plugin.id, hookName, err: matcherErr instanceof Error ? matcherErr : new Error(String(matcherErr)) },
+            "Plugin hook matcher threw — skipping entry",
+          );
+          continue;
+        }
+        if (!matched) continue;
+      }
+
+      // Handler throws propagate — intentional for "deny" use cases
+      let result: unknown;
+      try {
+        result = await entry.handler(mutableCtx);
+      } catch (err) {
+        log.warn(
+          { pluginId: plugin.id, hookName, err: err instanceof Error ? err : new Error(String(err)) },
+          "Plugin hook rejected operation",
+        );
+        throw err;
+      }
+
+      // Apply mutation if the handler returned one
+      if (result != null && typeof result === "object" && mutateKey in (result as Record<string, unknown>)) {
+        const newValue = (result as Record<string, unknown>)[mutateKey];
+        if (typeof newValue !== typeof currentValue) {
+          log.error(
+            { pluginId: plugin.id, hookName, mutateKey, expectedType: typeof currentValue, gotType: typeof newValue },
+            "Plugin returned wrong type for mutated value — ignoring mutation",
+          );
+          continue;
+        }
+        currentValue = newValue as T[K];
+        (mutableCtx as Record<string, unknown>)[mutateKey] = currentValue;
+        log.debug(
+          { pluginId: plugin.id, hookName, mutateKey },
+          "Plugin mutated hook value",
+        );
+      }
+    }
+  }
+
+  return currentValue;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Plugin system — public API from @atlas/api.
+ */
+
+export { plugins, PluginRegistry } from "./registry";
+export type { PluginLike, PluginContextLike, PluginHealthResult, PluginType, PluginStatus, PluginDescription } from "./registry";
+export { wireDatasourcePlugins, wireActionPlugins, wireInteractionPlugins, wireContextPlugins } from "./wiring";
+export { dispatchHook } from "./hooks";
+export { getPluginTools, setPluginTools, getContextFragments, setContextFragments } from "./tools";

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

@@ -0,0 +1,309 @@
+/**
+ * Schema-driven plugin migrations.
+ *
+ * Reads `schema` declarations from plugin objects, generates CREATE TABLE
+ * SQL for the internal database, and tracks applied migrations in a
+ * `plugin_migrations` table for idempotency.
+ *
+ * Table names are prefixed with `plugin_` to avoid collisions with Atlas
+ * internal tables.
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("plugins:migrate");
+
+// ---------------------------------------------------------------------------
+// Types (structural — no import from @atlas/plugin-sdk)
+// ---------------------------------------------------------------------------
+
+interface FieldDef {
+  type: "string" | "number" | "boolean" | "date";
+  required?: boolean;
+  references?: { model: string; field: string };
+  unique?: boolean;
+  defaultValue?: unknown;
+}
+
+interface TableDef {
+  fields: Record<string, FieldDef>;
+}
+
+interface PluginWithSchema {
+  id: string;
+  schema?: Record<string, TableDef>;
+}
+
+// ---------------------------------------------------------------------------
+// SQL type mapping
+// ---------------------------------------------------------------------------
+
+const TYPE_MAP: Record<string, string> = {
+  string: "TEXT",
+  number: "INTEGER",
+  boolean: "BOOLEAN",
+  date: "TIMESTAMPTZ",
+};
+
+const SAFE_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+function validateIdentifier(name: string, context: string): void {
+  if (!SAFE_IDENTIFIER.test(name)) {
+    throw new Error(
+      `Invalid identifier "${name}" in ${context}. ` +
+      `Must contain only letters, digits, and underscores, and start with a letter or underscore.`
+    );
+  }
+}
+
+function fieldToSQL(name: string, field: FieldDef): string {
+  validateIdentifier(name, "column name");
+
+  const sqlType = TYPE_MAP[field.type];
+  if (!sqlType) {
+    throw new Error(`Unknown field type "${field.type}" on column "${name}"`);
+  }
+
+  const parts = [`"${name}" ${sqlType}`];
+
+  if (field.required) parts.push("NOT NULL");
+  if (field.unique) parts.push("UNIQUE");
+
+  if (field.defaultValue !== undefined) {
+    if (typeof field.defaultValue === "string") {
+      // Escape single quotes in default values
+      parts.push(`DEFAULT '${field.defaultValue.replace(/'/g, "''")}'`);
+    } else if (typeof field.defaultValue === "boolean") {
+      parts.push(`DEFAULT ${field.defaultValue}`);
+    } else if (typeof field.defaultValue === "number") {
+      if (!Number.isFinite(field.defaultValue)) {
+        throw new Error(
+          `Invalid numeric defaultValue "${field.defaultValue}" on column "${name}". ` +
+          `Default values must be finite numbers.`
+        );
+      }
+      parts.push(`DEFAULT ${field.defaultValue}`);
+    } else {
+      throw new Error(
+        `Unsupported defaultValue type "${typeof field.defaultValue}" on column "${name}". ` +
+        `Only string, boolean, and number default values are supported.`
+      );
+    }
+  }
+
+  return parts.join(" ");
+}
+
+// ---------------------------------------------------------------------------
+// Table name prefixing
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a safe prefixed table name: `plugin_{pluginId}_{tableName}`.
+ * Replaces non-alphanumeric/underscore chars with underscores for safety.
+ */
+export function prefixTableName(pluginId: string, tableName: string): string {
+  const safePlugin = pluginId.replace(/[^a-zA-Z0-9_]/g, "_");
+  const safeTable = tableName.replace(/[^a-zA-Z0-9_]/g, "_");
+  return `plugin_${safePlugin}_${safeTable}`;
+}
+
+// ---------------------------------------------------------------------------
+// SQL generation
+// ---------------------------------------------------------------------------
+
+export interface MigrationStatement {
+  pluginId: string;
+  tableName: string;
+  prefixedName: string;
+  sql: string;
+  hash: string;
+}
+
+/**
+ * Hash a SQL string for change detection. Uses a simple string hash
+ * (not crypto — just for detecting drift, not security).
+ */
+function hashSQL(sql: string): string {
+  let h = 0;
+  for (let i = 0; i < sql.length; i++) {
+    h = ((h << 5) - h + sql.charCodeAt(i)) | 0;
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * Generate CREATE TABLE IF NOT EXISTS statements from plugin schema
+ * declarations. Each table gets an auto-generated `id` primary key
+ * and `created_at`/`updated_at` timestamps.
+ */
+export function generateMigrationSQL(plugins: PluginWithSchema[]): MigrationStatement[] {
+  const statements: MigrationStatement[] = [];
+
+  for (const plugin of plugins) {
+    if (!plugin.schema) continue;
+
+    for (const [tableName, tableDef] of Object.entries(plugin.schema)) {
+      const prefixed = prefixTableName(plugin.id, tableName);
+      const columns: string[] = [
+        '"id" UUID PRIMARY KEY DEFAULT gen_random_uuid()',
+      ];
+
+      for (const [fieldName, fieldDef] of Object.entries(tableDef.fields)) {
+        columns.push(fieldToSQL(fieldName, fieldDef));
+      }
+
+      // Add foreign key constraints after columns
+      for (const [fieldName, fieldDef] of Object.entries(tableDef.fields)) {
+        if (fieldDef.references) {
+          validateIdentifier(fieldDef.references.field, `references.field on column "${fieldName}"`);
+          const refTable = prefixTableName(plugin.id, fieldDef.references.model);
+          columns.push(
+            `FOREIGN KEY ("${fieldName}") REFERENCES "${refTable}"("${fieldDef.references.field}")`
+          );
+        }
+      }
+
+      columns.push('"created_at" TIMESTAMPTZ DEFAULT now()');
+      columns.push('"updated_at" TIMESTAMPTZ DEFAULT now()');
+
+      const sql = `CREATE TABLE IF NOT EXISTS "${prefixed}" (\n  ${columns.join(",\n  ")}\n);`;
+
+      statements.push({
+        pluginId: plugin.id,
+        tableName,
+        prefixedName: prefixed,
+        sql,
+        hash: hashSQL(sql),
+      });
+    }
+  }
+
+  return statements;
+}
+
+// ---------------------------------------------------------------------------
+// Migration tracking table
+// ---------------------------------------------------------------------------
+
+const MIGRATIONS_TABLE_SQL = `
+CREATE TABLE IF NOT EXISTS plugin_migrations (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  plugin_id TEXT NOT NULL,
+  table_name TEXT NOT NULL,
+  sql_hash TEXT NOT NULL,
+  applied_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE(plugin_id, table_name, sql_hash)
+);
+`;
+
+// ---------------------------------------------------------------------------
+// Apply migrations
+// ---------------------------------------------------------------------------
+
+/** Internal DB interface — matches the shape from internal.ts */
+export interface MigrateDB {
+  query(sql: string, params?: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+}
+
+/**
+ * Ensure the plugin_migrations tracking table exists.
+ */
+export async function ensureMigrationsTable(db: MigrateDB): Promise<void> {
+  await db.query(MIGRATIONS_TABLE_SQL);
+}
+
+/**
+ * Check which migrations have already been applied.
+ * Returns a Set of "pluginId:tableName:hash" keys.
+ */
+export async function getAppliedMigrations(db: MigrateDB): Promise<Set<string>> {
+  const result = await db.query(
+    "SELECT plugin_id, table_name, sql_hash FROM plugin_migrations"
+  );
+  const applied = new Set<string>();
+  for (const row of result.rows) {
+    applied.add(`${row.plugin_id}:${row.table_name}:${row.sql_hash}`);
+  }
+  return applied;
+}
+
+/**
+ * Apply pending migrations to the internal database.
+ * Skips already-applied migrations (idempotent).
+ *
+ * @returns Summary of applied and skipped migrations.
+ */
+export async function applyMigrations(
+  db: MigrateDB,
+  statements: MigrationStatement[],
+): Promise<{ applied: string[]; skipped: string[] }> {
+  await ensureMigrationsTable(db);
+  const existing = await getAppliedMigrations(db);
+  const applied: string[] = [];
+  const skipped: string[] = [];
+
+  for (const stmt of statements) {
+    const key = `${stmt.pluginId}:${stmt.tableName}:${stmt.hash}`;
+    if (existing.has(key)) {
+      skipped.push(stmt.prefixedName);
+      log.debug({ table: stmt.prefixedName }, "Migration already applied — skipping");
+      continue;
+    }
+
+    try {
+      await db.query(stmt.sql);
+      await db.query(
+        "INSERT INTO plugin_migrations (plugin_id, table_name, sql_hash) VALUES ($1, $2, $3)",
+        [stmt.pluginId, stmt.tableName, stmt.hash],
+      );
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Migration failed for "${stmt.prefixedName}": ${detail}. ` +
+        `Applied so far: [${applied.join(", ") || "none"}]. ` +
+        `Remaining migrations were not attempted.`,
+        { cause: err },
+      );
+    }
+    applied.push(stmt.prefixedName);
+    log.info({ table: stmt.prefixedName, pluginId: stmt.pluginId }, "Migration applied");
+  }
+
+  return { applied, skipped };
+}
+
+// ---------------------------------------------------------------------------
+// Diff: compare declared schema vs actual tables
+// ---------------------------------------------------------------------------
+
+export interface SchemaDiff {
+  newTables: string[];
+  existingTables: string[];
+}
+
+/**
+ * Compare declared plugin schemas against actual tables in the database.
+ */
+export async function diffSchema(
+  db: MigrateDB,
+  statements: MigrationStatement[],
+): Promise<SchemaDiff> {
+  const result = await db.query(
+    "SELECT tablename FROM pg_tables WHERE schemaname = 'public'"
+  );
+  const existing = new Set(result.rows.map((r) => String(r.tablename)));
+
+  const newTables: string[] = [];
+  const existingTables: string[] = [];
+
+  for (const stmt of statements) {
+    if (existing.has(stmt.prefixedName)) {
+      existingTables.push(stmt.prefixedName);
+    } else {
+      newTables.push(stmt.prefixedName);
+    }
+  }
+
+  return { newTables, existingTables };
+}