feat: add debug endpoint for configuration inspection in development/test environments

Author: Thavarshan

src/app.ts

@@ -5,13 +5,16 @@ import { createApiRouter } from './routes/index.ts';
 import type { SessionController } from './controllers/session-controller.ts';
 import type { LocalAuthController } from './controllers/local-auth-controller.ts';
 import type { LocalAuthService } from './services/local-auth-service.ts';
+import type { AppEnv } from './config/env.ts';
 import { createAuthMiddleware } from './middleware/auth-middleware.ts';
+import { createDebugHandler } from './controllers/debug-controller.ts';
 
 interface AppDeps {
   sessionController: SessionController;
   authController?: LocalAuthController;
   authService?: LocalAuthService;
   corsOrigin?: string | string[];
+  env?: AppEnv;
 }
 
 export function createApp(deps: AppDeps) {
@@ -35,6 +38,11 @@ export function createApp(deps: AppDeps) {
 
   app.get('/health', (_req, res) => res.json({ status: 'ok' }));
 
+  // Debug endpoint (only in dev/test)
+  if (deps.env) {
+    app.get('/debug/config', createDebugHandler(deps.env));
+  }
+
   app.use(
     '/api',
     createApiRouter({

src/clients/index.ts

@@ -1,27 +1,25 @@
 /**
  * Dependency injection factory for Auralyze Engine clients.
  *
- * Builds AuralyzeEngineDeps object containing HTTP clients for microservices
- * (metadata, analysis, feedback) or stub clients for development/testing.
+ * Builds AuralyzeEngineDeps object containing HTTP clients for microservices.
+ * **STUBS DISABLED:** Always requires real service configuration or fails at startup.
  *
  * **Architecture:**
  * Auralyze API orchestrates 3 microservices via HTTP:
  * 1. **audio-metadata-service**: Extract file info with ffprobe
  * 2. **audio-analysis-service**: DSP processing (loudness, dynamics, spectrum, stereo)
- * 3. **audio-feedback-service**: LLM-based feedback generation
+ * 3. **audio-feedback-service**: LLM-based feedback generation (optional - can use OpenAI direct)
  *
  * **Client Selection Strategy:**
  * Controlled by environment variables (AppEnv):
- * - `useStubClients=true`: Use stub clients for integration tests (no real services)
- * - `FEEDBACK_MODE='stub'`: Stub feedback (real metadata + analysis)
  * - `FEEDBACK_MODE='service'`: HTTP feedback client (remote feedback service)
  * - `FEEDBACK_MODE='openai'`: OpenAI direct client (API calls OpenAI, no feedback service)
  *
  * **Why Dependency Injection?**
- * - Testing: Swap real clients with stubs without modifying engine code
- * - Flexibility: Support multiple feedback implementations (OpenAI direct, service, stub)
- * - Development: Run API without spinning up all microservices (stub mode)
- * - Configuration: Environment-driven client selection (dev vs prod)
+ * - Testing: Engine tests can still use stubs by passing createStubDeps() directly
+ * - Flexibility: Support multiple feedback implementations (OpenAI direct vs service)
+ * - Fail Fast: Missing configuration causes immediate startup failure (not runtime errors)
+ * - Configuration: Environment-driven client selection (service vs OpenAI direct)
  *
  * **API Key Authentication:**
  * All HTTP clients use x-api-key header for simple symmetric auth.
@@ -46,25 +44,9 @@ import type { AppEnv } from '../config/env.ts';
 /**
  * Build AuralyzeEngineDeps from environment configuration.
  *
- * **Configuration Modes:**
+ * **STUBS DISABLED - Configuration Modes:**
  *
- * **1. Full Stub Mode (Development/Testing):**
- * ```env
- * USE_STUB_CLIENTS=true
- * ```
- * Returns stub clients for all services (no HTTP calls).
- *
- * **2. Hybrid Mode (Real services + Stub feedback):**
- * ```env
- * METADATA_SERVICE_URL=http://localhost:3001
- * METADATA_SERVICE_API_KEY=...
- * ANALYSIS_SERVICE_URL=http://localhost:3002
- * ANALYSIS_SERVICE_API_KEY=...
- * FEEDBACK_MODE=stub
- * ```
- * Real metadata/analysis, stub feedback (for testing feedback logic).
- *
- * **3. Full Service Mode (Production):**
+ * **1. Service Mode (Recommended for Production):**
  * ```env
  * METADATA_SERVICE_URL=http://metadata:3001
  * METADATA_SERVICE_API_KEY=...
@@ -76,7 +58,7 @@ import type { AppEnv } from '../config/env.ts';
  * ```
  * All clients use HTTP microservices.
  *
- * **4. OpenAI Direct Mode (Bypass feedback service):**
+ * **2. OpenAI Direct Mode (Bypass feedback service):**
  * ```env
  * METADATA_SERVICE_URL=http://metadata:3001
  * METADATA_SERVICE_API_KEY=...
@@ -106,10 +88,7 @@ import type { AppEnv } from '../config/env.ts';
  * ```
  */
 export function buildEngineDeps(env: AppEnv): AuralyzeEngineDeps {
-  if (env.useStubClients) {
-    return createStubDeps();
-  }
-
+  // STUBS DISABLED: Always use real services or fail
   if (!env.METADATA_SERVICE_URL || !env.ANALYSIS_SERVICE_URL) {
     throw new Error('Both METADATA_SERVICE_URL and ANALYSIS_SERVICE_URL are required');
   }
@@ -128,9 +107,7 @@ export function buildEngineDeps(env: AppEnv): AuralyzeEngineDeps {
   });
 
   let feedbackClient: AuralyzeEngineDeps['feedbackClient'];
-  if (env.FEEDBACK_MODE === 'stub') {
-    feedbackClient = createStubDeps().feedbackClient;
-  } else if (env.FEEDBACK_MODE === 'service') {
+  if (env.FEEDBACK_MODE === 'service') {
     if (!env.FEEDBACK_SERVICE_URL || !env.FEEDBACK_SERVICE_API_KEY) {
       throw new Error('FEEDBACK_SERVICE_URL and FEEDBACK_SERVICE_API_KEY are required');
     }

src/config/env.ts

@@ -12,13 +12,11 @@ const EnvSchema = z.object({
   ANALYSIS_SERVICE_API_KEY: z.string().optional(),
   FEEDBACK_SERVICE_URL: z.string().url().optional(),
   FEEDBACK_SERVICE_API_KEY: z.string().optional(),
-  FEEDBACK_MODE: z.enum(['openai', 'stub', 'service']).default('openai'),
-  USE_STUB_CLIENTS: z.coerce.boolean().optional(),
+  FEEDBACK_MODE: z.enum(['openai', 'service']).default('openai'),
   OPENAI_API_KEY: z.string().optional(),
 });
 
 export type AppEnv = z.infer<typeof EnvSchema> & {
-  useStubClients: boolean;
   corsOrigin: string | string[];
 };
 
@@ -38,11 +36,5 @@ export function loadEnv(): AppEnv {
   return {
     ...parsed.data,
     corsOrigin,
-    useStubClients:
-      parsed.data.USE_STUB_CLIENTS ??
-      (!parsed.data.METADATA_SERVICE_URL ||
-        !parsed.data.ANALYSIS_SERVICE_URL ||
-        !parsed.data.METADATA_SERVICE_API_KEY ||
-        !parsed.data.ANALYSIS_SERVICE_API_KEY),
   };
 }

src/controllers/debug-controller.ts

@@ -0,0 +1,38 @@
+import type { Request, Response } from 'express';
+import type { AppEnv } from '../config/env.ts';
+
+/**
+ * Debug endpoint to show current configuration (sanitized).
+ * Only available in development/test, not production.
+ */
+export function createDebugHandler(env: AppEnv) {
+  return (_req: Request, res: Response) => {
+    if (env.NODE_ENV === 'production') {
+      return res.status(404).json({ message: 'Not found' });
+    }
+
+    const config = {
+      nodeEnv: env.NODE_ENV,
+      stubsDisabled: true, // Hardcoded: stubs are permanently disabled
+      feedbackMode: env.FEEDBACK_MODE,
+      services: {
+        metadata: {
+          url: env.METADATA_SERVICE_URL,
+          hasApiKey: !!env.METADATA_SERVICE_API_KEY,
+        },
+        analysis: {
+          url: env.ANALYSIS_SERVICE_URL,
+          hasApiKey: !!env.ANALYSIS_SERVICE_API_KEY,
+        },
+        feedback: {
+          url: env.FEEDBACK_SERVICE_URL,
+          hasApiKey: !!env.FEEDBACK_SERVICE_API_KEY,
+        },
+      },
+      hasOpenAiKey: !!env.OPENAI_API_KEY,
+      corsOrigin: env.corsOrigin,
+    };
+
+    res.json(config);
+  };
+}

src/server.ts

@@ -38,6 +38,7 @@ async function bootstrap() {
     authController,
     authService,
     corsOrigin: env.corsOrigin,
+    env,
   });
 
   app.listen(env.PORT, () => {