@useatlas/create 0.0.1

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

@@ -0,0 +1,231 @@
+/**
+ * Runtime plugin registry for Atlas.
+ *
+ * Manages plugin lifecycle: registration → initialization → health checks → teardown.
+ * Uses a structural `PluginLike` interface defined locally so `@atlas/api` does not
+ * depend on `@atlas/plugin-sdk`.
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("plugins");
+
+// ---------------------------------------------------------------------------
+// Structural interfaces (no import from @atlas/plugin-sdk)
+// ---------------------------------------------------------------------------
+
+export interface PluginHealthResult {
+  healthy: boolean;
+  message?: string;
+  latencyMs?: number;
+}
+
+export type PluginType = "datasource" | "context" | "interaction" | "action" | "sandbox";
+export type PluginStatus = "registered" | "initializing" | "healthy" | "unhealthy" | "teardown";
+
+/**
+ * Structural plugin context (mirrors AtlasPluginContext from the SDK).
+ * Built at boot time from Atlas internals, passed to initialize().
+ */
+export interface PluginContextLike {
+  db: { query(sql: string, params?: unknown[]): Promise<unknown>; execute(sql: string, params?: unknown[]): Promise<void> } | null;
+  connections: { get(id: string): unknown; list(): string[] };
+  tools: { register(tool: { name: string; description: string; tool: unknown }): void };
+  logger: Record<string, unknown>;
+  config: Record<string, unknown>;
+}
+
+/**
+ * Structural interface matching AtlasPlugin from the SDK. The registry
+ * accepts any object satisfying this shape — no hard dependency on the SDK.
+ */
+export interface PluginLike {
+  readonly id: string;
+  readonly type: PluginType;
+  readonly version: string;
+  readonly name?: string;
+  initialize?(ctx: PluginContextLike): Promise<void>;
+  healthCheck?(): Promise<PluginHealthResult>;
+  teardown?(): Promise<void>;
+  // Additional properties from specific plugin types are accessed via
+  // type-narrowing in wiring.ts using structural checks.
+  readonly [key: string]: unknown;
+}
+
+interface PluginEntry {
+  plugin: PluginLike;
+  status: PluginStatus;
+}
+
+export interface PluginDescription {
+  id: string;
+  type: PluginType;
+  version: string;
+  name: string;
+  status: PluginStatus;
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export class PluginRegistry {
+  private entries: PluginEntry[] = [];
+  private idSet = new Set<string>();
+  private initialized = false;
+
+  register(plugin: PluginLike): void {
+    if (!plugin.id || !plugin.id.trim()) {
+      throw new Error("Plugin id must not be empty");
+    }
+    if (this.idSet.has(plugin.id)) {
+      throw new Error(`Plugin "${plugin.id}" is already registered`);
+    }
+    this.idSet.add(plugin.id);
+    this.entries.push({ plugin, status: "registered" });
+    log.info({ pluginId: plugin.id, type: plugin.type }, "Plugin registered");
+  }
+
+  /**
+   * Initialize all registered plugins sequentially. Each plugin's
+   * `initialize(ctx)` receives the Atlas context (db, connections, tools,
+   * logger, config). Plugins without an `initialize` method are marked
+   * healthy immediately. Failures set "unhealthy" + log — they don't crash.
+   */
+  async initializeAll(ctx: PluginContextLike): Promise<{ succeeded: string[]; failed: string[] }> {
+    if (this.initialized) {
+      throw new Error("Plugins already initialized — initializeAll() cannot be called twice");
+    }
+    this.initialized = true;
+
+    const succeeded: string[] = [];
+    const failed: string[] = [];
+
+    for (const entry of this.entries) {
+      entry.status = "initializing";
+      if (!entry.plugin.initialize) {
+        entry.status = "healthy";
+        succeeded.push(entry.plugin.id);
+        continue;
+      }
+      try {
+        const pluginCtx = {
+          ...ctx,
+          logger: typeof (ctx.logger as Record<string, unknown>)?.child === "function"
+            ? (ctx.logger as { child(bindings: Record<string, unknown>): unknown }).child({ pluginId: entry.plugin.id })
+            : ctx.logger,
+        };
+        await entry.plugin.initialize(pluginCtx as PluginContextLike);
+        entry.status = "healthy";
+        succeeded.push(entry.plugin.id);
+        log.info({ pluginId: entry.plugin.id }, "Plugin initialized");
+      } catch (err) {
+        entry.status = "unhealthy";
+        failed.push(entry.plugin.id);
+        log.error(
+          { pluginId: entry.plugin.id, err: err instanceof Error ? err : new Error(String(err)) },
+          "Plugin initialization failed",
+        );
+      }
+    }
+
+    return { succeeded, failed };
+  }
+
+  /**
+   * Run health checks on all registered plugins. Returns a map of plugin id
+   * to health result with current status. Catches exceptions from probes.
+   */
+  async healthCheckAll(): Promise<Map<string, PluginHealthResult & { status: PluginStatus }>> {
+    const results = new Map<string, PluginHealthResult & { status: PluginStatus }>();
+
+    for (const entry of this.entries) {
+      if (!entry.plugin.healthCheck) {
+        results.set(entry.plugin.id, { healthy: entry.status === "healthy", status: entry.status });
+        continue;
+      }
+      try {
+        const result = await entry.plugin.healthCheck();
+        entry.status = result.healthy ? "healthy" : "unhealthy";
+        results.set(entry.plugin.id, { ...result, status: entry.status });
+      } catch (err) {
+        entry.status = "unhealthy";
+        results.set(entry.plugin.id, {
+          healthy: false,
+          message: err instanceof Error ? err.message : String(err),
+          status: entry.status,
+        });
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Tear down all plugins in reverse registration order (LIFO).
+   * Catches and logs errors — teardown continues for remaining plugins.
+   */
+  async teardownAll(): Promise<void> {
+    for (let i = this.entries.length - 1; i >= 0; i--) {
+      const entry = this.entries[i];
+      entry.status = "teardown";
+      if (!entry.plugin.teardown) continue;
+      try {
+        await entry.plugin.teardown();
+        log.info({ pluginId: entry.plugin.id }, "Plugin torn down");
+      } catch (err) {
+        log.error(
+          { pluginId: entry.plugin.id, err: err instanceof Error ? err : new Error(String(err)) },
+          "Plugin teardown failed",
+        );
+      }
+    }
+  }
+
+  get(id: string): PluginLike | undefined {
+    return this.entries.find((e) => e.plugin.id === id)?.plugin;
+  }
+
+  getStatus(id: string): PluginStatus | undefined {
+    return this.entries.find((e) => e.plugin.id === id)?.status;
+  }
+
+  /** Return plugins of the given type that are currently healthy. */
+  getByType(type: PluginType): PluginLike[] {
+    return this.entries
+      .filter((e) => e.plugin.type === type && e.status === "healthy")
+      .map((e) => e.plugin);
+  }
+
+  /** Return all healthy plugins regardless of type (for cross-cutting hooks). */
+  getAllHealthy(): PluginLike[] {
+    return this.entries
+      .filter((e) => e.status === "healthy")
+      .map((e) => e.plugin);
+  }
+
+  /** Return metadata for all registered plugins. */
+  describe(): PluginDescription[] {
+    return this.entries.map((e) => ({
+      id: e.plugin.id,
+      type: e.plugin.type,
+      version: e.plugin.version,
+      name: e.plugin.name ?? e.plugin.id,
+      status: e.status,
+    }));
+  }
+
+  get size(): number {
+    return this.entries.length;
+  }
+
+  /** Reset registry state. For testing only. */
+  _reset(): void {
+    this.entries = [];
+    this.idSet.clear();
+    this.initialized = false;
+  }
+}
+
+/** Global singleton. */
+export const plugins = new PluginRegistry();

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

@@ -0,0 +1,39 @@
+/**
+ * Plugin bridge — stores plugin tool registry and context fragments for
+ * use by the chat route and agent loop respectively.
+ *
+ * server.ts writes these at boot; chat.ts and agent.ts read them at runtime.
+ */
+
+import type { ToolRegistry } from "@atlas/api/lib/tools/registry";
+
+let pluginToolRegistry: ToolRegistry | undefined;
+let contextFragments: string[] = [];
+
+export function setPluginTools(registry: ToolRegistry): void {
+  pluginToolRegistry = registry;
+}
+
+export function getPluginTools(): ToolRegistry | undefined {
+  return pluginToolRegistry;
+}
+
+export function setContextFragments(fragments: string[]): void {
+  contextFragments = fragments;
+}
+
+export function getContextFragments(): string[] {
+  return contextFragments;
+}
+
+import type { DialectHint } from "./wiring";
+
+let dialectHints: readonly DialectHint[] = [];
+
+export function setDialectHints(hints: readonly DialectHint[]): void {
+  dialectHints = hints;
+}
+
+export function getDialectHints(): readonly DialectHint[] {
+  return dialectHints;
+}

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

@@ -0,0 +1,291 @@
+/**
+ * Plugin wiring — bridges plugins into existing Atlas registries.
+ *
+ * Each function accepts DI params for testability. When registries are
+ * omitted, the global singletons are used.
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+import type { PluginRegistry, PluginLike } from "./registry";
+import type { ConnectionRegistry } from "@atlas/api/lib/db/connection";
+import type { ToolRegistry, AtlasTool } from "@atlas/api/lib/tools/registry";
+
+const log = createLogger("plugins:wiring");
+
+// ---------------------------------------------------------------------------
+// Structural checks for plugin subtypes (avoids SDK dependency)
+// ---------------------------------------------------------------------------
+
+interface ContextShape {
+  contextProvider: {
+    load(): Promise<string>;
+    refresh?(): Promise<void>;
+  };
+}
+
+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 };
+  };
+  entities?: unknown[] | (() => Promise<unknown[]> | unknown[]);
+  dialect?: string;
+}
+
+interface ActionShape {
+  actions: ReadonlyArray<{
+    name: string;
+    description: string;
+    tool: unknown;
+    actionType: string;
+    reversible: boolean;
+    defaultApproval: string;
+    requiredCredentials: string[];
+  }>;
+}
+
+interface InteractionShape {
+  routes: (app: unknown) => void;
+}
+
+function hasContextProvider(p: PluginLike): p is PluginLike & ContextShape {
+  return (
+    p.type === "context" &&
+    typeof (p as Record<string, unknown>).contextProvider === "object" &&
+    (p as Record<string, unknown>).contextProvider !== null &&
+    typeof ((p as Record<string, unknown>).contextProvider as Record<string, unknown>)?.load === "function"
+  );
+}
+
+function hasDatasource(p: PluginLike): p is PluginLike & DatasourceShape {
+  return (
+    p.type === "datasource" &&
+    typeof (p as Record<string, unknown>).connection === "object" &&
+    (p as Record<string, unknown>).connection !== null
+  );
+}
+
+function hasActions(p: PluginLike): p is PluginLike & ActionShape {
+  return p.type === "action" && Array.isArray((p as Record<string, unknown>).actions);
+}
+
+function hasRoutes(p: PluginLike): p is PluginLike & InteractionShape {
+  return p.type === "interaction" && typeof (p as Record<string, unknown>).routes === "function";
+}
+
+// ---------------------------------------------------------------------------
+// Wiring functions
+// ---------------------------------------------------------------------------
+
+export interface DialectHint {
+  readonly pluginId: string;
+  readonly dialect: string;
+}
+
+/**
+ * For each healthy datasource plugin, call `connection.create()` and register
+ * the resulting DBConnection in the ConnectionRegistry. Also resolves
+ * plugin-provided entities and collects dialect hints.
+ */
+export async function wireDatasourcePlugins(
+  pluginRegistry: PluginRegistry,
+  connectionRegistry?: ConnectionRegistry,
+): Promise<{ wired: string[]; failed: Array<{ pluginId: string; error: string }>; dialectHints: DialectHint[]; entityFailures: Array<{ pluginId: string; error: string }> }> {
+  const connRegistry = connectionRegistry ?? (await import("@atlas/api/lib/db/connection")).connections;
+  const datasources = pluginRegistry.getByType("datasource");
+  const wired: string[] = [];
+  const failed: Array<{ pluginId: string; error: string }> = [];
+  const dialectHints: DialectHint[] = [];
+  const entityFailures: Array<{ pluginId: string; error: string }> = [];
+
+  for (const plugin of datasources) {
+    if (!hasDatasource(plugin)) {
+      log.warn({ pluginId: plugin.id }, "Datasource plugin missing connection property — skipped");
+      continue;
+    }
+    try {
+      const conn = await plugin.connection.create();
+      await connRegistry.registerDirect(
+        plugin.id,
+        conn as Parameters<ConnectionRegistry["registerDirect"]>[1],
+        plugin.connection.dbType as Parameters<ConnectionRegistry["registerDirect"]>[2],
+        plugin.name ?? plugin.id,
+        plugin.connection.validate,
+      );
+      wired.push(plugin.id);
+      log.info({ pluginId: plugin.id, dbType: plugin.connection.dbType }, "Datasource plugin wired");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      failed.push({ pluginId: plugin.id, error: msg });
+      log.error(
+        { pluginId: plugin.id, err: err instanceof Error ? err : new Error(String(err)) },
+        "Failed to wire datasource plugin",
+      );
+      continue;
+    }
+
+    // Resolve plugin-provided entities (in-memory, no disk writes)
+    if (plugin.entities !== undefined) {
+      try {
+        const resolved = typeof plugin.entities === "function"
+          ? await plugin.entities()
+          : plugin.entities;
+        if (resolved != null && !Array.isArray(resolved)) {
+          const msg = `entities factory returned non-array (${typeof resolved})`;
+          log.error({ pluginId: plugin.id, type: typeof resolved }, msg);
+          entityFailures.push({ pluginId: plugin.id, error: msg });
+        } else if (Array.isArray(resolved) && resolved.length === 0) {
+          log.warn({ pluginId: plugin.id }, "Plugin entities factory returned empty array");
+        } else if (Array.isArray(resolved) && resolved.length > 0) {
+          // Validate per-element shape: must have string name and yaml
+          const valid: Array<{ name: string; yaml: string }> = [];
+          for (const el of resolved) {
+            if (
+              el != null &&
+              typeof el === "object" &&
+              typeof (el as Record<string, unknown>).name === "string" &&
+              typeof (el as Record<string, unknown>).yaml === "string"
+            ) {
+              valid.push(el as { name: string; yaml: string });
+            } else {
+              log.error(
+                { pluginId: plugin.id, element: el },
+                "Invalid entity element — expected { name: string; yaml: string }, skipping",
+              );
+            }
+          }
+          if (valid.length > 0) {
+            const { registerPluginEntities } = await import("@atlas/api/lib/semantic");
+            registerPluginEntities(plugin.id, valid);
+            log.info({ pluginId: plugin.id, entityCount: valid.length }, "Plugin entities registered");
+          }
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        entityFailures.push({ pluginId: plugin.id, error: msg });
+        log.error(
+          { pluginId: plugin.id, err: err instanceof Error ? err : new Error(String(err)) },
+          "Failed to resolve plugin entities — connection still wired",
+        );
+      }
+    }
+
+    // Collect dialect hints
+    if (typeof plugin.dialect === "string" && plugin.dialect.trim()) {
+      dialectHints.push({ pluginId: plugin.id, dialect: plugin.dialect });
+    }
+  }
+
+  return { wired, failed, dialectHints, entityFailures };
+}
+
+/**
+ * For each healthy action plugin, register each PluginAction as an AtlasTool
+ * in the ToolRegistry.
+ */
+export async function wireActionPlugins(
+  pluginRegistry: PluginRegistry,
+  toolRegistry?: ToolRegistry,
+): Promise<{ wired: string[]; failed: Array<{ pluginId: string; error: string }> }> {
+  const registry = toolRegistry ?? (await import("@atlas/api/lib/tools/registry")).defaultRegistry;
+  const actionPlugins = pluginRegistry.getByType("action");
+  const wired: string[] = [];
+  const failed: Array<{ pluginId: string; error: string }> = [];
+
+  for (const plugin of actionPlugins) {
+    if (!hasActions(plugin)) {
+      log.warn({ pluginId: plugin.id }, "Action plugin missing actions array — skipped");
+      continue;
+    }
+    for (const action of plugin.actions) {
+      try {
+        registry.register(action as unknown as AtlasTool);
+        wired.push(action.name);
+        log.info({ pluginId: plugin.id, action: action.name }, "Action plugin tool wired");
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        failed.push({ pluginId: plugin.id, error: msg });
+        log.error(
+          { pluginId: plugin.id, action: action.name, err: err instanceof Error ? err : new Error(String(err)) },
+          "Failed to wire action plugin tool",
+        );
+      }
+    }
+  }
+
+  return { wired, failed };
+}
+
+/**
+ * For each healthy interaction plugin, call `routes(app)` to mount Hono routes.
+ */
+export async function wireInteractionPlugins(
+  pluginRegistry: PluginRegistry,
+  app: unknown,
+): Promise<{ wired: string[]; failed: Array<{ pluginId: string; error: string }> }> {
+  const interactionPlugins = pluginRegistry.getByType("interaction");
+  const wired: string[] = [];
+  const failed: Array<{ pluginId: string; error: string }> = [];
+
+  for (const plugin of interactionPlugins) {
+    if (!hasRoutes(plugin)) {
+      log.debug({ pluginId: plugin.id }, "Interaction plugin has no routes — skipping route wiring");
+      continue;
+    }
+    try {
+      // Scope plugin routes under /api/plugins/:pluginId to prevent auth bypass
+      const { Hono } = await import("hono");
+      const subApp = new Hono();
+      plugin.routes(subApp);
+      (app as { route(path: string, app: unknown): void }).route(`/api/plugins/${plugin.id}`, subApp);
+      wired.push(plugin.id);
+      log.info({ pluginId: plugin.id, prefix: `/api/plugins/${plugin.id}` }, "Interaction plugin routes mounted");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      failed.push({ pluginId: plugin.id, error: msg });
+      log.error(
+        { pluginId: plugin.id, err: err instanceof Error ? err : new Error(String(err)) },
+        "Failed to wire interaction plugin routes",
+      );
+    }
+  }
+
+  return { wired, failed };
+}
+
+/**
+ * For each healthy context plugin, call `contextProvider.load()` and collect
+ * the returned text fragments. Fragments are injected into the agent system
+ * prompt to provide additional context from plugins.
+ */
+export async function wireContextPlugins(
+  pluginRegistry: PluginRegistry,
+): Promise<{ fragments: string[]; failed: Array<{ pluginId: string; error: string }> }> {
+  const contextPlugins = pluginRegistry.getByType("context");
+  const fragments: string[] = [];
+  const failed: Array<{ pluginId: string; error: string }> = [];
+
+  for (const plugin of contextPlugins) {
+    if (!hasContextProvider(plugin)) {
+      log.warn({ pluginId: plugin.id }, "Context plugin missing contextProvider — skipped");
+      continue;
+    }
+    try {
+      const fragment = await plugin.contextProvider.load();
+      if (fragment.trim()) {
+        fragments.push(fragment);
+      }
+      log.info({ pluginId: plugin.id, fragmentLength: fragment.length }, "Context plugin loaded");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      failed.push({ pluginId: plugin.id, error: msg });
+      log.error(
+        { pluginId: plugin.id, err: err instanceof Error ? err : new Error(String(err)) },
+        "Failed to load context plugin",
+      );
+    }
+  }
+
+  return { fragments, failed };
+}

package/templates/nextjs-standalone/src/lib/providers.ts

@@ -0,0 +1,102 @@
+/**
+ * Multi-provider LLM configuration.
+ *
+ * Set ATLAS_PROVIDER and the corresponding API key in your .env.
+ * Supports Anthropic, OpenAI, AWS Bedrock, Ollama, and Vercel AI Gateway.
+ */
+
+import { anthropic } from "@ai-sdk/anthropic";
+import { createOpenAI, openai } from "@ai-sdk/openai";
+import { bedrock } from "@ai-sdk/amazon-bedrock";
+import { bedrockAnthropic } from "@ai-sdk/amazon-bedrock/anthropic";
+import { gateway } from "ai";
+import type { LanguageModel } from "ai";
+
+/** Provider strings accepted in ATLAS_PROVIDER. */
+type ConfigProvider = "anthropic" | "openai" | "bedrock" | "ollama" | "gateway";
+
+/** Resolved provider type (bedrock splits into bedrock vs bedrock-anthropic). */
+export type ProviderType = ConfigProvider | "bedrock-anthropic";
+
+const VALID_PROVIDERS: ReadonlySet<ConfigProvider> = new Set([
+  "anthropic",
+  "openai",
+  "bedrock",
+  "ollama",
+  "gateway",
+]);
+
+const PROVIDER_DEFAULTS: Record<ConfigProvider, string> = {
+  anthropic: "claude-opus-4-6",
+  openai: "gpt-4o",
+  bedrock: "anthropic.claude-opus-4-6-v1:0",
+  ollama: "llama3.1",
+  gateway: "anthropic/claude-opus-4.6",
+};
+
+function isBedrockAnthropicModel(modelId: string): boolean {
+  return modelId.includes("anthropic") || modelId.includes("claude");
+}
+
+/**
+ * Read and validate ATLAS_PROVIDER / ATLAS_MODEL from env.
+ * Returns the validated config provider string and the resolved model ID.
+ */
+function resolveProvider(): { provider: ConfigProvider; modelId: string } {
+  const raw = process.env.ATLAS_PROVIDER ?? "anthropic";
+  if (!VALID_PROVIDERS.has(raw as ConfigProvider)) {
+    throw new Error(
+      `Unknown provider "${raw}". Supported: ${[...VALID_PROVIDERS].join(", ")}`
+    );
+  }
+  // Safe: validated by VALID_PROVIDERS.has() above
+  const provider = raw as ConfigProvider;
+  const modelId = process.env.ATLAS_MODEL ?? PROVIDER_DEFAULTS[provider];
+  return { provider, modelId };
+}
+
+export function getProviderType(): ProviderType {
+  const { provider, modelId } = resolveProvider();
+  if (provider === "bedrock" && isBedrockAnthropicModel(modelId)) {
+    return "bedrock-anthropic";
+  }
+  return provider;
+}
+
+export function getModel(): LanguageModel {
+  const { provider, modelId } = resolveProvider();
+
+  switch (provider) {
+    case "anthropic":
+      return anthropic(modelId);
+
+    case "openai":
+      return openai(modelId);
+
+    case "bedrock":
+      return isBedrockAnthropicModel(modelId)
+        ? bedrockAnthropic(modelId)
+        : bedrock(modelId);
+
+    case "ollama": {
+      const ollama = createOpenAI({
+        baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/v1",
+      });
+      return ollama(modelId);
+    }
+
+    case "gateway":
+      if (!process.env.AI_GATEWAY_API_KEY) {
+        throw new Error(
+          "AI_GATEWAY_API_KEY is not set. The gateway provider requires an API key. " +
+            "Create one at https://vercel.com/~/ai/api-keys and set it in your .env file."
+        );
+      }
+      return gateway(modelId);
+
+    default: {
+      const _exhaustive: never = provider;
+      throw new Error(`Unknown provider "${_exhaustive}"`);
+    }
+  }
+}