@useatlas/create 0.0.1 → 0.0.3

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

@@ -28,6 +28,8 @@ interface DatasourceShape {
     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 };
+    parserDialect?: string;
+    forbiddenPatterns?: RegExp[];
   };
   entities?: unknown[] | (() => Promise<unknown[]> | unknown[]);
   dialect?: string;
@@ -51,7 +53,7 @@ interface InteractionShape {
 
 function hasContextProvider(p: PluginLike): p is PluginLike & ContextShape {
   return (
-    p.type === "context" &&
+    p.types.includes("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"
@@ -60,18 +62,18 @@ function hasContextProvider(p: PluginLike): p is PluginLike & ContextShape {
 
 function hasDatasource(p: PluginLike): p is PluginLike & DatasourceShape {
   return (
-    p.type === "datasource" &&
+    p.types.includes("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);
+  return p.types.includes("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";
+  return p.types.includes("interaction") && typeof (p as Record<string, unknown>).routes === "function";
 }
 
 // ---------------------------------------------------------------------------
@@ -106,12 +108,16 @@ export async function wireDatasourcePlugins(
     }
     try {
       const conn = await plugin.connection.create();
+      const meta = (plugin.connection.parserDialect || plugin.connection.forbiddenPatterns)
+        ? { parserDialect: plugin.connection.parserDialect, forbiddenPatterns: plugin.connection.forbiddenPatterns }
+        : undefined;
       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,
+        meta,
       );
       wired.push(plugin.id);
       log.info({ pluginId: plugin.id, dbType: plugin.connection.dbType }, "Datasource plugin wired");
@@ -254,6 +260,109 @@ export async function wireInteractionPlugins(
   return { wired, failed };
 }
 
+// ---------------------------------------------------------------------------
+// Sandbox plugins
+// ---------------------------------------------------------------------------
+
+/**
+ * Duplicated from @useatlas/plugin-sdk/types to avoid runtime SDK dependency.
+ * Keep in sync — explore-sdk-compat.test.ts verifies structural equivalence.
+ */
+const SANDBOX_DEFAULT_PRIORITY = 60;
+
+/**
+ * Minimal interface for a sandbox execution backend.
+ * Structurally identical to ExploreBackend in explore.ts — duplicated here
+ * to avoid a circular dependency (explore.ts imports from wiring.ts).
+ * Changes to either interface should be mirrored.
+ */
+export interface SandboxExecBackend {
+  exec(command: string): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+  close?(): Promise<void>;
+}
+
+interface SandboxShape {
+  sandbox: {
+    create(root: string): Promise<SandboxExecBackend> | SandboxExecBackend;
+    priority?: number;
+  };
+}
+
+function hasSandbox(p: PluginLike): p is PluginLike & SandboxShape {
+  return (
+    p.types.includes("sandbox") &&
+    typeof (p as Record<string, unknown>).sandbox === "object" &&
+    (p as Record<string, unknown>).sandbox !== null &&
+    typeof ((p as Record<string, unknown>).sandbox as Record<string, unknown>)?.create === "function"
+  );
+}
+
+/**
+ * Discover sandbox plugins, sort by priority (highest first), and try to
+ * create a backend from each until one succeeds.
+ *
+ * Unlike other wire functions, sandbox plugins are not registered into a
+ * global registry — the caller receives a single backend instance directly.
+ *
+ * NOTE: In practice, called lazily from getExploreBackend() on the first
+ * explore command (not at startup), because the explore backend is cached
+ * as a singleton and depends on runtime environment detection.
+ */
+export async function wireSandboxPlugins(
+  pluginRegistry: PluginRegistry,
+  semanticRoot: string,
+): Promise<{
+  backend: SandboxExecBackend | null;
+  pluginId: string | null;
+  failed: Array<{ pluginId: string; error: string }>;
+}> {
+  const sandboxPlugins = pluginRegistry.getByType("sandbox");
+  const failed: Array<{ pluginId: string; error: string }> = [];
+
+  if (sandboxPlugins.length === 0) {
+    return { backend: null, pluginId: null, failed };
+  }
+
+  // Filter to valid sandbox plugins, sort by priority descending
+  const valid = sandboxPlugins.filter(hasSandbox);
+  if (valid.length === 0) {
+    for (const sp of sandboxPlugins) {
+      log.warn({ pluginId: sp.id }, "Sandbox plugin missing sandbox.create() — skipped");
+    }
+    return { backend: null, pluginId: null, failed };
+  }
+
+  const sorted = [...valid].sort((a, b) => {
+    const pa = a.sandbox.priority ?? SANDBOX_DEFAULT_PRIORITY;
+    const pb = b.sandbox.priority ?? SANDBOX_DEFAULT_PRIORITY;
+    return pb - pa;
+  });
+
+  for (const sp of sorted) {
+    try {
+      const backend = await sp.sandbox.create(semanticRoot);
+      if (!backend || typeof backend.exec !== "function") {
+        const msg = "create() returned invalid backend (missing exec method)";
+        failed.push({ pluginId: sp.id, error: msg });
+        log.error({ pluginId: sp.id }, msg);
+        continue;
+      }
+      log.info({ pluginId: sp.id }, "Using sandbox plugin for explore backend");
+      return { backend, pluginId: sp.id, failed };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      failed.push({ pluginId: sp.id, error: msg });
+      log.error(
+        { pluginId: sp.id, err: err instanceof Error ? err : new Error(String(err)) },
+        "Sandbox plugin create() failed, trying next",
+      );
+    }
+  }
+
+  log.error({ count: sorted.length }, "All sandbox plugins failed to create a backend");
+  return { backend: null, pluginId: null, failed };
+}
+
 /**
  * For each healthy context plugin, call `contextProvider.load()` and collect
  * the returned text fragments. Fragments are injected into the agent system

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

@@ -34,6 +34,11 @@ const PROVIDER_DEFAULTS: Record<ConfigProvider, string> = {
   gateway: "anthropic/claude-opus-4.6",
 };
 
+/** Returns the default provider string based on runtime environment. */
+export function getDefaultProvider(): ConfigProvider {
+  return process.env.VERCEL ? "gateway" : "anthropic";
+}
+
 function isBedrockAnthropicModel(modelId: string): boolean {
   return modelId.includes("anthropic") || modelId.includes("claude");
 }
@@ -43,7 +48,7 @@ function isBedrockAnthropicModel(modelId: string): boolean {
  * Returns the validated config provider string and the resolved model ID.
  */
 function resolveProvider(): { provider: ConfigProvider; modelId: string } {
-  const raw = process.env.ATLAS_PROVIDER ?? "anthropic";
+  const raw = process.env.ATLAS_PROVIDER ?? getDefaultProvider();
   if (!VALID_PROVIDERS.has(raw as ConfigProvider)) {
     throw new Error(
       `Unknown provider "${raw}". Supported: ${[...VALID_PROVIDERS].join(", ")}`

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

@@ -9,3 +9,27 @@
 
 export const SENSITIVE_PATTERNS =
   /password|secret|credential|connection.?string|pg_hba\.conf|SSL|certificate|Access denied for user|ER_ACCESS_DENIED_ERROR|ER_DBACCESS_DENIED_ERROR|ER_BAD_HOST_ERROR|ER_HOST_NOT_PRIVILEGED|ER_SPECIFIC_ACCESS_DENIED_ERROR|PROTOCOL_CONNECTION_LOST|Can't connect to MySQL server|Authentication failed|DB::Exception.*Authentication|UNKNOWN_USER|WRONG_PASSWORD|REQUIRED_PASSWORD|IP_ADDRESS_NOT_ALLOWED|ALL_CONNECTION_TRIES_FAILED|CLIENT_HAS_CONNECTED_TO_WRONG_PORT|AUTHENTICATION_FAILED|INVALID_SESSION_ID|LOGIN_MUST_USE_SECURITY_TOKEN|INVALID_LOGIN|INVALID_CLIENT_ID/i;
+
+/**
+ * Mask credentials in a database connection URL.
+ * Returns "<invalid-url>" for unparseable URLs to avoid leaking raw strings.
+ */
+const SENSITIVE_PARAMS = /^(password|secret|token|key|credential|auth)$/i;
+
+export function maskConnectionUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    if (parsed.username || parsed.password) {
+      parsed.username = "***";
+      parsed.password = "";
+    }
+    for (const key of [...parsed.searchParams.keys()]) {
+      if (SENSITIVE_PARAMS.test(key)) {
+        parsed.searchParams.set(key, "***");
+      }
+    }
+    return parsed.toString();
+  } catch {
+    return "<invalid-url>";
+  }
+}

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

@@ -86,6 +86,8 @@ function loadEntitiesFromDir(
   for (const file of files) {
     try {
       const content = fs.readFileSync(path.join(dir, file), "utf-8");
+      // js-yaml v4+ yaml.load() uses DEFAULT_SCHEMA (JSON + core YAML types) which is
+      // safe — it does not instantiate arbitrary JS objects (unlike v3's yaml.load).
       const raw = yaml.load(content);
       const parsed = EntityShape.safeParse(raw);
       if (!parsed.success) {

package/templates/nextjs-standalone/src/lib/sidecar-types.ts

@@ -1,7 +1,7 @@
 /**
  * Types for the sidecar HTTP contract.
  * Used by both the sidecar server (packages/sandbox-sidecar) and
- * the sidecar client (packages/api/src/lib/tools/explore-sidecar.ts).
+ * the sidecar clients (explore-sidecar.ts, python-sidecar.ts).
  */
 
 export interface SidecarExecRequest {
@@ -14,3 +14,14 @@ export interface SidecarExecResponse {
   stderr: string;
   exitCode: number;
 }
+
+// --- Python execution ---
+
+export interface SidecarPythonRequest {
+  code: string;
+  data?: { columns: string[]; rows: unknown[][] };
+  timeout?: number;
+}
+
+/** Wire-format alias — canonical type lives in python.ts. */
+export type { PythonResult as SidecarPythonResponse } from "@atlas/api/lib/tools/python";

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

@@ -7,7 +7,9 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import { detectDBType } from "./db/connection";
+import { detectDBType, resolveDatasourceUrl } from "./db/connection";
+import { maskConnectionUrl } from "./security";
+import { getDefaultProvider } from "./providers";
 import { detectAuthMode, getAuthModeSource } from "./auth/detect";
 import { createLogger } from "./logger";
 
@@ -18,7 +20,8 @@ export type DiagnosticCode =
   | "MISSING_SEMANTIC_LAYER" | "INVALID_SCHEMA" | "INTERNAL_DB_UNREACHABLE"
   | "WEAK_AUTH_SECRET" | "INVALID_JWKS_URL" | "MISSING_AUTH_ISSUER"
   | "MISSING_AUTH_PREREQ"
-  | "ACTIONS_REQUIRE_AUTH" | "ACTIONS_MISSING_CREDENTIALS";
+  | "ACTIONS_REQUIRE_AUTH" | "ACTIONS_MISSING_CREDENTIALS"
+  | "INVALID_CONFIG";
 
 export interface DiagnosticError {
   code: DiagnosticCode;
@@ -33,6 +36,12 @@ const PROVIDER_KEY_MAP: Record<string, string> = {
   gateway: "AI_GATEWAY_API_KEY",
 };
 
+const PROVIDER_SIGNUP_URL: Record<string, string> = {
+  anthropic: "https://console.anthropic.com/settings/keys",
+  openai: "https://platform.openai.com/api-keys",
+  gateway: "https://vercel.com/~/ai/api-keys",
+};
+
 let _cached: DiagnosticError[] | null = null;
 let _cachedAt = 0;
 const _startupWarnings: string[] = [];
@@ -67,14 +76,23 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
 
   const errors: DiagnosticError[] = [];
 
-  // 1. ATLAS_DATASOURCE_URL — error if DATABASE_URL looks like a migration leftover
-  if (!process.env.ATLAS_DATASOURCE_URL) {
-    if (process.env.DATABASE_URL) {
+  // 1. Analytics datasource — resolve from ATLAS_DATASOURCE_URL or Neon fallback
+  const resolvedDatasourceUrl = resolveDatasourceUrl();
+  if (!resolvedDatasourceUrl) {
+    if (process.env.ATLAS_DEMO_DATA === "true") {
+      const msg =
+        "ATLAS_DEMO_DATA=true but neither DATABASE_URL_UNPOOLED nor DATABASE_URL is set. " +
+        "The Neon integration may not have provisioned a database. " +
+        "Check your Vercel project's storage integrations.";
+      log.error(msg);
+      errors.push({ code: "MISSING_DATASOURCE_URL", message: msg });
+    } else if (process.env.DATABASE_URL) {
       const msg =
         "DATABASE_URL is set but ATLAS_DATASOURCE_URL is not. " +
         "As of v0.5, the analytics datasource uses ATLAS_DATASOURCE_URL. " +
         "DATABASE_URL is now reserved for Atlas's internal Postgres. " +
-        "Rename your analytics connection to ATLAS_DATASOURCE_URL.";
+        "Rename your analytics connection to ATLAS_DATASOURCE_URL, " +
+        "or set ATLAS_DEMO_DATA=true to use the same database for demo data.";
       log.error(msg);
       errors.push({ code: "MISSING_DATASOURCE_URL", message: msg });
     } else {
@@ -87,19 +105,23 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
       }
       log.warn(msg);
     }
+  } else if (!process.env.ATLAS_DATASOURCE_URL && process.env.ATLAS_DEMO_DATA === "true") {
+    const source = process.env.DATABASE_URL_UNPOOLED ? "DATABASE_URL_UNPOOLED" : "DATABASE_URL";
+    log.info("Demo mode: using %s as analytics datasource", source);
   }
 
   // 2. API key for configured provider
-  const provider = process.env.ATLAS_PROVIDER ?? "anthropic";
+  const provider = process.env.ATLAS_PROVIDER ?? getDefaultProvider();
   const requiredKey = PROVIDER_KEY_MAP[provider];
 
   if (requiredKey === undefined) {
     // Unknown provider — providers.ts will throw a descriptive error at model init,
     // so we don't duplicate that check here.
   } else if (requiredKey && !process.env[requiredKey]) {
-    let message = `${requiredKey} is not set. Atlas needs an API key for the ${provider} provider.`;
-    if (provider === "gateway") {
-      message += " Create one at https://vercel.com/~/ai/api-keys";
+    let message = `${requiredKey} is not set. Atlas needs an API key for the "${provider}" provider. Set it in your .env file.`;
+    const signupUrl = PROVIDER_SIGNUP_URL[provider];
+    if (signupUrl) {
+      message += ` Get one at ${signupUrl}`;
     }
     errors.push({ code: "MISSING_API_KEY", message });
   }
@@ -129,11 +151,11 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
     });
   }
 
-  // 4. Datasource connectivity (only if ATLAS_DATASOURCE_URL is set)
-  if (process.env.ATLAS_DATASOURCE_URL) {
+  // 4. Datasource connectivity (only if a datasource URL is resolved)
+  if (resolvedDatasourceUrl) {
     let dbType: ReturnType<typeof detectDBType> | null = null;
     try {
-      dbType = detectDBType();
+      dbType = detectDBType(resolvedDatasourceUrl);
     } catch (err) {
       const detail = err instanceof Error ? err.message : String(err);
       log.error({ err: detail }, "Unsupported datasource URL");
@@ -142,7 +164,7 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
 
     if (dbType === "mysql") {
       // MySQL: URL validation + connection test
-      if (!isValidUrl(process.env.ATLAS_DATASOURCE_URL)) {
+      if (!isValidUrl(resolvedDatasourceUrl)) {
         errors.push({
           code: "DB_UNREACHABLE",
           message: "ATLAS_DATASOURCE_URL appears malformed. Expected format: mysql://user:pass@host:3306/dbname",
@@ -153,7 +175,7 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
         let pool;
         try {
           pool = mysql.createPool({
-            uri: process.env.ATLAS_DATASOURCE_URL,
+            uri: resolvedDatasourceUrl,
             connectionLimit: 1,
             connectTimeout: 5000,
           });
@@ -163,7 +185,7 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
           const detail = err instanceof Error ? err.message : "";
           log.error({ err: detail }, "MySQL connection check failed");
 
-          let message = "Cannot connect to the database. Check that the server is running and the connection string is correct.";
+          let message = `Cannot connect to ${maskConnectionUrl(resolvedDatasourceUrl)}. Check the connection string and ensure the database is running.`;
 
           if (/ECONNREFUSED/i.test(detail)) {
             message += " The connection was refused — is the MySQL server running?";
@@ -184,47 +206,6 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
           }
         }
       }
-    } else if (dbType === "clickhouse") {
-      // ClickHouse: connectivity test via SELECT 1
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      let createClient: any = null;
-      try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        ({ createClient } = require("@clickhouse/client"));
-      } catch {
-        errors.push({
-          code: "DB_UNREACHABLE",
-          message: "ClickHouse support requires the @clickhouse/client package. Install it with: bun add @clickhouse/client",
-        });
-      }
-
-      if (createClient) {
-        const { rewriteClickHouseUrl } = await import("./db/connection");
-        const httpUrl = rewriteClickHouseUrl(process.env.ATLAS_DATASOURCE_URL!);
-        const client = createClient({ url: httpUrl });
-        try {
-          await client.query({ query: "SELECT 1", format: "JSON" });
-        } catch (err) {
-          const detail = err instanceof Error ? err.message : "";
-          log.error({ err: detail }, "ClickHouse connection check failed");
-
-          let message = "Cannot connect to ClickHouse. Check that the server is running and the connection string is correct.";
-
-          if (/ECONNREFUSED/i.test(detail)) {
-            message += " The connection was refused — is the ClickHouse server running?";
-          } else if (/Authentication/i.test(detail) || /AUTHENTICATION_FAILED/i.test(detail)) {
-            message += " Authentication failed — check your username and password.";
-          } else if (/timeout/i.test(detail)) {
-            message += " The connection timed out — check network/firewall settings.";
-          }
-
-          errors.push({ code: "DB_UNREACHABLE", message });
-        } finally {
-          await client.close().catch((err: unknown) => {
-            log.warn({ err: err instanceof Error ? err.message : String(err) }, "ClickHouse client cleanup warning");
-          });
-        }
-      }
     } else if (dbType === "postgres") {
       // PostgreSQL: existing URL validation + connection test + schema validation
       const atlasSchema = process.env.ATLAS_SCHEMA;
@@ -238,7 +219,7 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
         });
       }
 
-      if (!isValidUrl(process.env.ATLAS_DATASOURCE_URL)) {
+      if (!isValidUrl(resolvedDatasourceUrl)) {
         errors.push({
           code: "DB_UNREACHABLE",
           message: "ATLAS_DATASOURCE_URL appears malformed. Expected format: postgresql://user:pass@host:5432/dbname",
@@ -247,7 +228,7 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
         const { Pool } = require("pg");
         const pool = new Pool({
-          connectionString: process.env.ATLAS_DATASOURCE_URL,
+          connectionString: resolvedDatasourceUrl,
           max: 1,
           connectionTimeoutMillis: 5000,
         });
@@ -281,7 +262,7 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
           const detail = err instanceof Error ? err.message : "";
           log.error({ err: detail }, "DB connection check failed");
 
-          let message = "Cannot connect to the database. Check that the server is running and the connection string is correct.";
+          let message = `Cannot connect to ${maskConnectionUrl(resolvedDatasourceUrl)}. Check the connection string and ensure the database is running.`;
 
           if (/ECONNREFUSED/i.test(detail)) {
             message += " The connection was refused — is the database server running?";
@@ -298,46 +279,14 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
           });
         }
       }
-    } else if (dbType === "salesforce") {
-      // Salesforce: test login + listObjects
-      try {
-        const { parseSalesforceURL, createSalesforceDataSource } = await import("./db/salesforce");
-        const config = parseSalesforceURL(process.env.ATLAS_DATASOURCE_URL!);
-        const source = createSalesforceDataSource(config);
-        try {
-          await source.listObjects();
-        } finally {
-          await source.close().catch((err: unknown) => {
-            log.warn({ err: err instanceof Error ? err.message : String(err) }, "Salesforce cleanup warning");
-          });
-        }
-      } catch (err) {
-        const detail = err instanceof Error ? err.message : "";
-        log.error({ err: detail }, "Salesforce connection check failed");
-
-        let message = "Cannot connect to Salesforce. Check that your credentials and connection string are correct.";
-
-        if (/LOGIN_MUST_USE_SECURITY_TOKEN/i.test(detail)) {
-          message += " A security token is required — add ?token=YOUR_TOKEN to the connection URL.";
-        } else if (/INVALID_LOGIN/i.test(detail)) {
-          message += " Authentication failed — check your username and password.";
-        } else if (/timeout/i.test(detail)) {
-          message += " The connection timed out — check network/firewall settings.";
-        }
-
-        errors.push({ code: "DB_UNREACHABLE", message });
-      }
     }
-
-    // Snowflake: warn that SQL validation is the sole read-only enforcement layer
-    if (dbType === "snowflake") {
-      const msg =
-        "Snowflake connections rely solely on SQL validation for read-only enforcement (no session-level read-only mode). " +
-        "Configure the Snowflake role with SELECT-only privileges for defense-in-depth.";
-      if (!_startupWarnings.includes(msg)) {
-        _startupWarnings.push(msg);
-      }
-      log.warn(msg);
+    // Non-core database types are validated by their respective datasource plugins.
+    if (dbType && dbType !== "postgres" && dbType !== "mysql") {
+      log.info(
+        { dbType },
+        "Non-core datasource type '%s' — connectivity validation deferred to plugin initialize()",
+        dbType,
+      );
     }
   }
 
@@ -363,7 +312,7 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
         const detail = err instanceof Error ? err.message : "";
         log.error({ err: detail }, "Internal DB connection check failed");
 
-        let message = "Cannot connect to the internal database (DATABASE_URL). Check that the server is running and the connection string is correct.";
+        let message = `Cannot connect to the internal database at ${maskConnectionUrl(process.env.DATABASE_URL!)}. Check the connection string and ensure the database is running.`;
         if (/ECONNREFUSED/i.test(detail)) {
           message += " The connection was refused — is the database server running?";
         } else if (/timeout/i.test(detail)) {
@@ -394,6 +343,18 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
     errors.push({ code: "INTERNAL_DB_UNREACHABLE", message: migrationErr });
   }
 
+  // 5.5. Config file validation (atlas.config.ts)
+  try {
+    const configMod = await import("@atlas/api/lib/config");
+    if (typeof configMod.loadConfig === "function" && !configMod.getConfig()) {
+      await configMod.loadConfig();
+    }
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    log.error({ err: detail }, "Config validation failed");
+    errors.push({ code: "INVALID_CONFIG", message: detail });
+  }
+
   // 6. Auth mode diagnostics
   const authMode = detectAuthMode();
   const authSource = getAuthModeSource();
@@ -441,7 +402,8 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
       errors.push({
         code: "WEAK_AUTH_SECRET",
         message:
-          "BETTER_AUTH_SECRET is shorter than 32 characters. Use a cryptographically random string of at least 32 characters.",
+          `BETTER_AUTH_SECRET must be at least 32 characters (currently ${secret.length}). ` +
+          "Generate one with: openssl rand -base64 32",
       });
     }
     if (!process.env.BETTER_AUTH_URL) {
@@ -490,6 +452,14 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
           "ATLAS_AUTH_ISSUER is required for BYOT auth mode. Set it to your identity provider's issuer URL (e.g. https://your-idp.com/).",
       });
     }
+
+    if (process.env.ATLAS_AUTH_AUDIENCE === "") {
+      const msg =
+        "ATLAS_AUTH_AUDIENCE is set to an empty string — audience validation will be skipped. " +
+        "Remove the variable entirely if audience checking is not needed, or set it to a valid audience value.";
+      if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
+      log.warn(msg);
+    }
   }
 
   // Warn about orphaned auth env vars that suggest misconfiguration

package/templates/nextjs-standalone/src/lib/tools/__tests__/custom-validation.test.ts

@@ -72,6 +72,8 @@ mock.module("@atlas/api/lib/db/connection", () => ({
     getTargetHost: () => "localhost",
     list: () => ["default", "salesforce-plugin"],
     getValidator: (id: string) => validatorMap.get(id),
+    getParserDialect: () => undefined,
+    getForbiddenPatterns: () => [],
   },
   detectDBType: () => "postgres",
 }));