fraim-framework 2.0.89 → 2.0.91

package/bin/fraim-mcp.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * FRAIM MCP Server - Smart Entry Point

package/dist/src/core/utils/stub-generator.js

@@ -50,11 +50,11 @@ function extractLeadParagraph(content) {
  * These stubs are committed to the user's repo for discoverability.
  */
 function generateWorkflowStub(workflowName, workflowPath, intent, principles) {
-    return `${STUB_MARKER}
-# FRAIM Workflow: ${workflowName}
-
-> [!IMPORTANT]
-> This is a **FRAIM-managed workflow stub**. 
+    return `${STUB_MARKER}
+# FRAIM Workflow: ${workflowName}
+
+> [!IMPORTANT]
+> This is a **FRAIM-managed workflow stub**. 
 > To load the full context (rules, templates, and execution steps), ask your AI agent to:
 > \`@fraim get_fraim_workflow("${workflowName}")\`
 >
@@ -81,19 +81,19 @@ function parseRegistryWorkflow(content) {
  * Coaching stubs are discoverability artifacts and should be resolved with get_fraim_file.
  */
 function generateJobStub(jobName, _jobPath, intent, outcome, steps) {
-    return `${STUB_MARKER}
-# FRAIM Job: ${jobName}
-
-## Intent
-${intent}
-
-## Outcome
-${outcome}
-
-## Steps
-${steps}
-
----
+    return `${STUB_MARKER}
+# FRAIM Job: ${jobName}
+
+## Intent
+${intent}
+
+## Outcome
+${outcome}
+
+## Steps
+${steps}
+
+---
 
 > [!IMPORTANT]
 > **For AI Agents:** Do NOT attempt to execute this job based on the Intent/Outcome above.
@@ -110,41 +110,41 @@ ${steps}
  * Generates a lightweight markdown stub for a skill.
  */
 function generateSkillStub(skillName, skillPath, skillInput, skillOutput) {
-    return `${STUB_MARKER}
-# FRAIM Skill: ${skillName}
-
-## Skill Input
-${skillInput}
-
-## Skill Output
-${skillOutput}
-
----
-
-> [!IMPORTANT]
-> **For AI Agents:** This is a discoverability stub for the skill.
-> All execution details must be fetched from MCP before use.
-> To retrieve the complete skill instructions, call:
-> \`get_fraim_file({ path: "skills/${skillPath}" })\`
+    return `${STUB_MARKER}
+# FRAIM Skill: ${skillName}
+
+## Skill Input
+${skillInput}
+
+## Skill Output
+${skillOutput}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** This is a discoverability stub for the skill.
+> All execution details must be fetched from MCP before use.
+> To retrieve the complete skill instructions, call:
+> \`get_fraim_file({ path: "skills/${skillPath}" })\`
 `;
 }
 /**
  * Generates a lightweight markdown stub for a rule.
  */
 function generateRuleStub(ruleName, rulePath, intent) {
-    return `${STUB_MARKER}
-# FRAIM Rule: ${ruleName}
-
-## Intent
-${intent}
-
----
-
-> [!IMPORTANT]
-> **For AI Agents:** This is a discoverability stub for the rule.
-> All rule details must be fetched from MCP before use.
-> To retrieve the complete rule instructions, call:
-> \`get_fraim_file({ path: "rules/${rulePath}" })\`
+    return `${STUB_MARKER}
+# FRAIM Rule: ${ruleName}
+
+## Intent
+${intent}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** This is a discoverability stub for the rule.
+> All rule details must be fetched from MCP before use.
+> To retrieve the complete rule instructions, call:
+> \`get_fraim_file({ path: "rules/${rulePath}" })\`
 `;
 }
 /**

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

@@ -29,6 +29,7 @@ const provider_utils_1 = require("../core/utils/provider-utils");
 const object_utils_1 = require("../core/utils/object-utils");
 const local_registry_resolver_1 = require("../core/utils/local-registry-resolver");
 const ai_mentor_1 = require("../core/ai-mentor");
+const usage_collector_js_1 = require("./usage-collector.js");
 /**
  * Handle template substitution logic separately for better testability
  */
@@ -264,6 +265,9 @@ class FraimLocalMCPServer {
         this.log(`🔑 API key: ${this.apiKey.substring(0, 10)}...`);
         this.log(`Local MCP version: ${this.localVersion}`);
         this.log(`🔍 DEBUG BUILD: Machine detection v2 active`);
+        // Initialize usage collector
+        this.usageCollector = new usage_collector_js_1.UsageCollector();
+        this.log('📊 Usage analytics collector initialized');
     }
     /**
      * Load API key from environment variable or user config file
@@ -1402,9 +1406,9 @@ class FraimLocalMCPServer {
         // Force ALL tools/call requests to return raw definitions so the proxy
         // can resolve templates and replace includes locally
         const toolName = request.params?.name;
+        const args = request.params?.arguments || {};
         let injectedRequest = request;
         if (request.method === 'tools/call' && typeof toolName === 'string') {
-            const args = request.params.arguments || {};
             // 🔍 SMART DISPATCHER: Intercept mentoring and job/workflow tools for local overrides
             if (toolName === 'seekMentoring') {
                 try {
@@ -1482,6 +1486,11 @@ class FraimLocalMCPServer {
         }
         const response = await this._doProxyToRemote(injectedRequest, requestId);
         const processedResponse = await this.finalizeToolResponse(injectedRequest, response, requestSessionId, requestId);
+        // Single point for usage tracking - log all tool calls
+        if (injectedRequest.method === 'tools/call' && requestSessionId && toolName) {
+            const success = !processedResponse.error;
+            this.usageCollector.collectMCPCall(toolName, args, requestSessionId, success);
+        }
         this.log(`📤 ${injectedRequest.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
         return processedResponse;
     }
@@ -1574,6 +1583,17 @@ class FraimLocalMCPServer {
     start() {
         let buffer = '';
         process.stdin.setEncoding('utf8');
+        // Set up periodic usage data upload
+        const uploadInterval = setInterval(() => {
+            this.uploadUsageData().catch(error => {
+                this.log(`⚠️ Failed to upload usage data: ${error.message}`);
+            });
+        }, 60000); // Upload every minute
+        // Clean up interval on shutdown
+        const cleanup = () => {
+            clearInterval(uploadInterval);
+            this.usageCollector.shutdown();
+        };
         process.stdin.on('data', async (chunk) => {
             buffer += chunk;
             // Process complete JSON-RPC messages (newline-delimited)
@@ -1629,21 +1649,52 @@ class FraimLocalMCPServer {
         });
         process.stdin.on('end', () => {
             this.log('🛑 Stdin closed, shutting down...');
+            cleanup();
             this.emitFallbackSummary('stdin_end');
             process.exit(0);
         });
         process.on('SIGTERM', () => {
             this.log('🛑 SIGTERM received, shutting down...');
+            cleanup();
             this.emitFallbackSummary('sigterm');
             process.exit(0);
         });
         process.on('SIGINT', () => {
             this.log('🛑 SIGINT received, shutting down...');
+            cleanup();
             this.emitFallbackSummary('sigint');
             process.exit(0);
         });
         this.log('✅ FRAIM Local MCP Server ready');
     }
+    /**
+     * Upload collected usage data to the remote server
+     */
+    async uploadUsageData() {
+        const events = this.usageCollector.getEventsForUpload();
+        if (events.length === 0) {
+            return; // Nothing to upload
+        }
+        try {
+            const response = await axios_1.default.post(`${this.remoteUrl}/api/analytics/events`, { events }, {
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey
+                },
+                timeout: 10000
+            });
+            if (response.status === 200) {
+                this.log(`📊 Uploaded ${events.length} usage events`);
+            }
+            else {
+                this.log(`⚠️ Usage upload failed: ${response.status}`);
+            }
+        }
+        catch (error) {
+            this.log(`❌ Usage upload error: ${error.message}`);
+            // Don't re-queue on failure - keep it simple
+        }
+    }
 }
 exports.FraimLocalMCPServer = FraimLocalMCPServer;
 FraimLocalMCPServer.AGENT_RESOLUTION_NOTICE = [

package/dist/src/local-mcp-server/usage-collector.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageCollector = void 0;
+/**
+ * Usage event collector for local MCP proxy
+ * Collects usage events and batches them for upload
+ */
+class UsageCollector {
+    constructor() {
+        this.events = [];
+        this.apiKeyId = null;
+    }
+    /**
+     * Set the API key ID for this session
+     */
+    setApiKeyId(apiKeyId) {
+        this.apiKeyId = apiKeyId;
+    }
+    /**
+     * Collect MCP tool call event
+     */
+    collectMCPCall(toolName, args, sessionId, success = true, duration) {
+        if (!this.apiKeyId) {
+            return; // Silently skip if no API key
+        }
+        const parsed = this.parseMCPCall(toolName, args);
+        if (!parsed)
+            return;
+        const event = {
+            type: parsed.type,
+            name: parsed.name,
+            apiKeyId: this.apiKeyId,
+            sessionId,
+            success
+        };
+        if (duration !== undefined) {
+            event.duration = duration;
+        }
+        this.events.push(event);
+    }
+    /**
+     * Collect usage event directly (for backward compatibility with tests)
+     */
+    collectEvent(type, name, sessionId, success = true, duration) {
+        if (!this.apiKeyId) {
+            return; // Silently skip if no API key
+        }
+        const event = {
+            type,
+            name,
+            apiKeyId: this.apiKeyId,
+            sessionId,
+            success
+        };
+        if (duration !== undefined) {
+            event.duration = duration;
+        }
+        this.events.push(event);
+    }
+    /**
+     * Parse MCP tool call to extract usage analytics info
+     */
+    parseMCPCall(toolName, args) {
+        switch (toolName) {
+            case 'get_fraim_job':
+                return { type: 'job', name: args.job || 'unknown' };
+            case 'get_fraim_file':
+                if (args.path) {
+                    return UsageCollector.parseComponentName(args.path);
+                }
+                return null;
+            case 'seekMentoring':
+                return { type: 'mentoring', name: args.workflowType || 'unknown' };
+            default:
+                return null;
+        }
+    }
+    /**
+     * Get collected events for upload and clear the queue
+     */
+    getEventsForUpload() {
+        const eventsToUpload = [...this.events];
+        this.events = [];
+        return eventsToUpload;
+    }
+    /**
+     * Get current event count
+     */
+    getEventCount() {
+        return this.events.length;
+    }
+    /**
+     * Shutdown the collector
+     */
+    shutdown() {
+        this.events = [];
+    }
+    /**
+     * Parse component name from file path
+     */
+    static parseComponentName(path) {
+        if (path.includes('/jobs/')) {
+            const jobMatch = path.match(/\/jobs\/[^/]+\/[^/]+\/([^/]+)\.md$/);
+            if (jobMatch) {
+                return { type: 'job', name: jobMatch[1] };
+            }
+        }
+        if (path.includes('/skills/')) {
+            const skillMatch = path.match(/\/skills\/[^/]+\/([^/]+)\.md$/);
+            if (skillMatch) {
+                return { type: 'skill', name: skillMatch[1] };
+            }
+        }
+        if (path.includes('/rules/')) {
+            const ruleMatch = path.match(/\/rules\/[^/]+\/([^/]+)\.md$/);
+            if (ruleMatch) {
+                return { type: 'rule', name: ruleMatch[1] };
+            }
+        }
+        return null;
+    }
+}
+exports.UsageCollector = UsageCollector;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.89",
+  "version": "2.0.91",
   "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": {

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

@@ -1,171 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.testMCPCommand = exports.runTestMCP = void 0;
-const commander_1 = require("commander");
-const chalk_1 = __importDefault(require("chalk"));
-const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
-const ide_detector_1 = require("../setup/ide-detector");
-const script_sync_utils_1 = require("../utils/script-sync-utils");
-const testIDEConfig = async (ide) => {
-    const result = {
-        ide: ide.name,
-        configExists: false,
-        configValid: false,
-        mcpServers: [],
-        errors: []
-    };
-    const configPath = (0, ide_detector_1.expandPath)(ide.configPath);
-    if (!fs_1.default.existsSync(configPath)) {
-        result.errors.push('Config file does not exist');
-        return result;
-    }
-    result.configExists = true;
-    try {
-        if (ide.configFormat === 'json') {
-            const configContent = fs_1.default.readFileSync(configPath, 'utf8');
-            const config = JSON.parse(configContent);
-            const servers = ide.configType === 'vscode' ? config.servers : config.mcpServers;
-            if (servers) {
-                result.configValid = true;
-                result.mcpServers = Object.keys(servers);
-            }
-            else {
-                const expectedKey = ide.configType === 'vscode' ? 'servers' : 'mcpServers';
-                result.errors.push(`No ${expectedKey} section found`);
-            }
-        }
-        else if (ide.configFormat === 'toml') {
-            const configContent = fs_1.default.readFileSync(configPath, 'utf8');
-            // Simple TOML parsing for MCP servers
-            const serverMatches = configContent.match(/\[mcp_servers\.(\w+)\]/g);
-            if (serverMatches) {
-                result.configValid = true;
-                result.mcpServers = serverMatches.map(match => match.replace(/\[mcp_servers\.(\w+)\]/, '$1'));
-            }
-            else {
-                result.errors.push('No mcp_servers sections found');
-            }
-        }
-    }
-    catch (error) {
-        result.errors.push(`Failed to parse config: ${error instanceof Error ? error.message : 'Unknown error'}`);
-    }
-    return result;
-};
-const checkGlobalSetup = () => {
-    const globalConfigPath = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'config.json');
-    return fs_1.default.existsSync(globalConfigPath);
-};
-const runTestMCP = async () => {
-    console.log(chalk_1.default.blue('🔍 Testing MCP configuration...\n'));
-    // Check global setup
-    if (!checkGlobalSetup()) {
-        console.log(chalk_1.default.red('❌ Global FRAIM setup not found.'));
-        console.log(chalk_1.default.yellow('Please run: fraim setup --key=<your-fraim-key>'));
-        return;
-    }
-    console.log(chalk_1.default.green('✅ Global FRAIM setup found'));
-    // Detect IDEs
-    const detectedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
-    if (detectedIDEs.length === 0) {
-        console.log(chalk_1.default.yellow('⚠️ No supported IDEs detected.'));
-        return;
-    }
-    console.log(chalk_1.default.blue(`\n🔍 Testing ${detectedIDEs.length} detected IDEs...\n`));
-    const results = await Promise.all(detectedIDEs.map(ide => testIDEConfig(ide)));
-    let totalConfigured = 0;
-    let totalWithFRAIM = 0;
-    for (const result of results) {
-        console.log(chalk_1.default.white(`📱 ${result.ide}`));
-        if (!result.configExists) {
-            console.log(chalk_1.default.red('   ❌ No MCP config found'));
-            console.log(chalk_1.default.gray(`   💡 Run: fraim setup --ide=${result.ide.toLowerCase()}`));
-        }
-        else if (!result.configValid) {
-            console.log(chalk_1.default.yellow('   ⚠️ Config exists but invalid'));
-            result.errors.forEach(error => {
-                console.log(chalk_1.default.red(`   ❌ ${error}`));
-            });
-        }
-        else {
-            totalConfigured++;
-            console.log(chalk_1.default.green(`   ✅ MCP config valid (${result.mcpServers.length} servers)`));
-            // Check for essential servers
-            const { BASE_MCP_SERVERS } = await Promise.resolve().then(() => __importStar(require('../mcp/mcp-server-registry')));
-            const essentialServers = BASE_MCP_SERVERS.map(s => s.id); // fraim, git, playwright
-            const hasEssential = essentialServers.filter(server => result.mcpServers.includes(server));
-            if (hasEssential.includes('fraim')) {
-                totalWithFRAIM++;
-                console.log(chalk_1.default.green('   ✅ FRAIM server configured'));
-            }
-            else {
-                console.log(chalk_1.default.yellow('   ⚠️ FRAIM server missing'));
-            }
-            if (hasEssential.length > 1) {
-                console.log(chalk_1.default.green(`   ✅ ${hasEssential.length - 1} additional servers: ${hasEssential.filter(s => s !== 'fraim').join(', ')}`));
-            }
-            const missingEssential = essentialServers.filter(server => !result.mcpServers.includes(server));
-            if (missingEssential.length > 0) {
-                console.log(chalk_1.default.yellow(`   ⚠️ Missing servers: ${missingEssential.join(', ')}`));
-            }
-        }
-        console.log(); // Empty line
-    }
-    // Summary
-    console.log(chalk_1.default.blue('📊 Summary:'));
-    console.log(chalk_1.default.green(`   ✅ ${totalConfigured}/${detectedIDEs.length} IDEs have valid MCP configs`));
-    console.log(chalk_1.default.green(`   ✅ ${totalWithFRAIM}/${detectedIDEs.length} IDEs have FRAIM configured`));
-    if (totalWithFRAIM === 0) {
-        console.log(chalk_1.default.red('\n❌ No IDEs have FRAIM configured!'));
-        console.log(chalk_1.default.yellow('💡 Run: fraim setup --key=<your-fraim-key>'));
-    }
-    else if (totalWithFRAIM < detectedIDEs.length) {
-        console.log(chalk_1.default.yellow(`\n⚠️ ${detectedIDEs.length - totalWithFRAIM} IDEs missing FRAIM configuration`));
-        console.log(chalk_1.default.yellow('💡 Run: fraim setup to configure remaining IDEs'));
-    }
-    else {
-        console.log(chalk_1.default.green('\n🎉 All detected IDEs have FRAIM configured!'));
-        console.log(chalk_1.default.blue('💡 Try running: fraim init-project in any project'));
-    }
-};
-exports.runTestMCP = runTestMCP;
-exports.testMCPCommand = new commander_1.Command('test-mcp')
-    .description('Test MCP server configurations for all detected IDEs')
-    .action(exports.runTestMCP);