fraim-framework 2.0.177 → 2.0.180

package/dist/src/fraim/issues.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileFraimIssue = fileFraimIssue;
+exports.listFraimIssuesByReporter = listFraimIssuesByReporter;
+const axios_1 = __importDefault(require("axios"));
+const FRAIM_REPO_OWNER = 'mathursrus';
+const FRAIM_REPO_NAME = 'FRAIM';
+const DEFAULT_LIST_LIMIT = 20;
+const MAX_LIST_LIMIT = 100;
+function normalizeLimit(limit) {
+    if (!Number.isFinite(limit))
+        return DEFAULT_LIST_LIMIT;
+    const parsed = Math.trunc(limit);
+    if (parsed <= 0)
+        return DEFAULT_LIST_LIMIT;
+    return Math.min(parsed, MAX_LIST_LIMIT);
+}
+/**
+ * File an issue in the FRAIM repository
+ *
+ * This function creates issues in the FRAIM repository for bug reports,
+ * feature requests, and workflow contributions.
+ */
+async function fileFraimIssue(params) {
+    const { title, labels, dryRun, reporterEmail } = params;
+    // Prepend reporter line so the close-the-loop job can identify who filed the issue
+    const reporterLine = reporterEmail ? `**Reported by:** ${reporterEmail}\n\n` : '';
+    const body = reporterLine + params.body;
+    // Always target the FRAIM repository
+    const owner = FRAIM_REPO_OWNER;
+    const repo = FRAIM_REPO_NAME;
+    if (dryRun) {
+        return {
+            success: true,
+            dryRun: true,
+            message: `[DRY RUN] Would create GitHub issue: "${title}" in ${owner}/${repo}.`
+        };
+    }
+    try {
+        // Check for GitHub token
+        const token = process.env.GITHUB_TOKEN;
+        if (!token) {
+            return {
+                success: false,
+                message: `GitHub integration requires GITHUB_TOKEN environment variable.
+                
+Please set GITHUB_TOKEN environment variable to file issues in ${owner}/${repo}.`
+            };
+        }
+        // Create the issue in FRAIM repository
+        const url = `https://api.github.com/repos/${owner}/${repo}/issues`;
+        const payload = { title, body };
+        if (labels && labels.length > 0) {
+            payload.labels = labels;
+        }
+        const response = await axios_1.default.post(url, payload, {
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Accept': 'application/vnd.github.v3+json',
+                'Content-Type': 'application/json',
+            },
+        });
+        return {
+            success: true,
+            issueNumber: response.data.number,
+            htmlUrl: response.data.html_url
+        };
+    }
+    catch (error) {
+        let errorMessage = 'Unknown error';
+        if (axios_1.default.isAxiosError(error)) {
+            errorMessage = `Status: ${error.response?.status} - ${JSON.stringify(error.response?.data)}`;
+        }
+        else if (error instanceof Error) {
+            errorMessage = error.message;
+        }
+        return {
+            success: false,
+            message: `Failed to create issue in FRAIM repository: ${errorMessage}`
+        };
+    }
+}
+/**
+ * List issues filed into the FRAIM repository by a specific reporter email.
+ *
+ * Uses GitHub search against the existing "Reported by:" marker in issue bodies
+ * so we do not need a second FRAIM-owned index.
+ */
+async function listFraimIssuesByReporter(params) {
+    const { reporterEmail } = params;
+    const limit = normalizeLimit(params.limit);
+    if (!reporterEmail) {
+        return {
+            success: false,
+            message: 'Reporter email is required to list FRAIM GitHub issues.'
+        };
+    }
+    const token = process.env.GITHUB_TOKEN;
+    if (!token) {
+        return {
+            success: false,
+            message: `GitHub integration requires GITHUB_TOKEN environment variable.
+                
+Please set GITHUB_TOKEN environment variable to query issues in ${FRAIM_REPO_OWNER}/${FRAIM_REPO_NAME}.`
+        };
+    }
+    const query = `repo:${FRAIM_REPO_OWNER}/${FRAIM_REPO_NAME} is:issue "Reported by: ${reporterEmail}" in:body`;
+    try {
+        const response = await axios_1.default.get('https://api.github.com/search/issues', {
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Accept': 'application/vnd.github+json',
+                'X-GitHub-Api-Version': '2022-11-28'
+            },
+            params: {
+                q: query,
+                sort: 'created',
+                order: 'desc',
+                per_page: limit,
+                page: 1
+            }
+        });
+        const issues = Array.isArray(response.data?.items)
+            ? response.data.items.map((item) => ({
+                issueNumber: item.number,
+                title: item.title,
+                status: item.state === 'closed' ? 'closed' : 'open',
+                createdAt: item.created_at
+            }))
+            : [];
+        return {
+            success: true,
+            issues
+        };
+    }
+    catch (error) {
+        let errorMessage = 'Unknown error';
+        if (axios_1.default.isAxiosError(error)) {
+            errorMessage = `Status: ${error.response?.status} - ${JSON.stringify(error.response?.data)}`;
+        }
+        else if (error instanceof Error) {
+            errorMessage = error.message;
+        }
+        return {
+            success: false,
+            message: `Failed to query issues in the FRAIM repository: ${errorMessage}`
+        };
+    }
+}

