@useatlas/create 0.0.6 → 0.0.7

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

@@ -7,11 +7,13 @@
 
 import * as fs from "fs";
 import * as path from "path";
+import { matchError } from "@useatlas/types";
 import { detectDBType, resolveDatasourceUrl } from "./db/connection";
 import { maskConnectionUrl } from "./security";
 import { getDefaultProvider } from "./providers";
 import { detectAuthMode, getAuthModeSource } from "./auth/detect";
 import { createLogger } from "./logger";
+import { getSemanticRoot as getDefaultSemanticRoot } from "./semantic/files";
 
 const log = createLogger("startup");
 
@@ -76,8 +78,63 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
 
   const errors: DiagnosticError[] = [];
 
-  // 1. Analytics datasource — resolve from ATLAS_DATASOURCE_URL or Neon fallback
+  // 1. Analytics datasource URL presence
   const resolvedDatasourceUrl = resolveDatasourceUrl();
+  checkDatasourceUrlPresence(errors, resolvedDatasourceUrl);
+
+  // 2. API key for configured provider
+  checkProviderApiKey(errors);
+
+  // 3. Semantic layer presence
+  checkSemanticLayerPresence(errors);
+
+  // 4. Datasource connectivity (only if a datasource URL is resolved)
+  if (resolvedDatasourceUrl) {
+    await checkDatasourceConnectivity(errors, resolvedDatasourceUrl);
+  }
+
+  // 5. Internal database (DATABASE_URL) — optional, for auth/audit/settings
+  await checkInternalDbConnectivity(errors);
+
+  // Check if boot-time migration reported errors
+  const { getMigrationError } = await import("@atlas/api/lib/auth/migrate");
+  const migrationErr = getMigrationError();
+  if (migrationErr) {
+    errors.push({ code: "INTERNAL_DB_UNREACHABLE", message: migrationErr });
+  }
+
+  // 5.5. Config file validation (atlas.config.ts)
+  await checkConfigFile(errors);
+
+  // 6. Auth mode diagnostics + 6.5. encryption key check
+  const authMode = await checkAuthModeDiagnostics(errors);
+
+  // 7. Action framework diagnostics
+  if (process.env.ATLAS_ACTIONS_ENABLED === "true") {
+    await checkActionFramework(errors, authMode);
+  }
+
+  // 8. Slack integration — optional, informational only
+  if (process.env.SLACK_SIGNING_SECRET) {
+    const slackMode = process.env.SLACK_CLIENT_ID ? "oauth" : "single-workspace";
+    log.info({ slackMode }, "Slack integration enabled");
+  }
+
+  // 9. Sandbox plugins + 10. Sandbox pre-flight
+  await logSandboxPlugins();
+  await checkSandboxPreFlight();
+
+  _cached = errors;
+  _cachedAt = Date.now();
+  return errors;
+}
+
+// ── Startup validation helpers ──────────────────────────────────────────
+
+function checkDatasourceUrlPresence(
+  errors: DiagnosticError[],
+  resolvedDatasourceUrl: string | undefined,
+): void {
   if (!resolvedDatasourceUrl) {
     if (process.env.ATLAS_DEMO_DATA === "true") {
       const msg =
@@ -109,8 +166,9 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
     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
+function checkProviderApiKey(errors: DiagnosticError[]): void {
   const provider = process.env.ATLAS_PROVIDER ?? getDefaultProvider();
   const requiredKey = PROVIDER_KEY_MAP[provider];
 
@@ -125,9 +183,10 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
     }
     errors.push({ code: "MISSING_API_KEY", message });
   }
+}
 
-  // 3. Semantic layer presence
-  const semanticDir = path.resolve(process.cwd(), "semantic", "entities");
+function checkSemanticLayerPresence(errors: DiagnosticError[]): void {
+  const semanticDir = path.join(getDefaultSemanticRoot(), "entities");
   let hasEntities = false;
   try {
     const files = fs.readdirSync(semanticDir);
@@ -135,7 +194,6 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
   } catch (err) {
     const code = err instanceof Error && "code" in err ? (err as NodeJS.ErrnoException).code : undefined;
     if (code !== "ENOENT") {
-      // Non-ENOENT errors (permissions, not a directory, etc.) — report the real problem
       errors.push({
         code: "MISSING_SEMANTIC_LAYER",
         message: `Could not read semantic layer directory: ${err instanceof Error ? err.message : String(err)}. Check file permissions.`,
@@ -150,147 +208,210 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
         "No semantic layer found. Run 'bun run atlas -- init' to generate one from your database, or 'bun run atlas -- init --demo' to load demo data.",
     });
   }
+}
 
-  // 4. Datasource connectivity (only if a datasource URL is resolved)
-  if (resolvedDatasourceUrl) {
-    let dbType: ReturnType<typeof detectDBType> | null = null;
-    try {
-      dbType = detectDBType(resolvedDatasourceUrl);
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      log.error({ err: detail }, "Unsupported datasource URL");
-      errors.push({ code: "DB_UNREACHABLE", message: detail });
-    }
+async function checkDatasourceConnectivity(
+  errors: DiagnosticError[],
+  resolvedDatasourceUrl: string,
+): Promise<void> {
+  let dbType: ReturnType<typeof detectDBType> | null = null;
+  try {
+    dbType = detectDBType(resolvedDatasourceUrl);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    log.error({ err: detail }, "Unsupported datasource URL");
+    errors.push({ code: "DB_UNREACHABLE", message: detail });
+  }
 
-    if (dbType === "mysql") {
-      // MySQL: URL validation + connection test
-      if (!isValidUrl(resolvedDatasourceUrl)) {
-        errors.push({
-          code: "DB_UNREACHABLE",
-          message: "ATLAS_DATASOURCE_URL appears malformed. Expected format: mysql://user:pass@host:3306/dbname",
+  if (dbType === "mysql") {
+    await checkMysqlConnectivity(errors, resolvedDatasourceUrl);
+  } else if (dbType === "postgres") {
+    await checkPostgresConnectivity(errors, resolvedDatasourceUrl);
+  }
+
+  // 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,
+    );
+  }
+}
+
+async function checkMysqlConnectivity(
+  errors: DiagnosticError[],
+  url: string,
+): Promise<void> {
+  if (!isValidUrl(url)) {
+    errors.push({
+      code: "DB_UNREACHABLE",
+      message: "ATLAS_DATASOURCE_URL appears malformed. Expected format: mysql://user:pass@host:3306/dbname",
+    });
+    return;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const mysql = require("mysql2/promise");
+  let pool;
+  try {
+    pool = mysql.createPool({
+      uri: url,
+      connectionLimit: 1,
+      connectTimeout: 5000,
+    });
+    const conn = await pool.getConnection();
+    conn.release();
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : "";
+    log.error({ err: detail }, "MySQL connection check failed");
+
+    const maskedUrl = maskConnectionUrl(url);
+    const matched = matchError(err);
+    let message: string;
+    if (matched) {
+      message = `Cannot connect to ${maskedUrl}. ${matched.message}`;
+    } else if (/Access denied/i.test(detail) || /ER_ACCESS_DENIED/i.test(detail)) {
+      message = `Cannot connect to ${maskedUrl}. Authentication failed — check your username and password.`;
+    } else if (/ER_BAD_DB_ERROR/i.test(detail)) {
+      let dbHint = "";
+      try {
+        const noDatabaseUrl = url.replace(/\/[^/?#]+(?=[?#]|$)/, "/");
+        const listPool = mysql.createPool({
+          uri: noDatabaseUrl,
+          connectionLimit: 1,
+          connectTimeout: 5000,
         });
-      } else {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const mysql = require("mysql2/promise");
-        let pool;
         try {
-          pool = mysql.createPool({
-            uri: resolvedDatasourceUrl,
-            connectionLimit: 1,
-            connectTimeout: 5000,
-          });
-          const conn = await pool.getConnection();
-          conn.release();
-        } catch (err) {
-          const detail = err instanceof Error ? err.message : "";
-          log.error({ err: detail }, "MySQL connection check failed");
-
-          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?";
-          } else if (/Access denied/i.test(detail) || /ER_ACCESS_DENIED/i.test(detail)) {
-            message += " Authentication failed — check your username and password.";
-          } else if (/ER_BAD_DB_ERROR/i.test(detail)) {
-            message += " The specified database does not exist.";
-          } else if (/timeout/i.test(detail)) {
-            message += " The connection timed out — check network/firewall settings.";
+          const listConn = await listPool.getConnection();
+          const [dbRows] = await listConn.query(
+            "SELECT schema_name FROM information_schema.schemata " +
+            "WHERE schema_name NOT IN ('mysql', 'sys', 'performance_schema', 'information_schema') " +
+            "ORDER BY schema_name"
+          );
+          const schemas = (dbRows as Array<{ schema_name: string }>).map(r => r.schema_name);
+          if (schemas.length > 0) {
+            dbHint = ` Available databases: ${schemas.join(", ")}.`;
           }
-
-          errors.push({ code: "DB_UNREACHABLE", message });
+          listConn.release();
         } finally {
-          if (pool) {
-            await pool.end().catch((err: unknown) => {
-              log.warn({ err: err instanceof Error ? err.message : String(err) }, "Pool cleanup warning");
-            });
-          }
+          await listPool.end().catch(() => {});
         }
+      } catch {
+        // Database listing failed — fall back to generic message
       }
-    } else if (dbType === "postgres") {
-      // PostgreSQL: existing URL validation + connection test + schema validation
-      const atlasSchema = process.env.ATLAS_SCHEMA;
-      const VALID_SQL_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+      message = `Cannot connect to ${maskedUrl}. The specified database does not exist.${dbHint}`;
+    } else {
+      message = `Cannot connect to ${maskedUrl}. Check the connection string and ensure the database is running.`;
+    }
 
-      // Validate ATLAS_SCHEMA format before attempting connection
-      if (atlasSchema && !VALID_SQL_IDENTIFIER.test(atlasSchema)) {
-        errors.push({
-          code: "INVALID_SCHEMA",
-          message: `Invalid ATLAS_SCHEMA "${atlasSchema}". Must be a valid SQL identifier (letters, digits, underscores).`,
-        });
-      }
+    errors.push({ code: "DB_UNREACHABLE", message });
+  } finally {
+    if (pool) {
+      await pool.end().catch((err: unknown) => {
+        log.warn({ err: err instanceof Error ? err.message : String(err) }, "Pool cleanup warning");
+      });
+    }
+  }
+}
 
-      if (!isValidUrl(resolvedDatasourceUrl)) {
-        errors.push({
-          code: "DB_UNREACHABLE",
-          message: "ATLAS_DATASOURCE_URL appears malformed. Expected format: postgresql://user:pass@host:5432/dbname",
-        });
-      } else {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const { Pool } = require("pg");
-        const pool = new Pool({
-          connectionString: resolvedDatasourceUrl,
-          max: 1,
-          connectionTimeoutMillis: 5000,
-        });
-        try {
-          const client = await pool.connect();
-
-          // Verify schema exists if ATLAS_SCHEMA is set and valid
-          if (atlasSchema && atlasSchema !== "public" && VALID_SQL_IDENTIFIER.test(atlasSchema)) {
-            try {
-              const result = await client.query(
-                "SELECT 1 FROM pg_namespace WHERE nspname = $1",
-                [atlasSchema]
-              );
-              if (result.rows.length === 0) {
-                errors.push({
-                  code: "INVALID_SCHEMA",
-                  message: `Schema "${atlasSchema}" does not exist in the database. Check ATLAS_SCHEMA in your .env file.`,
-                });
-              }
-            } catch (schemaErr) {
-              log.error({ err: schemaErr instanceof Error ? schemaErr.message : String(schemaErr) }, "Schema existence check failed");
-              errors.push({
-                code: "INVALID_SCHEMA",
-                message: `Could not verify schema "${atlasSchema}". Check ATLAS_SCHEMA and database permissions.`,
-              });
-            }
-          }
+async function checkPostgresConnectivity(
+  errors: DiagnosticError[],
+  url: string,
+): Promise<void> {
+  const atlasSchema = process.env.ATLAS_SCHEMA;
+  const VALID_SQL_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 
-          client.release();
-        } catch (err) {
-          const detail = err instanceof Error ? err.message : "";
-          log.error({ err: detail }, "DB connection check failed");
+  // Validate ATLAS_SCHEMA format before attempting connection
+  if (atlasSchema && !VALID_SQL_IDENTIFIER.test(atlasSchema)) {
+    errors.push({
+      code: "INVALID_SCHEMA",
+      message: `Invalid ATLAS_SCHEMA "${atlasSchema}". Must be a valid SQL identifier (letters, digits, underscores).`,
+    });
+  }
 
-          let message = `Cannot connect to ${maskConnectionUrl(resolvedDatasourceUrl)}. Check the connection string and ensure the database is running.`;
+  if (!isValidUrl(url)) {
+    errors.push({
+      code: "DB_UNREACHABLE",
+      message: "ATLAS_DATASOURCE_URL appears malformed. Expected format: postgresql://user:pass@host:5432/dbname",
+    });
+    return;
+  }
 
-          if (/ECONNREFUSED/i.test(detail)) {
-            message += " The connection was refused — is the database server running?";
-          } else if (/timeout/i.test(detail)) {
-            message += " The connection timed out — check network/firewall settings.";
-          } else if (/authentication/i.test(detail) || /password/i.test(detail)) {
-            message += " Authentication failed — check your username and password.";
-          }
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { Pool } = require("pg");
+  const pool = new Pool({
+    connectionString: url,
+    max: 1,
+    connectionTimeoutMillis: 5000,
+  });
+  try {
+    const client = await pool.connect();
 
-          errors.push({ code: "DB_UNREACHABLE", message });
-        } finally {
-          await pool.end().catch((err: unknown) => {
-            log.warn({ err: err instanceof Error ? err.message : String(err) }, "Pool cleanup warning");
+    // Verify schema exists if ATLAS_SCHEMA is set and valid
+    if (atlasSchema && atlasSchema !== "public" && VALID_SQL_IDENTIFIER.test(atlasSchema)) {
+      try {
+        const result = await client.query(
+          "SELECT 1 FROM pg_namespace WHERE nspname = $1",
+          [atlasSchema]
+        );
+        if (result.rows.length === 0) {
+          let schemaHint = "";
+          try {
+            const schemasResult = await client.query(
+              "SELECT schema_name FROM information_schema.schemata " +
+              "WHERE schema_name NOT IN ('pg_catalog', 'information_schema', 'pg_toast') " +
+              "AND schema_name NOT LIKE 'pg_temp_%' AND schema_name NOT LIKE 'pg_toast_temp_%' " +
+              "ORDER BY schema_name"
+            );
+            const schemas = schemasResult.rows.map(
+              (r: { schema_name: string }) => r.schema_name
+            );
+            if (schemas.length > 0) {
+              schemaHint = ` Available schemas: ${schemas.join(", ")}.`;
+            }
+          } catch {
+            // Schema listing failed — fall back to generic message
+          }
+          errors.push({
+            code: "INVALID_SCHEMA",
+            message: `Schema "${atlasSchema}" does not exist in the database.${schemaHint} Check ATLAS_SCHEMA in your .env file.`,
           });
         }
+      } catch (schemaErr) {
+        log.error({ err: schemaErr instanceof Error ? schemaErr.message : String(schemaErr) }, "Schema existence check failed");
+        errors.push({
+          code: "INVALID_SCHEMA",
+          message: `Could not verify schema "${atlasSchema}". Check ATLAS_SCHEMA and database permissions.`,
+        });
       }
     }
-    // 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,
-      );
+
+    client.release();
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : "";
+    log.error({ err: detail }, "DB connection check failed");
+
+    const maskedUrl = maskConnectionUrl(url);
+    const matched = matchError(err);
+    let message: string;
+    if (matched) {
+      message = `Cannot connect to ${maskedUrl}. ${matched.message}`;
+    } else if (/authentication/i.test(detail) || /password/i.test(detail)) {
+      message = `Cannot connect to ${maskedUrl}. Authentication failed — check your username and password.`;
+    } else {
+      message = `Cannot connect to ${maskedUrl}. Check the connection string and ensure the database is running.`;
     }
+
+    errors.push({ code: "DB_UNREACHABLE", message });
+  } finally {
+    await pool.end().catch((err: unknown) => {
+      log.warn({ err: err instanceof Error ? err.message : String(err) }, "Pool cleanup warning");
+    });
   }
+}
 
-  // 5. Internal database (DATABASE_URL) — optional, for auth/audit/settings
+async function checkInternalDbConnectivity(errors: DiagnosticError[]): Promise<void> {
   if (process.env.DATABASE_URL) {
     if (!isValidUrl(process.env.DATABASE_URL)) {
       errors.push({
@@ -312,13 +433,15 @@ 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 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)) {
-          message += " The connection timed out — check network/firewall settings.";
+        const maskedUrl = maskConnectionUrl(process.env.DATABASE_URL!);
+        const matched = matchError(err);
+        let message: string;
+        if (matched) {
+          message = `Cannot connect to internal database at ${maskedUrl}. ${matched.message}`;
         } else if (/authentication/i.test(detail) || /password/i.test(detail)) {
-          message += " Authentication failed — check your username and password.";
+          message = `Cannot connect to internal database at ${maskedUrl}. Authentication failed — check your username and password.`;
+        } else {
+          message = `Cannot connect to internal database at ${maskedUrl}. Check the connection string and ensure the database is running.`;
         }
 
         errors.push({ code: "INTERNAL_DB_UNREACHABLE", message });
@@ -335,15 +458,9 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
     }
     log.warn(msg);
   }
+}
 
-  // Check if boot-time migration reported errors
-  const { getMigrationError } = await import("@atlas/api/lib/auth/migrate");
-  const migrationErr = getMigrationError();
-  if (migrationErr) {
-    errors.push({ code: "INTERNAL_DB_UNREACHABLE", message: migrationErr });
-  }
-
-  // 5.5. Config file validation (atlas.config.ts)
+async function checkConfigFile(errors: DiagnosticError[]): Promise<void> {
   try {
     const configMod = await import("@atlas/api/lib/config");
     if (typeof configMod.loadConfig === "function" && !configMod.getConfig()) {
@@ -354,27 +471,29 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
     log.error({ err: detail }, "Config validation failed");
     errors.push({ code: "INVALID_CONFIG", message: detail });
   }
+}
 
-  // 6. Auth mode diagnostics
+async function checkAuthModeDiagnostics(errors: DiagnosticError[]): Promise<string> {
   const authMode = detectAuthMode();
   const authSource = getAuthModeSource();
   log.info({ authMode, source: authSource }, "Auth mode: %s (%s)", authMode, authSource);
 
-  // When mode is explicit, verify prerequisite env vars are present
-  if (authSource === "explicit") {
+  // When mode is pinned (explicit env var or config file), verify prerequisite env vars
+  if (authSource === "explicit" || authSource === "config") {
+    const source = authSource === "config" ? "atlas.config.ts" : "ATLAS_AUTH_MODE";
     if (authMode === "simple-key" && !process.env.ATLAS_API_KEY) {
       errors.push({
         code: "MISSING_AUTH_PREREQ",
         message:
-          "ATLAS_AUTH_MODE is set to 'api-key' but ATLAS_API_KEY is not set. " +
-          "Set ATLAS_API_KEY to a shared secret, or remove ATLAS_AUTH_MODE to use auto-detection.",
+          `Auth mode is 'api-key' (from ${source}) but ATLAS_API_KEY is not set. ` +
+          "Set ATLAS_API_KEY to a shared secret, or change auth to 'auto'.",
       });
     }
     if (authMode === "managed" && !process.env.BETTER_AUTH_SECRET) {
       errors.push({
         code: "MISSING_AUTH_PREREQ",
         message:
-          "ATLAS_AUTH_MODE is set to 'managed' but BETTER_AUTH_SECRET is not set. " +
+          `Auth mode is 'managed' (from ${source}) but BETTER_AUTH_SECRET is not set. ` +
           "Set BETTER_AUTH_SECRET to a random string of at least 32 characters.",
       });
     }
@@ -382,91 +501,115 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
       errors.push({
         code: "MISSING_AUTH_PREREQ",
         message:
-          "ATLAS_AUTH_MODE is set to 'byot' but ATLAS_AUTH_JWKS_URL is not set. " +
+          `Auth mode is 'byot' (from ${source}) but ATLAS_AUTH_JWKS_URL is not set. ` +
           "Set ATLAS_AUTH_JWKS_URL to your identity provider's JWKS endpoint.",
       });
     }
   }
 
   if (authMode === "managed") {
-    if (!process.env.DATABASE_URL) {
-      errors.push({
-        code: "INTERNAL_DB_UNREACHABLE",
-        message:
-          "Managed auth mode requires DATABASE_URL for session storage. " +
-          "Set DATABASE_URL to a PostgreSQL connection string (postgresql://user:pass@host:5432/atlas).",
-      });
-    }
-    const secret = process.env.BETTER_AUTH_SECRET ?? "";
-    if (secret.length < 32) {
-      errors.push({
-        code: "WEAK_AUTH_SECRET",
-        message:
-          `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) {
-      const msg =
-        "BETTER_AUTH_URL is not set. Better Auth will auto-detect from the request, " +
-        "but setting it explicitly is recommended for production.";
-      if (!_startupWarnings.includes(msg)) {
-        _startupWarnings.push(msg);
-      }
-      log.warn(msg);
-    }
+    checkManagedAuthMode(errors);
   }
 
   if (authMode === "byot") {
-    const jwksUrl = process.env.ATLAS_AUTH_JWKS_URL ?? "";
-    let jwksUrlValid = false;
-    try {
-      new URL(jwksUrl);
-      jwksUrlValid = true;
-    } catch (err) {
-      errors.push({
-        code: "INVALID_JWKS_URL",
-        message:
-          `ATLAS_AUTH_JWKS_URL is not a valid URL (${err instanceof Error ? err.message : "parse error"}). Expected format: https://your-idp.com/.well-known/jwks.json`,
-      });
+    await checkByotAuthMode(errors);
+  }
+
+  // Warn about orphaned auth env vars that suggest misconfiguration
+  warnOrphanedAuthVars(authMode, authSource);
+
+  // 6.5. Connection encryption key check — only relevant when internal DB stores connection URLs
+  if (process.env.DATABASE_URL && !process.env.ATLAS_ENCRYPTION_KEY && !process.env.BETTER_AUTH_SECRET) {
+    const msg =
+      "No encryption key available for connection URLs. Set ATLAS_ENCRYPTION_KEY or BETTER_AUTH_SECRET " +
+      "to encrypt connection credentials at rest.";
+    if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
+    log.warn(msg);
+  }
+
+  return authMode;
+}
+
+function checkManagedAuthMode(errors: DiagnosticError[]): void {
+  if (!process.env.DATABASE_URL) {
+    errors.push({
+      code: "INTERNAL_DB_UNREACHABLE",
+      message:
+        "Managed auth mode requires DATABASE_URL for session storage. " +
+        "Set DATABASE_URL to a PostgreSQL connection string (postgresql://user:pass@host:5432/atlas).",
+    });
+  }
+  const secret = process.env.BETTER_AUTH_SECRET ?? "";
+  if (secret.length < 32) {
+    errors.push({
+      code: "WEAK_AUTH_SECRET",
+      message:
+        `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) {
+    const msg =
+      "BETTER_AUTH_URL is not set. Better Auth will auto-detect from the request, " +
+      "but setting it explicitly is recommended for production.";
+    if (!_startupWarnings.includes(msg)) {
+      _startupWarnings.push(msg);
     }
+    log.warn(msg);
+  }
+}
 
-    // Reachability check — non-blocking warning since the IdP might be temporarily down
-    if (jwksUrlValid) {
-      try {
-        const resp = await fetch(jwksUrl, { signal: AbortSignal.timeout(5000) });
-        if (!resp.ok) {
-          const msg = `JWKS endpoint returned HTTP ${resp.status}. Verify the URL is correct.`;
-          log.warn({ jwksUrl, status: resp.status }, msg);
-          if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
-        }
-      } catch (err) {
-        log.warn({ err: err instanceof Error ? err.message : String(err), jwksUrl }, "JWKS endpoint unreachable during startup check");
+async function checkByotAuthMode(errors: DiagnosticError[]): Promise<void> {
+  const jwksUrl = process.env.ATLAS_AUTH_JWKS_URL ?? "";
+  let jwksUrlValid = false;
+  try {
+    new URL(jwksUrl);
+    jwksUrlValid = true;
+  } catch (err) {
+    errors.push({
+      code: "INVALID_JWKS_URL",
+      message:
+        `ATLAS_AUTH_JWKS_URL is not a valid URL (${err instanceof Error ? err.message : "parse error"}). Expected format: https://your-idp.com/.well-known/jwks.json`,
+    });
+  }
+
+  // Reachability check — non-blocking warning since the IdP might be temporarily down
+  if (jwksUrlValid) {
+    try {
+      const resp = await fetch(jwksUrl, { signal: AbortSignal.timeout(5000) });
+      if (!resp.ok) {
+        const msg = `JWKS endpoint returned HTTP ${resp.status}. Verify the URL is correct.`;
+        log.warn({ jwksUrl, status: resp.status }, msg);
+        if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
       }
+    } catch (err) {
+      log.warn({ err: err instanceof Error ? err.message : String(err), jwksUrl }, "JWKS endpoint unreachable during startup check");
     }
+  }
 
-    if (!process.env.ATLAS_AUTH_ISSUER) {
-      errors.push({
-        code: "MISSING_AUTH_ISSUER",
-        message:
-          "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_ISSUER) {
+    errors.push({
+      code: "MISSING_AUTH_ISSUER",
+      message:
+        "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);
-    }
+  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
+function warnOrphanedAuthVars(authMode: string, authSource: string | null): void {
   if (authMode !== "byot" && process.env.ATLAS_AUTH_ISSUER) {
-    const msg = authSource === "explicit"
-      ? `ATLAS_AUTH_ISSUER is set but auth mode is '${authMode}' (explicit). ` +
-        "Remove ATLAS_AUTH_ISSUER, or set ATLAS_AUTH_MODE=byot to use it."
+    const pinned = authSource === "explicit" || authSource === "config";
+    const msg = pinned
+      ? `ATLAS_AUTH_ISSUER is set but auth mode is '${authMode}' (${authSource}). ` +
+        "Remove ATLAS_AUTH_ISSUER, or change auth to 'byot' to use it."
       : "ATLAS_AUTH_ISSUER is set but ATLAS_AUTH_JWKS_URL is not — BYOT auth mode is not active. " +
         "Set ATLAS_AUTH_JWKS_URL to enable BYOT, or remove ATLAS_AUTH_ISSUER.";
     if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
@@ -474,86 +617,81 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
   }
 
   if (authMode !== "managed" && (process.env.BETTER_AUTH_URL || process.env.BETTER_AUTH_TRUSTED_ORIGINS)) {
-    const msg = authSource === "explicit"
-      ? `BETTER_AUTH_URL or BETTER_AUTH_TRUSTED_ORIGINS is set but auth mode is '${authMode}' (explicit). ` +
-        "Remove these env vars, or set ATLAS_AUTH_MODE=managed to use them."
+    const pinned = authSource === "explicit" || authSource === "config";
+    const msg = pinned
+      ? `BETTER_AUTH_URL or BETTER_AUTH_TRUSTED_ORIGINS is set but auth mode is '${authMode}' (${authSource}). ` +
+        "Remove these env vars, or change auth to 'managed' to use them."
       : "BETTER_AUTH_URL or BETTER_AUTH_TRUSTED_ORIGINS is set but BETTER_AUTH_SECRET is not — " +
         "managed auth mode is not active. Set BETTER_AUTH_SECRET to enable managed auth.";
     if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
     log.warn(msg);
   }
+}
 
-  // 7. Action framework diagnostics
-  if (process.env.ATLAS_ACTIONS_ENABLED === "true") {
-    log.info("Action framework enabled");
+async function checkActionFramework(errors: DiagnosticError[], authMode: string): Promise<void> {
+  log.info("Action framework enabled");
 
-    // Actions require authentication — reject "none" auth mode
-    if (authMode === "none") {
-      errors.push({
-        code: "ACTIONS_REQUIRE_AUTH",
-        message:
-          "Actions require authentication. Set ATLAS_API_KEY, BETTER_AUTH_SECRET, or ATLAS_AUTH_JWKS_URL to enable an auth mode.",
-      });
-    }
-
-    // Check required credentials for registered actions (warnings only —
-    // missing optional action credentials should not block chat queries)
-    try {
-      const { buildRegistry } = await import("@atlas/api/lib/tools/registry");
-      const actionRegistry = await buildRegistry({ includeActions: true });
-      const missingCreds = actionRegistry.validateActionCredentials();
-      for (const { action, missing } of missingCreds) {
-        const msg = `Action "${action}" missing credentials: ${missing.join(", ")}`;
-        if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
-        log.warn(msg);
-      }
-    } catch (err) {
-      log.warn(
-        { err: err instanceof Error ? err.message : String(err) },
-        "Could not validate action credentials at startup",
-      );
-    }
+  // Actions require authentication — reject "none" auth mode
+  if (authMode === "none") {
+    errors.push({
+      code: "ACTIONS_REQUIRE_AUTH",
+      message:
+        "Actions require authentication. Set ATLAS_API_KEY, BETTER_AUTH_SECRET, or ATLAS_AUTH_JWKS_URL to enable an auth mode.",
+    });
+  }
 
-    // Warn if no internal DB for persistent tracking
-    if (!process.env.DATABASE_URL) {
-      const msg =
-        "Action framework requires DATABASE_URL for persistent tracking. " +
-        "Actions will use in-memory storage only (lost on restart).";
+  // Check required credentials for registered actions (warnings only —
+  // missing optional action credentials should not block chat queries)
+  try {
+    const { buildRegistry } = await import("@atlas/api/lib/tools/registry");
+    const { registry: actionRegistry } = await buildRegistry({ includeActions: true });
+    const missingCreds = actionRegistry.validateActionCredentials();
+    for (const { action, missing } of missingCreds) {
+      const msg = `Action "${action}" missing credentials: ${missing.join(", ")}`;
       if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
       log.warn(msg);
     }
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Could not validate action credentials at startup",
+    );
+  }
 
-    // Warn about high-risk actions set to auto-approve
-    try {
-      const { getConfig } = await import("@atlas/api/lib/config");
-      const config = getConfig();
-      const actionsConfig = config?.actions;
-      if (actionsConfig) {
-        const highRiskActions = ["email:send", "jira:create", "salesforce:update", "salesforce:create"];
-        for (const actionType of highRiskActions) {
-          const perAction = actionsConfig[actionType] as { approval?: string } | undefined;
-          if (perAction?.approval === "auto") {
-            const msg = `${actionType} configured for auto-approve — ensure you understand the risk`;
-            if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
-            log.warn(msg);
-          }
+  // Warn if no internal DB for persistent tracking
+  if (!process.env.DATABASE_URL) {
+    const msg =
+      "Action framework requires DATABASE_URL for persistent tracking. " +
+      "Actions will use in-memory storage only (lost on restart).";
+    if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
+    log.warn(msg);
+  }
+
+  // Warn about high-risk actions set to auto-approve
+  try {
+    const { getConfig } = await import("@atlas/api/lib/config");
+    const config = getConfig();
+    const actionsConfig = config?.actions;
+    if (actionsConfig) {
+      const highRiskActions = ["email:send", "jira:create", "salesforce:update", "salesforce:create"];
+      for (const actionType of highRiskActions) {
+        const perAction = actionsConfig[actionType] as { approval?: string } | undefined;
+        if (perAction?.approval === "auto") {
+          const msg = `${actionType} configured for auto-approve — ensure you understand the risk`;
+          if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
+          log.warn(msg);
         }
       }
-    } catch (err) {
-      log.warn(
-        { err: err instanceof Error ? err.message : String(err) },
-        "Could not validate action config at startup",
-      );
     }
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "Could not validate action config at startup",
+    );
   }
+}
 
-  // 8. Slack integration — optional, informational only
-  if (process.env.SLACK_SIGNING_SECRET) {
-    const slackMode = process.env.SLACK_CLIENT_ID ? "oauth" : "single-workspace";
-    log.info({ slackMode }, "Slack integration enabled");
-  }
-
-  // 9. Sandbox plugins — log any registered sandbox plugins before built-in pre-flight
+async function logSandboxPlugins(): Promise<void> {
   try {
     const { plugins: pluginRegistry } = await import("@atlas/api/lib/plugins/registry");
     try {
@@ -579,115 +717,143 @@ export async function validateEnvironment(): Promise<DiagnosticError[]> {
   } catch {
     // Plugin registry module not available — skip
   }
+}
+
+async function checkSandboxPreFlight(): Promise<void> {
+  try {
+    const { getConfig: getAtlasConfig } = await import("@atlas/api/lib/config");
+    const sandboxPriority = getAtlasConfig()?.sandbox?.priority;
+    if (sandboxPriority) {
+      log.info(
+        { priority: sandboxPriority },
+        "Custom sandbox priority configured: %s",
+        sandboxPriority.join(" > "),
+      );
+    }
+  } catch (err) {
+    const isModuleErr = err != null && typeof err === "object" && "code" in err
+      && (err as NodeJS.ErrnoException).code === "MODULE_NOT_FOUND";
+    if (!isModuleErr) {
+      log.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        "Failed to read sandbox priority from config",
+      );
+    }
+  }
 
-  // 10. Sandbox pre-flight (explore tool isolation)
   const isVercel = process.env.ATLAS_RUNTIME === "vercel" || !!process.env.VERCEL;
   if (isVercel) {
     log.info("Explore tool: Vercel sandbox active");
   } else if (process.env.ATLAS_SANDBOX === "nsjail") {
-    // Explicit nsjail — probe and warn/error, no sidecar check
-    try {
-      const { findNsjailBinary, testNsjailCapabilities } = await import(
-        "@atlas/api/lib/tools/explore-nsjail"
-      );
-      const { markNsjailFailed } = await import(
-        "@atlas/api/lib/tools/explore"
-      );
-      const nsjailPath = findNsjailBinary();
-      if (nsjailPath) {
-        const semanticRoot = path.resolve(process.cwd(), "semantic");
-        const capResult = await testNsjailCapabilities(nsjailPath, semanticRoot);
-        if (capResult.ok) {
-          log.info("Explore tool: nsjail sandbox active");
-        } else {
-          markNsjailFailed();
-          const msg =
-            `nsjail explicitly requested (ATLAS_SANDBOX=nsjail) but namespace creation failed: ${capResult.error}. ` +
-            "This platform may not support Linux namespaces. " +
-            "Set ATLAS_SANDBOX= (empty) to allow fallback to just-bash, or check platform documentation for namespace support.";
-          log.error(msg);
-          if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
-        }
-      } else {
-        const msg =
-          "ATLAS_SANDBOX=nsjail is set but nsjail binary was not found. " +
-          "Install nsjail or set ATLAS_NSJAIL_PATH to the binary location.";
-        log.error(msg);
-        if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
-      }
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      log.warn({ err: detail }, "Sandbox pre-flight check skipped");
-    }
+    await checkExplicitNsjail();
   } else if (process.env.ATLAS_SANDBOX_URL) {
-    // Sidecar is the intended backend — skip nsjail entirely (no noisy warnings)
-    const sidecarUrl = process.env.ATLAS_SANDBOX_URL;
-    const { markSidecarFailed } = await import(
+    await checkSidecarHealth();
+  } else {
+    await autoDetectNsjail();
+  }
+}
+
+async function checkExplicitNsjail(): Promise<void> {
+  try {
+    const { findNsjailBinary, testNsjailCapabilities } = await import(
+      "@atlas/api/lib/tools/explore-nsjail"
+    );
+    const { markNsjailFailed } = await import(
       "@atlas/api/lib/tools/explore"
     );
-    try {
-      const healthUrl = new URL("/health", sidecarUrl).toString();
-      const resp = await fetch(healthUrl, { signal: AbortSignal.timeout(5000) });
-      if (resp.ok) {
-        log.info({ url: sidecarUrl }, "Explore tool: sidecar sandbox active");
+    const nsjailPath = findNsjailBinary();
+    if (nsjailPath) {
+      const semanticRoot = getDefaultSemanticRoot();
+      const capResult = await testNsjailCapabilities(nsjailPath, semanticRoot);
+      if (capResult.ok) {
+        log.info("Explore tool: nsjail sandbox active");
       } else {
-        markSidecarFailed();
+        markNsjailFailed();
         const msg =
-          `Sidecar health check returned HTTP ${resp.status} at ${sidecarUrl}. ` +
-          "Check that the sandbox-sidecar service is running and healthy.";
+          `nsjail explicitly requested (ATLAS_SANDBOX=nsjail) but namespace creation failed: ${capResult.error}. ` +
+          "This platform may not support Linux namespaces. " +
+          "Set ATLAS_SANDBOX= (empty) to allow fallback to just-bash, or check platform documentation for namespace support.";
         log.error(msg);
         if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
       }
-    } catch (err) {
-      markSidecarFailed();
-      const detail = err instanceof Error ? err.message : String(err);
+    } else {
       const msg =
-        `Sidecar unreachable at ${sidecarUrl}: ${detail}. ` +
-        "The sidecar may not be running yet — explore will retry on first use.";
+        "ATLAS_SANDBOX=nsjail is set but nsjail binary was not found. " +
+        "Install nsjail or set ATLAS_NSJAIL_PATH to the binary location.";
       log.error(msg);
       if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
     }
-  } else {
-    // Auto-detect nsjail, fall back to just-bash
-    let nsjailActive = false;
-    try {
-      const { findNsjailBinary, testNsjailCapabilities } = await import(
-        "@atlas/api/lib/tools/explore-nsjail"
-      );
-      const { markNsjailFailed } = await import(
-        "@atlas/api/lib/tools/explore"
-      );
-      const nsjailPath = findNsjailBinary();
-      if (nsjailPath) {
-        const semanticRoot = path.resolve(process.cwd(), "semantic");
-        const capResult = await testNsjailCapabilities(nsjailPath, semanticRoot);
-        if (capResult.ok) {
-          log.info("Explore tool: nsjail sandbox active");
-          nsjailActive = true;
-        } else {
-          markNsjailFailed();
-          const msg =
-            `nsjail available but namespace creation failed: ${capResult.error} — ` +
-            "falling back to just-bash (no process isolation).";
-          log.warn(msg);
-          if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
-        }
-      }
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      log.warn({ err: detail }, "Sandbox pre-flight check skipped");
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    log.warn({ err: detail }, "Sandbox pre-flight check skipped");
+  }
+}
+
+async function checkSidecarHealth(): Promise<void> {
+  // Caller guarantees ATLAS_SANDBOX_URL is set
+  const sidecarUrl = process.env.ATLAS_SANDBOX_URL!;
+  const { markSidecarFailed } = await import(
+    "@atlas/api/lib/tools/explore"
+  );
+  try {
+    const healthUrl = new URL("/health", sidecarUrl).toString();
+    const resp = await fetch(healthUrl, { signal: AbortSignal.timeout(5000) });
+    if (resp.ok) {
+      log.info({ url: sidecarUrl }, "Explore tool: sidecar sandbox active");
+    } else {
+      markSidecarFailed();
+      const msg =
+        `Sidecar health check returned HTTP ${resp.status} at ${sidecarUrl}. ` +
+        "Check that the sandbox-sidecar service is running and healthy.";
+      log.error(msg);
+      if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
     }
+  } catch (err) {
+    markSidecarFailed();
+    const detail = err instanceof Error ? err.message : String(err);
+    const msg =
+      `Sidecar unreachable at ${sidecarUrl}: ${detail}. ` +
+      "The sidecar may not be running yet — explore will retry on first use.";
+    log.error(msg);
+    if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
+  }
+}
 
-    if (!nsjailActive) {
-      log.info(
-        "Explore tool: just-bash (no process isolation). Install nsjail or configure ATLAS_SANDBOX_URL for sandboxed execution.",
-      );
+async function autoDetectNsjail(): Promise<void> {
+  let nsjailActive = false;
+  try {
+    const { findNsjailBinary, testNsjailCapabilities } = await import(
+      "@atlas/api/lib/tools/explore-nsjail"
+    );
+    const { markNsjailFailed } = await import(
+      "@atlas/api/lib/tools/explore"
+    );
+    const nsjailPath = findNsjailBinary();
+    if (nsjailPath) {
+      const semanticRoot = getDefaultSemanticRoot();
+      const capResult = await testNsjailCapabilities(nsjailPath, semanticRoot);
+      if (capResult.ok) {
+        log.info("Explore tool: nsjail sandbox active");
+        nsjailActive = true;
+      } else {
+        markNsjailFailed();
+        const msg =
+          `nsjail available but namespace creation failed: ${capResult.error} — ` +
+          "falling back to just-bash (no process isolation).";
+        log.warn(msg);
+        if (!_startupWarnings.includes(msg)) _startupWarnings.push(msg);
+      }
     }
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    log.warn({ err: detail }, "Sandbox pre-flight check skipped");
   }
 
-  _cached = errors;
-  _cachedAt = Date.now();
-  return errors;
+  if (!nsjailActive) {
+    log.info(
+      "Explore tool: just-bash (no process isolation). Install nsjail or configure ATLAS_SANDBOX_URL for sandboxed execution.",
+    );
+  }
 }
 
 function isValidUrl(url: string): boolean {