@useatlas/create 0.0.5 → 0.0.7

package/templates/nextjs-standalone/src/lib/effect/sql.ts

@@ -0,0 +1,178 @@
+/**
+ * Atlas SQL Client as Effect Service (P11a).
+ *
+ * Wraps the existing DBConnection interface from ConnectionRegistry
+ * in an Effect Context.Tag so it can be yielded from Effect programs.
+ *
+ * This is a bridge layer — the actual DB connections are still managed
+ * by ConnectionRegistry (raw pg/mysql2 pools). P11b will migrate to
+ * native @effect/sql-pg and @effect/sql-mysql2 clients.
+ *
+ * @example
+ * ```ts
+ * import { AtlasSqlClient } from "@atlas/api/lib/effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const sql = yield* AtlasSqlClient;
+ *   const result = yield* sql.query("SELECT count(*) FROM users");
+ *   return result.rows;
+ * });
+ * ```
+ */
+
+import { Context, Effect, Layer } from "effect";
+import { ConnectionRegistry } from "./services";
+
+// ── Service interface ────────────────────────────────────────────────
+
+/**
+ * Atlas SQL client service — provides query execution.
+ *
+ * Bridges the existing DBConnection.query() to Effect Context.
+ * The query method returns an Effect that succeeds with { columns, rows }
+ * or fails with an Error.
+ */
+export interface AtlasSqlClientShape {
+  /** Execute a SQL query and return { columns, rows }. */
+  query(
+    sql: string,
+    timeoutMs?: number,
+  ): Effect.Effect<
+    { columns: string[]; rows: Record<string, unknown>[] },
+    Error
+  >;
+  /** The database type of the current connection. */
+  readonly dbType: string;
+  /** The connection ID being used. */
+  readonly connectionId: string;
+}
+
+// ── Context.Tag ──────────────────────────────────────────────────────
+
+export class AtlasSqlClient extends Context.Tag("AtlasSqlClient")<
+  AtlasSqlClient,
+  AtlasSqlClientShape
+>() {}
+
+// ── Live Layer ───────────────────────────────────────────────────────
+
+/**
+ * Create a Live layer for AtlasSqlClient from the ConnectionRegistry.
+ *
+ * Reads the specified connection (or default) from the registry and
+ * wraps its query() method as an Effect.
+ *
+ * @param connectionId - Connection ID to use. Defaults to "default".
+ */
+export function makeAtlasSqlClientLive(
+  connectionId?: string,
+): Layer.Layer<AtlasSqlClient, Error, ConnectionRegistry> {
+  return Layer.effect(
+    AtlasSqlClient,
+    Effect.gen(function* () {
+      const registry = yield* ConnectionRegistry;
+      const id = connectionId ?? "default";
+
+      if (!registry.has(id)) {
+        return yield* Effect.fail(
+          new Error(`Connection "${id}" not found in registry`),
+        );
+      }
+
+      const conn = registry.get(id);
+      const dbType = registry.getDBType(id);
+
+      const service: AtlasSqlClientShape = {
+        query: (sql, timeoutMs) =>
+          Effect.tryPromise({
+            try: () => conn.query(sql, timeoutMs),
+            catch: (err) =>
+              new Error(
+                `SQL query failed: ${err instanceof Error ? err.message : String(err)}`,
+              ),
+          }),
+        dbType,
+        connectionId: id,
+      };
+
+      return service;
+    }),
+  );
+}
+
+/**
+ * Create a Live layer for AtlasSqlClient for an org-scoped connection.
+ *
+ * Uses ConnectionRegistry.getForOrg() to get the org-specific pool.
+ */
+export function makeOrgSqlClientLive(
+  orgId: string,
+  connectionId?: string,
+): Layer.Layer<AtlasSqlClient, Error, ConnectionRegistry> {
+  return Layer.effect(
+    AtlasSqlClient,
+    Effect.gen(function* () {
+      const registry = yield* ConnectionRegistry;
+      const id = connectionId ?? "default";
+      const conn = registry.getForOrg(orgId, connectionId);
+      // Use the base connection ID for dbType lookup — org pools inherit
+      // the database type from their parent connection, not from the org ID.
+      const dbType = registry.getDBType(id);
+
+      const service: AtlasSqlClientShape = {
+        query: (sql, timeoutMs) =>
+          Effect.tryPromise({
+            try: () => conn.query(sql, timeoutMs),
+            catch: (err) =>
+              new Error(
+                `SQL query failed: ${err instanceof Error ? err.message : String(err)}`,
+              ),
+          }),
+        dbType,
+        connectionId: id,
+      };
+
+      return service;
+    }),
+  );
+}
+
+// ── Test helper ──────────────────────────────────────────────────────
+
+/**
+ * Create a test Layer for AtlasSqlClient.
+ *
+ * Provides a mock SQL client with configurable query results.
+ * Does NOT require ConnectionRegistry — fully self-contained.
+ *
+ * @example
+ * ```ts
+ * const TestLayer = createSqlClientTestLayer({
+ *   queryResult: { columns: ["count"], rows: [{ count: 42 }] },
+ * });
+ *
+ * const result = await runTest(
+ *   Effect.gen(function* () {
+ *     const sql = yield* AtlasSqlClient;
+ *     return yield* sql.query("SELECT count(*) FROM users");
+ *   }),
+ * );
+ * ```
+ */
+export function createSqlClientTestLayer(options?: {
+  queryResult?: { columns: string[]; rows: Record<string, unknown>[] };
+  queryError?: Error;
+  dbType?: string;
+  connectionId?: string;
+}): Layer.Layer<AtlasSqlClient> {
+  return Layer.succeed(AtlasSqlClient, {
+    query: (_sql, _timeoutMs) =>
+      options?.queryError
+        ? Effect.fail(options.queryError)
+        : Effect.succeed(
+            options?.queryResult ?? { columns: [], rows: [] },
+          ),
+    dbType: options?.dbType ?? "postgres",
+    connectionId: options?.connectionId ?? "default",
+  });
+}

