@iservu-inc/adf-cli 0.4.25 → 0.4.26

package/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to `@iservu-inc/adf-cli` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.26] - 2025-10-04
+
+### 🔧 Improved Error Handling
+
+**Enhanced: AI Model Selection Error Messages**
+- **Problem:** When model selection fails (e.g., OpenRouter free models, unavailable models), error messages were not helpful
+- **Solution:** Added comprehensive error detection and helpful guidance for common issues
+- **Improvements:**
+  - **Privacy/Data Policy Errors:** Specific guidance for OpenRouter free models requiring privacy settings
+  - **404/Not Found Errors:** Clear explanation when models are unavailable or require specific endpoints
+  - **400/Parameter Errors:** Help for models using different API parameters (e.g., experimental models)
+  - **401/Invalid Key:** API key validation guidance
+  - **429/Rate Limit:** Rate limit detection with retry suggestion
+  - **Generic Fallback:** Helpful tip for unknown errors
+
+**Added: OpenRouter Model Recommendations**
+- Shows recommended models when 50+ models are available
+- Warns users about free model privacy requirements
+- Suggests most compatible models:
+  - anthropic/claude-sonnet-4-5
+  - openai/gpt-4-turbo
+  - google/gemini-pro-1.5
+
+**Technical Details:**
+- `ai-config.js:330-366`: Enhanced error handling with category detection
+- `ai-config.js:282-288`: Added model recommendation tip for OpenRouter
+- Error messages now provide actionable solutions, not just error text
+- All 120 tests passing
+
+**Impact:**
+- Users get clear guidance when model selection fails
+- Reduces confusion about privacy settings and model availability
+- Faster troubleshooting with specific solutions
+
 ## [0.4.25] - 2025-10-04
 
 ### 🔧 UX Improvements

package/lib/ai/ai-config.js

@@ -278,6 +278,15 @@ async function configureAIProvider(projectPath = process.cwd()) {
   // Fetch available models
   const availableModels = await fetchAvailableModels(selectedProvider, apiKey);
 
+  // Show helpful tip about model selection
+  if (selectedProvider.id === 'openrouter' && availableModels.length > 50) {
+    console.log(chalk.gray('\n💡 Tip: Recommended models for best compatibility:'));
+    console.log(chalk.gray('   • anthropic/claude-sonnet-4-5'));
+    console.log(chalk.gray('   • openai/gpt-4-turbo'));
+    console.log(chalk.gray('   • google/gemini-pro-1.5'));
+    console.log(chalk.yellow('   ⚠️  Free models may require specific privacy settings\n'));
+  }
+
   // Model selection with autocomplete
   console.log('');
   const { model } = await inquirer.prompt([
@@ -327,6 +336,44 @@ async function configureAIProvider(projectPath = process.cwd()) {
       spinner.fail(chalk.red('AI connection failed'));
       console.log(chalk.red(`\nError: ${error.message}\n`));
 
+      // Provide specific guidance for common errors
+      const errorMsg = error.message.toLowerCase();
+
+      if (errorMsg.includes('data policy') || errorMsg.includes('privacy')) {
+        console.log(chalk.yellow('📋 Privacy/Data Policy Issue:\n'));
+        if (selectedProvider.id === 'openrouter') {
+          console.log(chalk.gray('   OpenRouter: Free models require specific privacy settings.'));
+          console.log(chalk.cyan('   Solutions:'));
+          console.log(chalk.gray('   1. Configure privacy: https://openrouter.ai/settings/privacy'));
+          console.log(chalk.gray('   2. Select a paid model instead (recommended)'));
+          console.log(chalk.gray('   3. Enable "Free model publication" in settings\n'));
+        } else {
+          console.log(chalk.gray('   The selected model may require specific account settings.'));
+          console.log(chalk.gray('   Try selecting a different model or check your provider settings.\n'));
+        }
+      } else if (errorMsg.includes('404') || errorMsg.includes('not found') || errorMsg.includes('no endpoints')) {
+        console.log(chalk.yellow('📋 Model Not Available:\n'));
+        console.log(chalk.gray('   The selected model may no longer be available or accessible.'));
+        console.log(chalk.cyan('   Solutions:'));
+        console.log(chalk.gray('   1. Select a different, more widely supported model'));
+        console.log(chalk.gray('   2. Check the provider\'s model availability'));
+        console.log(chalk.gray('   3. Some models require specific API endpoints or settings\n'));
+      } else if (errorMsg.includes('400') || errorMsg.includes('unsupported parameter')) {
+        console.log(chalk.yellow('📋 Model Parameter Incompatibility:\n'));
+        console.log(chalk.gray('   The selected model may use different API parameters.'));
+        console.log(chalk.cyan('   Solutions:'));
+        console.log(chalk.gray('   1. Try a more standard model (e.g., gpt-4-turbo, claude-3-5-sonnet)'));
+        console.log(chalk.gray('   2. Some newer/experimental models may not be fully supported yet\n'));
+      } else if (errorMsg.includes('401') || errorMsg.includes('invalid') || errorMsg.includes('unauthorized')) {
+        console.log(chalk.yellow('📋 Invalid API Key:\n'));
+        console.log(chalk.gray('   Please check that your API key is correct and active.\n'));
+      } else if (errorMsg.includes('429') || errorMsg.includes('rate limit')) {
+        console.log(chalk.yellow('📋 Rate Limit:\n'));
+        console.log(chalk.gray('   You\'ve hit the API rate limit. Please wait a moment and try again.\n'));
+      } else {
+        console.log(chalk.yellow('💡 Tip: Try selecting a more widely supported model\n'));
+      }
+
       const { retry } = await inquirer.prompt([
         {
           type: 'confirm',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iservu-inc/adf-cli",
-  "version": "0.4.25",
+  "version": "0.4.26",
   "description": "CLI tool for AgentDevFramework - AI-assisted development framework with multi-provider AI support",
   "main": "index.js",
   "bin": {