fix(test): Fix DATABASE_URL environment setup for integration tests

Fixes integration test failures caused by missing DATABASE_URL environment variable.

Changes:
- Add dotenv as dev dependency to load .env.test in vitest setup
- Add .env.test to .gitignore to prevent committing test credentials
- Create .env.test.example with warning comments for documentation
- Add conditional test skipping when DATABASE_URL is not available
- Add DATABASE_URL format validation in vitest setup
- Add error handling to test cleanup to prevent silent failures
- Remove filesystem path disclosure from error messages

The fix allows integration tests to:
- Load DATABASE_URL from .env.test locally for developers with database setup
- Skip gracefully if DATABASE_URL is not available (no database running)
- Connect to postgres service in CI where DATABASE_URL is explicitly provided

Tests affected: auth-rls.integration.spec.ts and other integration tests
requiring real database connections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

apps/api/.env.test.example

@@ -0,0 +1,9 @@
+# WARNING: These are example test credentials for local integration testing.
+# Copy this file to .env.test and customize the values for your local environment.
+# NEVER use these credentials in any shared environment or commit .env.test to git.
+
+DATABASE_URL="postgresql://test:test@localhost:5432/test"
+ENCRYPTION_KEY="test-encryption-key-32-characters"
+JWT_SECRET="test-jwt-secret"
+INSTANCE_NAME="Test Instance"
+INSTANCE_URL="https://test.example.com"

apps/api/package.json

@@ -89,6 +89,7 @@
     "@types/sanitize-html": "^2.16.0",
     "@types/supertest": "^6.0.3",
     "@vitest/coverage-v8": "^4.0.18",
+    "dotenv": "^17.2.4",
     "express": "^5.2.1",
     "prisma": "^6.19.2",
     "supertest": "^7.2.2",

apps/api/vitest.setup.ts

@@ -1 +1,31 @@
 import "reflect-metadata";
+import * as dotenv from "dotenv";
+import * as path from "path";
+import * as fs from "fs";
+
+// Load environment variables from .env.test if it exists
+// This allows local integration tests to run with a local database
+// CI environments explicitly provide DATABASE_URL in the test step
+const envTestPath = path.resolve(__dirname, ".env.test");
+if (fs.existsSync(envTestPath)) {
+  const result = dotenv.config({ path: envTestPath });
+  if (result.error) {
+    throw new Error(
+      `Failed to load test environment configuration: ${result.error.message}\n` +
+        `Ensure .env.test exists in the api directory and is properly formatted.`
+    );
+  }
+
+  // Validate DATABASE_URL format if provided
+  if (process.env.DATABASE_URL && !process.env.DATABASE_URL.startsWith("postgresql://")) {
+    throw new Error(
+      "Invalid DATABASE_URL format in .env.test. " +
+        "Expected format: postgresql://user:password@host:port/database"
+    );
+  }
+
+  // Log only in debug mode
+  if (process.env.DEBUG) {
+    console.debug("Test environment variables loaded from .env.test");
+  }
+}