fraim-framework 2.0.71 → 2.0.73

package/dist/src/core/utils/local-registry-resolver.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * LocalRegistryResolver
+ *
+ * Resolves registry file requests by checking for local overrides first,
+ * then falling back to remote registry. Handles inheritance via InheritanceParser.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalRegistryResolver = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const inheritance_parser_1 = require("./inheritance-parser");
+class LocalRegistryResolver {
+    constructor(options) {
+        this.workspaceRoot = options.workspaceRoot;
+        this.remoteContentResolver = options.remoteContentResolver;
+        this.parser = new inheritance_parser_1.InheritanceParser(options.maxDepth);
+    }
+    /**
+     * Check if a local override exists for the given path
+     */
+    hasLocalOverride(path) {
+        const overridePath = this.getOverridePath(path);
+        const exists = (0, fs_1.existsSync)(overridePath);
+        console.error(`[LocalRegistryResolver] hasLocalOverride(${path}) -> ${overridePath} -> ${exists}`);
+        return exists;
+    }
+    /**
+     * Get the full path to a local override file
+     */
+    getOverridePath(path) {
+        return (0, path_1.join)(this.workspaceRoot, '.fraim/overrides', path);
+    }
+    /**
+     * Read local override file content
+     */
+    readLocalOverride(path) {
+        const overridePath = this.getOverridePath(path);
+        try {
+            return (0, fs_1.readFileSync)(overridePath, 'utf-8');
+        }
+        catch (error) {
+            throw new Error(`Failed to read local override: ${path}. ${error.message}`);
+        }
+    }
+    /**
+     * Resolve inheritance in local override content
+     */
+    async resolveInheritance(content, currentPath) {
+        // Check if content has imports
+        const parseResult = this.parser.parse(content);
+        if (!parseResult.hasImports) {
+            return { content, imports: [] };
+        }
+        // Resolve imports
+        try {
+            const resolved = await this.parser.resolve(content, currentPath, {
+                fetchParent: this.remoteContentResolver,
+                maxDepth: 5
+            });
+            return {
+                content: resolved,
+                imports: parseResult.imports
+            };
+        }
+        catch (error) {
+            if (error instanceof inheritance_parser_1.InheritanceError) {
+                throw error;
+            }
+            throw new Error(`Failed to resolve inheritance for ${currentPath}: ${error.message}`);
+        }
+    }
+    /**
+     * Generate metadata comment for resolved content
+     */
+    generateMetadata(result) {
+        if (result.source === 'remote') {
+            return '';
+        }
+        if (result.inherited && result.imports && result.imports.length > 0) {
+            return `<!-- 📝 Using local override (inherited from: ${result.imports.join(', ')}) -->\n\n`;
+        }
+        return `<!-- 📝 Using local override -->\n\n`;
+    }
+    /**
+     * Resolve a registry file request
+     *
+     * Resolution order:
+     * 1. Check for local override in .fraim/overrides/
+     * 2. If found, read and resolve inheritance
+     * 3. If not found, fetch from remote
+     *
+     * @param path - Registry path (e.g., "workflows/product-building/spec.md")
+     * @returns Resolved file with metadata
+     */
+    async resolveFile(path) {
+        console.error(`[LocalRegistryResolver] ===== resolveFile called for: ${path} =====`);
+        // Check for local override
+        if (!this.hasLocalOverride(path)) {
+            // No override, fetch from remote
+            try {
+                const content = await this.remoteContentResolver(path);
+                return {
+                    content,
+                    source: 'remote',
+                    inherited: false
+                };
+            }
+            catch (error) {
+                throw new Error(`Failed to fetch from remote: ${path}. ${error.message}`);
+            }
+        }
+        // Read local override
+        let localContent;
+        try {
+            localContent = this.readLocalOverride(path);
+        }
+        catch (error) {
+            // If local read fails, fall back to remote
+            console.warn(`Local override read failed, falling back to remote: ${path}`);
+            const content = await this.remoteContentResolver(path);
+            return {
+                content,
+                source: 'remote',
+                inherited: false
+            };
+        }
+        // Resolve inheritance
+        let resolved;
+        try {
+            console.error(`[LocalRegistryResolver] Resolving inheritance for ${path}`);
+            console.error(`[LocalRegistryResolver] Local content length: ${localContent.length} chars`);
+            console.error(`[LocalRegistryResolver] Local content preview: ${localContent.substring(0, 200)}`);
+            resolved = await this.resolveInheritance(localContent, path);
+            console.error(`[LocalRegistryResolver] Inheritance resolved: ${resolved.imports.length} imports`);
+            console.error(`[LocalRegistryResolver] Resolved content length: ${resolved.content.length} chars`);
+            console.error(`[LocalRegistryResolver] Resolved content preview: ${resolved.content.substring(0, 200)}`);
+        }
+        catch (error) {
+            // If inheritance resolution fails, fall back to remote
+            console.error(`❌ Inheritance resolution failed for ${path}:`, error);
+            const content = await this.remoteContentResolver(path);
+            return {
+                content,
+                source: 'remote',
+                inherited: false
+            };
+        }
+        // Build result
+        const result = {
+            content: resolved.content,
+            source: 'local',
+            inherited: resolved.imports.length > 0,
+            imports: resolved.imports.length > 0 ? resolved.imports : undefined
+        };
+        // Add metadata comment
+        const metadata = this.generateMetadata(result);
+        if (metadata) {
+            result.metadata = metadata;
+            result.content = metadata + result.content;
+        }
+        return result;
+    }
+}
+exports.LocalRegistryResolver = LocalRegistryResolver;

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