package/templates/nextjs-standalone/src/lib/effect/toolkit.ts

@@ -0,0 +1,123 @@
+/**
+ * Atlas Toolkit as Effect Service (P10b foundation).
+ *
+ * Wraps the existing ToolRegistry in an Effect Context.Tag so it can
+ * be yielded from Effect programs. The toolkit provides tool descriptions
+ * for the system prompt and the tool set for the agent loop.
+ *
+ * This is a bridge layer — the actual tools are still Vercel AI SDK
+ * ToolSet entries. P10c will migrate tool definitions to @effect/ai
+ * AiTool.make() and create a native AiToolkit.
+ *
+ * @example
+ * ```ts
+ * import { AtlasToolkit } from "@atlas/api/lib/effect";
+ *
+ * const program = Effect.gen(function* () {
+ *   const toolkit = yield* AtlasToolkit;
+ *   const tools = toolkit.getAll();       // ToolSet for streamText
+ *   const desc = toolkit.describe();      // System prompt fragment
+ *   return { toolCount: toolkit.size };
+ * });
+ * ```
+ */
+
+import { Context, Effect, Layer } from "effect";
+import type { ToolSet } from "ai";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("effect:toolkit");
+
+// ── Service interface ────────────────────────────────────────────────
+
+/**
+ * Atlas toolkit service — provides tools for the agent loop.
+ *
+ * Bridges the existing ToolRegistry to Effect Context.
+ */
+export interface AtlasToolkitShape {
+  /** Get all tools as a Vercel AI SDK ToolSet. */
+  getAll(): ToolSet;
+  /** Get tool descriptions for the system prompt. */
+  describe(): string;
+  /** Number of registered tools. */
+  readonly size: number;
+  /** Check if a tool is registered. */
+  has(name: string): boolean;
+}
+
+// ── Context.Tag ──────────────────────────────────────────────────────
+
+export class AtlasToolkit extends Context.Tag("AtlasToolkit")<
+  AtlasToolkit,
+  AtlasToolkitShape
+>() {}
+
+// ── Live Layer ───────────────────────────────────────────────────────
+
+/**
+ * Create the Live layer for AtlasToolkit.
+ *
+ * Builds the tool registry (including Python and action tools based on
+ * config) and wraps it as an Effect service.
+ */
+export function makeAtlasToolkitLive(options?: {
+  includeActions?: boolean;
+}): Layer.Layer<AtlasToolkit, Error> {
+  return Layer.effect(
+    AtlasToolkit,
+    Effect.gen(function* () {
+      const { registry, warnings } = yield* Effect.tryPromise({
+        try: async () => {
+          const { buildRegistry } = await import(
+            "@atlas/api/lib/tools/registry"
+          );
+          return buildRegistry(options);
+        },
+        catch: (err) =>
+          new Error(
+            `Tool registry build failed: ${err instanceof Error ? err.message : String(err)}`,
+          ),
+      });
+
+      if (warnings.length > 0) {
+        log.warn({ warnings }, "Tool registry built with warnings");
+      }
+
+      log.info({ tools: registry.size }, "Atlas toolkit ready");
+
+      return {
+        getAll: () => registry.getAll(),
+        describe: () => registry.describe(),
+        get size() {
+          return registry.size;
+        },
+        has: (name) => registry.get(name) !== undefined,
+      } satisfies AtlasToolkitShape;
+    }),
+  );
+}
+
+/** Default Live layer using default buildRegistry options. */
+export const AtlasToolkitLive: ReturnType<typeof makeAtlasToolkitLive> =
+  makeAtlasToolkitLive();
+
+// ── Test helper ──────────────────────────────────────────────────────
+
+/**
+ * Create a test Layer for AtlasToolkit.
+ *
+ * Provides a mock toolkit with configurable tools. Defaults to empty.
+ */
+export function createToolkitTestLayer(
+  partial: Partial<AtlasToolkitShape> = {},
+): Layer.Layer<AtlasToolkit> {
+  return Layer.succeed(AtlasToolkit, {
+    getAll: partial.getAll ?? (() => ({})),
+    describe: partial.describe ?? (() => ""),
+    get size() {
+      return partial.size ?? 0;
+    },
+    has: partial.has ?? (() => false),
+  });
+}

