fraim-framework 2.0.63 → 2.0.65

package/bin/fraim-mcp.js

@@ -1,30 +1,63 @@
 #!/usr/bin/env node
+
 /**
- * FRAIM Local MCP Proxy
- * 
- * This is a thin wrapper that launches the local STDIO MCP server.
- * The actual implementation is in dist/src/local-mcp-server/stdio-server.js
+ * FRAIM MCP Server - Smart Entry Point
+ * This file handles both production (dist/) and development (src/) environments.
  */
 
 const path = require('path');
+const fs = require('fs');
 const { spawn } = require('child_process');
 
-// Path to the actual server implementation
-const serverPath = path.join(__dirname, '..', 'dist', 'src', 'local-mcp-server', 'stdio-server.js');
+/**
+ * Runs the MCP server using either the compiled JS or the source TS via tsx
+ */
+function runMCPServer() {
+    const distPath = path.join(__dirname, '..', 'dist', 'src', 'local-mcp-server', 'stdio-server.js');
+    const srcPath = path.join(__dirname, '..', 'src', 'local-mcp-server', 'stdio-server.ts');
 
-// Spawn the server with all arguments and environment variables
-const server = spawn('node', [serverPath, ...process.argv.slice(2)], {
-    stdio: 'inherit',
-    env: process.env
-});
+    // 1. Check if we have a compiled version (Production / CI)
+    if (fs.existsSync(distPath)) {
+        // Use spawn to run the compiled JS so it's treated as the main module
+        const result = spawn('node', [distPath, ...process.argv.slice(2)], {
+            stdio: 'inherit',
+            shell: false,
+            windowsHide: true
+        });
+        
+        // Forward exit code
+        result.on('exit', (code) => {
+            process.exit(code || 0);
+        });
+        
+        return;
+    }
 
-// Forward exit code
-server.on('exit', (code) => {
-    process.exit(code || 0);
-});
+    // 2. Fallback to source version using tsx (Development)
+    if (fs.existsSync(srcPath)) {
+        // Use spawn to run tsx so it handles stdio correctly for MCP
+        const result = spawn('npx', ['tsx', srcPath, ...process.argv.slice(2)], {
+            stdio: 'inherit',
+            shell: true,
+            windowsHide: true
+        });
+        
+        // Forward exit code
+        result.on('exit', (code) => {
+            process.exit(code || 0);
+        });
+        
+        return;
+    }
 
-// Handle errors
-server.on('error', (err) => {
-    console.error('Failed to start FRAIM MCP server:', err);
+    console.error('❌ FRAIM MCP Server Error: Could not find server entry point.');
+    console.error('Expected one of:');
+    console.error(` - ${distPath}`);
+    console.error(` - ${srcPath}`);
     process.exit(1);
-});
+}
+
+// If this file is run directly, run the MCP server
+if (require.main === module) {
+    runMCPServer();
+}

package/bin/fraim.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * FRAIM Framework CLI Entry Point
+ *
+ * This file delegates to the compiled TypeScript implementation.
+ */
+
+try {
+    // In production/installed package, code is in dist/
+    require('../dist/src/cli/fraim.js');
+} catch (error) {
+    if (error.code === 'MODULE_NOT_FOUND') {
+        // In development (local clone), we might use tsx if dist is missing
+        // But typically we should just tell user to build.
+        console.error('❌ Could not find FRAIM CLI implementation.');
+        console.error('   If you are running from source, please run "npm run build" first.');
+        console.error(`   Error details: ${error.message}`);
+        process.exit(1);
+    } else {
+        throw error;
+    }
+}

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

@@ -21,7 +21,8 @@ const loadGlobalConfig = () => {
         const config = JSON.parse(fs_1.default.readFileSync(globalConfigPath, 'utf8'));
         return {
             fraimKey: config.apiKey,
-            githubToken: config.githubToken
+            githubToken: config.tokens?.github || config.githubToken, // Support both old and new format
+            mode: config.mode
         };
     }
     catch (e) {
@@ -29,22 +30,44 @@ const loadGlobalConfig = () => {
     }
 };
 exports.loadGlobalConfig = loadGlobalConfig;