package/dist/src/fraim/template-processor.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateEngine = void 0;
+exports.getTemplateEngine = getTemplateEngine;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const provider_utils_1 = require("../core/utils/provider-utils");
+const object_utils_1 = require("../core/utils/object-utils");
+/**
+ * Multi-Provider Template Engine
+ * Processes workflow templates with provider-specific action mappings
+ */
+class TemplateEngine {
+    constructor(registryPath) {
+        this.providers = new Map();
+        this.registryPath = registryPath || (0, path_1.join)(__dirname, '../../registry');
+        this.loadProviders();
+    }
+    loadProviders() {
+        try {
+            // Load GitHub provider templates
+            const githubPath = (0, path_1.join)(this.registryPath, 'providers/github.json');
+            if ((0, fs_1.existsSync)(githubPath)) {
+                const githubTemplates = JSON.parse((0, fs_1.readFileSync)(githubPath, 'utf-8'));
+                this.providers.set('github', githubTemplates);
+            }
+            // Load ADO provider templates
+            const adoPath = (0, path_1.join)(this.registryPath, 'providers/ado.json');
+            if ((0, fs_1.existsSync)(adoPath)) {
+                const adoTemplates = JSON.parse((0, fs_1.readFileSync)(adoPath, 'utf-8'));
+                this.providers.set('ado', adoTemplates);
+            }
+            // Load Jira provider templates
+            const jiraPath = (0, path_1.join)(this.registryPath, 'providers/jira.json');
+            if ((0, fs_1.existsSync)(jiraPath)) {
+                const jiraTemplates = JSON.parse((0, fs_1.readFileSync)(jiraPath, 'utf-8'));
+                this.providers.set('jira', jiraTemplates);
+            }
+            // Load GitLab provider templates
+            const gitlabPath = (0, path_1.join)(this.registryPath, 'providers/gitlab.json');
+            if ((0, fs_1.existsSync)(gitlabPath)) {
+                const gitlabTemplates = JSON.parse((0, fs_1.readFileSync)(gitlabPath, 'utf-8'));
+                this.providers.set('gitlab', gitlabTemplates);
+            }
+            console.log(`✅ Loaded ${this.providers.size} provider templates`);
+        }
+        catch (error) {
+            console.warn('⚠️ Failed to load provider templates:', error);
+        }
+    }
+    /**
+     * Process workflow content with provider actions only
+     */
+    processWorkflow(workflowContent, repositoryInfo) {
+        // Only process provider actions, no client-side config variables
+        return this.processProviderActions(workflowContent, repositoryInfo);
+    }
+    processProviderActions(workflowContent, repositoryInfo) {
+        // Determine code provider from repository info using shared utility
+        const repoData = repositoryInfo?.repository || repositoryInfo;
+        const codeProvider = repoData?.provider || (0, provider_utils_1.detectProvider)(repoData?.url);
+        // Determine issue provider from explicit issueTracking context only
+        const issueProvider = repositoryInfo?.issueTracking?.provider;
+        // Get templates for both providers
+        const codeTemplates = this.providers.get(codeProvider);
+        const issueTemplates = issueProvider ? this.providers.get(issueProvider) : undefined;
+        if (!codeTemplates && !issueTemplates) {
+            console.warn(`⚠️ No templates found for providers: code=${codeProvider}, issue=${issueProvider}`);
+            return workflowContent;
+        }
+        // Process with both providers
+        return this.processWithSplitProviders(workflowContent, codeProvider, issueProvider, repositoryInfo);
+    }
+    processWithSplitProviders(workflowContent, codeProvider, issueProvider, repositoryInfo) {
+        const codeTemplates = this.providers.get(codeProvider);
+        const issueTemplates = issueProvider ? this.providers.get(issueProvider) : undefined;
+        let processed = workflowContent;
+        // Define which actions are code-related vs issue-related
+        const issueActions = new Set([
+            'get_issue', 'update_issue_status', 'add_issue_comment',
+            'create_issue', 'assign_issue', 'search_issues',
+            'close_issue', 'list_issues'
+        ]);
+        const codeActions = new Set([
+            'create_pr', 'get_pr', 'get_pr_comments', 'get_pr_review_comments',
+            'get_pr_reviews', 'add_pr_comment', 'merge_pr', 'create_branch',
+            'switch_branch', 'commit_changes', 'push_branch'
+        ]);
+        // Replace issue actions with issue provider templates
+        if (issueTemplates) {
+            for (const [action, template] of Object.entries(issueTemplates)) {
+                if (issueActions.has(action)) {
+                    const regex = new RegExp(`{{${action}}}`, 'g');
+                    const renderedTemplate = this.renderTemplate(template, repositoryInfo);
+                    processed = processed.replace(regex, renderedTemplate);
+                }
+            }
+        }
+        // Replace code actions with code provider templates
+        if (codeTemplates) {
+            for (const [action, template] of Object.entries(codeTemplates)) {
+                if (codeActions.has(action)) {
+                    const regex = new RegExp(`{{${action}}}`, 'g');
+                    const renderedTemplate = this.renderTemplate(template, repositoryInfo);
+                    processed = processed.replace(regex, renderedTemplate);
+                }
+            }
+        }
+        return processed;
+    }
+    /**
+     * Render template with repository variable substitution
+     */
+    renderTemplate(template, repositoryInfo) {
+        if (!repositoryInfo)
+            return template;
+        return template.replace(/{{([^}]+)}}/g, (match, path) => {
+            const trimmedPath = path.trim();
+            // Handle proxy.repository.* variables
+            if (trimmedPath.startsWith('proxy.repository.')) {
+                const repoPath = trimmedPath.substring('proxy.repository.'.length);
+                let repoData = repositoryInfo.repository || repositoryInfo;
+                const value = (0, object_utils_1.getNestedValue)(repoData, repoPath);
+                return value !== undefined ? String(value) : match;
+            }
+            // Handle proxy.issueTracking.* variables (for split provider mode)
+            if (trimmedPath.startsWith('proxy.issueTracking.')) {
+                const issueTrackingPath = trimmedPath.substring('proxy.issueTracking.'.length);
+                const issueTrackingData = repositoryInfo.issueTracking;
+                if (issueTrackingData) {
+                    const value = (0, object_utils_1.getNestedValue)(issueTrackingData, issueTrackingPath);
+                    return value !== undefined ? String(value) : match;
+                }
+                return match;
+            }
+            return match;
+        });
+    }
+    /**
+     * Get available providers
+     */
+    getAvailableProviders() {
+        return Array.from(this.providers.keys());
+    }
+    /**
+     * Get available actions for a provider
+     */
+    getProviderActions(provider) {
+        const templates = this.providers.get(provider);
+        return templates ? Object.keys(templates) : [];
+    }
+    /**
+     * Validate that all template actions in content are supported
+     */
+    validateWorkflow(workflowContent, provider) {
+        const actionRegex = /{{(\w+)}}/g;
+        const actions = new Set();
+        let match;
+        while ((match = actionRegex.exec(workflowContent)) !== null) {
+            // Skip config variables
+            if (!match[1].startsWith('config.')) {
+                actions.add(match[1]);
+            }
+        }
+        const providerActions = this.getProviderActions(provider);
+        const missingActions = Array.from(actions).filter(action => !providerActions.includes(action));
+        return {
+            valid: missingActions.length === 0,
+            missingActions
+        };
+    }
+}
+exports.TemplateEngine = TemplateEngine;
+// Global template engine instance
+let globalTemplateEngine = null;
+/**
+ * Get or create global template engine instance
+ */
+function getTemplateEngine(registryPath) {
+    if (!globalTemplateEngine || (registryPath && registryPath !== globalTemplateEngine['registryPath'])) {
+        globalTemplateEngine = new TemplateEngine(registryPath);
+    }
+    return globalTemplateEngine;
+}

