fraim-framework 2.0.83 → 2.0.84

package/README.md

@@ -228,11 +228,24 @@ R - Retrospectives: Continuous learning from experience
 **Why Git Bash on Windows?** All FRAIM scripts use Unix-style paths and Bash commands. Git Bash ensures consistent behavior across platforms.
 
 ### **Install & Initialize**
+
+**Recommended: Use npx (no installation needed)**
+```bash
+npx fraim-framework@latest setup --key=<your-fraim-key>
+
+# Optional: Create alias for convenience
+echo 'alias fraim="npx fraim-framework"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+**Alternative: Global install**
 ```bash
 npm install -g fraim-framework
-fraim setup  # Complete setup with IDE configuration
+fraim setup --key=<your-fraim-key>
 ```
 
+> **💡 Why npx?** Works with any Node version (16+), no conflicts when switching Node versions, always uses correct dependencies, and identical functionality to global install. Perfect for users with nvm, volta, or multiple Node versions.
+
 The setup command supports three modes:
 
 **Conversational Mode**: AI workflows only, no platform integration required
@@ -282,7 +295,7 @@ fraim setup --jira                  # Add Jira integration
 fraim init-project                  # Initialize FRAIM in current project
 
 # Testing and validation
-fraim test-mcp                      # Test MCP server connections
+fraim doctor --test-mcp            # Test MCP server connections
 fraim doctor                        # Diagnose configuration issues
 
 # Sync and maintenance
@@ -325,7 +338,7 @@ FRAIM uses the official Model Context Protocol (MCP) server for Jira integration
 **Troubleshooting**:
 ```bash
 # Test Jira MCP connection
-fraim test-mcp
+fraim doctor --test-mcp
 
 # Reconfigure Jira integration
 fraim setup --jira

package/dist/src/cli/commands/add-ide.js

@@ -418,7 +418,7 @@ const runAddIDE = async (options) => {
         console.log(chalk_1.default.blue('\n🔄 Next steps:'));
         console.log(chalk_1.default.cyan('   1. Restart your configured IDEs'));
         console.log(chalk_1.default.cyan('   2. Ask your AI agent: "list fraim workflows"'));
-        console.log(chalk_1.default.blue('\n💡 Use "fraim test-mcp" to verify the configuration.'));
+        console.log(chalk_1.default.blue('\n💡 Use "fraim doctor --test-mcp" to verify the configuration.'));
     }
 };
 exports.runAddIDE = runAddIDE;

package/dist/src/cli/commands/setup.js

