fraim 2.0.100 → 2.0.102

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

@@ -81,7 +81,12 @@ class FraimTemplateEngine {
         return this.userEmail;
     }
     substituteTemplates(content) {
+        return this.substituteTemplatesWithNotices(content).content;
+    }
+    substituteTemplatesWithNotices(content) {
         let result = content;
+        const notices = [];
+        const blockingRequirements = [];
         // Substitute {{proxy.user.email}} with the email captured from fraim_connect
         if (this.userEmail) {
             result = result.replace(/\{\{proxy\.user\.email\}\}/g, this.userEmail);
@@ -103,22 +108,17 @@ class FraimTemplateEngine {
             return match;
         });
         // First, substitute config variables with fallback support.
-        // Fallbacks must work even when local config is unavailable.
-        result = result.replace(/\{\{proxy\.config\.([^}|]+)(?:\s*\|\s*"([^"]+)")?\}\}/g, (match, path, fallback) => {
-            try {
-                if (this.config) {
-                    const value = (0, object_utils_1.getNestedValue)(this.config, path.trim());
-                    if (value !== undefined) {
-                        return typeof value === 'object'
-                            ? JSON.stringify(value)
-                            : String(value);
-                    }
-                }
-                return fallback !== undefined ? fallback : match;
-            }
-            catch (error) {
-                return fallback !== undefined ? fallback : match;
-            }
+        // Supported forms:
+        //   {{proxy.config.path}}
+        //   {{proxy.config.path | "fallback"}}
+        //   {{proxy.config.path | INFORM | "fallback behavior"}}
+        //   {{proxy.config.path | NO_OP | "fallback behavior"}}
+        //   {{proxy.config.path | REQUIRE | "fallback behavior"}}
+        // Note: \s* tolerates optional whitespace inside {{...}} (e.g. from remote server formatting).
+        // This must match the same set of templates that rewriteProxyTokensInText can rewrite,
+        // so that config templates are always resolved here rather than falling through to the fallback rewriter.
+        result = result.replace(/\{\{\s*proxy\.config\.([^}]+?)\s*\}\}/g, (match, expression) => {
+            return this.resolveConfigTemplate(match, expression, notices, blockingRequirements);
         });
         // Second, substitute {{proxy.delivery.*}} templates
         const deliveryValues = this.loadDeliveryTemplates();
@@ -130,7 +130,130 @@ class FraimTemplateEngine {
         }
         // Third, substitute platform-specific action templates
         result = this.substitutePlatformActions(result);
-        return result;
+        return {
+            content: result,
+            notices,
+            blockingRequirements
+        };
+    }
+    resolveConfigTemplate(originalMatch, expression, notices, blockingRequirements) {
+        const segments = this.splitTemplateSegments(expression);
+        if (segments.length === 0)
+            return originalMatch;
+        const path = segments[0].trim();
+        const remainder = segments.slice(1).map(segment => segment.trim()).filter(Boolean);
+        let action = null;
+        let fallback;
+        if (remainder.length === 1) {
+            fallback = this.parseQuotedTemplateValue(remainder[0]);
+            if (fallback === undefined)
+                return originalMatch;
+        }
+        else if (remainder.length === 2) {
+            const candidateAction = remainder[0].toUpperCase();
+            if (!FraimTemplateEngine.CONFIG_TEMPLATE_ACTIONS.has(candidateAction)) {
+                return originalMatch;
+            }
+            fallback = this.parseQuotedTemplateValue(remainder[1]);
+            if (fallback === undefined)
+                return originalMatch;
+            action = candidateAction;
+        }
+        else if (remainder.length > 0) {
+            return originalMatch;
+        }
+        try {
+            if (this.config) {
+                const value = (0, object_utils_1.getNestedValue)(this.config, path);
+                if (value !== undefined) {
+                    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+                }
+            }
+            if (fallback === undefined) {
+                return originalMatch;
+            }
+            if (action === null || action === 'NO_OP') {
+                return fallback;
+            }
+            if (action === 'REQUIRE') {
+                blockingRequirements.push(this.buildMissingConfigNotice(path, action));
+            }
+            else {
+                notices.push(this.buildMissingConfigNotice(path, action));
+            }
+            return fallback;
+        }
+        catch (error) {
+            if (fallback === undefined) {
+                return originalMatch;
+            }
+            if (action === null || action === 'NO_OP') {
+                return fallback;
+            }
+            if (action === 'REQUIRE') {
+                blockingRequirements.push(this.buildMissingConfigNotice(path, action));
+            }
+            else {
+                notices.push(this.buildMissingConfigNotice(path, action));
+            }
+            return fallback;
+        }
+    }
+    splitTemplateSegments(expression) {
+        const segments = [];
+        let current = '';
+        let inQuotes = false;
+        for (let i = 0; i < expression.length; i += 1) {
+            const char = expression[i];
+            const prev = i > 0 ? expression[i - 1] : '';
+            if (char === '"' && prev !== '\\') {
+                inQuotes = !inQuotes;
+                current += char;
+                continue;
+            }
+            if (char === '|' && !inQuotes) {
+                segments.push(current);
+                current = '';
+                continue;
+            }
+            current += char;
+        }
+        segments.push(current);
+        return segments;
+    }
+    parseQuotedTemplateValue(segment) {
+        const trimmed = segment.trim();
+        if (!trimmed.startsWith('"') || !trimmed.endsWith('"')) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    buildMissingConfigNotice(path, action) {
+        const metadata = FraimTemplateEngine.CONFIG_CONTEXT_METADATA[path];
+        const label = metadata?.label || `config value \`${path}\``;
+        const onboardingHint = metadata?.onboardingHint || `provide \`${path}\` in \`fraim/config.json\``;
+        if (action === 'REQUIRE') {
+            return {
+                action,
+                path,
+                message: `${this.capitalizeFirst(label)} is required for this task but is not configured. Invoke the manager \`project-onboarding\` job and ${onboardingHint} before continuing.`
+            };
+        }
+        return {
+            action,
+            path,
+            message: `${this.capitalizeFirst(label)} is not configured. Invoke the manager \`project-onboarding\` job and ${onboardingHint}.`
+        };
+    }
+    capitalizeFirst(value) {
+        if (!value)
+            return value;
+        return value.charAt(0).toUpperCase() + value.slice(1);
     }
     loadDeliveryTemplates() {
         if (this.deliveryTemplatesCache)
@@ -235,6 +358,25 @@ class FraimTemplateEngine {
     }
 }
 exports.FraimTemplateEngine = FraimTemplateEngine;
+FraimTemplateEngine.CONFIG_TEMPLATE_ACTIONS = new Set(['INFORM', 'NO_OP', 'REQUIRE']);
+FraimTemplateEngine.CONFIG_CONTEXT_METADATA = {
+    'customizations.architectureDoc': {
+        label: 'project-specific architecture document',
+        onboardingHint: 'provide the architecture document path in `fraim/config.json`'
+    },
+    'customizations.designSystem.path': {
+        label: 'project-specific design system',
+        onboardingHint: 'provide the design system path in `fraim/config.json`'
+    },
+    compliance: {
+        label: 'project compliance configuration',
+        onboardingHint: 'record the project compliance requirements in `fraim/config.json`'
+    },
+    'compliance.regulations': {
+        label: 'project compliance regulations',
+        onboardingHint: 'record the applicable compliance regulations in `fraim/config.json`'
+    }
+};
 FraimTemplateEngine.PROXY_ACTION_PREFIX = 'proxy.action.';
 FraimTemplateEngine.ISSUE_ACTIONS = new Set([
     'get_issue',
@@ -798,6 +940,11 @@ class FraimLocalMCPServer {
             await this.ensureProviderTemplatesAvailable(processedResponse, requestSessionId);
             processedResponse = this.processResponse(processedResponse);
         }
+        const blockingResponse = this.failForMissingRequiredConfig(processedResponse);
+        if (blockingResponse) {
+            return blockingResponse;
+        }
+        processedResponse = this.prependMissingConfigNotices(processedResponse);
         return this.applyAgentFallbackForUnresolvedProxy(processedResponse);
     }
     async resolveIncludesInResponse(response, requestSessionId, requestId) {
@@ -856,12 +1003,11 @@ class FraimLocalMCPServer {
                         // personalized-employee/ takes priority; when remote fails, resolver falls back to synced/cached content
                         const resolved = await resolver.resolveFile(registryPath).catch(() => null);
                         if (resolved?.content) {
-                            const substitutedContent = this.substituteTemplates(resolved.content);
                             const newResponse = {
                                 ...response,
                                 result: {
                                     ...response.result,
-                                    content: [{ type: 'text', text: substitutedContent }]
+                                    content: [{ type: 'text', text: resolved.content }]
                                 }
                             };
                             delete newResponse.error;
@@ -925,12 +1071,24 @@ class FraimLocalMCPServer {
         const tokens = new Set();
         const rewritten = text.replace(/\{\{\s*proxy\.([^}]+?)\s*\}\}/g, (_match, proxyPath) => {
             const normalized = proxyPath.trim();
+            // proxy.config.* must never reach here — substituteTemplatesWithNotices resolves all of
+            // them (with config values or fallback text). If one slips through it is a bug; strip it
+            // and log rather than rewriting to {{agent.config.*}} which confuses the agent (issue #210).
+            if (normalized.startsWith('config.')) {
+                this.logError(`[${FraimLocalMCPServer.FALLBACK_ALERT_MARKER}] BUG: unresolved proxy.${normalized} survived processResponse — stripping`);
+                return '';
+            }
             tokens.add(`proxy.${normalized}`);
             return `{{agent.${normalized}}}`;
         });
-        if (tokens.size === 0) {
+        // If nothing changed at all, return early (no allocation, no notice).
+        if (rewritten === text) {
             return { text, tokens: [] };
         }
+        // Only prepend the agent-resolution notice when there are actual agent tokens to resolve.
+        if (tokens.size === 0) {
+            return { text: rewritten, tokens: [] };
+        }
         const hasResolutionNotice = rewritten.includes('## Agent Resolution Needed');
         const finalText = hasResolutionNotice
             ? rewritten
@@ -970,6 +1128,84 @@ class FraimLocalMCPServer {
     substituteTemplates(content) {
         return this.ensureEngine().substituteTemplates(content);
     }
+    prependMissingConfigNotices(response) {
+        if (!response.result?.content || !Array.isArray(response.result.content)) {
+            return response;
+        }
+        const contentBlocks = response.result.content;
+        const firstTextIndex = contentBlocks.findIndex((block) => block?.type === 'text' && typeof block.text === 'string');
+        if (firstTextIndex === -1) {
+            return response;
+        }
+        const existingText = contentBlocks[firstTextIndex].text;
+        const notices = response.result.__proxyMissingConfigNotices;
+        if (!notices || notices.length === 0) {
+            return response;
+        }
+        const uniqueNotices = [];
+        const seen = new Set();
+        for (const notice of notices) {
+            const key = `${notice.action}:${notice.path}:${notice.message}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            uniqueNotices.push(notice);
+        }
+        if (uniqueNotices.length === 0) {
+            return response;
+        }
+        const noticeLines = ['## Missing Project Context'];
+        for (const notice of uniqueNotices) {
+            noticeLines.push(`- ${notice.message}`);
+        }
+        const prefix = `${noticeLines.join('\n')}\n\n---\n\n`;
+        const transformedContent = contentBlocks.map((block, index) => {
+            if (index !== firstTextIndex)
+                return block;
+            return {
+                ...block,
+                text: prefix + existingText
+            };
+        });
+        const { __proxyMissingConfigNotices, ...restResult } = response.result;
+        return {
+            ...response,
+            result: {
+                ...restResult,
+                content: transformedContent
+            }
+        };
+    }
+    failForMissingRequiredConfig(response) {
+        const requirements = response.result?.__proxyMissingConfigRequirements;
+        if (!requirements || requirements.length === 0) {
+            return null;
+        }
+        const uniqueRequirements = [];
+        const seen = new Set();
+        for (const requirement of requirements) {
+            const key = `${requirement.action}:${requirement.path}:${requirement.message}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            uniqueRequirements.push(requirement);
+        }
+        const messageLines = ['Required project context is missing:'];
+        for (const requirement of uniqueRequirements) {
+            messageLines.push(`- ${requirement.message}`);
+        }
+        return {
+            jsonrpc: response.jsonrpc,
+            id: response.id ?? null,
+            error: {
+                code: -32003,
+                message: messageLines.join('\n'),
+                data: {
+                    missingConfigPaths: uniqueRequirements.map((requirement) => requirement.path)
+                }
+            }
+        };
+    }
     /**
      * Initialize the LocalRegistryResolver for override resolution
      */
@@ -1057,10 +1293,15 @@ class FraimLocalMCPServer {
     processResponse(response) {
         if (!response.result)
             return response;
+        const notices = [];
+        const blockingRequirements = [];
         // Recursively substitute templates in all string values
         const processValue = (value) => {
             if (typeof value === 'string') {
-                return this.substituteTemplates(value);
+                const substitution = this.ensureEngine().substituteTemplatesWithNotices(value);
+                notices.push(...substitution.notices);
+                blockingRequirements.push(...substitution.blockingRequirements);
+                return substitution.content;
             }
             else if (Array.isArray(value)) {
                 return value.map(processValue);
@@ -1074,14 +1315,25 @@ class FraimLocalMCPServer {
             }
             return value;
         };
+        const processedResult = processValue(response.result);
+        if (notices.length > 0 && processedResult && typeof processedResult === 'object') {
+            processedResult.__proxyMissingConfigNotices = notices;
+        }
+        if (blockingRequirements.length > 0 && processedResult && typeof processedResult === 'object') {
+            processedResult.__proxyMissingConfigRequirements = blockingRequirements;
+        }
         return {
             ...response,
-            result: processValue(response.result)
+            result: processedResult
         };
     }
     applyAgentFallbackForUnresolvedProxy(response) {
         if (!response.result)
             return response;
+        // Rewrite any unresolved {{proxy.*}} placeholders to {{agent.*}} so the agent can
+        // handle them. proxy.config.* is excluded inside rewriteProxyTokensInText — those
+        // must have been fully resolved by substituteTemplatesWithNotices; any that survive
+        // are bugs and get stripped with a log warning rather than rewritten.
         const rewritten = this.rewriteUnresolvedProxyPlaceholders(response.result);
         if (rewritten.tokens.length > 0) {
             this.logError(`[${FraimLocalMCPServer.FALLBACK_ALERT_MARKER}] Rewrote unresolved proxy placeholders to agent placeholders: ${rewritten.tokens.join(', ')}`);
@@ -1249,7 +1501,30 @@ class FraimLocalMCPServer {
             // Resolve templates in the outgoing request so the remote server 
             // only ever sees finalized values.
             const stringifiedRequest = JSON.stringify(request);
-            const resolvedRequestStr = this.substituteTemplates(stringifiedRequest);
+            const requestSubstitution = this.ensureEngine().substituteTemplatesWithNotices(stringifiedRequest);
+            if (requestSubstitution.blockingRequirements.length > 0) {
+                const uniqueRequirements = [];
+                const seen = new Set();
+                for (const requirement of requestSubstitution.blockingRequirements) {
+                    const key = `${requirement.action}:${requirement.path}:${requirement.message}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    uniqueRequirements.push(requirement);
+                }
+                return {
+                    jsonrpc: '2.0',
+                    id: request.id,
+                    error: {
+                        code: -32003,
+                        message: ['Required project context is missing:', ...uniqueRequirements.map((requirement) => `- ${requirement.message}`)].join('\n'),
+                        data: {
+                            missingConfigPaths: uniqueRequirements.map((requirement) => requirement.path)
+                        }
+                    }
+                };
+            }
+            const resolvedRequestStr = requestSubstitution.content;
             const finalRequest = JSON.parse(resolvedRequestStr);
             const response = await axios_1.default.post(`${this.remoteUrl}/mcp`, finalRequest, {
                 headers,

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

@@ -4,19 +4,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UsageCollector = void 0;
-const mongodb_1 = require("mongodb");
 const axios_1 = __importDefault(require("axios"));
-// A placeholder ObjectId used when the real API key ID is not yet known.
-// The server will override this with the correct ID from the authenticated API key.
-const PLACEHOLDER_API_KEY_ID = new mongodb_1.ObjectId('000000000000000000000000');
 /**
- * Usage event collector for local MCP proxy
- * Collects usage events and batches them for upload
+ * UsageCollector is responsible for collecting usage events from MCP tools
+ * and formatting them for the analytics system.
  */
 class UsageCollector {
     constructor() {
         this.events = [];
-        this.apiKeyId = null;
+        this.userId = null;
     }
     static resolveMentoringJobName(args) {
         if (!args || typeof args !== 'object') {
@@ -35,10 +31,10 @@ class UsageCollector {
         return 'unknown';
     }
     /**
-     * Set the API key ID for this session
+     * Set the user ID for this session
      */
-    setApiKeyId(apiKeyId) {
-        this.apiKeyId = apiKeyId;
+    setUserId(userId) {
+        this.userId = userId;
     }
     /**
      * Collect MCP tool call event
@@ -53,19 +49,23 @@ class UsageCollector {
             return;
         }
         // Extract useful args for analytics
-        const analyticsArgs = this.extractAnalyticsArgs(toolName, args);
+        const analyticsArgs = this.extractAnalyticsArgs(toolName, args) || {};
+        // Ensure category from path parsing is included in args
+        if (parsed.category && !analyticsArgs.category) {
+            analyticsArgs.category = parsed.category;
+        }
         const event = {
             type: parsed.type,
             name: parsed.name,
-            // Use set apiKeyId if available, otherwise a placeholder.
-            // The server will override this with the correct value from the auth token.
-            apiKeyId: this.apiKeyId || PLACEHOLDER_API_KEY_ID,
+            // Use set userId if available; the server will override with the authenticated userId.
+            userId: this.userId || 'unknown',
             sessionId,
             success,
-            args: analyticsArgs
+            category: parsed.category,
+            args: Object.keys(analyticsArgs).length > 0 ? analyticsArgs : undefined
         };
         this.events.push(event);
-        const successMsg = `[UsageCollector] ✅ Collected event: ${parsed.type}/${parsed.name} (session: ${sessionId}, queue: ${this.events.length})`;
+        const successMsg = `[UsageCollector] ✅ Collected event: ${parsed.type}/${parsed.name} (category: ${parsed.category || 'none'}, session: ${sessionId}, queue: ${this.events.length})`;
         console.error(successMsg);
         // Also log to stderr for better visibility in main logs
         process.stderr.write(successMsg + '\n');
@@ -73,13 +73,12 @@ class UsageCollector {
     /**
      * Collect usage event directly (for backward compatibility with tests)
      */
-    collectEvent(type, name, sessionId, success = true, args) {
+    collectEvent(type, name, sessionId, success = true, args, category) {
         const event = {
             type,
             name,
-            // Use set apiKeyId if available, otherwise a placeholder.
-            // The server will override this with the correct value from the auth token.
-            apiKeyId: this.apiKeyId || PLACEHOLDER_API_KEY_ID,
+            category,
+            userId: this.userId || 'unknown',
             sessionId,
             success,
             args
@@ -138,16 +137,18 @@ class UsageCollector {
     parseMCPCall(toolName, args) {
         switch (toolName) {
             case 'get_fraim_job':
-                return { type: 'job', name: args.job || 'unknown' };
+                const jobPath = args.job || 'unknown';
+                const parsedJob = this.parseComponentName(jobPath);
+                return parsedJob || { type: 'job', name: jobPath };
             case 'get_fraim_file':
                 if (args.path) {
-                    return UsageCollector.parseComponentName(args.path);
+                    return this.parseComponentName(args.path);
                 }
                 return null;
             case 'seekMentoring':
-                return { type: 'mentoring', name: UsageCollector.resolveMentoringJobName(args) };
+                return { type: 'mentoring', name: UsageCollector.resolveMentoringJobName(args), category: 'mentoring' };
             case 'list_fraim_jobs':
-                return { type: 'job', name: 'list' };
+                return { type: 'job', name: 'list', category: 'none' };
             case 'fraim_connect':
                 return { type: 'session', name: 'connect' };
             default:
@@ -226,37 +227,47 @@ class UsageCollector {
     /**
      * Parse component name from file path
      */
-    static parseComponentName(path) {
-        // Normalize path to have leading slash for consistent regex matching
-        const normalizedPath = path.startsWith('/') ? path : `/${path}`;
-        // Match skills files: /skills/category/skill-name.md
-        if (normalizedPath.includes('/skills/')) {
-            const skillMatch = normalizedPath.match(/\/skills\/[^/]+\/([^/]+)\.md$/);
-            if (skillMatch) {
-                return { type: 'skill', name: skillMatch[1] };
-            }
+    parseComponentName(path) {
+        if (!path || typeof path !== 'string')
+            return null;
+        // Clean path: handle backslashes, optional 'registry/' prefix
+        let cleanPath = path.replace(/\\/g, '/');
+        cleanPath = cleanPath.replace(/^(registry\/)/, '');
+        if (cleanPath.startsWith('/'))
+            cleanPath = cleanPath.substring(1);
+        const parts = cleanPath.split('/');
+        const fileName = parts[parts.length - 1];
+        // If it doesn't end in .md, it might still be a job name (e.g. from get_fraim_job)
+        if (!fileName.endsWith('.md')) {
+            return null;
         }
-        // Match job files: /jobs/category/subcategory/job-name.md
-        if (normalizedPath.includes('/jobs/')) {
-            const jobMatch = normalizedPath.match(/\/jobs\/[^/]+\/[^/]+\/([^/]+)\.md$/);
-            if (jobMatch) {
-                return { type: 'job', name: jobMatch[1] };
-            }
+        const name = fileName.replace(/\.md$/, '');
+        const typeStr = parts[0];
+        // Match skills files
+        if (typeStr === 'skills') {
+            // Structure: skills/category/name.md or skills/name.md
+            // Category is the directory immediately following 'skills'
+            const category = parts.length > 2 ? parts[1] : undefined;
+            return { type: 'skill', name, category };
         }
-        // Match rule files: /rules/category/rule-name.md
-        if (normalizedPath.includes('/rules/')) {
-            const ruleMatch = normalizedPath.match(/\/rules\/[^/]+\/([^/]+)\.md$/);
-            if (ruleMatch) {
-                return { type: 'rule', name: ruleMatch[1] };
+        // Match job files
+        if (typeStr === 'jobs') {
+            // Structure: jobs/ai-employee/category/name.md
+            // Or: jobs/category/name.md
+            let category;
+            if (parts[1] === 'ai-employee' || parts[1] === 'ai-manager' || parts[1] === 'personalized-employee') {
+                category = parts[2]; // e.g. jobs/ai-employee/product-building/job.md -> product-building
+            }
+            else if (parts.length > 2) {
+                category = parts[1]; // e.g. jobs/legal/job.md -> legal
             }
+            return { type: 'job', name, category };
         }
-        // For other paths that don't match the expected patterns, 
-        // we'll classify them as 'job' type with a generic name
-        // This ensures we track usage even for non-standard paths
-        const fileName = normalizedPath.split('/').pop();
-        if (fileName && fileName.endsWith('.md')) {
-            const baseName = fileName.replace(/\.md$/, '');
-            return { type: 'job', name: baseName };
+        // Match rule files (already defined in UsageEventType)
+        if (typeStr === 'rules') {
+            // Structure: rules/category/name.md or rules/name.md
+            const category = parts.length > 2 ? parts[1] : undefined;
+            return { type: 'rule', name, category };
         }
         return null;
     }