-const promptForGitHubToken = async () => {
-    console.log(chalk_1.default.yellow('\n🔑 GitHub token needed for MCP configuration'));
-    console.log(chalk_1.default.gray('This is required for git and GitHub MCP servers to function properly.\n'));
+const promptForGitHubToken = async (isConversationalMode = false) => {
+    if (isConversationalMode) {
+        console.log(chalk_1.default.yellow('\n🔑 GitHub token (optional for conversational mode)'));
+        console.log(chalk_1.default.gray('GitHub token enables GitHub-specific MCP features.\n'));
+        const wantsToken = await (0, prompts_1.default)({
+            type: 'confirm',
+            name: 'addToken',
+            message: 'Do you want to add a GitHub token?',
+            initial: false
+        });
+        if (!wantsToken.addToken) {
+            console.log(chalk_1.default.blue('ℹ️  Skipping GitHub token - GitHub MCP server will not be configured'));
+            return '';
+        }
+    }
+    else {
+        console.log(chalk_1.default.yellow('\n🔑 GitHub token needed for MCP configuration'));
+        console.log(chalk_1.default.gray('This is required for git and GitHub MCP servers to function properly.\n'));
+    }
     const tokenResponse = await (0, prompts_1.default)({
         type: 'password',
         name: 'token',
         message: 'Enter your GitHub token',
         validate: (value) => {
-            if (!value)
+            if (!value && !isConversationalMode)
                 return 'GitHub token is required';
+            if (!value && isConversationalMode)
+                return true; // Allow empty in conversational mode
             if (value.startsWith('ghp_') || value.startsWith('github_pat_'))
                 return true;
             return 'Please enter a valid GitHub token (starts with ghp_ or github_pat_)';
         }
     });
     if (!tokenResponse.token) {
+        if (isConversationalMode) {
+            console.log(chalk_1.default.blue('ℹ️  No GitHub token provided - GitHub MCP server will not be configured'));
+            return '';
+        }
         console.log(chalk_1.default.red('GitHub token is required. Exiting.'));
         process.exit(1);
     }
@@ -55,7 +78,13 @@ const saveGitHubTokenToConfig = (githubToken) => {
     if (fs_1.default.existsSync(globalConfigPath)) {
         try {
             const config = JSON.parse(fs_1.default.readFileSync(globalConfigPath, 'utf8'));
-            config.githubToken = githubToken;
+            // Use new tokens structure if it exists, otherwise fall back to old format
+            if (config.tokens) {
+                config.tokens.github = githubToken;
+            }
+            else {
+                config.githubToken = githubToken;
+            }
             fs_1.default.writeFileSync(globalConfigPath, JSON.stringify(config, null, 2));
             console.log(chalk_1.default.green('✅ GitHub token saved to global config'));
         }
@@ -170,7 +199,7 @@ const listSupportedIDEs = () => {
     console.log(chalk_1.default.yellow('💡 Use "fraim add-ide --ide <name>" to configure a specific IDE'));
     console.log(chalk_1.default.yellow('   Example: fraim add-ide --ide claude'));
 };
-const promptForIDESelection = async (availableIDEs) => {
+const promptForIDESelection = async (availableIDEs, githubToken) => {
     console.log(chalk_1.default.green(`✅ Found ${availableIDEs.length} IDEs that can be configured:\n`));
     availableIDEs.forEach((ide, index) => {
         const configExists = fs_1.default.existsSync((0, ide_detector_1.expandPath)(ide.configPath));
@@ -181,7 +210,9 @@ const promptForIDESelection = async (availableIDEs) => {
     console.log(chalk_1.default.blue('\nFRAIM will add these MCP servers:'));
     console.log(chalk_1.default.gray('   • fraim (workflows and AI management)'));
     console.log(chalk_1.default.gray('   • git (version control integration)'));
-    console.log(chalk_1.default.gray('   • github (GitHub API access)'));
+    if (githubToken) {
+        console.log(chalk_1.default.gray('   • github (GitHub API access)'));
+    }
     console.log(chalk_1.default.gray('   • playwright (browser automation)'));
     const response = await (0, prompts_1.default)({
         type: 'text',
@@ -221,12 +252,20 @@ const runAddIDE = async (options) => {
         process.exit(1);
     }
     let githubToken = globalConfig.githubToken;
-    if (!githubToken) {
+    const isConversationalMode = globalConfig.mode === 'conversational';
+    if (!githubToken && !isConversationalMode) {
         console.log(chalk_1.default.yellow('⚠️ No GitHub token found in configuration.'));
-        githubToken = await promptForGitHubToken();
-        saveGitHubTokenToConfig(githubToken);
+        githubToken = await promptForGitHubToken(false);
+        if (githubToken) {
+            saveGitHubTokenToConfig(githubToken);
+        }
+    }
+    if (isConversationalMode && !githubToken) {
+        console.log(chalk_1.default.blue('ℹ️  Conversational mode: Configuring MCP without GitHub integration\n'));
+    }
+    else {
+        console.log(chalk_1.default.green('✅ Using existing FRAIM configuration\n'));
     }
-    console.log(chalk_1.default.green('✅ Using existing FRAIM configuration\n'));
     // Detect available IDEs
     const detectedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
     if (detectedIDEs.length === 0) {
@@ -258,7 +297,7 @@ const runAddIDE = async (options) => {
     }
     else {
         // Interactive selection
-        idesToConfigure = await promptForIDESelection(detectedIDEs);
+        idesToConfigure = await promptForIDESelection(detectedIDEs, githubToken);
     }
     if (idesToConfigure.length === 0) {
         console.log(chalk_1.default.yellow('⚠️ No IDEs selected for configuration.'));
@@ -271,7 +310,7 @@ const runAddIDE = async (options) => {
     };
     for (const ide of idesToConfigure) {
         try {
-            await configureIDEMCP(ide, globalConfig.fraimKey, githubToken);
+            await configureIDEMCP(ide, globalConfig.fraimKey, githubToken || '');
             results.successful.push(ide.name);
         }
         catch (error) {

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

@@ -8,7 +8,6 @@ const commander_1 = require("commander");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
-const digest_utils_1 = require("../../utils/digest-utils");
 exports.doctorCommand = new commander_1.Command('doctor')
     .description('Validate FRAIM installation and configuration')
     .action(async () => {
@@ -50,33 +49,22 @@ exports.doctorCommand = new commander_1.Command('doctor')
             issuesFound++;
         }
     }
-    // 4. Check registry & sync status
-    const digestPath = path_1.default.join(fraimDir, '.digest');
-    // Try 4 levels up (dist/src/cli/commands -> root)
-    let registryPath = path_1.default.join(__dirname, '../../../../registry/stubs');
-    if (!fs_1.default.existsSync(registryPath)) {
-        // Try 3 levels up (src/cli/commands -> root)
-        registryPath = path_1.default.join(__dirname, '../../../registry/stubs');
-    }
-    // Fallback for local development if running from within the framework repo itself (and CWD is root)
-    if (!fs_1.default.existsSync(registryPath)) {
-        registryPath = path_1.default.join(projectRoot, 'registry/stubs');
-    }
-    if (!fs_1.default.existsSync(registryPath)) {
-        console.log(chalk_1.default.yellow('⚠️ Could not locate framework stub registry. (Expected in node_modules/@fraim/framework/registry/stubs)'));
-    }
-    else {
-        console.log(chalk_1.default.green('✅ Framework stub registry found.'));
-        const currentDigest = await (0, digest_utils_1.generateDigest)(registryPath);
-        const existingDigest = fs_1.default.existsSync(digestPath) ? fs_1.default.readFileSync(digestPath, 'utf8') : '';
-        if (currentDigest !== existingDigest) {
-            console.log(chalk_1.default.yellow('⚠️ Local stubs are out of sync with registry. Run "fraim sync".'));
-            issuesFound++;
+    // 4. Check sync status (remote or local)
+    // With Issue #83, stubs are no longer in the package - they're fetched from remote server
+    // Check if config has remoteUrl configured
+    try {
+        const config = JSON.parse(fs_1.default.readFileSync(configPath, 'utf8'));
+        if (config.remoteUrl && config.apiKey) {
+            console.log(chalk_1.default.green('✅ Remote sync configured (remoteUrl and apiKey present).'));
         }
         else {
-            console.log(chalk_1.default.green('✅ Local stubs are in sync.'));
+            console.log(chalk_1.default.yellow('⚠️ Remote sync not configured. Run "fraim sync" to fetch workflows from server.'));
+            console.log(chalk_1.default.gray('   Add remoteUrl and apiKey to .fraim/config.json for remote sync.'));
         }
     }
+    catch (e) {
+        // Config check already failed above, skip this check
+    }
     if (issuesFound === 0) {
         console.log(chalk_1.default.green('\n✨ Everything looks great! Your project is FRAIM-ready.'));
     }

package/dist/src/cli/commands/init-project.js

@@ -62,7 +62,6 @@ const runInitProject = async () => {
                 project: {
                     name: projectName
                 },
-                mode: 'conversational',
                 customizations: {
                     workflowsPath: '.fraim/workflows'
                 }
@@ -88,7 +87,6 @@ const runInitProject = async () => {
                         name: detection.repository.name
                     },
                     repository: detection.repository,
-                    mode: 'integrated',
                     customizations: {
                         workflowsPath: '.fraim/workflows'
                     }
@@ -123,7 +121,6 @@ const runInitProject = async () => {
                         url: `https://github.com/your-username/${repoName}.git`,
                         defaultBranch: 'main'
                     },
-                    mode: 'integrated',
                     customizations: {
                         workflowsPath: '.fraim/workflows'
                     }

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

@@ -61,7 +61,6 @@ const runInit = async (options = {}) => {
                 project: {
                     name: projectName
                 },
-                mode: 'conversational',
                 customizations: {
                     workflowsPath: '.fraim/workflows'
                 }
@@ -99,7 +98,6 @@ const runInit = async (options = {}) => {
                     name: detection.repository.name
                 },
                 repository: detection.repository,
-                mode: 'integrated',
                 customizations: {
                     workflowsPath: '.fraim/workflows'
                 }

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

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpCommand = void 0;
+const commander_1 = require("commander");
+const server_1 = require("../../local-mcp-server/server");
+const chalk_1 = __importDefault(require("chalk"));
+exports.mcpCommand = new commander_1.Command('mcp')
+    .description('Start the local FRAIM MCP server')
+    .option('-p, --port <port>', 'Port to run the server on', '3003')
+    .option('--remote-only', 'Use remote server only (skip local proxy)', false)
+    .action(async (options) => {
+    try {
+        if (options.remoteOnly) {
+            console.log(chalk_1.default.yellow('⚠️ Remote-only mode not yet implemented'));
+            console.log(chalk_1.default.blue('ℹ️ Starting local MCP server instead...'));
+        }
+        const port = parseInt(options.port);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            console.error(chalk_1.default.red('❌ Invalid port number. Must be between 1 and 65535.'));
+            process.exit(1);
+        }
+        console.log(chalk_1.default.blue('🚀 Starting FRAIM Local MCP Server...'));
+        console.log(chalk_1.default.gray(`📡 Port: ${port}`));
+        console.log(chalk_1.default.gray(`🔄 Auto-updates: Every 5 minutes`));
+        console.log(chalk_1.default.gray(`📁 Cache: ~/.fraim/cache`));
+        console.log('');
+        // Set the port in environment
+        process.env.FRAIM_LOCAL_MCP_PORT = port.toString();
+        // Start the server
+        await (0, server_1.startLocalMCPServer)();
+        // Server is now running, show configuration instructions
+        console.log('');
+        console.log(chalk_1.default.green('✅ FRAIM Local MCP Server is running!'));
+        console.log('');
+        console.log(chalk_1.default.bold('📋 Agent Configuration:'));
+        console.log('');
+        console.log(chalk_1.default.gray('Add this to your agent\'s MCP configuration:'));
+        console.log('');
+        console.log(chalk_1.default.cyan(JSON.stringify({
+            "mcpServers": {
+                "fraim": {
+                    "command": "fraim",
+                    "args": ["mcp"],
+                    "env": {}
+                }
+            }
+        }, null, 2)));
+        console.log('');
+        console.log(chalk_1.default.bold('🔗 Endpoints:'));
+        console.log(chalk_1.default.gray(`  MCP: http://localhost:${port}/mcp`));
+        console.log(chalk_1.default.gray(`  Health: http://localhost:${port}/health`));
+        console.log('');
+        console.log(chalk_1.default.bold('🛑 To stop the server:'));
+        console.log(chalk_1.default.gray('  Press Ctrl+C'));
+        console.log('');
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('❌ Failed to start Local MCP Server:'));
+        console.error(chalk_1.default.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});

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

@@ -370,8 +370,24 @@ const runSetup = async (options) => {
     // Save global configuration
     console.log(chalk_1.default.blue('💾 Saving global configuration...'));
     saveGlobalConfig(fraimKey, mode, tokens);
-    // Sync global scripts (only on initial setup)
+    // Configure MCP servers (only on initial setup)
     if (!isUpdate) {
+        console.log(chalk_1.default.blue('\n🔌 Configuring MCP servers...'));
+        // For conversational mode, we still configure MCP but without GitHub token requirement
+        // The FRAIM MCP server works without GitHub token, other servers can be optional
+        const mcpGitHubToken = tokens.github || '';
+        if (mode === 'conversational' && !mcpGitHubToken) {
+            console.log(chalk_1.default.yellow('ℹ️  Conversational mode: Configuring MCP servers without GitHub integration'));
+            console.log(chalk_1.default.gray('   FRAIM workflows will work, but GitHub-specific features will be unavailable\n'));
+        }
+        try {
+            await (0, auto_mcp_setup_1.autoConfigureMCP)(fraimKey, mcpGitHubToken, options.ide ? [options.ide] : undefined);
+        }
+        catch (e) {
+            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'));
+        }
+        // Sync global scripts
         syncGlobalScripts();
     }
     // Show summary