@@ -240,16 +240,20 @@ const runSetup = async (options) => {
         console.log(chalk_1.default.blue('📝 Updating existing FRAIM configuration...\n'));
         try {
             const existingConfig = JSON.parse(fs_1.default.readFileSync(globalConfigPath, 'utf8'));
-            fraimKey = existingConfig.apiKey;
+            // Allow updating FRAIM key even without provider changes
+            fraimKey = options.key || existingConfig.apiKey;
             // Now we can parse options with the FRAIM key
             const parsed = await parseLegacyOptions(options, fraimKey);
             requestedProviders = parsed.requestedProviders;
             providedTokens = parsed.providedTokens;
             providedConfigs = parsed.providedConfigs;
-            // Only proceed with update if providers were requested
-            if (requestedProviders.length === 0) {
-                console.log(chalk_1.default.yellow('⚠️ No providers specified for update.'));
-                console.log(chalk_1.default.gray('Use --github, --gitlab, --jira, etc. to add providers.'));
+            // Check if this is just a key update or a provider update
+            const isKeyUpdate = options.key && options.key !== existingConfig.apiKey;
+            const isProviderUpdate = requestedProviders.length > 0;
+            // Only proceed if there's something to update
+            if (!isKeyUpdate && !isProviderUpdate) {
+                console.log(chalk_1.default.yellow('⚠️ No changes specified.'));
+                console.log(chalk_1.default.gray('Use --key to update FRAIM key, or --github, --gitlab, etc. to add providers.'));
                 return;
             }
             mode = existingConfig.mode || 'integrated';
@@ -377,8 +381,9 @@ const runSetup = async (options) => {
     // Save global configuration
     console.log(chalk_1.default.blue('💾 Saving global configuration...'));
     saveGlobalConfig(fraimKey, mode, tokens, configs);
-    // Configure MCP servers (only on initial setup)
+    // Configure MCP servers
     if (!isUpdate) {
+        // Initial setup - configure all detected IDEs
         console.log(chalk_1.default.blue('\n🔌 Configuring MCP servers...'));
         // Convert to legacy format for MCP config generator
         const mcpTokens = {};
@@ -401,7 +406,39 @@ const runSetup = async (options) => {
             console.log(chalk_1.default.yellow('⚠️  MCP configuration encountered issues'));
             console.log(chalk_1.default.gray('   You can configure MCP manually or run setup again later\n'));
         }
-        // Auto-run project init if we're in a git repo
+    }
+    else {
+        // Update existing setup - refresh all IDE MCP configs with new keys
+        console.log(chalk_1.default.blue('\n🔄 Updating IDE MCP configurations...'));
+        try {
+            const { detectInstalledIDEs } = await Promise.resolve().then(() => __importStar(require('../setup/ide-detector')));
+            const installedIDEs = detectInstalledIDEs();
+            if (installedIDEs.length === 0) {
+                console.log(chalk_1.default.gray('   No IDE configurations found to update'));
+            }
+            else {
+                // Convert to legacy format for MCP config generator
+                const mcpTokens = {};
+                Object.entries(tokens).forEach(([id, token]) => {
+                    mcpTokens[id] = token;
+                });
+                // Build providerConfigs map from configs
+                const providerConfigsMap = {};
+                Object.entries(configs).forEach(([providerId, config]) => {
+                    providerConfigsMap[providerId] = config;
+                });
+                const ideNames = installedIDEs.map(ide => ide.name);
+                await (0, auto_mcp_setup_1.autoConfigureMCP)(fraimKey, mcpTokens, ideNames, providerConfigsMap);
+                console.log(chalk_1.default.green(`✅ Updated MCP configs for: ${ideNames.join(', ')}`));
+            }
+        }
+        catch (e) {
+            console.log(chalk_1.default.yellow('⚠️  Failed to update IDE MCP configurations'));
+            console.log(chalk_1.default.gray('   You can update them manually with: fraim add-ide <ide-name>\n'));
+        }
+    }
+    // Auto-run project init if we're in a git repo (only on initial setup)
+    if (!isUpdate) {
         if ((0, platform_detection_1.isGitRepository)()) {
             console.log(chalk_1.default.blue('\n📁 Git repository detected — initializing project...'));
             await (0, init_project_1.runInitProject)();

package/dist/src/cli/fraim.js

@@ -43,7 +43,6 @@ const doctor_1 = require("./commands/doctor");
 const list_1 = require("./commands/list");
 const setup_1 = require("./commands/setup");
 const init_project_1 = require("./commands/init-project");
-const test_mcp_1 = require("./commands/test-mcp");
 const add_ide_1 = require("./commands/add-ide");
 const add_provider_1 = require("./commands/add-provider");
 const override_1 = require("./commands/override");
@@ -80,7 +79,6 @@ program.addCommand(doctor_1.doctorCommand);
 program.addCommand(list_1.listCommand);
 program.addCommand(setup_1.setupCommand);
 program.addCommand(init_project_1.initProjectCommand);
-program.addCommand(test_mcp_1.testMCPCommand);
 program.addCommand(add_ide_1.addIDECommand);
 program.addCommand(add_provider_1.addProviderCommand);
 program.addCommand(override_1.overrideCommand);

package/dist/src/cli/mcp/mcp-server-registry.js

@@ -38,6 +38,8 @@ exports.BASE_MCP_SERVERS = [
         buildServer: (fraimKey) => ({
             command: 'fraim-mcp',
             env: {
+                // Include API key for IDE configs (Codex, VSCode, etc.)
+                // The stdio-server will use this if set, otherwise falls back to ~/.fraim/config.json
                 FRAIM_API_KEY: fraimKey,
                 FRAIM_REMOTE_URL: 'https://fraim.wellnessatwork.me'
             }

package/dist/src/cli/setup/auto-mcp-setup.js

@@ -203,12 +203,20 @@ const configureIDEMCP = async (ide, fraimKey, tokenInput, providerConfigs) => {
         // Merge MCP servers intelligently
         const mergedMCPServers = { ...existingMCPServers };
         const addedServers = [];
+        const updatedServers = [];
         const skippedServers = [];
+        // Servers that should always be updated (not skipped)
+        const alwaysUpdateServers = new Set(['fraim', 'github', 'gitlab', 'jira', 'ado', 'linear']);
         for (const [serverName, serverConfig] of Object.entries(newMCPServers)) {
             if (!existingMCPServers[serverName]) {
                 mergedMCPServers[serverName] = serverConfig;
                 addedServers.push(serverName);
             }
+            else if (alwaysUpdateServers.has(serverName)) {
+                // Always update these servers to ensure keys/tokens are current
+                mergedMCPServers[serverName] = serverConfig;
+                updatedServers.push(serverName);
+            }
             else {
                 skippedServers.push(serverName);
             }
@@ -223,8 +231,11 @@ const configureIDEMCP = async (ide, fraimKey, tokenInput, providerConfigs) => {
         addedServers.forEach(server => {
             console.log(chalk_1.default.green(`  ✅ Added ${server} MCP server`));
         });
+        updatedServers.forEach(server => {
+            console.log(chalk_1.default.blue(`  🔄 Updated ${server} MCP server`));
+        });
         skippedServers.forEach(server => {
-            console.log(chalk_1.default.gray(`  ⏭️ Skipped ${server} (already exists)`));
+            console.log(chalk_1.default.gray(`  ⏭️  Skipped ${server} (already exists)`));
         });
     }
     console.log(chalk_1.default.green(`✅ Updated ${configPath}`));

package/dist/src/core/utils/workflow-parser.js

@@ -13,7 +13,11 @@ class WorkflowParser {
     static parse(filePath) {
         if (!(0, fs_1.existsSync)(filePath))
             return null;
-        const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        let content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        // Strip optional UTF-8 BOM so frontmatter regex remains stable across editors.
+        if (content.charCodeAt(0) === 0xfeff) {
+            content = content.slice(1);
+        }
         // Try to extract JSON Metadata (frontmatter)
         const metadataMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
         if (metadataMatch) {

package/dist/src/local-mcp-server/stdio-server.js

@@ -227,10 +227,11 @@ class FraimLocalMCPServer {
         this.pendingFallbackEvents = [];
         this.fallbackSummaryEmitted = false;
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
-        this.apiKey = process.env.FRAIM_API_KEY || '';
+        this.apiKey = this.loadApiKey();
         this.localVersion = this.detectLocalVersion();
         if (!this.apiKey) {
-            this.logError('❌ FRAIM_API_KEY environment variable is required');
+            this.logError('❌ FRAIM API key is required');
+            this.logError('   Set FRAIM_API_KEY environment variable or add apiKey to ~/.fraim/config.json');
             process.exit(1);
         }
         this.log('🚀 FRAIM Local MCP Server starting... [DEBUG-PROXY-V3]');
@@ -239,6 +240,33 @@ class FraimLocalMCPServer {
         this.log(`Local MCP version: ${this.localVersion}`);
         this.log(`🔍 DEBUG BUILD: Machine detection v2 active`);
     }
+    /**
+     * Load API key from environment variable or user config file
+     * Priority: FRAIM_API_KEY env var > ~/.fraim/config.json
+     */
+    loadApiKey() {
+        // First try environment variable (for IDE MCP configs)
+        if (process.env.FRAIM_API_KEY) {
+            return process.env.FRAIM_API_KEY;
+        }
+        // Fallback to user config file
+        try {
+            const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+            if (!homeDir)
+                return '';
+            const configPath = (0, path_1.join)(homeDir, '.fraim', 'config.json');
+            if ((0, fs_1.existsSync)(configPath)) {
+                const config = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+                if (config.apiKey) {
+                    return config.apiKey;
+                }
+            }
+        }
+        catch (error) {
+            // Ignore errors, will fail with clear message below
+        }
+        return '';
+    }
     log(message) {
         // Log to stderr (stdout is reserved for MCP protocol)
         const key = this.apiKey || 'MISSING_API_KEY';
@@ -736,38 +764,10 @@ class FraimLocalMCPServer {
                 if (parsed) {
                     engine.setProviderTemplates(provider, parsed);
                     this.writeCachedTemplateFile(filename, parsed);
-                    continue;
                 }
             }
-            const bundled = this.readBundledTemplateFile(filename);
-            if (bundled) {
-                engine.setProviderTemplates(provider, bundled);
-            }
         }
     }
-    readBundledTemplateFile(filename) {
-        const candidates = [
-            (0, path_1.join)(__dirname, '..', '..', '..', 'registry', 'providers', filename),
-            (0, path_1.join)(__dirname, '..', '..', 'registry', 'providers', filename),
-            (0, path_1.join)(process.cwd(), 'registry', 'providers', filename)
-        ];
-        for (const candidate of candidates) {
-            try {
-                if (!(0, fs_1.existsSync)(candidate))
-                    continue;
-                const content = (0, fs_1.readFileSync)(candidate, 'utf8');
-                const parsed = JSON.parse(content);
-                if (parsed && typeof parsed === 'object') {
-                    this.log(`✅ Loaded bundled provider template: ${candidate}`);
-                    return parsed;
-                }
-            }
-            catch (error) {
-                this.log(`⚠️ Failed to load bundled template ${candidate}: ${error.message}`);
-            }
-        }
-        return null;
-    }
     async hydrateTemplateCachesForResponse(response, requestSessionId) {
         if (!response.result)
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.83",
+  "version": "2.0.84",
   "description": "FRAIM v2: Framework for Rigor-based AI Management - Transform from solo developer to AI manager orchestrating production-ready code with enterprise-grade discipline",
   "main": "index.js",
   "bin": {
@@ -29,14 +29,16 @@
     "postinstall": "fraim sync --skip-updates || echo 'FRAIM setup skipped.'",
     "prepublishOnly": "npm run build",
     "release": "npm version patch && npm publish",
-    "validate:registry": "tsx scripts/verify-registry-paths.ts && npm run validate:workflows && npm run validate:skills && npm run validate:platform-agnostic && npm run validate:template-namespaces && npm run validate:config-fallbacks && npm run validate:bootstrap-config-coverage && npm run validate:provider-action-mappings",
+    "validate:registry": "tsx scripts/verify-registry-paths.ts && npm run validate:workflows && npm run validate:skills && npm run validate:platform-agnostic && npm run validate:template-namespaces && npm run validate:config-fallbacks && npm run validate:bootstrap-config-coverage && npm run validate:provider-action-mappings && npm run validate:fidelity && npm run validate:config-tokens",
     "validate:workflows": "tsx scripts/validate-workflows.ts",
     "validate:platform-agnostic": "tsx scripts/validate-platform-agnostic.ts",
     "validate:skills": "tsx scripts/validate-skills.ts",
     "validate:template-namespaces": "tsx scripts/validate-template-namespaces.ts",
     "validate:config-fallbacks": "tsx scripts/validate-config-fallbacks.ts",
     "validate:bootstrap-config-coverage": "tsx scripts/validate-bootstrap-config-coverage.ts",
-    "validate:provider-action-mappings": "tsx scripts/validate-provider-action-mappings.ts"
+    "validate:provider-action-mappings": "tsx scripts/validate-provider-action-mappings.ts",
+    "validate:fidelity": "tsx scripts/validate-fidelity.ts",
+    "validate:config-tokens": "tsx scripts/validate-config-tokens.ts"
   },
   "repository": {
     "type": "git",