feat(api): add provider runtime status and readiness gating

Author: 7vignesh

apps/api/.env.example

@@ -1,5 +1,6 @@
 PORT=3001
 NODE_ENV=development
+STACKFORGE_PROVIDER=auto
 OPENROUTER_API_KEY=
 OPENROUTER_ENDPOINT=https://openrouter.ai/api/v1/chat/completions
 OPENROUTER_APP_NAME=stackforge-api

apps/api/src/controllers/generate.controller.ts

@@ -1,6 +1,6 @@
 import type { Request, Response, NextFunction } from "express";
 import { GenerateRequestSchema } from "@stackforge/shared";
-import { generateProject } from "../services/generate.service.js";
+import { generateProject, getRuntimeStatus } from "../services/generate.service.js";
 
 export function generateController(req: Request, res: Response, next: NextFunction): void {
   const parsed = GenerateRequestSchema.safeParse(req.body);
@@ -12,6 +12,15 @@ export function generateController(req: Request, res: Response, next: NextFuncti
 
   const { prompt, projectName } = parsed.data;
   const resolvedName = projectName ?? prompt.slice(0, 40).replace(/\s+/g, "-").toLowerCase();
+  const runtime = getRuntimeStatus();
+
+  if (!runtime.ready) {
+    res.status(503).json({
+      error: runtime.reason ?? "LLM provider is not configured",
+      provider: runtime.provider,
+    });
+    return;
+  }
 
   try {
     const job = generateProject(prompt, resolvedName);

apps/api/src/controllers/jobs.controller.ts

@@ -1,8 +1,14 @@
 import type { Request, Response, NextFunction } from "express";
 import { JobIdParamSchema, JOB_STATUS } from "@stackforge/shared";
 import { getJob, listJobs, summarizeJobTokenUsage } from "../store/job.store.js";
+import { getRuntimeStatus } from "../services/generate.service.js";
 import { subscribe, unsubscribe } from "../services/sse.service.js";
 
+export function runtimeController(_req: Request, res: Response): void {
+  const runtime = getRuntimeStatus();
+  res.status(runtime.ready ? 200 : 503).json(runtime);
+}
+
 export function listJobsController(_req: Request, res: Response): void {
   const jobs = listJobs().map((job) => ({
     id: job.id,

apps/api/src/index.ts

@@ -8,6 +8,18 @@ const PORT = process.env["PORT"] ?? "3001";
 
 app.use(express.json());
 
+// CORS for Vite dev server
+app.use((_req, res, next) => {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+  if (_req.method === "OPTIONS") {
+    res.sendStatus(204);
+    return;
+  }
+  next();
+});
+
 app.get("/healthz", (_req, res) => {
   res.json({ status: "ok", service: "stackforge-api", ts: new Date().toISOString() });
 });

apps/api/src/routes/index.ts

@@ -1,10 +1,16 @@
 import { Router, type IRouter } from "express";
 import { generateController } from "../controllers/generate.controller.js";
-import { listJobsController, getJobController, streamController } from "../controllers/jobs.controller.js";
+import {
+	runtimeController,
+	listJobsController,
+	getJobController,
+	streamController,
+} from "../controllers/jobs.controller.js";
 
 const router: IRouter = Router();
 
 router.post("/generate", generateController);
+router.get("/runtime", runtimeController);
 router.get("/jobs", listJobsController);
 router.get("/jobs/:jobId", getJobController);
 router.get("/stream/:jobId", streamController);

apps/api/src/services/generate.service.ts

@@ -1,7 +1,13 @@
 import type { SSEEvent, AgentName } from "@stackforge/shared";
 
 import { JOB_STATUS } from "@stackforge/shared";
-import { OpenRouterProvider, AgentCache, runOrchestrator } from "@stackforge/agents";
+import {
+  OpenRouterProvider,
+  MockProvider,
+  AgentCache,
+  runOrchestrator,
+  type LLMProvider,
+} from "@stackforge/agents";
 import {
   createJob,
   getJob,
@@ -11,6 +17,29 @@ import {
 } from "../store/job.store.js";
 import { broadcast, closeJobClients } from "./sse.service.js";
 
+type ProviderMode = "openrouter" | "mock";
+
+export type RuntimeStatus = {
+  provider: ProviderMode;
+  ready: boolean;
+  reason?: string;
+};
+
+function resolveProviderMode(): ProviderMode {
+  const configured = (process.env["STACKFORGE_PROVIDER"] ?? "auto").trim().toLowerCase();
+
+  if (configured === "openrouter") {
+    return "openrouter";
+  }
+
+  if (configured === "mock") {
+    return "mock";
+  }
+
+  const hasOpenRouterKey = (process.env["OPENROUTER_API_KEY"] ?? "").trim().length > 0;
+  return hasOpenRouterKey ? "openrouter" : "mock";
+}
+
 function readEnv(name: string): string {
   const value = process.env[name];
   if (value === undefined || value.trim().length === 0) {
@@ -19,7 +48,7 @@ function readEnv(name: string): string {
   return value;
 }
 
-function buildProvider(): OpenRouterProvider {
+function buildOpenRouterProvider(): OpenRouterProvider {
   const endpoint = process.env["OPENROUTER_ENDPOINT"];
   const options = {
     apiKey: readEnv("OPENROUTER_API_KEY"),
@@ -31,16 +60,38 @@ function buildProvider(): OpenRouterProvider {
   return new OpenRouterProvider(options);
 }
 
-let provider: OpenRouterProvider | undefined;
+function buildProvider(mode: ProviderMode): LLMProvider {
+  if (mode === "mock") {
+    return new MockProvider();
+  }
+
+  return buildOpenRouterProvider();
+}
 
-function getProvider(): OpenRouterProvider {
+let provider: LLMProvider | undefined;
+let providerMode: ProviderMode | undefined;
+
+function getProvider(): LLMProvider {
   if (provider === undefined) {
-    provider = buildProvider();
+    providerMode = resolveProviderMode();
+    provider = buildProvider(providerMode);
   }
 
   return provider;
 }
 
+export function getRuntimeStatus(): RuntimeStatus {
+  const mode = providerMode ?? resolveProviderMode();
+
+  try {
+    void getProvider();
+    return { provider: mode, ready: true };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { provider: mode, ready: false, reason };
+  }
+}
+
 const cache = new AgentCache();
 
 function buildEmitter(jobId: string): (event: SSEEvent) => void {