fix: add model fallback chain to enhancer + dependency install enforcement in system prompt

Author: zebbern

app/lib/common/prompts/new-prompt.ts

@@ -101,6 +101,14 @@ export const getFineTunedPrompt = (
    - If the request is complex, REDUCE feature scope but ALWAYS include: App.tsx with working UI, at least one feature component, all routing, and state management
    - SELF-CHECK before finishing: Count your component files (*.tsx with JSX). If the count is ZERO, you have failed — go back and write the components
    - File priority: App.tsx and feature components FIRST, config files SECOND. Never stop after config files
+
+  DEPENDENCY INSTALLATION (CRITICAL — SECOND MOST COMMON FAILURE):
+  - For EVERY third-party package imported in your code, you MUST include a shell action: npm install <package>
+  - SELF-CHECK before finishing: Scan every import statement. If a package is NOT in the starter template's package.json, it MUST have a corresponding npm install action
+  - Common missed packages: @dnd-kit/core, @dnd-kit/sortable, class-variance-authority, clsx, tailwind-merge, zustand, @tanstack/react-query, framer-motion, react-icons, lucide-react, recharts, react-router-dom, @radix-ui/*
+  - Combine all installs into ONE shell action when possible: npm install pkg1 pkg2 pkg3
+  - Place npm install AFTER package.json is written but BEFORE npm run dev
+  - If you import from a package and forget to install it, the app WILL crash with "Module not found" errors
 </completeness_requirements>
 
 <response_requirements>

app/routes/api.enhancer.ts

@@ -12,6 +12,7 @@ import { AppError, AppErrorType } from '~/lib/api/errors';
 import { AUTH_PRESETS } from '~/lib/security-config';
 import { DEFAULT_PROVIDER, PROVIDER_LIST } from '~/utils/constants';
 import { resolveModel } from '~/lib/.server/llm/resolve-model';
+import { LLMManager } from '~/lib/modules/llm/manager';
 
 export const action = withSecurity(enhancerAction, {
   auth: AUTH_PRESETS.authenticated,
@@ -22,6 +23,26 @@ export const action = withSecurity(enhancerAction, {
 
 const logger = createScopedLogger('api.enhancer');
 
+const MAX_FALLBACK_ATTEMPTS = 3;
+
+/**
+ * Checks whether an error indicates the model is unavailable (deprecated, removed, not found).
+ * Only these errors warrant a fallback attempt — auth errors, rate limits, and other
+ * failures should propagate immediately.
+ */
+function isModelNotFoundError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+  const status = (error as { status?: number })?.status ?? (error as { statusCode?: number })?.statusCode;
+
+  return (
+    status === 404 ||
+    (message.includes('not found') && (message.includes('model') || message.includes('models/'))) ||
+    message.includes('model_not_found') ||
+    message.includes('does not exist') ||
+    message.includes('deprecated')
+  );
+}
+
 // providerSchema imported from ~/lib/api/schemas
 
 const enhancerRequestSchema = z.object({
@@ -73,6 +94,29 @@ async function enhancerAction({ context, request }: ActionFunctionArgs) {
     logger,
   });
 
+  // Build the shared generateText parameters (reused across primary + fallback attempts)
+  const systemPrompt =
+    "You are a prompt engineer for an AI web app builder. The builder runs locally with Node.js and creates complete apps using React (default), Vue, Svelte, or Angular with Tailwind CSS. Apps use local state management and seed data — never external APIs with API keys. Your job: take the user's idea and produce a clear, specific, buildable prompt. Output ONLY the enhanced prompt text.";
+  const userPrompt = stripIndents`
+    Enhance the user's prompt so an AI coding assistant can build a complete, working app in one response.
+
+    <original_prompt>
+      ${message}
+    </original_prompt>
+
+    Enhancement rules:
+    1. PRESERVE the user's core intent — do NOT change what they want to build
+    2. If the app has multiple pages/views, LIST each page and its purpose explicitly
+    3. For data-driven apps, DEFINE the data model (entity names, key fields, relationships)
+    4. Specify interactive features: CRUD operations, filters, search, sorting, modals, form validation
+    5. Add a brief design direction ONLY if the user gave none (e.g., "clean minimal dark theme with blue accents")
+    6. Mention responsive behavior: sidebar collapses on mobile, grid stacks to single column, etc.
+    7. If the app needs sample data, say "populate with realistic seed data" — NEVER suggest external API calls
+    8. Keep the enhanced prompt concise — add only details that prevent ambiguity
+    9. NEVER add: external APIs, API keys, deployment, hosting, CI/CD, testing, or authentication unless the user asked for it
+    10. Output ONLY the enhanced prompt — no explanations, headers, or wrapper tags
+  `;
+
   try {
     const result = await generateText({
       model: resolvedProvider.getModelInstance({
@@ -81,27 +125,8 @@ async function enhancerAction({ context, request }: ActionFunctionArgs) {
         apiKeys,
         providerSettings,
       }),
-      system:
-        "You are a prompt engineer for an AI web app builder. The builder runs locally with Node.js and creates complete apps using React (default), Vue, Svelte, or Angular with Tailwind CSS. Apps use local state management and seed data — never external APIs with API keys. Your job: take the user's idea and produce a clear, specific, buildable prompt. Output ONLY the enhanced prompt text.",
-      prompt: stripIndents`
-        Enhance the user's prompt so an AI coding assistant can build a complete, working app in one response.
-
-        <original_prompt>
-          ${message}
-        </original_prompt>
-
-        Enhancement rules:
-        1. PRESERVE the user's core intent — do NOT change what they want to build
-        2. If the app has multiple pages/views, LIST each page and its purpose explicitly
-        3. For data-driven apps, DEFINE the data model (entity names, key fields, relationships)
-        4. Specify interactive features: CRUD operations, filters, search, sorting, modals, form validation
-        5. Add a brief design direction ONLY if the user gave none (e.g., "clean minimal dark theme with blue accents")
-        6. Mention responsive behavior: sidebar collapses on mobile, grid stacks to single column, etc.
-        7. If the app needs sample data, say "populate with realistic seed data" — NEVER suggest external API calls
-        8. Keep the enhanced prompt concise — add only details that prevent ambiguity
-        9. NEVER add: external APIs, API keys, deployment, hosting, CI/CD, testing, or authentication unless the user asked for it
-        10. Output ONLY the enhanced prompt — no explanations, headers, or wrapper tags
-      `,
+      system: systemPrompt,
+      prompt: userPrompt,
     });
 
     return new Response(result.text, {
@@ -110,11 +135,84 @@ async function enhancerAction({ context, request }: ActionFunctionArgs) {
         'Content-Type': 'text/plain; charset=utf-8',
       },
     });
-  } catch (error: unknown) {
-    logger.error(error);
+  } catch (primaryError: unknown) {
+    logger.error(
+      `Primary model ${providerName}/${modelDetails.name} failed:`,
+      primaryError instanceof Error ? primaryError.message : String(primaryError),
+    );
+
+    // Only attempt fallback for model-not-found errors (deprecated, removed, 404).
+    // Auth errors, rate limits, and other failures propagate immediately.
+    if (isModelNotFoundError(primaryError)) {
+      const llm = LLMManager.getInstance();
+      let candidateModels = llm.getModelList().filter(
+        (m) => m.provider === resolvedProvider.name && m.name !== modelDetails.name,
+      );
+
+      // If the full model list has no alternatives, fall back to static list
+      if (candidateModels.length === 0) {
+        candidateModels = llm.getStaticModelListFromProvider(resolvedProvider).filter(
+          (m) => m.name !== modelDetails.name,
+        );
+      }
+
+      // Limit fallback attempts to avoid excessive API calls
+      const attemptsToTry = candidateModels.slice(0, MAX_FALLBACK_ATTEMPTS);
+
+      for (const candidate of attemptsToTry) {
+        logger.info(`Trying fallback candidate: ${resolvedProvider.name}/${candidate.name}`);
+
+        try {
+          const candidateModelDetails = await resolveModel({
+            provider: resolvedProvider,
+            currentModel: candidate.name,
+            apiKeys,
+            providerSettings,
+            serverEnv: context.cloudflare?.env,
+            logger,
+          });
+
+          const fallbackResult = await generateText({
+            model: resolvedProvider.getModelInstance({
+              model: candidateModelDetails.name,
+              serverEnv: context.cloudflare?.env,
+              apiKeys,
+              providerSettings,
+            }),
+            system: systemPrompt,
+            prompt: userPrompt,
+          });
+
+          logger.info(
+            `Fallback succeeded: ${resolvedProvider.name}/${candidateModelDetails.name} ` +
+              `(primary ${providerName}/${modelDetails.name} was unavailable)`,
+          );
+
+          return new Response(fallbackResult.text, {
+            status: 200,
+            headers: {
+              'Content-Type': 'text/plain; charset=utf-8',
+            },
+          });
+        } catch (candidateError: unknown) {
+          logger.warn(
+            `Fallback candidate ${resolvedProvider.name}/${candidate.name} failed: ` +
+              `${candidateError instanceof Error ? candidateError.message : String(candidateError)}`,
+          );
+          // Continue to next candidate
+        }
+      }
+
+      // All fallback candidates exhausted
+      logger.error(
+        `All ${attemptsToTry.length} fallback candidates for ${resolvedProvider.name} failed ` +
+          `(primary model ${modelDetails.name} was unavailable)`,
+      );
+    }
 
-    if (error instanceof Error) {
-      const msg = error.message.toLowerCase();
+    // Auth error detection — surface a clear message for API key issues
+    if (primaryError instanceof Error) {
+      const msg = primaryError.message.toLowerCase();
 
       if (
         msg.includes('api key') ||
@@ -130,6 +228,6 @@ async function enhancerAction({ context, request }: ActionFunctionArgs) {
       }
     }
 
-    return errorResponse(error instanceof Error ? error : new AppError(AppErrorType.INTERNAL, 'Internal Server Error'));
+    return errorResponse(primaryError instanceof Error ? primaryError : new AppError(AppErrorType.INTERNAL, 'Internal Server Error'));
   }
 }