package/dist/src/fraim/utils/request-utils.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMAIL_REGEX = void 0;
+exports.validateEmail = validateEmail;
+exports.getRequestMeta = getRequestMeta;
+/**
+ * Standard email validation regex
+ */
+exports.EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Validate an email address
+ */
+function validateEmail(email) {
+    return exports.EMAIL_REGEX.test(email);
+}
+/**
+ * Extract IP and UserAgent from an Express Request
+ */
+function getRequestMeta(req) {
+    const ip = req.headers['x-forwarded-for'] || req.ip || 'unknown';
+    const userAgent = req.headers['user-agent'] || 'unknown';
+    return { ip, userAgent };
+}

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

@@ -413,6 +413,7 @@ class FraimLocalMCPServer {
         this.otlpServer = null;
         this.isShutdown = false;
         this.mentoringResponseCache = null;
+        this.jobStartCache = new Map();
         this.connectSyncInFlight = null;
         this.latestConnectSyncWarning = null;
         this.orgCacheRefreshInFlight = false;
@@ -1996,7 +1997,7 @@ class FraimLocalMCPServer {
                     if (!this.mentoringResponseCache) {
                         this.mentoringResponseCache = new Map();
                     }
-                    this.mentoringResponseCache.set(requestId, {
+                    this.mentoringResponseCache.set(request.id, {
                         nextPhase: tutoringResponse.nextPhase,
                         jobId: args.jobId || requestSessionId // Use jobId from args, fallback to sessionId
                     });
@@ -2063,10 +2064,13 @@ class FraimLocalMCPServer {
                         const overview = await mentor.getJobOverview(name);
                         if (overview) {
                             this.log(`✅ Local override found for get_fraim_job: ${name}`);
+                            const jobId = (0, crypto_1.randomUUID)();
+                            this.jobStartCache.set(request.id, { jobId, jobName: name });
+                            this.log(`📊 Generated jobId=${jobId} for job=${name}`);
                             let responseText = overview.overview;
                             if (!overview.isSimple) {
                                 responseText = `${mentor.getCompactPhaseAuthority()}\n\n${responseText}`;
-                                responseText += `\n\n---\n\n**This job has phases.** Use \`seekMentoring\` to get phase-specific instructions.`;
+                                responseText += `\n\n---\n\n**Job ID:** \`${jobId}\`\n\n**This job has phases.** Use \`seekMentoring\` with the jobId above to get phase-specific instructions.`;
                             }
                             // Inject local learning context for job requests (RFC 177).
                             const userEmail = this.ensureEngine().getUserEmail();
@@ -2356,7 +2360,7 @@ class FraimLocalMCPServer {
             if (!this.repoInfo) {
                 this.detectRepoInfo();
             }
-            // Bug fix: Enrich seekMentoring args with response data
+            // Enrich seekMentoring args with response data (nextPhase, jobId from cache)
             if (toolName === 'seekMentoring' && this.mentoringResponseCache) {
                 const requestId = request.id;
                 const cachedResponse = this.mentoringResponseCache.get(requestId);
@@ -2366,10 +2370,20 @@ class FraimLocalMCPServer {
                         nextPhase: cachedResponse.nextPhase,
                         jobId: cachedResponse.jobId
                     };
-                    this.mentoringResponseCache.delete(requestId); // Clean up
+                    this.mentoringResponseCache.delete(requestId);
                     this.log(`📊 Enriched seekMentoring args with nextPhase=${cachedResponse.nextPhase}, jobId=${cachedResponse.jobId}`);
                 }
             }
+            // Enrich get_fraim_job args with the UUID jobId and action:start from jobStartCache
+            if (toolName === 'get_fraim_job') {
+                const requestId = request.id;
+                const cached = this.jobStartCache.get(requestId);
+                if (cached) {
+                    args = { ...args, jobId: cached.jobId, action: 'start' };
+                    this.jobStartCache.delete(requestId);
+                    this.log(`📊 Enriched get_fraim_job args with jobId=${cached.jobId}, action=start`);
+                }
+            }
             // Capture the current queue size before collection
             const beforeCount = this.usageCollector.getEventCount();
             try {
@@ -2410,6 +2424,16 @@ class FraimLocalMCPServer {
                         this.log(`📊 🔍 Debug: get_fraim_file path="${args.path}"`);
                     }
                 }
+                // Emit job-complete event when seekMentoring reaches the final phase
+                if (toolName === 'seekMentoring' && args.nextPhase === null && args.jobName && args.jobId) {
+                    try {
+                        this.usageCollector.collectJobComplete(args.jobName, args.jobId, requestSessionId);
+                        this.log(`📊 ✅ Job complete event emitted: ${args.jobName} (jobId: ${args.jobId})`);
+                    }
+                    catch (err) {
+                        this.log(`📊 ⚠️ Job complete event failed (non-blocking): ${err.message}`);
+                    }
+                }
             }
             catch (error) {
                 this.log(`📊 ❌ Usage collection error: ${error.message}`);

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

@@ -142,6 +142,8 @@ class UsageCollector {
             case 'get_fraim_job':
                 if (args.job)
                     analyticsArgs.job = args.job;
+                if (args.action)
+                    analyticsArgs.action = args.action;
                 break;
             case 'fraim_connect':
                 if (args.agent?.name)
@@ -179,6 +181,28 @@ class UsageCollector {
                 return null;
         }
     }
+    /**
+     * Emit a job-completion event when seekMentoring returns nextPhase === null.
+     * Called by the local proxy after the final mentoring event is queued.
+     */
+    collectJobComplete(jobName, jobId, sessionId) {
+        const event = {
+            type: 'job',
+            name: jobName,
+            userId: this.userId || 'unknown',
+            sessionId,
+            success: true,
+            jobId,
+            repoIdentifier: this.repoIdentifier || undefined,
+            agentName: this.agentName || undefined,
+            agentModel: this.agentModel || undefined,
+            args: { action: 'complete', jobId },
+        };
+        this.events.push(event);
+        const msg = `[UsageCollector] ✅ Job complete event: ${jobName} (jobId: ${jobId}, queue: ${this.events.length})`;
+        console.error(msg);
+        process.stderr.write(msg + '\n');
+    }
     /**
      * Get collected events for upload and clear the queue
      */