@useatlas/create 0.0.1

package/templates/docker/src/lib/db/salesforce.ts

@@ -0,0 +1,342 @@
+/**
+ * Salesforce DataSource adapter via jsforce.
+ *
+ * Salesforce uses SOQL, not SQL, so it cannot be a DBConnection (which has
+ * `query(sql)`). Instead, it exposes a separate DataSource interface and
+ * a separate registry.
+ *
+ * Connection URL format: salesforce://user:pass@login.salesforce.com?token=TOKEN
+ */
+
+import type { QueryResult, ConnectionMetadata } from "@atlas/api/lib/db/connection";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("salesforce");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SObjectInfo {
+  name: string;
+  label: string;
+  queryable: boolean;
+}
+
+export interface SObjectField {
+  name: string;
+  type: string;
+  label: string;
+  picklistValues: { value: string; label: string; active: boolean }[];
+  referenceTo: string[];
+  nillable: boolean;
+  length: number;
+}
+
+export interface SObjectDescribe {
+  name: string;
+  label: string;
+  fields: SObjectField[];
+}
+
+export interface SalesforceConfig {
+  loginUrl: string;
+  username: string;
+  password: string;
+  securityToken?: string;
+  clientId?: string;
+  clientSecret?: string;
+}
+
+export interface SalesforceDataSource {
+  query(soql: string, timeoutMs?: number): Promise<QueryResult>;
+  describe(objectName: string): Promise<SObjectDescribe>;
+  listObjects(): Promise<SObjectInfo[]>;
+  close(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// URL parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a Salesforce connection URL into SalesforceConfig.
+ *
+ * Format: salesforce://user:pass@login.salesforce.com?token=TOKEN
+ *
+ * - hostname → loginUrl (default `login.salesforce.com`)
+ * - URL username/password → credentials
+ * - Query params: `token` (security token), `clientId`, `clientSecret`
+ */
+export function parseSalesforceURL(url: string): SalesforceConfig {
+  const parsed = new URL(url);
+  if (parsed.protocol !== "salesforce:") {
+    throw new Error(
+      `Invalid Salesforce URL: expected salesforce:// scheme, got "${parsed.protocol}"`,
+    );
+  }
+
+  const username = decodeURIComponent(parsed.username);
+  if (!username) {
+    throw new Error("Invalid Salesforce URL: missing username.");
+  }
+
+  const password = decodeURIComponent(parsed.password);
+  if (!password) {
+    throw new Error("Invalid Salesforce URL: missing password.");
+  }
+
+  const hostname = parsed.hostname || "login.salesforce.com";
+  const loginUrl = `https://${hostname}`;
+
+  const securityToken = parsed.searchParams.get("token") ?? undefined;
+  const clientId = parsed.searchParams.get("clientId") ?? undefined;
+  const clientSecret = parsed.searchParams.get("clientSecret") ?? undefined;
+
+  return { loginUrl, username, password, securityToken, clientId, clientSecret };
+}
+
+// ---------------------------------------------------------------------------
+// DataSource factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Salesforce DataSource backed by jsforce.
+ */
+export function createSalesforceDataSource(
+  config: SalesforceConfig,
+): SalesforceDataSource {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let jsforce: any;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    jsforce = require("jsforce");
+  } catch {
+    throw new Error(
+      "Salesforce support requires the jsforce package. Install it with: bun add jsforce",
+    );
+  }
+
+  const connOpts: Record<string, unknown> = {
+    loginUrl: config.loginUrl,
+  };
+
+  if (config.clientId && config.clientSecret) {
+    connOpts.oauth2 = {
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      loginUrl: config.loginUrl,
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const conn = new jsforce.Connection(connOpts) as any;
+
+  let loginPromise: Promise<void> | null = null;
+
+  async function ensureLoggedIn(): Promise<void> {
+    if (loginPromise) return loginPromise;
+    loginPromise = (async () => {
+      const loginPassword = config.securityToken
+        ? config.password + config.securityToken
+        : config.password;
+      try {
+        await conn.login(config.username, loginPassword);
+      } catch (err) {
+        loginPromise = null;
+        log.error(
+          {
+            err: err instanceof Error ? err : new Error(String(err)),
+            loginUrl: config.loginUrl,
+            username: config.username,
+          },
+          "Salesforce login failed",
+        );
+        throw err;
+      }
+      log.info("Salesforce login successful");
+    })();
+    return loginPromise;
+  }
+
+  function isSessionExpiredError(err: unknown): boolean {
+    if (!(err instanceof Error)) return false;
+    const msg = err.message;
+    return (
+      msg.includes("INVALID_SESSION_ID") ||
+      msg.includes("Session expired") ||
+      msg.includes("session has expired")
+    );
+  }
+
+  async function withSessionRetry<T>(fn: () => Promise<T>): Promise<T> {
+    try {
+      return await fn();
+    } catch (err) {
+      if (isSessionExpiredError(err)) {
+        log.warn("Salesforce session expired — re-authenticating and retrying");
+        loginPromise = null;
+        await ensureLoggedIn();
+        return await fn();
+      }
+      throw err;
+    }
+  }
+
+  return {
+    async query(soql: string, timeoutMs = 30000): Promise<QueryResult> {
+      return withSessionRetry(async () => {
+        await ensureLoggedIn();
+
+        let timeoutId: ReturnType<typeof setTimeout>;
+        const result = await Promise.race([
+          conn.query(soql),
+          new Promise<never>((_, reject) => {
+            timeoutId = setTimeout(
+              () => reject(new Error("Salesforce query timed out")),
+              timeoutMs,
+            );
+          }),
+        ]).finally(() => clearTimeout(timeoutId!));
+
+        const records = (result.records ?? []) as Record<string, unknown>[];
+
+        if (records.length === 0) {
+          return { columns: [], rows: [] };
+        }
+
+        // Extract columns from first record, filtering out the `attributes` metadata key
+        const columns = Object.keys(records[0]).filter(
+          (k) => k !== "attributes",
+        );
+
+        const rows = records.map((record) => {
+          const row: Record<string, unknown> = {};
+          for (const col of columns) {
+            row[col] = record[col];
+          }
+          return row;
+        });
+
+        return { columns, rows };
+      });
+    },
+
+    async describe(objectName: string): Promise<SObjectDescribe> {
+      return withSessionRetry(async () => {
+        await ensureLoggedIn();
+        const desc = await conn.describe(objectName);
+        return {
+          name: desc.name,
+          label: desc.label,
+          fields: (desc.fields ?? []).map(
+            (f: Record<string, unknown>) => ({
+              name: f.name as string,
+              type: f.type as string,
+              label: f.label as string,
+              picklistValues: Array.isArray(f.picklistValues)
+                ? f.picklistValues.map(
+                    (pv: Record<string, unknown>) => ({
+                      value: pv.value as string,
+                      label: pv.label as string,
+                      active: pv.active as boolean,
+                    }),
+                  )
+                : [],
+              referenceTo: Array.isArray(f.referenceTo)
+                ? (f.referenceTo as string[])
+                : [],
+              nillable: f.nillable as boolean,
+              length: (f.length as number) ?? 0,
+            }),
+          ),
+        };
+      });
+    },
+
+    async listObjects(): Promise<SObjectInfo[]> {
+      return withSessionRetry(async () => {
+        await ensureLoggedIn();
+        const result = await conn.describeGlobal();
+        return (result.sobjects ?? [])
+          .filter((obj: Record<string, unknown>) => obj.queryable === true)
+          .map((obj: Record<string, unknown>) => ({
+            name: obj.name as string,
+            label: obj.label as string,
+            queryable: true,
+          }));
+      });
+    },
+
+    async close(): Promise<void> {
+      if (loginPromise) {
+        try {
+          await loginPromise;
+          await conn.logout();
+        } catch (err) {
+          log.warn(
+            { err: err instanceof Error ? err.message : String(err) },
+            "Failed to logout from Salesforce",
+          );
+        }
+        loginPromise = null;
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Source registry (parallel to ConnectionRegistry)
+// ---------------------------------------------------------------------------
+
+const _sources = new Map<string, SalesforceDataSource>();
+
+export function registerSalesforceSource(
+  id: string,
+  config: SalesforceConfig,
+): void {
+  const existing = _sources.get(id);
+  const newSource = createSalesforceDataSource(config);
+  _sources.set(id, newSource);
+  if (existing) {
+    existing.close().catch((err) => {
+      log.warn(
+        { err: err instanceof Error ? err.message : String(err), sourceId: id },
+        "Failed to close previous Salesforce source during re-registration",
+      );
+    });
+  }
+}
+
+export function getSalesforceSource(id: string): SalesforceDataSource {
+  const source = _sources.get(id);
+  if (!source) {
+    throw new Error(`Salesforce source "${id}" is not registered.`);
+  }
+  return source;
+}
+
+export function listSalesforceSources(): string[] {
+  return Array.from(_sources.keys());
+}
+
+/** Return ConnectionMetadata for each registered Salesforce source. */
+export function describeSalesforceSources(): ConnectionMetadata[] {
+  return Array.from(_sources.keys()).map((id) => ({
+    id,
+    dbType: "salesforce" as const,
+  }));
+}
+
+/** Test helper — clears all registered sources. */
+export function _resetSalesforceSources(): void {
+  for (const [id, source] of _sources.entries()) {
+    source.close().catch((err) => {
+      log.warn(
+        { err: err instanceof Error ? err.message : String(err), sourceId: id },
+        "Failed to close Salesforce source during registry reset",
+      );
+    });
+  }
+  _sources.clear();
+}

package/templates/docker/src/lib/db/source-rate-limit.ts

@@ -0,0 +1,191 @@
+/**
+ * Per-source rate limiting for multi-database deployments.
+ *
+ * Enforces QPM (queries per minute) and concurrency limits per datasource.
+ * Uses a sliding-window pattern for QPM tracking.
+ */
+
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("source-rate-limit");
+
+const WINDOW_MS = 60_000;
+
+export interface SourceRateLimit {
+  readonly queriesPerMinute: number;
+  readonly concurrency: number;
+}
+
+const DEFAULT_LIMIT: SourceRateLimit = {
+  queriesPerMinute: 60,
+  concurrency: 5,
+};
+
+/** Per-source config overrides. */
+const limits = new Map<string, SourceRateLimit>();
+
+/** Per-source sliding window of request timestamps. */
+const windows = new Map<string, number[]>();
+
+/** Per-source current concurrency count. */
+const concurrency = new Map<string, number>();
+
+/** Register a custom rate limit for a datasource. */
+export function registerSourceRateLimit(id: string, limit: SourceRateLimit): void {
+  if (!Number.isInteger(limit.queriesPerMinute) || limit.queriesPerMinute < 1) {
+    throw new Error(`queriesPerMinute must be a positive integer, got ${limit.queriesPerMinute}`);
+  }
+  if (!Number.isInteger(limit.concurrency) || limit.concurrency < 1) {
+    throw new Error(`concurrency must be a positive integer, got ${limit.concurrency}`);
+  }
+  limits.set(id, limit);
+}
+
+/** Remove a custom rate limit for a datasource. */
+export function clearSourceRateLimit(id: string): void {
+  limits.delete(id);
+}
+
+function getLimit(id: string): SourceRateLimit {
+  return limits.get(id) ?? DEFAULT_LIMIT;
+}
+
+export function checkSourceRateLimit(sourceId: string): {
+  allowed: boolean;
+  reason?: string;
+  retryAfterMs?: number;
+} {
+  const limit = getLimit(sourceId);
+
+  // Check concurrency first
+  const current = concurrency.get(sourceId) ?? 0;
+  if (current >= limit.concurrency) {
+    return {
+      allowed: false,
+      reason: `Source "${sourceId}" concurrency limit reached (${limit.concurrency})`,
+    };
+  }
+
+  // Check QPM
+  const now = Date.now();
+  const cutoff = now - WINDOW_MS;
+
+  let timestamps = windows.get(sourceId);
+  if (!timestamps) {
+    timestamps = [];
+    windows.set(sourceId, timestamps);
+  }
+
+  // Evict stale entries
+  const firstValid = timestamps.findIndex((t) => t > cutoff);
+  if (firstValid > 0) timestamps.splice(0, firstValid);
+  else if (firstValid === -1) timestamps.length = 0;
+
+  if (timestamps.length >= limit.queriesPerMinute) {
+    const retryAfterMs = Math.max(1, timestamps[0] + WINDOW_MS - now);
+    return {
+      allowed: false,
+      reason: `Source "${sourceId}" QPM limit reached (${limit.queriesPerMinute}/min)`,
+      retryAfterMs,
+    };
+  }
+
+  timestamps.push(now);
+  return { allowed: true };
+}
+
+/**
+ * Atomic check-and-acquire: checks both QPM and concurrency limits, and if
+ * allowed, atomically records the QPM timestamp AND increments the concurrency
+ * counter. This prevents the TOCTOU race where two concurrent requests both
+ * pass the concurrency check before either increments.
+ *
+ * Callers MUST call `decrementSourceConcurrency()` in a `finally` block after
+ * the query completes (success or failure).
+ */
+export function acquireSourceSlot(sourceId: string): {
+  acquired: boolean;
+  reason?: string;
+  retryAfterMs?: number;
+} {
+  const limit = getLimit(sourceId);
+
+  // Check concurrency first
+  const current = concurrency.get(sourceId) ?? 0;
+  if (current >= limit.concurrency) {
+    return {
+      acquired: false,
+      reason: `Source "${sourceId}" concurrency limit reached (${limit.concurrency})`,
+    };
+  }
+
+  // Check QPM
+  const now = Date.now();
+  const cutoff = now - WINDOW_MS;
+
+  let timestamps = windows.get(sourceId);
+  if (!timestamps) {
+    timestamps = [];
+    windows.set(sourceId, timestamps);
+  }
+
+  // Evict stale entries
+  const firstValid = timestamps.findIndex((t) => t > cutoff);
+  if (firstValid > 0) timestamps.splice(0, firstValid);
+  else if (firstValid === -1) timestamps.length = 0;
+
+  if (timestamps.length >= limit.queriesPerMinute) {
+    const retryAfterMs = Math.max(1, timestamps[0] + WINDOW_MS - now);
+    return {
+      acquired: false,
+      reason: `Source "${sourceId}" QPM limit reached (${limit.queriesPerMinute}/min)`,
+      retryAfterMs,
+    };
+  }
+
+  // Atomically record QPM timestamp AND increment concurrency
+  timestamps.push(now);
+  concurrency.set(sourceId, current + 1);
+  return { acquired: true };
+}
+
+/** Increment concurrency counter before query execution. */
+export function incrementSourceConcurrency(sourceId: string): void {
+  concurrency.set(sourceId, (concurrency.get(sourceId) ?? 0) + 1);
+}
+
+/** Decrement concurrency counter after query execution. */
+export function decrementSourceConcurrency(sourceId: string): void {
+  const current = concurrency.get(sourceId) ?? 0;
+  concurrency.set(sourceId, Math.max(0, current - 1));
+}
+
+/** Periodic cleanup — evict stale QPM windows. */
+const cleanupInterval = setInterval(() => {
+  try {
+    const cutoff = Date.now() - WINDOW_MS;
+    for (const [key, timestamps] of windows) {
+      if (timestamps.length === 0 || timestamps[timestamps.length - 1] <= cutoff) {
+        windows.delete(key);
+      }
+    }
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err : new Error(String(err)) },
+      "Source rate limit cleanup failed",
+    );
+  }
+}, WINDOW_MS);
+cleanupInterval.unref();
+
+/** Stop the periodic cleanup timer. For tests. */
+export function _stopSourceRateLimitCleanup(): void {
+  clearInterval(cleanupInterval);
+}
+
+/** Reset all state. For tests. */
+export function _resetSourceRateLimits(): void {
+  limits.clear();
+  windows.clear();
+  concurrency.clear();
+}

package/templates/docker/src/lib/errors.ts

@@ -0,0 +1,154 @@
+/**
+ * Client-side error parsing for Atlas chat errors.
+ *
+ * The server returns JSON error bodies with { error, message, retryAfterSeconds? }.
+ * This module parses those into user-friendly `ChatErrorInfo` objects.
+ */
+
+import type { AuthMode } from "@atlas/api/lib/auth/types";
+
+/* ------------------------------------------------------------------ */
+/*  ChatErrorCode — all server error codes                             */
+/* ------------------------------------------------------------------ */
+
+export const CHAT_ERROR_CODES = [
+  "auth_error",
+  "rate_limited",
+  "configuration_error",
+  "no_datasource",
+  "invalid_request",
+  "provider_model_not_found",
+  "provider_auth_error",
+  "provider_rate_limit",
+  "provider_timeout",
+  "provider_unreachable",
+  "provider_error",
+  "internal_error",
+] as const;
+
+/** Union of all error codes the server can return in the `error` field. */
+export type ChatErrorCode = (typeof CHAT_ERROR_CODES)[number];
+
+/* ------------------------------------------------------------------ */
+/*  ChatErrorInfo                                                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Structured error info extracted from a chat error response.
+ *
+ * - `title`  — Primary user-facing message (always present).
+ * - `detail` — Optional secondary message with extra context.
+ * - `retryAfterSeconds` — Seconds to wait before retrying (rate_limited only).
+ *   Clamped to [0, 300].
+ * - `code` — The server error code, if the response was valid JSON with a known code.
+ */
+export interface ChatErrorInfo {
+  title: string;
+  detail?: string;
+  retryAfterSeconds?: number;
+  code?: ChatErrorCode;
+}
+
+/* ------------------------------------------------------------------ */
+/*  authErrorMessage                                                   */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Map an auth mode to a user-friendly error message.
+ *
+ * Different auth modes require different guidance:
+ * - `simple-key`: the user needs to check or re-enter their API key.
+ * - `managed`: the session likely expired; a fresh sign-in is needed.
+ * - `byot`: the external token may have expired or been revoked.
+ * - `none`: auth should not fail in this mode; a generic message is shown.
+ */
+export function authErrorMessage(authMode: AuthMode): string {
+  switch (authMode) {
+    case "simple-key":
+      return "Invalid or missing API key. Check your key and try again.";
+    case "managed":
+      return "Your session has expired. Please sign in again.";
+    case "byot":
+      return "Authentication failed. Your token may have expired.";
+    case "none":
+      return "An unexpected authentication error occurred. Please refresh the page.";
+    default: {
+      const _exhaustive: never = authMode;
+      return `Authentication failed (unknown mode: ${_exhaustive}).`;
+    }
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/*  parseChatError                                                     */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Parse an AI SDK chat error into a user-friendly `ChatErrorInfo`.
+ *
+ * Expects `error.message` to contain a JSON string with `{ error, message, retryAfterSeconds? }`.
+ * Falls back to a generic message when the body is not valid JSON (e.g. network failures,
+ * HTML error pages, or unexpected formats).
+ */
+export function parseChatError(error: Error, authMode: AuthMode): ChatErrorInfo {
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(error.message);
+  } catch {
+    return { title: "Something went wrong. Please try again." };
+  }
+
+  const code = typeof parsed.error === "string" ? parsed.error : undefined;
+  const serverMessage = typeof parsed.message === "string" ? parsed.message : undefined;
+
+  switch (code) {
+    case "auth_error":
+      return { title: authErrorMessage(authMode), code };
+
+    case "rate_limited": {
+      const raw = typeof parsed.retryAfterSeconds === "number" ? parsed.retryAfterSeconds : undefined;
+      const clamped = raw !== undefined ? Math.max(0, Math.min(raw, 300)) : undefined;
+      return {
+        title: "Too many requests.",
+        detail: clamped !== undefined
+          ? `Try again in ${clamped} seconds.`
+          : "Please wait before trying again.",
+        retryAfterSeconds: clamped,
+        code,
+      };
+    }
+
+    case "configuration_error":
+      return { title: "Atlas is not fully configured.", detail: serverMessage, code };
+
+    case "no_datasource":
+      return { title: "No data source configured.", detail: serverMessage, code };
+
+    case "invalid_request":
+      return { title: "Invalid request.", detail: serverMessage, code };
+
+    case "provider_model_not_found":
+      return { title: "The configured AI model was not found.", detail: serverMessage, code };
+
+    case "provider_auth_error":
+      return { title: "The AI provider could not authenticate.", detail: serverMessage, code };
+
+    case "provider_rate_limit":
+      return { title: "The AI provider is rate limiting requests.", detail: serverMessage, code };
+
+    case "provider_timeout":
+      return { title: "The AI provider timed out.", detail: serverMessage, code };
+
+    case "provider_unreachable":
+      return { title: "Could not reach the AI provider.", detail: serverMessage, code };
+
+    case "provider_error":
+      return { title: "The AI provider returned an error.", detail: serverMessage, code };
+
+    case "internal_error":
+      return { title: serverMessage ?? "An unexpected error occurred.", code };
+
+    default:
+      return { title: serverMessage ?? "Something went wrong. Please try again." };
+  }
+}