package/templates/nextjs-standalone/src/lib/email/delivery.ts

@@ -0,0 +1,232 @@
+/**
+ * Email delivery abstraction.
+ *
+ * Supports delivery backends (checked in order):
+ * 1. DB-stored email config per org (when orgId is provided).
+ *    SendGrid and Postmark are called directly via their APIs.
+ *    SMTP and SES require ATLAS_SMTP_URL as an HTTP bridge.
+ * 2. Webhook via ATLAS_SMTP_URL (POST JSON to any email API endpoint)
+ * 3. Resend API via RESEND_API_KEY (existing scheduler integration)
+ * 4. Logging fallback when nothing is configured (dev mode).
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("email-delivery");
+
+export interface EmailMessage {
+  to: string;
+  subject: string;
+  html: string;
+}
+
+export interface DeliveryResult {
+  success: boolean;
+  provider: "sendgrid" | "postmark" | "smtp" | "ses" | "webhook" | "resend" | "log";
+  error?: string;
+}
+
+/**
+ * Get the email transport config for an org from the internal database.
+ * Returns null if no DB config exists, if the internal DB is not available,
+ * or on any error during lookup (errors are logged at warn level to allow
+ * env-var fallback).
+ */
+export async function getEmailTransport(
+  orgId: string,
+): Promise<{ provider: string; senderAddress: string; config: Record<string, unknown> } | null> {
+  try {
+    const { getEmailInstallationByOrg } = await import("@atlas/api/lib/email/store");
+    const install = await getEmailInstallationByOrg(orgId);
+    if (install) {
+      return {
+        provider: install.provider,
+        senderAddress: install.sender_address,
+        config: install.config as unknown as Record<string, unknown>,
+      };
+    }
+  } catch (err) {
+    log.warn(
+      { orgId, err: err instanceof Error ? err.message : String(err) },
+      "Failed to load email transport from DB — falling back to env vars",
+    );
+  }
+  return null;
+}
+
+/**
+ * Send an email using the configured delivery backend.
+ *
+ * Priority: DB config (per-org) → ATLAS_SMTP_URL (webhook) → RESEND_API_KEY → console log (dev fallback).
+ *
+ * Pass `orgId` to enable DB-backed email config lookup. When omitted, falls back to env vars.
+ */
+export async function sendEmail(message: EmailMessage, orgId?: string): Promise<DeliveryResult> {
+  // 1. Try DB-stored config for the org
+  if (orgId) {
+    const transport = await getEmailTransport(orgId);
+    if (transport) {
+      return deliverViaTransport(message, transport);
+    }
+  }
+
+  const fromAddress = process.env.ATLAS_EMAIL_FROM ?? "Atlas <noreply@useatlas.dev>";
+
+  // 2. Webhook delivery (generic email API)
+  if (process.env.ATLAS_SMTP_URL) {
+    return deliverWebhook(message, fromAddress);
+  }
+
+  // 3. Resend API delivery (same provider as scheduler)
+  if (process.env.RESEND_API_KEY) {
+    return deliverResend(message, fromAddress);
+  }
+
+  // 4. Dev fallback — log instead of sending. Returns success: false so the email
+  // is not recorded as sent, allowing retry when a provider is configured.
+  log.warn(
+    { to: message.to, subject: message.subject },
+    "Email delivery skipped — no ATLAS_SMTP_URL or RESEND_API_KEY configured",
+  );
+  return { success: false, provider: "log", error: "No email delivery backend configured (set ATLAS_SMTP_URL or RESEND_API_KEY)" };
+}
+
+/**
+ * Deliver an email using a DB-stored transport config.
+ */
+async function deliverViaTransport(
+  message: EmailMessage,
+  transport: { provider: string; senderAddress: string; config: Record<string, unknown> },
+): Promise<DeliveryResult> {
+  const from = transport.senderAddress;
+
+  switch (transport.provider) {
+    case "sendgrid": {
+      const apiKey = transport.config.apiKey;
+      if (typeof apiKey !== "string") return { success: false, provider: "sendgrid", error: "Missing SendGrid API key in stored config" };
+      try {
+        const res = await fetch("https://api.sendgrid.com/v3/mail/send", {
+          method: "POST",
+          headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+          body: JSON.stringify({
+            personalizations: [{ to: [{ email: message.to }] }],
+            from: { email: from },
+            subject: message.subject,
+            content: [{ type: "text/html", value: message.html }],
+          }),
+          signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          log.error({ to: message.to, status: res.status }, "SendGrid delivery failed");
+          return { success: false, provider: "sendgrid", error: `SendGrid error (${res.status}): ${text.slice(0, 200)}` };
+        }
+        log.info({ to: message.to, subject: message.subject }, "Email sent via SendGrid (DB config)");
+        return { success: true, provider: "sendgrid" };
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        log.error({ to: message.to, err: error }, "SendGrid delivery error");
+        return { success: false, provider: "sendgrid", error };
+      }
+    }
+
+    case "postmark": {
+      const serverToken = transport.config.serverToken;
+      if (typeof serverToken !== "string") return { success: false, provider: "postmark", error: "Missing Postmark token in stored config" };
+      try {
+        const res = await fetch("https://api.postmarkapp.com/email", {
+          method: "POST",
+          headers: { "Content-Type": "application/json", "X-Postmark-Server-Token": serverToken },
+          body: JSON.stringify({ From: from, To: message.to, Subject: message.subject, HtmlBody: message.html }),
+          signal: AbortSignal.timeout(15_000),
+        });
+        if (!res.ok) {
+          const text = await res.text().catch(() => "");
+          log.error({ to: message.to, status: res.status }, "Postmark delivery failed");
+          return { success: false, provider: "postmark", error: `Postmark error (${res.status}): ${text.slice(0, 200)}` };
+        }
+        log.info({ to: message.to, subject: message.subject }, "Email sent via Postmark (DB config)");
+        return { success: true, provider: "postmark" };
+      } catch (err) {
+        const error = err instanceof Error ? err.message : String(err);
+        log.error({ to: message.to, err: error }, "Postmark delivery error");
+        return { success: false, provider: "postmark", error };
+      }
+    }
+
+    default:
+      // For smtp/ses, delegate to ATLAS_SMTP_URL webhook if available
+      if (process.env.ATLAS_SMTP_URL) {
+        return deliverWebhook(message, from);
+      }
+      log.warn({ to: message.to, provider: transport.provider }, "DB email config found but provider requires ATLAS_SMTP_URL bridge");
+      return { success: false, provider: "log", error: `${transport.provider} provider requires ATLAS_SMTP_URL bridge` };
+  }
+}
+
+/**
+ * Webhook delivery — POST JSON payload to ATLAS_SMTP_URL.
+ * Compatible with any email service that accepts JSON webhooks.
+ */
+async function deliverWebhook(message: EmailMessage, from: string): Promise<DeliveryResult> {
+  const url = process.env.ATLAS_SMTP_URL!;
+  try {
+    const resp = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        from,
+        to: message.to,
+        subject: message.subject,
+        html: message.html,
+      }),
+    });
+
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => "");
+      const error = `Webhook returned ${resp.status}: ${text.slice(0, 200)}`;
+      log.error({ to: message.to, status: resp.status }, "Webhook email delivery failed");
+      return { success: false, provider: "webhook", error };
+    }
+
+    log.info({ to: message.to, subject: message.subject }, "Email sent via webhook");
+    return { success: true, provider: "webhook" };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    log.error({ to: message.to, err: error }, "Webhook email delivery error");
+    return { success: false, provider: "webhook", error };
+  }
+}
+
+async function deliverResend(message: EmailMessage, from: string, apiKey?: string): Promise<DeliveryResult> {
+  const key = apiKey ?? process.env.RESEND_API_KEY;
+  try {
+    const resp = await fetch("https://api.resend.com/emails", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        from,
+        to: [message.to],
+        subject: message.subject,
+        html: message.html,
+      }),
+    });
+
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => "");
+      const error = `Resend API returned ${resp.status}: ${text.slice(0, 200)}`;
+      log.error({ to: message.to, status: resp.status, body: text.slice(0, 200) }, "Resend delivery failed");
+      return { success: false, provider: "resend", error };
+    }
+
+    log.info({ to: message.to, subject: message.subject }, "Email sent via Resend");
+    return { success: true, provider: "resend" };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    log.error({ to: message.to, err: error }, "Resend delivery error");
+    return { success: false, provider: "resend", error };
+  }
+}