@useatlas/create 0.0.1 → 0.0.3

package/templates/docker/src/lib/plugins/__tests__/wiring.test.ts

@@ -1,7 +1,8 @@
 import { describe, test, expect, beforeEach, mock } from "bun:test";
 import { PluginRegistry } from "../registry";
 import type { PluginLike, PluginContextLike } from "../registry";
-import { wireDatasourcePlugins, wireActionPlugins, wireInteractionPlugins, wireContextPlugins } from "../wiring";
+import { wireDatasourcePlugins, wireActionPlugins, wireInteractionPlugins, wireContextPlugins, wireSandboxPlugins } from "../wiring";
+import type { SandboxExecBackend } from "../wiring";
 
 const minimalCtx: PluginContextLike = {
   db: null,
@@ -15,9 +16,9 @@ const minimalCtx: PluginContextLike = {
 
 function makeMockConnectionRegistry() {
   return {
-    registered: [] as { id: string; conn: unknown; dbType: string; description?: string; validate?: unknown }[],
-    async registerDirect(id: string, conn: unknown, dbType: string, description?: string, validate?: unknown) {
-      this.registered.push({ id, conn, dbType, description, validate });
+    registered: [] as { id: string; conn: unknown; dbType: string; description?: string; validate?: unknown; meta?: unknown }[],
+    registerDirect(id: string, conn: unknown, dbType: string, description?: string, validate?: unknown, meta?: unknown) {
+      this.registered.push({ id, conn, dbType, description, validate, meta });
     },
   };
 }
@@ -49,7 +50,7 @@ function makeDatasourcePlugin(
   };
   return {
     id,
-    type: "datasource",
+    types: ["datasource"],
     version: "1.0.0",
     connection: {
       create: () => conn,
@@ -66,7 +67,7 @@ function makeDatasourcePlugin(
 function makeActionPlugin(id: string, opts?: { unhealthy?: boolean }): PluginLike {
   return {
     id,
-    type: "action",
+    types: ["action"],
     version: "1.0.0",
     actions: [
       {
@@ -88,7 +89,7 @@ function makeActionPlugin(id: string, opts?: { unhealthy?: boolean }): PluginLik
 function makeInteractionPlugin(id: string, routesFn: (app: unknown) => void, opts?: { unhealthy?: boolean }): PluginLike {
   return {
     id,
-    type: "interaction",
+    types: ["interaction"],
     version: "1.0.0",
     routes: routesFn,
     ...(opts?.unhealthy
@@ -127,7 +128,7 @@ describe("wireDatasourcePlugins", () => {
     const validator = (q: string) => ({ valid: /^SELECT/i.test(q) });
     const plugin: PluginLike = {
       id: "validated-ds",
-      type: "datasource",
+      types: ["datasource"],
       version: "1.0.0",
       connection: {
         create: () => ({ query: async () => ({ columns: [], rows: [] }), close: async () => {} }),
@@ -147,6 +148,47 @@ describe("wireDatasourcePlugins", () => {
     expect(connRegistry.registered[0].validate).toBe(validator);
   });
 
+  test("passes parserDialect and forbiddenPatterns through meta", async () => {
+    const patterns = [/^\s*(KILL)\b/i];
+    const plugin: PluginLike = {
+      id: "meta-ds",
+      types: ["datasource"],
+      version: "1.0.0",
+      connection: {
+        create: () => ({ query: async () => ({ columns: [], rows: [] }), close: async () => {} }),
+        dbType: "clickhouse",
+        parserDialect: "PostgresQL",
+        forbiddenPatterns: patterns,
+      },
+    };
+    registry.register(plugin);
+    await registry.initializeAll(minimalCtx);
+
+    await wireDatasourcePlugins(
+      registry,
+      connRegistry as unknown as import("@atlas/api/lib/db/connection").ConnectionRegistry,
+    );
+
+    expect(connRegistry.registered).toHaveLength(1);
+    expect(connRegistry.registered[0].meta).toEqual({
+      parserDialect: "PostgresQL",
+      forbiddenPatterns: patterns,
+    });
+  });
+
+  test("passes undefined meta when no parserDialect or forbiddenPatterns", async () => {
+    registry.register(makeDatasourcePlugin("plain-meta"));
+    await registry.initializeAll(minimalCtx);
+
+    await wireDatasourcePlugins(
+      registry,
+      connRegistry as unknown as import("@atlas/api/lib/db/connection").ConnectionRegistry,
+    );
+
+    expect(connRegistry.registered).toHaveLength(1);
+    expect(connRegistry.registered[0].meta).toBeUndefined();
+  });
+
   test("passes undefined validate when not provided", async () => {
     registry.register(makeDatasourcePlugin("plain-ds"));
     await registry.initializeAll(minimalCtx);
@@ -179,7 +221,7 @@ describe("wireDatasourcePlugins", () => {
   test("continues when one create() throws and returns failures", async () => {
     const failingPlugin: PluginLike = {
       id: "failing-ds",
-      type: "datasource",
+      types: ["datasource"],
       version: "1.0.0",
       connection: {
         create: () => { throw new Error("conn failed"); },
@@ -389,7 +431,7 @@ describe("wireActionPlugins", () => {
   test("registers all actions from a multi-action plugin", async () => {
     const plugin: PluginLike = {
       id: "multi-action",
-      type: "action",
+      types: ["action"],
       version: "1.0.0",
       actions: [
         { name: "action-a", description: "A", tool: {}, actionType: "t", reversible: false, defaultApproval: "manual", requiredCredentials: [] },
@@ -421,7 +463,7 @@ describe("wireActionPlugins", () => {
 
     const plugin: PluginLike = {
       id: "fail-action",
-      type: "action",
+      types: ["action"],
       version: "1.0.0",
       actions: [
         { name: "fail-action", description: "Fails", tool: {}, actionType: "t", reversible: false, defaultApproval: "manual", requiredCredentials: [] },
@@ -485,7 +527,7 @@ describe("wireInteractionPlugins", () => {
     const fakeApp = { route: mock(() => {}) };
     const routelessPlugin: PluginLike = {
       id: "stdio-interaction",
-      type: "interaction",
+      types: ["interaction"],
       version: "1.0.0",
       // No routes property — like MCP stdio transport
     };
@@ -506,7 +548,7 @@ describe("wireInteractionPlugins", () => {
 function makeContextPlugin(id: string, loadFn: () => Promise<string>, opts?: { unhealthy?: boolean }): PluginLike {
   return {
     id,
-    type: "context",
+    types: ["context"],
     version: "1.0.0",
     contextProvider: { load: loadFn },
     ...(opts?.unhealthy
@@ -571,7 +613,7 @@ describe("wireContextPlugins", () => {
   test("skips context plugins without contextProvider", async () => {
     const noProvider: PluginLike = {
       id: "no-provider",
-      type: "context",
+      types: ["context"],
       version: "1.0.0",
     };
     registry.register(noProvider);
@@ -583,3 +625,175 @@ describe("wireContextPlugins", () => {
     expect(result.failed).toEqual([]);
   });
 });
+
+// --- wireSandboxPlugins ---
+
+function makeMockBackend(tag: string): SandboxExecBackend {
+  return {
+    exec: async (command: string) => ({
+      stdout: `[${tag}] ${command}`,
+      stderr: "",
+      exitCode: 0,
+    }),
+  };
+}
+
+function makeSandboxPlugin(
+  id: string,
+  opts?: { priority?: number; createFn?: (root: string) => Promise<SandboxExecBackend> | SandboxExecBackend; unhealthy?: boolean },
+): PluginLike {
+  return {
+    id,
+    types: ["sandbox"],
+    version: "1.0.0",
+    sandbox: {
+      create: opts?.createFn ?? (async () => makeMockBackend(id)),
+      ...(opts?.priority !== undefined ? { priority: opts.priority } : {}),
+    },
+    ...(opts?.unhealthy
+      ? { initialize: async () => { throw new Error("fail"); } }
+      : {}),
+  };
+}
+
+describe("wireSandboxPlugins", () => {
+  let registry: PluginRegistry;
+
+  beforeEach(() => {
+    registry = new PluginRegistry();
+  });
+
+  test("returns backend from a single sandbox plugin", async () => {
+    registry.register(makeSandboxPlugin("my-sandbox"));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.backend).not.toBeNull();
+    expect(result.pluginId).toBe("my-sandbox");
+    expect(result.failed).toEqual([]);
+  });
+
+  test("selects highest-priority plugin", async () => {
+    registry.register(makeSandboxPlugin("low", { priority: 40 }));
+    registry.register(makeSandboxPlugin("high", { priority: 90 }));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.pluginId).toBe("high");
+    const output = await result.backend!.exec("ls");
+    expect(output.stdout).toContain("[high]");
+  });
+
+  test("uses default priority (60) when omitted", async () => {
+    registry.register(makeSandboxPlugin("explicit-low", { priority: 50 }));
+    registry.register(makeSandboxPlugin("default-priority")); // no priority → 60
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.pluginId).toBe("default-priority");
+  });
+
+  test("falls through to next plugin when create() throws", async () => {
+    registry.register(makeSandboxPlugin("broken", {
+      priority: 90,
+      createFn: async () => { throw new Error("init failed"); },
+    }));
+    registry.register(makeSandboxPlugin("working", { priority: 50 }));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.pluginId).toBe("working");
+    expect(result.failed).toHaveLength(1);
+    expect(result.failed[0].pluginId).toBe("broken");
+    expect(result.failed[0].error).toBe("init failed");
+  });
+
+  test("returns null when all plugins fail", async () => {
+    registry.register(makeSandboxPlugin("broken-1", {
+      createFn: async () => { throw new Error("fail 1"); },
+    }));
+    registry.register(makeSandboxPlugin("broken-2", {
+      createFn: async () => { throw new Error("fail 2"); },
+    }));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.backend).toBeNull();
+    expect(result.pluginId).toBeNull();
+    expect(result.failed).toHaveLength(2);
+  });
+
+  test("returns null when no sandbox plugins registered", async () => {
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.backend).toBeNull();
+    expect(result.pluginId).toBeNull();
+    expect(result.failed).toEqual([]);
+  });
+
+  test("skips unhealthy sandbox plugins", async () => {
+    registry.register(makeSandboxPlugin("healthy"));
+    registry.register(makeSandboxPlugin("unhealthy", { unhealthy: true }));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.pluginId).toBe("healthy");
+    expect(result.failed).toEqual([]);
+  });
+
+  test("skips sandbox plugins missing sandbox.create()", async () => {
+    const noCreate: PluginLike = {
+      id: "no-create",
+      types: ["sandbox"],
+      version: "1.0.0",
+      // No sandbox property
+    };
+    registry.register(noCreate);
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    expect(result.backend).toBeNull();
+    expect(result.pluginId).toBeNull();
+    expect(result.failed).toEqual([]);
+  });
+
+  test("passes semanticRoot to sandbox.create()", async () => {
+    let receivedRoot: string | undefined;
+    registry.register(makeSandboxPlugin("root-check", {
+      createFn: async (root: string) => {
+        receivedRoot = root;
+        return makeMockBackend("root-check");
+      },
+    }));
+    await registry.initializeAll(minimalCtx);
+
+    await wireSandboxPlugins(registry, "/my/custom/semantic");
+
+    expect(receivedRoot).toBe("/my/custom/semantic");
+  });
+
+  test("rejects backend missing exec method from create()", async () => {
+    registry.register(makeSandboxPlugin("bad-backend", {
+      createFn: async () => ({} as SandboxExecBackend),
+    }));
+    registry.register(makeSandboxPlugin("good-backend", { priority: 40 }));
+    await registry.initializeAll(minimalCtx);
+
+    const result = await wireSandboxPlugins(registry, "/semantic");
+
+    // bad-backend has default priority (60) > good-backend (40), tried first but rejected
+    expect(result.pluginId).toBe("good-backend");
+    expect(result.failed).toHaveLength(1);
+    expect(result.failed[0].pluginId).toBe("bad-backend");
+    expect(result.failed[0].error).toContain("missing exec method");
+  });
+});

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

@@ -4,6 +4,9 @@
 
 export { plugins, PluginRegistry } from "./registry";
 export type { PluginLike, PluginContextLike, PluginHealthResult, PluginType, PluginStatus, PluginDescription } from "./registry";
-export { wireDatasourcePlugins, wireActionPlugins, wireInteractionPlugins, wireContextPlugins } from "./wiring";
+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";

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

@@ -14,7 +14,7 @@ import { createLogger } from "@atlas/api/lib/logger";
 const log = createLogger("plugins:migrate");
 
 // ---------------------------------------------------------------------------
-// Types (structural — no import from @atlas/plugin-sdk)
+// Types (structural — no import from @useatlas/plugin-sdk)
 // ---------------------------------------------------------------------------
 
 interface FieldDef {
@@ -273,6 +273,109 @@ export async function applyMigrations(
   return { applied, skipped };
 }
 
+// ---------------------------------------------------------------------------
+// Column migrations (ALTER TABLE ADD COLUMN)
+// ---------------------------------------------------------------------------
+
+/**
+ * Query the actual columns for a given table from information_schema.
+ * Returns a Set of lowercase column names.
+ */
+async function getExistingColumns(db: MigrateDB, tableName: string): Promise<Set<string>> {
+  const result = await db.query(
+    "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = $1",
+    [tableName],
+  );
+  return new Set(result.rows.map((r) => String(r.column_name).toLowerCase()));
+}
+
+/**
+ * Generate ALTER TABLE ADD COLUMN IF NOT EXISTS statements for fields
+ * that exist in the plugin schema but not in the actual database table.
+ *
+ * Column detection queries `information_schema.columns` in the `public`
+ * schema. Only handles column additions — column removal and type
+ * changes are not supported (require manual migration).
+ */
+export async function generateColumnMigrations(
+  db: MigrateDB,
+  plugins: PluginWithSchema[],
+): Promise<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);
+
+      // Check if table exists at all — skip if it doesn't (CREATE TABLE will handle it)
+      const existing = await getExistingColumns(db, prefixed);
+      if (existing.size === 0) {
+        log.debug({ table: prefixed, pluginId: plugin.id }, "Table not in information_schema — skipping column migration");
+        continue;
+      }
+
+      for (const [fieldName, fieldDef] of Object.entries(tableDef.fields)) {
+        if (existing.has(fieldName.toLowerCase())) continue;
+
+        let colDef: string;
+        try {
+          colDef = fieldToSQL(fieldName, fieldDef);
+        } catch (err) {
+          throw new Error(
+            `Plugin "${plugin.id}", table "${prefixed}": ${err instanceof Error ? err.message : String(err)}`,
+            { cause: err },
+          );
+        }
+        const sql = `ALTER TABLE "${prefixed}" ADD COLUMN IF NOT EXISTS ${colDef};`;
+
+        statements.push({
+          pluginId: plugin.id,
+          tableName,
+          prefixedName: prefixed,
+          sql,
+          hash: hashSQL(sql),
+        });
+      }
+    }
+  }
+
+  return statements;
+}
+
+// ---------------------------------------------------------------------------
+// High-level orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Run all plugin schema migrations: CREATE TABLE for new tables, then
+ * ALTER TABLE ADD COLUMN for new fields on existing tables.
+ *
+ * Idempotent — safe to call on every startup.
+ */
+export async function runPluginMigrations(
+  db: MigrateDB,
+  plugins: PluginWithSchema[],
+): Promise<{ applied: string[]; skipped: string[] }> {
+  // Phase 1: CREATE TABLE
+  const createStatements = generateMigrationSQL(plugins);
+  const createResult = await applyMigrations(db, createStatements);
+
+  // Phase 2: ALTER TABLE ADD COLUMN (for tables that already existed or were just created)
+  const columnStatements = await generateColumnMigrations(db, plugins);
+  if (columnStatements.length === 0) {
+    return createResult;
+  }
+
+  const columnResult = await applyMigrations(db, columnStatements);
+
+  return {
+    applied: [...createResult.applied, ...columnResult.applied],
+    skipped: [...createResult.skipped, ...columnResult.skipped],
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Diff: compare declared schema vs actual tables
 // ---------------------------------------------------------------------------

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

@@ -3,7 +3,7 @@
  *
  * 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`.
+ * depend on `@useatlas/plugin-sdk`.
  */
 
 import { createLogger } from "@atlas/api/lib/logger";
@@ -11,7 +11,7 @@ import { createLogger } from "@atlas/api/lib/logger";
 const log = createLogger("plugins");
 
 // ---------------------------------------------------------------------------
-// Structural interfaces (no import from @atlas/plugin-sdk)
+// Structural interfaces (no import from @useatlas/plugin-sdk)
 // ---------------------------------------------------------------------------
 
 export interface PluginHealthResult {
@@ -41,7 +41,8 @@ export interface PluginContextLike {
  */
 export interface PluginLike {
   readonly id: string;
-  readonly type: PluginType;
+  /** Plugin type(s). A plugin can implement multiple types. */
+  readonly types: readonly PluginType[];
   readonly version: string;
   readonly name?: string;
   initialize?(ctx: PluginContextLike): Promise<void>;
@@ -59,7 +60,7 @@ interface PluginEntry {
 
 export interface PluginDescription {
   id: string;
-  type: PluginType;
+  types: readonly PluginType[];
   version: string;
   name: string;
   status: PluginStatus;
@@ -83,7 +84,7 @@ export class PluginRegistry {
     }
     this.idSet.add(plugin.id);
     this.entries.push({ plugin, status: "registered" });
-    log.info({ pluginId: plugin.id, type: plugin.type }, "Plugin registered");
+    log.info({ pluginId: plugin.id, types: plugin.types }, "Plugin registered");
   }
 
   /**
@@ -190,13 +191,18 @@ export class PluginRegistry {
     return this.entries.find((e) => e.plugin.id === id)?.status;
   }
 
-  /** Return plugins of the given type that are currently healthy. */
+  /** Return plugins whose types array includes the given type and are currently healthy. */
   getByType(type: PluginType): PluginLike[] {
     return this.entries
-      .filter((e) => e.plugin.type === type && e.status === "healthy")
+      .filter((e) => e.plugin.types.includes(type) && e.status === "healthy")
       .map((e) => e.plugin);
   }
 
+  /** Return all registered plugins regardless of status (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). */
   getAllHealthy(): PluginLike[] {
     return this.entries
@@ -208,7 +214,7 @@ export class PluginRegistry {
   describe(): PluginDescription[] {
     return this.entries.map((e) => ({
       id: e.plugin.id,
-      type: e.plugin.type,
+      types: e.plugin.types,
       version: e.plugin.version,
       name: e.plugin.name ?? e.plugin.id,
       status: e.status,