fraim-framework 2.0.56 → 2.0.58

package/dist/src/fraim/issue-tracking/github-provider.js

@@ -0,0 +1,200 @@
+"use strict";
+/**
+ * GitHub Issue Tracking Provider
+ *
+ * Implements the IssueTrackingProvider interface for GitHub Issues
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubIssueProvider = void 0;
+const axios_1 = __importDefault(require("axios"));
+class GitHubIssueProvider {
+    constructor(config) {
+        this.config = config;
+        this.baseUrl = `https://api.github.com/repos/${config.owner}/${config.repo}`;
+    }
+    async createIssue(params) {
+        const { title, body, labels, assignee, dryRun } = params;
+        const payload = {
+            title,
+            body
+        };
+        if (labels && labels.length > 0) {
+            payload.labels = labels;
+        }
+        if (assignee) {
+            payload.assignee = assignee;
+        }
+        if (dryRun) {
+            return {
+                success: true,
+                dryRun: true,
+                provider: 'github',
+                message: `[DRY RUN] Would create GitHub issue: "${title}" in ${this.config.owner}/${this.config.repo}`
+            };
+        }
+        try {
+            const response = await axios_1.default.post(`${this.baseUrl}/issues`, payload, {
+                headers: {
+                    'Authorization': `Bearer ${this.config.token}`,
+                    'Accept': 'application/vnd.github.v3+json',
+                    'Content-Type': 'application/json',
+                },
+            });
+            return {
+                success: true,
+                issueNumber: response.data.number,
+                issueId: response.data.number,
+                htmlUrl: response.data.html_url,
+                provider: 'github'
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                provider: 'github',
+                message: this.formatError(error)
+            };
+        }
+    }
+    async getIssue(issueId) {
+        try {
+            const response = await axios_1.default.get(`${this.baseUrl}/issues/${issueId}`, {
+                headers: {
+                    'Authorization': `Bearer ${this.config.token}`,
+                    'Accept': 'application/vnd.github.v3+json',
+                },
+            });
+            const issue = response.data;
+            return {
+                id: issue.number,
+                title: issue.title,
+                body: issue.body || '',
+                state: issue.state === 'open' ? 'open' : 'closed',
+                assignee: issue.assignee?.login,
+                labels: issue.labels.map((label) => label.name),
+                createdAt: new Date(issue.created_at),
+                updatedAt: new Date(issue.updated_at),
+                htmlUrl: issue.html_url
+            };
+        }
+        catch (error) {
+            if (error.response?.status === 404) {
+                return null;
+            }
+            throw new Error(this.formatError(error));
+        }
+    }
+    async updateIssue(issueId, updates) {
+        const payload = {};
+        if (updates.title)
+            payload.title = updates.title;
+        if (updates.body)
+            payload.body = updates.body;
+        if (updates.labels)
+            payload.labels = updates.labels;
+        if (updates.assignee)
+            payload.assignee = updates.assignee;
+        if (updates.dryRun) {
+            return {
+                success: true,
+                dryRun: true,
+                provider: 'github',
+                message: `[DRY RUN] Would update GitHub issue #${issueId} in ${this.config.owner}/${this.config.repo}`
+            };
+        }
+        try {
+            const response = await axios_1.default.patch(`${this.baseUrl}/issues/${issueId}`, payload, {
+                headers: {
+                    'Authorization': `Bearer ${this.config.token}`,
+                    'Accept': 'application/vnd.github.v3+json',
+                    'Content-Type': 'application/json',
+                },
+            });
+            return {
+                success: true,
+                issueNumber: response.data.number,
+                issueId: response.data.number,
+                htmlUrl: response.data.html_url,
+                provider: 'github'
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                provider: 'github',
+                message: this.formatError(error)
+            };
+        }
+    }
+    async listIssues(filters) {
+        const params = {
+            per_page: filters?.limit || 30
+        };
+        if (filters?.state && filters.state !== 'all') {
+            params.state = filters.state;
+        }
+        if (filters?.assignee) {
+            params.assignee = filters.assignee;
+        }
+        if (filters?.labels && filters.labels.length > 0) {
+            params.labels = filters.labels.join(',');
+        }
+        try {
+            const response = await axios_1.default.get(`${this.baseUrl}/issues`, {
+                headers: {
+                    'Authorization': `Bearer ${this.config.token}`,
+                    'Accept': 'application/vnd.github.v3+json',
+                },
+                params
+            });
+            return response.data.map((issue) => ({
+                id: issue.number,
+                title: issue.title,
+                body: issue.body || '',
+                state: issue.state === 'open' ? 'open' : 'closed',
+                assignee: issue.assignee?.login,
+                labels: issue.labels.map((label) => label.name),
+                createdAt: new Date(issue.created_at),
+                updatedAt: new Date(issue.updated_at),
+                htmlUrl: issue.html_url
+            }));
+        }
+        catch (error) {
+            throw new Error(this.formatError(error));
+        }
+    }
+    async validateConfig() {
+        try {
+            // Test by getting repository info
+            const response = await axios_1.default.get(this.baseUrl, {
+                headers: {
+                    'Authorization': `Bearer ${this.config.token}`,
+                    'Accept': 'application/vnd.github.v3+json',
+                },
+            });
+            return {
+                valid: true,
+                message: `Connected to ${response.data.full_name}`
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                message: this.formatError(error)
+            };
+        }
+    }
+    formatError(error) {
+        if (axios_1.default.isAxiosError(error)) {
+            return `GitHub API Error: ${error.response?.status} - ${JSON.stringify(error.response?.data)}`;
+        }
+        else if (error instanceof Error) {
+            return `GitHub Error: ${error.message}`;
+        }
+        return 'Unknown GitHub error';
+    }
+}
+exports.GitHubIssueProvider = GitHubIssueProvider;

package/dist/src/fraim/issue-tracking/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Issue Tracking System Types
+ *
+ * Defines the common interface for all issue tracking systems (GitHub, ADO, etc.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/fraim/issue-tracking-config.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Issue Tracking Configuration Helper
+ *
+ * Provides guidance on which MCP tools to use based on configuration.
+ * This replaces custom providers with MCP tool recommendations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getIssueTrackingGuidance = getIssueTrackingGuidance;
+exports.getRepositoryInfo = getRepositoryInfo;
+const config_loader_1 = require("./config-loader");
+/**
+ * Get guidance on which MCP tools to use for issue tracking
+ */
+function getIssueTrackingGuidance() {
+    const config = (0, config_loader_1.loadFraimConfig)();
+    // Check for ADO configuration
+    if (config.repository?.provider === 'ado') {
+        return {
+            provider: 'ado',
+            mcpTools: {
+                createIssue: 'mcp_ado_create_work_item',
+                getIssue: 'mcp_ado_get_work_item',
+                updateIssue: 'mcp_ado_update_work_item',
+                listIssues: 'mcp_ado_list_work_items',
+                createPR: 'mcp_ado_create_pull_request',
+                getPR: 'mcp_ado_get_pull_request',
+                mergePR: 'mcp_ado_merge_pull_request'
+            },
+            config: {
+                organization: config.repository.organization,
+                project: config.repository.project
+            },
+            environmentVars: ['ADO_TOKEN', 'AZURE_DEVOPS_TOKEN'],
+            setupInstructions: `Configure ADO MCP server in your IDE with:
+- Organization: ${config.repository.organization}
+- Project: ${config.repository.project}
+- Token: Set ADO_TOKEN or AZURE_DEVOPS_TOKEN environment variable`
+        };
+    }
+    // Default to GitHub
+    const owner = config.repository?.owner || config.git?.repoOwner || 'mathursrus';
+    const repo = config.repository?.name || config.git?.repoName || 'FRAIM';
+    return {
+        provider: 'github',
+        mcpTools: {
+            createIssue: 'mcp_github_issue_write',
+            getIssue: 'mcp_github_issue_read',
+            updateIssue: 'mcp_github_issue_write',
+            listIssues: 'mcp_github_list_issues',
+            createPR: 'mcp_github_create_pull_request',
+            getPR: 'mcp_github_pull_request_read',
+            mergePR: 'mcp_github_merge_pull_request'
+        },
+        config: {
+            owner,
+            repo
+        },
+        environmentVars: ['GITHUB_TOKEN'],
+        setupInstructions: `GitHub MCP tools are configured for:
+- Repository: ${owner}/${repo}
+- Token: Set GITHUB_TOKEN environment variable
+- MCP Server: Ensure GitHub MCP server is configured in your IDE`
+    };
+}
+/**
+ * Get repository information from .fraim/config.json
+ */
+function getRepositoryInfo() {
+    try {
+        const config = (0, config_loader_1.loadFraimConfig)();
+        const owner = config.repository?.owner || config.git?.repoOwner;
+        const repo = config.repository?.name || config.git?.repoName;
+        return {
+            owner,
+            repo,
+            url: owner && repo ? `https://github.com/${owner}/${repo}.git` : undefined
+        };
+    }
+    catch (e) {
+        return {};
+    }
+}

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

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * FRAIM Local MCP Server - STDIO Version
+ *
+ * Simple proxy that:
+ * 1. Accepts MCP requests via stdin/stdout
+ * 2. Proxies to remote FRAIM server
+ * 3. Performs template substitution using local .fraim/config.json
+ * 4. Returns processed content to agent
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FraimLocalMCPServer = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const axios_1 = __importDefault(require("axios"));
+class FraimLocalMCPServer {
+    constructor() {
+        this.config = null;
+        this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
+        this.apiKey = process.env.FRAIM_API_KEY || '';
+        if (!this.apiKey) {
+            this.logError('❌ FRAIM_API_KEY environment variable is required');
+            process.exit(1);
+        }
+        this.loadConfig();
+        this.log('🚀 FRAIM Local MCP Server starting...');
+        this.log(`📡 Remote server: ${this.remoteUrl}`);
+        this.log(`🔑 API key: ${this.apiKey.substring(0, 10)}...`);
+    }
+    log(message) {
+        // Log to stderr (stdout is reserved for MCP protocol)
+        console.error(`[FRAIM] ${message}`);
+    }
+    logError(message) {
+        console.error(`[FRAIM ERROR] ${message}`);
+    }
+    loadConfig() {
+        try {
+            const configPath = (0, path_1.join)(process.cwd(), '.fraim', 'config.json');
+            if ((0, fs_1.existsSync)(configPath)) {
+                const configContent = (0, fs_1.readFileSync)(configPath, 'utf8');
+                this.config = JSON.parse(configContent);
+                this.log('✅ Loaded local .fraim/config.json');
+            }
+            else {
+                this.log('⚠️ No .fraim/config.json found - template substitution disabled');
+            }
+        }
+        catch (error) {
+            this.logError(`Failed to load config: ${error}`);
+            this.config = null;
+        }
+    }
+    /**
+     * Substitute template variables in content
+     * Replaces {{config.path.to.value}} with actual values from config
+     */
+    substituteTemplates(content) {
+        if (!this.config)
+            return content;
+        return content.replace(/\{\{config\.([^}]+)\}\}/g, (match, path) => {
+            try {
+                const keys = path.split('.');
+                let value = this.config;
+                for (const key of keys) {
+                    if (value && typeof value === 'object' && key in value) {
+                        value = value[key];
+                    }
+                    else {
+                        // Keep original placeholder if path not found
+                        return match;
+                    }
+                }
+                return String(value);
+            }
+            catch (error) {
+                // Keep original placeholder on error
+                return match;
+            }
+        });
+    }
+    /**
+     * Process template substitution in MCP response
+     */
+    processResponse(response) {
+        if (!response.result)
+            return response;
+        // Process content fields that might contain templates
+        const processValue = (value) => {
+            if (typeof value === 'string') {
+                return this.substituteTemplates(value);
+            }
+            else if (Array.isArray(value)) {
+                return value.map(processValue);
+            }
+            else if (value && typeof value === 'object') {
+                const processed = {};
+                for (const [key, val] of Object.entries(value)) {
+                    processed[key] = processValue(val);
+                }
+                return processed;
+            }
+            return value;
+        };
+        return {
+            ...response,
+            result: processValue(response.result)
+        };
+    }
+    /**
+     * Proxy request to remote FRAIM server
+     */
+    async proxyToRemote(request) {
+        try {
+            const response = await axios_1.default.post(`${this.remoteUrl}/mcp`, request, {
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey
+                },
+                timeout: 30000
+            });
+            return response.data;
+        }
+        catch (error) {
+            this.logError(`Remote request failed: ${error.message}`);
+            return {
+                jsonrpc: '2.0',
+                id: request.id,
+                error: {
+                    code: -32603,
+                    message: `Remote server error: ${error.message}`
+                }
+            };
+        }
+    }
+    /**
+     * Handle incoming MCP request
+     */
+    async handleRequest(request) {
+        this.log(`📥 ${request.method}`);
+        // Proxy to remote server
+        const response = await this.proxyToRemote(request);
+        // Process template substitution
+        const processedResponse = this.processResponse(response);
+        this.log(`📤 ${request.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
+        return processedResponse;
+    }
+    /**
+     * Start STDIO server
+     */
+    start() {
+        let buffer = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', async (chunk) => {
+            buffer += chunk;
+            // Process complete JSON-RPC messages (newline-delimited)
+            let newlineIndex;
+            while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                buffer = buffer.slice(newlineIndex + 1);
+                if (line) {
+                    try {
+                        const request = JSON.parse(line);
+                        const response = await this.handleRequest(request);
+                        // Send response to stdout
+                        process.stdout.write(JSON.stringify(response) + '\n');
+                    }
+                    catch (error) {
+                        this.logError(`Request processing failed: ${error.message}`);
+                        // Send error response
+                        const errorResponse = {
+                            jsonrpc: '2.0',
+                            error: {
+                                code: -32700,
+                                message: `Parse error: ${error.message}`
+                            }
+                        };
+                        process.stdout.write(JSON.stringify(errorResponse) + '\n');
+                    }
+                }
+            }
+        });
+        process.stdin.on('end', () => {
+            this.log('🛑 Stdin closed, shutting down...');
+            process.exit(0);
+        });
+        process.on('SIGTERM', () => {
+            this.log('🛑 SIGTERM received, shutting down...');
+            process.exit(0);
+        });
+        process.on('SIGINT', () => {
+            this.log('🛑 SIGINT received, shutting down...');
+            process.exit(0);
+        });
+        this.log('✅ FRAIM Local MCP Server ready');
+    }
+}
+exports.FraimLocalMCPServer = FraimLocalMCPServer;
+// Start server if run directly
+if (require.main === module) {
+    const server = new FraimLocalMCPServer();
+    server.start();
+}

package/dist/src/utils/workflow-parser.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowParser = void 0;
+const fs_1 = require("fs");
+class WorkflowParser {
+    /**
+     * Parse a workflow markdown file into a structured definition
+     */
+    static parse(filePath) {
+        if (!(0, fs_1.existsSync)(filePath))
+            return null;
+        const content = (0, fs_1.readFileSync)(filePath, 'utf-8');
+        // 1. Extract JSON Metadata
+        const metadataMatch = content.match(/^---\r?\n([\s\S]+?)\r?\n---/);
+        if (!metadataMatch)
+            return null;
+        let metadata;
+        try {
+            metadata = JSON.parse(metadataMatch[1]);
+        }
+        catch (e) {
+            console.error(`❌ Failed to parse JSON metadata in ${filePath}:`, e);
+            return null;
+        }
+        // 2. Extract Overview (Content after metadata but before first phase header)
+        const contentAfterMetadata = content.substring(metadataMatch[0].length).trim();
+        const firstPhaseIndex = contentAfterMetadata.search(/^##\s+Phase:/m);
+        let overview = '';
+        let restOfContent = '';
+        if (firstPhaseIndex !== -1) {
+            overview = contentAfterMetadata.substring(0, firstPhaseIndex).trim();
+            restOfContent = contentAfterMetadata.substring(firstPhaseIndex);
+        }
+        else {
+            overview = contentAfterMetadata;
+        }
+        // 3. Extract Phases (id -> content)
+        const phases = new Map();
+        const phaseSections = restOfContent.split(/^##\s+Phase:\s+/m);
+        // Skip the first part (empty or overview overlap)
+        for (let i = 1; i < phaseSections.length; i++) {
+            const section = phaseSections[i];
+            const sectionLines = section.split('\n');
+            const firstLine = sectionLines[0].trim();
+            // Extract phase ID (slug before any (Phase X) or space)
+            const id = firstLine.split(/[ (]/)[0].trim().toLowerCase();
+            // The content includes the header (we'll reconstruct it for the agent or just return the body)
+            // But usually, the agent wants the whole section including the Phase ID header.
+            // We'll store the whole section but prepend the header because split removed it.
+            phases.set(id, `## Phase: ${section.trim()}`);
+        }
+        return {
+            metadata,
+            overview,
+            phases
+        };
+    }
+    /**
+     * Extract description for listing workflows (intent or first para of overview)
+     */
+    static extractDescription(filePath) {
+        const wf = this.parse(filePath);
+        if (!wf)
+            return '';
+        // Try to find Intent section in overview
+        const intentMatch = wf.overview.match(/## Intent\s+([\s\S]+?)(?:\r?\n##|$)/);
+        if (intentMatch)
+            return intentMatch[1].trim().split(/\r?\n/)[0];
+        // Fallback to first non-header line
+        const firstPara = wf.overview.split(/\r?\n/).find(l => l.trim() !== '' && !l.startsWith('#'));
+        return firstPara ? firstPara.trim() : '';
+    }
+    /**
+     * Get just the overview for an agent starting a workflow
+     */
+    static getOverview(filePath) {
+        const wf = this.parse(filePath);
+        return wf ? wf.overview : null;
+    }
+}
+exports.WorkflowParser = WorkflowParser;

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.56",
+  "version": "2.0.58",
   "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": {
     "fraim": "./index.js",
-    "fraim-setup": "./index.js"
+    "fraim-mcp": "./bin/fraim-mcp.js"
   },
   "scripts": {
-    "setup": "node setup.js",
-    "dev": "tsx --watch src/fraim-mcp-server.ts",
+    "dev": "tsx --watch src/fraim-mcp-server.ts > server.log 2>&1",
     "build": "tsc && node scripts/copy-ai-manager-rules.js && npm run build:stubs && npm run validate:registry",
     "build:stubs": "tsx scripts/build-stub-registry.ts",
     "test": "node scripts/test-with-server.js",
@@ -26,7 +25,8 @@
     "release": "npm version patch && npm publish",
     "test-smoke-ci": "tsx --test tests/test-genericization.ts tests/test-cli.ts tests/test-stub-registry.ts tests/test-sync-stubs.ts",
     "test-all-ci": "tsx --test tests/test-*.ts",
-    "validate:registry": "tsx scripts/verify-registry-paths.ts"
+    "validate:registry": "tsx scripts/verify-registry-paths.ts && npm run validate:workflows",
+    "validate:workflows": "tsx scripts/validate-workflows.ts"
   },
   "repository": {
     "type": "git",
@@ -69,14 +69,19 @@
     "typescript": "^5.0.0"
   },
   "files": [
-    "dist/",
+    "dist/src/local-mcp-server/",
+    "dist/src/cli/",
+    "dist/src/fraim/",
+    "dist/src/utils/",
     "registry/stubs/",
     "registry/scripts/",
-    "bin/",
-    "*.js",
-    "*.ts",
-    "*.md",
-    "*.json"
+    "bin/fraim.js",
+    "bin/fraim-mcp.js",
+    "index.js",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "package.json"
   ],
   "publishConfig": {
     "access": "public"
@@ -92,7 +97,7 @@
     "markdown-it-highlightjs": "^4.2.0",
     "mongodb": "^7.0.0",
     "prompts": "^2.4.2",
-    "puppeteer": "^24.35.0",
+    "puppeteer": "^24.36.1",
     "sharp": "^0.34.5",
     "tree-kill": "^1.2.2"
   }