@@ -27,6 +27,7 @@ const crypto_1 = require("crypto");
 const axios_1 = __importDefault(require("axios"));
 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");
 /**
  * Handle template substitution logic separately for better testability
  */
@@ -80,22 +81,35 @@ class FraimTemplateEngine {
         const filename = this.workingStyle === 'Conversation' ? 'delivery-conversation.json' : 'delivery-pr.json';
         try {
             let content = null;
-            if (this.projectRoot) {
-                const deliveryPath = (0, path_1.join)(this.projectRoot, 'registry', 'providers', filename);
-                if ((0, fs_1.existsSync)(deliveryPath)) {
-                    content = (0, fs_1.readFileSync)(deliveryPath, 'utf-8');
-                }
-            }
+            // Try framework installation directory first (relative to this file)
+            // This file is in dist/src/local-mcp-server/, so go up to framework root
+            const frameworkRoot = (0, path_1.join)(__dirname, '..', '..', '..');
+            const frameworkPath = (0, path_1.join)(frameworkRoot, 'registry', 'providers', filename);
+            if ((0, fs_1.existsSync)(frameworkPath)) {
+                content = (0, fs_1.readFileSync)(frameworkPath, 'utf-8');
+                this.logFn(`✅ Loaded delivery templates from framework: ${frameworkPath}`);
+            }
+            // Fallback: try node_modules if not found in framework root
             if (!content) {
                 const nodeModulesPath = (0, path_1.join)(process.cwd(), 'node_modules', '@fraim', 'framework', 'registry', 'providers', filename);
                 if ((0, fs_1.existsSync)(nodeModulesPath)) {
                     content = (0, fs_1.readFileSync)(nodeModulesPath, 'utf-8');
+                    this.logFn(`✅ Loaded delivery templates from node_modules: ${nodeModulesPath}`);
+                }
+            }
+            // Last resort: try project root (for custom overrides)
+            if (!content && this.projectRoot) {
+                const deliveryPath = (0, path_1.join)(this.projectRoot, 'registry', 'providers', filename);
+                if ((0, fs_1.existsSync)(deliveryPath)) {
+                    content = (0, fs_1.readFileSync)(deliveryPath, 'utf-8');
+                    this.logFn(`✅ Loaded delivery templates from project: ${deliveryPath}`);
                 }
             }
             if (content) {
                 this.deliveryTemplatesCache = JSON.parse(content);
                 return this.deliveryTemplatesCache;
             }
+            this.logFn(`⚠️ Could not find delivery templates: ${filename}`);
             return null;
         }
         catch (error) {
@@ -121,18 +135,26 @@ class FraimTemplateEngine {
             return this.providerTemplatesCache[provider];
         try {
             let content = null;
-            if (this.projectRoot) {
-                const providerPath = (0, path_1.join)(this.projectRoot, 'registry', 'providers', `${provider}.json`);
-                if ((0, fs_1.existsSync)(providerPath)) {
-                    content = (0, fs_1.readFileSync)(providerPath, 'utf-8');
-                }
+            // Try framework installation directory first (relative to this file)
+            const frameworkRoot = (0, path_1.join)(__dirname, '..', '..', '..');
+            const frameworkPath = (0, path_1.join)(frameworkRoot, 'registry', 'providers', `${provider}.json`);
+            if ((0, fs_1.existsSync)(frameworkPath)) {
+                content = (0, fs_1.readFileSync)(frameworkPath, 'utf-8');
             }
+            // Fallback: try node_modules
             if (!content) {
                 const nodeModulesPath = (0, path_1.join)(process.cwd(), 'node_modules', '@fraim', 'framework', 'registry', 'providers', `${provider}.json`);
                 if ((0, fs_1.existsSync)(nodeModulesPath)) {
                     content = (0, fs_1.readFileSync)(nodeModulesPath, 'utf-8');
                 }
             }
+            // Last resort: try project root (for custom overrides)
+            if (!content && this.projectRoot) {
+                const providerPath = (0, path_1.join)(this.projectRoot, 'registry', 'providers', `${provider}.json`);
+                if ((0, fs_1.existsSync)(providerPath)) {
+                    content = (0, fs_1.readFileSync)(providerPath, 'utf-8');
+                }
+            }
             if (content) {
                 const templates = JSON.parse(content);
                 this.providerTemplatesCache[provider] = templates;
@@ -178,6 +200,7 @@ class FraimLocalMCPServer {
         this.machineInfo = null;
         this.repoInfo = null;
         this.engine = null;
+        this.registryResolver = null;
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = process.env.FRAIM_API_KEY || '';
         this.localVersion = this.detectLocalVersion();
@@ -349,6 +372,10 @@ class FraimLocalMCPServer {
         if (this.repoInfo) {
             return this.repoInfo;
         }
+        // Ensure config is loaded before trying to detect repo info
+        if (!this.config) {
+            this.loadConfig();
+        }
         try {
             const projectDir = this.findProjectRoot() || process.cwd();
             // Try to get git remote URL
@@ -464,6 +491,112 @@ class FraimLocalMCPServer {
         }
         return this.engine.substituteTemplates(content);
     }
+    /**
+     * Initialize the LocalRegistryResolver for override resolution
+     */
+    getRegistryResolver() {
+        if (!this.registryResolver) {
+            const projectRoot = this.findProjectRoot();
+            this.log(`🔍 getRegistryResolver: projectRoot = ${projectRoot}`);
+            if (!projectRoot) {
+                this.log('⚠️ No project root found, override resolution disabled');
+                // Return a resolver that always falls back to remote
+                this.registryResolver = new local_registry_resolver_1.LocalRegistryResolver({
+                    workspaceRoot: process.cwd(),
+                    remoteContentResolver: async (path) => {
+                        throw new Error('No project root available');
+                    }
+                });
+            }
+            else {
+                this.registryResolver = new local_registry_resolver_1.LocalRegistryResolver({
+                    workspaceRoot: projectRoot,
+                    remoteContentResolver: async (path) => {
+                        // Fetch parent content from remote for inheritance
+                        this.log(`🔄 Remote content resolver: fetching ${path}`);
+                        let request;
+                        if (path.startsWith('workflows/')) {
+                            // Extract workflow name from path: workflows/category/name.md -> name
+                            const pathParts = path.replace('workflows/', '').replace('.md', '').split('/');
+                            const workflowName = pathParts[pathParts.length - 1]; // Get last part (name)
+                            this.log(`🔄 Fetching workflow: ${workflowName}`);
+                            request = {
+                                jsonrpc: '2.0',
+                                id: (0, crypto_1.randomUUID)(),
+                                method: 'tools/call',
+                                params: {
+                                    name: 'get_fraim_workflow',
+                                    arguments: { workflow: workflowName }
+                                }
+                            };
+                        }
+                        else {
+                            // For non-workflow files (templates, rules, etc.), use get_fraim_file
+                            this.log(`🔄 Fetching file: ${path}`);
+                            request = {
+                                jsonrpc: '2.0',
+                                id: (0, crypto_1.randomUUID)(),
+                                method: 'tools/call',
+                                params: {
+                                    name: 'get_fraim_file',
+                                    arguments: { path }
+                                }
+                            };
+                        }
+                        const response = await this.proxyToRemote(request);
+                        if (response.error) {
+                            this.logError(`❌ Remote content resolver failed: ${response.error.message}`);
+                            throw new Error(`Failed to fetch parent: ${response.error.message}`);
+                        }
+                        // Extract content from MCP response format
+                        if (response.result?.content && Array.isArray(response.result.content)) {
+                            const textContent = response.result.content.find((c) => c.type === 'text');
+                            if (textContent?.text) {
+                                this.log(`✅ Remote content resolver: fetched ${textContent.text.length} chars`);
+                                return textContent.text;
+                            }
+                        }
+                        this.logError(`❌ Remote content resolver: no content in response for ${path}`);
+                        this.logError(`Response: ${JSON.stringify(response, null, 2)}`);
+                        throw new Error(`No content in remote response for ${path}`);
+                    }
+                });
+            }
+        }
+        return this.registryResolver;
+    }
+    /**
+     * Determine workflow category from workflow name
+     */
+    getWorkflowCategory(workflowName) {
+        // Product development workflows
+        const productWorkflows = [
+            'prep-issue', 'spec', 'design', 'implement', 'test', 'resolve',
+            'prototype', 'refactor', 'iterate-on-pr-comments', 'retrospect'
+        ];
+        // Customer development workflows
+        const customerWorkflows = [
+            'linkedin-outreach', 'customer-interview', 'insight-analysis',
+            'insight-triage', 'interview-preparation', 'strategic-brainstorming',
+            'thank-customers', 'user-survey-dispatch', 'users-to-target', 'weekly-newsletter'
+        ];
+        // Business development workflows
+        const businessWorkflows = [
+            'partnership-outreach', 'investor-pitch', 'create-business-plan',
+            'ideate-business-opportunity', 'price-product'
+        ];
+        if (productWorkflows.includes(workflowName)) {
+            return 'product-building';
+        }
+        else if (customerWorkflows.includes(workflowName)) {
+            return 'customer-development';
+        }
+        else if (businessWorkflows.includes(workflowName)) {
+            return 'business-development';
+        }
+        // Default to product-building for unknown workflows
+        return 'product-building';
+    }
     /**
      * Process template substitution in MCP response
      */
@@ -522,16 +655,20 @@ class FraimLocalMCPServer {
                     this.log(`[req:${requestId}] Auto-detected and injected repo info: ${args.repo.owner}/${args.repo.name}`);
                 }
                 else {
-                    // If detection fails completely, return error instead of sending garbage
-                    this.logError(`[req:${requestId}] Could not detect repo info and no config available`);
-                    return {
-                        jsonrpc: '2.0',
-                        id: request.id,
-                        error: {
-                            code: -32603,
-                            message: 'Failed to detect repository information. Please ensure you are in a git repository or have .fraim/config.json configured with repository details.'
-                        }
-                    };
+                    // If detection fails, use agent-provided values (if any)
+                    if (!args.repo || !args.repo.url) {
+                        // Only return error if agent didn't provide repo info either
+                        this.logError(`[req:${requestId}] Could not detect repo info and no repo info provided by agent`);
+                        return {
+                            jsonrpc: '2.0',
+                            id: request.id,
+                            error: {
+                                code: -32603,
+                                message: 'Failed to detect repository information. Please ensure you are in a git repository or have .fraim/config.json configured with repository details, or provide repo info in fraim_connect arguments.'
+                            }
+                        };
+                    }
+                    this.log(`[req:${requestId}] Using agent-provided repo info: ${args.repo.owner}/${args.repo.name}`);
                 }
                 // Update the request with injected info
                 request.params.arguments = args;
@@ -640,6 +777,94 @@ class FraimLocalMCPServer {
             this.log(`📤 ${request.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
             return processedResponse;
         }
+        // Intercept get_fraim_workflow and get_fraim_file for override resolution
+        if (request.method === 'tools/call' &&
+            (request.params?.name === 'get_fraim_workflow' ||
+                request.params?.name === 'get_fraim_file')) {
+            try {
+                const toolName = request.params.name;
+                const args = request.params.arguments || {};
+                // Extract the requested path
+                let requestedPath;
+                if (toolName === 'get_fraim_workflow') {
+                    // Convert workflow name to path (e.g., "spec" -> "workflows/product-building/spec.md")
+                    const workflowName = args.workflow;
+                    if (!workflowName) {
+                        this.log('⚠️ No workflow name provided in get_fraim_workflow');
+                    }
+                    else {
+                        // Determine workflow category from name
+                        const category = this.getWorkflowCategory(workflowName);
+                        requestedPath = `workflows/${category}/${workflowName}.md`;
+                        this.log(`🔍 Checking for override: ${requestedPath}`);
+                        const resolver = this.getRegistryResolver();
+                        const hasOverride = resolver.hasLocalOverride(requestedPath);
+                        this.log(`🔍 hasLocalOverride(${requestedPath}) = ${hasOverride}`);
+                        if (hasOverride) {
+                            this.log(`✅ Local override found: ${requestedPath}`);
+                            const resolved = await resolver.resolveFile(requestedPath);
+                            this.log(`📝 Override resolved (source: ${resolved.source}, inherited: ${resolved.inherited})`);
+                            // Build MCP response with resolved content
+                            const response = {
+                                jsonrpc: '2.0',
+                                id: request.id,
+                                result: {
+                                    content: [
+                                        {
+                                            type: 'text',
+                                            text: resolved.content
+                                        }
+                                    ]
+                                }
+                            };
+                            // Apply template substitution
+                            const processedResponse = this.processResponse(response);
+                            this.log(`📤 ${request.method} → OK`);
+                            return processedResponse;
+                        }
+                    }
+                }
+                else if (toolName === 'get_fraim_file') {
+                    requestedPath = args.path;
+                    if (!requestedPath) {
+                        this.log('⚠️ No path provided in get_fraim_file');
+                    }
+                    else {
+                        this.log(`🔍 Checking for override: ${requestedPath}`);
+                        const resolver = this.getRegistryResolver();
+                        const hasOverride = resolver.hasLocalOverride(requestedPath);
+                        this.log(`🔍 hasLocalOverride(${requestedPath}) = ${hasOverride}`);
+                        if (hasOverride) {
+                            this.log(`✅ Local override found: ${requestedPath}`);
+                            const resolved = await resolver.resolveFile(requestedPath);
+                            this.log(`📝 Override resolved (source: ${resolved.source}, inherited: ${resolved.inherited})`);
+                            // Build MCP response with resolved content
+                            const response = {
+                                jsonrpc: '2.0',
+                                id: request.id,
+                                result: {
+                                    content: [
+                                        {
+                                            type: 'text',
+                                            text: resolved.content
+                                        }
+                                    ]
+                                }
+                            };
+                            // Apply template substitution
+                            const processedResponse = this.processResponse(response);
+                            this.log(`📤 ${request.method} → OK`);
+                            return processedResponse;
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                this.logError(`Override resolution failed: ${error.message}`);
+                this.log('⚠️ Falling back to remote');
+                // Fall through to proxy to remote
+            }
+        }
         // Proxy to remote server
         const response = await this.proxyToRemote(request);
         // Process template substitution (config vars, platform actions, delivery templates)

package/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.71",
+  "version": "2.0.73",
   "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/CHANGELOG.md

@@ -1,76 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-
-## [2.1.0] - 2026-02-04
-
-### 🔄 Workflow Refinement
-- **Consolidated Workflows**: Inlined all phase content into main workflow files (`spec.md`, `design.md`, `implement.md`) for better context retention and reduced file scatter.
-- **Removed Redundant Files**: Deleted separate phase folders (`design-phases`, `implement-phases`, `spec-phases`, etc.) to streamline repository structure.
-- **Terminology Update**: Renamed "AI Coach" to "AI Mentor" across all workflows to align with new branding.
-- **Enhanced Spec Workflow**: Added `spec-competitor-analysis` phase and inlined validation steps.
-- **Retrospective Integration**: Inlined retrospective phase content into all major workflows.
-
-## [2.0.0] - 2024-12-19
-
-### 🚀 Major Release: FRAIM v2 - The Future of AI-Assisted Development
-
-#### ✨ New Features
-- **Complete Generic Framework**: Removed all Ashley-specific IP, making FRAIM truly universal
-- **Enhanced Rule System**: 13 comprehensive rule files covering all aspects of AI agent management
-- **Simplified Label System**: Streamlined to 9 essential labels matching real-world usage
-- **Spec Workflow**: Added specification phase for requirements and user experience definition
-- **Timeout Management**: Advanced timeout scripts with output visibility for long-running tasks
-- **Evidence-Based Validation**: Mandatory test evidence collection and validation
-- **Systematic Debugging**: Structured debugging patterns with learning capture
-
-#### 🔧 Improvements
-- **Single Install Method**: Simplified to `npm install -g fraim-framework`
-- **Better Documentation**: Comprehensive README with marketing-style positioning
-- **Example Test Cases**: Complete example with tagging system and documentation
-- **TypeScript Support**: Full TypeScript compilation and type safety
-- **Git Safety**: Safe Git commands preventing agent hangs
-- **Merge Requirements**: Advanced branch management with conflict resolution
-
-#### 🛡️ Security & Reliability
-- **Agent Integrity Rules**: Prevents "fake it till you make it" behavior
-- **Test Ethics**: Mandatory evidence collection and validation
-- **Communication Standards**: Clear accountability and progress reporting
-- **Architecture Discipline**: Clean separation of concerns and technical debt prevention
-
-#### 📚 Documentation
-- **Marketing README**: Compelling documentation positioning FRAIM as the future
-- **Problem-Solution Mapping**: Each rule clearly mapped to specific problems
-- **Human-Agent Parallels**: Clear comparison between human and AI development
-- **Success Stories**: Realistic testimonials and quantified benefits
-
-#### 🎯 Workflow Enhancements
-- **RIGOR Methodology**: Reviews, Isolation, GitOps, Observability, Retrospectives
-- **Phase-Based Development**: Spec → Design → Implementation → Testing → Resolution
-- **Agent Coordination**: Seamless handoffs between multiple AI agents
-- **Continuous Learning**: Retrospective-driven improvement system
-
-#### 🔄 Breaking Changes
-- **Simplified Labels**: Reduced from 15 to 9 essential labels
-- **Install Method**: Single npm install method (removed curl, Python options)
-- **Generic Examples**: All Ashley-specific examples replaced with universal patterns
-
-#### 🐛 Bug Fixes
-- **TypeScript Compilation**: Fixed all compilation issues
-- **Import Dependencies**: Resolved missing dependencies
-- **Test Utilities**: Made generic and framework-agnostic
-- **Repository References**: Updated all URLs to point to FRAIM repository
-
-#### 📦 Dependencies
-- Added TypeScript support with proper type definitions
-- Added tsx for TypeScript execution
-- Added dotenv for environment management
-- Updated Node.js engine requirement to >=16.0.0
-
----
-
-## [1.0.12] - Previous Release
-- Initial FRAIM framework with Ashley-specific implementations
-- Basic rule system and workflows
-- GitHub integration and automation