fraim-framework 2.0.56 → 2.0.58

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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

package/bin/fraim-mcp.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * FRAIM MCP Server Entry Point
+ * 
+ * This is called by MCP clients (Cursor, Claude Desktop, Windsurf, Kiro, etc.)
+ * It starts the local STDIO MCP server that proxies to the remote FRAIM server
+ * and performs template substitution.
+ */
+
+// Load and start the server
+const { FraimLocalMCPServer } = require('../dist/src/local-mcp-server/stdio-server.js');
+
+const server = new FraimLocalMCPServer();
+server.start();

package/bin/fraim.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * FRAIM Framework CLI Entry Point
+ *
+ * This file delegates to the compiled TypeScript implementation.
+ */
+
+try {
+    // In production/installed package, code is in dist/
+    require('../dist/src/cli/fraim.js');
+} catch (error) {
+    if (error.code === 'MODULE_NOT_FOUND') {
+        // In development (local clone), we might use tsx if dist is missing
+        // But typically we should just tell user to build.
+        console.error('❌ Could not find FRAIM CLI implementation.');
+        console.error('   If you are running from source, please run "npm run build" first.');
+        console.error(`   Error details: ${error.message}`);
+        process.exit(1);
+    } else {
+        throw error;
+    }
+}

package/dist/src/cli/commands/init-project.js

@@ -39,18 +39,24 @@ const runInitProject = async () => {
     if (!fs_1.default.existsSync(configPath)) {
         const remoteInfo = (0, git_utils_1.getGitRemoteInfo)();
         // Git remote is optional for project init
+        const repoOwner = remoteInfo.owner || 'your-username';
+        const repoName = remoteInfo.repo || path_1.default.basename(projectRoot);
+        const repoUrl = remoteInfo.owner && remoteInfo.repo
+            ? `https://github.com/${remoteInfo.owner}/${remoteInfo.repo}.git`
+            : `https://github.com/${repoOwner}/${repoName}.git`;
         const config = {
             ...types_1.DEFAULT_FRAIM_CONFIG,
             version: (0, version_utils_1.getFraimVersion)(),
             project: {
                 ...types_1.DEFAULT_FRAIM_CONFIG.project,
-                name: remoteInfo.repo || path_1.default.basename(projectRoot)
+                name: repoName
             },
             repository: {
                 provider: 'github',
-                owner: remoteInfo.owner || 'your-username',
-                name: remoteInfo.repo || path_1.default.basename(projectRoot),
-                defaultBranch: 'main'
+                owner: repoOwner,
+                name: repoName,
+                url: repoUrl,
+                defaultBranch: remoteInfo.defaultBranch || 'main'
             }
         };
         fs_1.default.writeFileSync(configPath, JSON.stringify(config, null, 2));

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

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpCommand = void 0;
+const commander_1 = require("commander");
+const server_1 = require("../../local-mcp-server/server");
+const chalk_1 = __importDefault(require("chalk"));
+exports.mcpCommand = new commander_1.Command('mcp')
+    .description('Start the local FRAIM MCP server')
+    .option('-p, --port <port>', 'Port to run the server on', '3003')
+    .option('--remote-only', 'Use remote server only (skip local proxy)', false)
+    .action(async (options) => {
+    try {
+        if (options.remoteOnly) {
+            console.log(chalk_1.default.yellow('⚠️ Remote-only mode not yet implemented'));
+            console.log(chalk_1.default.blue('ℹ️ Starting local MCP server instead...'));
+        }
+        const port = parseInt(options.port);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            console.error(chalk_1.default.red('❌ Invalid port number. Must be between 1 and 65535.'));
+            process.exit(1);
+        }
+        console.log(chalk_1.default.blue('🚀 Starting FRAIM Local MCP Server...'));
+        console.log(chalk_1.default.gray(`📡 Port: ${port}`));
+        console.log(chalk_1.default.gray(`🔄 Auto-updates: Every 5 minutes`));
+        console.log(chalk_1.default.gray(`📁 Cache: ~/.fraim/cache`));
+        console.log('');
+        // Set the port in environment
+        process.env.FRAIM_LOCAL_MCP_PORT = port.toString();
+        // Start the server
+        await (0, server_1.startLocalMCPServer)();
+        // Server is now running, show configuration instructions
+        console.log('');
+        console.log(chalk_1.default.green('✅ FRAIM Local MCP Server is running!'));
+        console.log('');
+        console.log(chalk_1.default.bold('📋 Agent Configuration:'));
+        console.log('');
+        console.log(chalk_1.default.gray('Add this to your agent\'s MCP configuration:'));
+        console.log('');
+        console.log(chalk_1.default.cyan(JSON.stringify({
+            "mcpServers": {
+                "fraim": {
+                    "command": "fraim",
+                    "args": ["mcp"],
+                    "env": {}
+                }
+            }
+        }, null, 2)));
+        console.log('');
+        console.log(chalk_1.default.bold('🔗 Endpoints:'));
+        console.log(chalk_1.default.gray(`  MCP: http://localhost:${port}/mcp`));
+        console.log(chalk_1.default.gray(`  Health: http://localhost:${port}/health`));
+        console.log('');
+        console.log(chalk_1.default.bold('🛑 To stop the server:'));
+        console.log(chalk_1.default.gray('  Press Ctrl+C'));
+        console.log('');
+    }
+    catch (error) {
+        console.error(chalk_1.default.red('❌ Failed to start Local MCP Server:'));
+        console.error(chalk_1.default.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+});

package/dist/src/cli/setup/mcp-config-generator.js

@@ -18,9 +18,10 @@ const generateStandardMCPServers = (fraimKey, githubToken) => ({
             args: ["-y", "@playwright/mcp"]
         },
         fraim: {
-            serverUrl: "https://fraim.wellnessatwork.me",
-            headers: {
-                "x-api-key": fraimKey
+            command: "fraim-mcp",
+            env: {
+                FRAIM_API_KEY: fraimKey,
+                FRAIM_REMOTE_URL: "https://fraim.wellnessatwork.me"
             }
         }
     }
@@ -44,10 +45,10 @@ const generateClaudeMCPServers = (fraimKey, githubToken) => ({
             args: ["-y", "@playwright/mcp"]
         },
         fraim: {
-            type: "http",
-            url: "https://fraim.wellnessatwork.me",
-            headers: {
-                "x-api-key": fraimKey
+            command: "fraim-mcp",
+            env: {
+                FRAIM_API_KEY: fraimKey,
+                FRAIM_REMOTE_URL: "https://fraim.wellnessatwork.me"
             }
         }
     }
@@ -70,9 +71,10 @@ const generateKiroMCPServers = (fraimKey, githubToken) => ({
             args: ["-y", "@playwright/mcp"]
         },
         fraim: {
-            url: "https://fraim.wellnessatwork.me",
-            headers: {
-                "x-api-key": fraimKey
+            command: "fraim-mcp",
+            env: {
+                FRAIM_API_KEY: fraimKey,
+                FRAIM_REMOTE_URL: "https://fraim.wellnessatwork.me"
             }
         }
     }
@@ -92,10 +94,11 @@ command = "npx"
 args = ["-y", "@playwright/mcp"]
 
 [mcp_servers.fraim]
-url = "https://fraim.wellnessatwork.me/"
+command = "fraim-mcp"
 
-[mcp_servers.fraim.headers]
-x-api-key = "${fraimKey}"
+[mcp_servers.fraim.env]
+FRAIM_API_KEY = "${fraimKey}"
+FRAIM_REMOTE_URL = "https://fraim.wellnessatwork.me"
 `;
 exports.generateCodexMCPServers = generateCodexMCPServers;
 const generateWindsurfMCPServers = (fraimKey, githubToken) => ({
@@ -116,10 +119,10 @@ const generateWindsurfMCPServers = (fraimKey, githubToken) => ({
             args: ["-y", "@playwright/mcp"]
         },
         fraim: {
-            command: "npx",
-            args: ["-y", "@modelcontextprotocol/server-fetch", "https://fraim.wellnessatwork.me"],
+            command: "fraim-mcp",
             env: {
-                FRAIM_API_KEY: fraimKey
+                FRAIM_API_KEY: fraimKey,
+                FRAIM_REMOTE_URL: "https://fraim.wellnessatwork.me"
             }
         }
     }

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

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * Azure DevOps (ADO) Issue Tracking Provider
+ *
+ * Implements the IssueTrackingProvider interface for Azure DevOps Work Items
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdoIssueProvider = void 0;
+const axios_1 = __importDefault(require("axios"));
+class AdoIssueProvider {
+    constructor(config) {
+        this.config = config;
+        // Support both cloud and on-premise ADO
+        this.baseUrl = config.baseUrl || `https://dev.azure.com/${config.organization}`;
+    }
+    async createIssue(params) {
+        const { title, body, labels, assignee, priority, dryRun } = params;
+        // ADO uses PATCH with JSON Patch format for work item creation
+        const patchDocument = [
+            {
+                op: 'add',
+                path: '/fields/System.Title',
+                value: title
+            },
+            {
+                op: 'add',
+                path: '/fields/System.Description',
+                value: body
+            }
+        ];
+        // Add assignee if provided
+        if (assignee) {
+            patchDocument.push({
+                op: 'add',
+                path: '/fields/System.AssignedTo',
+                value: assignee
+            });
+        }
+        // Map priority to ADO priority values
+        if (priority) {
+            const adoPriority = this.mapPriorityToAdo(priority);
+            patchDocument.push({
+                op: 'add',
+                path: '/fields/Microsoft.VSTS.Common.Priority',
+                value: adoPriority
+            });
+        }
+        // Add tags (ADO equivalent of labels)
+        if (labels && labels.length > 0) {
+            patchDocument.push({
+                op: 'add',
+                path: '/fields/System.Tags',
+                value: labels.join('; ')
+            });
+        }
+        if (dryRun) {
+            return {
+                success: true,
+                dryRun: true,
+                provider: 'ado',
+                message: `[DRY RUN] Would create ADO work item: "${title}" in ${this.config.organization}/${this.config.project}`
+            };
+        }
+        try {
+            const url = `${this.baseUrl}/${this.config.project}/_apis/wit/workitems/$Bug?api-version=7.0`;
+            const response = await axios_1.default.post(url, patchDocument, {
+                headers: {
+                    'Authorization': `Basic ${Buffer.from(`:${this.config.token}`).toString('base64')}`,
+                    'Content-Type': 'application/json-patch+json',
+                },
+            });
+            return {
+                success: true,
+                issueId: response.data.id,
+                issueNumber: response.data.id,
+                htmlUrl: response.data._links.html.href,
+                provider: 'ado'
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                provider: 'ado',
+                message: this.formatError(error)
+            };
+        }
+    }
+    async getIssue(issueId) {
+        try {
+            const url = `${this.baseUrl}/${this.config.project}/_apis/wit/workitems/${issueId}?api-version=7.0`;
+            const response = await axios_1.default.get(url, {
+                headers: {
+                    'Authorization': `Basic ${Buffer.from(`:${this.config.token}`).toString('base64')}`,
+                },
+            });
+            const workItem = response.data;
+            const fields = workItem.fields;
+            return {
+                id: workItem.id,
+                title: fields['System.Title'] || '',
+                body: fields['System.Description'] || '',
+                state: this.mapAdoStateToGeneric(fields['System.State']),
+                assignee: fields['System.AssignedTo']?.displayName,
+                labels: fields['System.Tags'] ? fields['System.Tags'].split('; ') : [],
+                createdAt: new Date(fields['System.CreatedDate']),
+                updatedAt: new Date(fields['System.ChangedDate']),
+                htmlUrl: workItem._links.html.href
+            };
+        }
+        catch (error) {
+            if (error.response?.status === 404) {
+                return null;
+            }
+            throw new Error(this.formatError(error));
+        }
+    }
+    async updateIssue(issueId, updates) {
+        const patchDocument = [];
+        if (updates.title) {
+            patchDocument.push({
+                op: 'replace',
+                path: '/fields/System.Title',
+                value: updates.title
+            });
+        }
+        if (updates.body) {
+            patchDocument.push({
+                op: 'replace',
+                path: '/fields/System.Description',
+                value: updates.body
+            });
+        }
+        if (updates.assignee) {
+            patchDocument.push({
+                op: 'replace',
+                path: '/fields/System.AssignedTo',
+                value: updates.assignee
+            });
+        }
+        if (updates.priority) {
+            patchDocument.push({
+                op: 'replace',
+                path: '/fields/Microsoft.VSTS.Common.Priority',
+                value: this.mapPriorityToAdo(updates.priority)
+            });
+        }
+        if (updates.labels) {
+            patchDocument.push({
+                op: 'replace',
+                path: '/fields/System.Tags',
+                value: updates.labels.join('; ')
+            });
+        }
+        if (updates.dryRun) {
+            return {
+                success: true,
+                dryRun: true,
+                provider: 'ado',
+                message: `[DRY RUN] Would update ADO work item #${issueId} in ${this.config.organization}/${this.config.project}`
+            };
+        }
+        try {
+            const url = `${this.baseUrl}/${this.config.project}/_apis/wit/workitems/${issueId}?api-version=7.0`;
+            const response = await axios_1.default.patch(url, patchDocument, {
+                headers: {
+                    'Authorization': `Basic ${Buffer.from(`:${this.config.token}`).toString('base64')}`,
+                    'Content-Type': 'application/json-patch+json',
+                },
+            });
+            return {
+                success: true,
+                issueId: response.data.id,
+                issueNumber: response.data.id,
+                htmlUrl: response.data._links.html.href,
+                provider: 'ado'
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                provider: 'ado',
+                message: this.formatError(error)
+            };
+        }
+    }
+    async listIssues(filters) {
+        let wiql = `SELECT [System.Id], [System.Title], [System.State], [System.AssignedTo], [System.CreatedDate], [System.ChangedDate] FROM WorkItems WHERE [System.TeamProject] = '${this.config.project}'`;
+        // Add state filter
+        if (filters?.state && filters.state !== 'all') {
+            const adoState = filters.state === 'open' ? 'Active' : 'Closed';
+            wiql += ` AND [System.State] = '${adoState}'`;
+        }
+        // Add assignee filter
+        if (filters?.assignee) {
+            wiql += ` AND [System.AssignedTo] = '${filters.assignee}'`;
+        }
+        // Add label filter (tags in ADO)
+        if (filters?.labels && filters.labels.length > 0) {
+            const tagConditions = filters.labels.map(label => `[System.Tags] CONTAINS '${label}'`).join(' OR ');
+            wiql += ` AND (${tagConditions})`;
+        }
+        wiql += ' ORDER BY [System.CreatedDate] DESC';
+        try {
+            // First, execute WIQL query to get work item IDs
+            const queryUrl = `${this.baseUrl}/${this.config.project}/_apis/wit/wiql?api-version=7.0`;
+            const queryResponse = await axios_1.default.post(queryUrl, { query: wiql }, {
+                headers: {
+                    'Authorization': `Basic ${Buffer.from(`:${this.config.token}`).toString('base64')}`,
+                    'Content-Type': 'application/json',
+                },
+            });
+            const workItemIds = queryResponse.data.workItems.map((wi) => wi.id);
+            if (workItemIds.length === 0) {
+                return [];
+            }
+            // Limit results
+            const limitedIds = workItemIds.slice(0, filters?.limit || 30);
+            // Get detailed work item information
+            const detailsUrl = `${this.baseUrl}/${this.config.project}/_apis/wit/workitems?ids=${limitedIds.join(',')}&api-version=7.0`;
+            const detailsResponse = await axios_1.default.get(detailsUrl, {
+                headers: {
+                    'Authorization': `Basic ${Buffer.from(`:${this.config.token}`).toString('base64')}`,
+                },
+            });
+            return detailsResponse.data.value.map((workItem) => {
+                const fields = workItem.fields;
+                return {
+                    id: workItem.id,
+                    title: fields['System.Title'] || '',
+                    body: fields['System.Description'] || '',
+                    state: this.mapAdoStateToGeneric(fields['System.State']),
+                    assignee: fields['System.AssignedTo']?.displayName,
+                    labels: fields['System.Tags'] ? fields['System.Tags'].split('; ') : [],
+                    createdAt: new Date(fields['System.CreatedDate']),
+                    updatedAt: new Date(fields['System.ChangedDate']),
+                    htmlUrl: workItem._links.html.href
+                };
+            });
+        }
+        catch (error) {
+            throw new Error(this.formatError(error));
+        }
+    }
+    async validateConfig() {
+        try {
+            // Test by getting project info
+            const url = `${this.baseUrl}/_apis/projects/${this.config.project}?api-version=7.0`;
+            const response = await axios_1.default.get(url, {
+                headers: {
+                    'Authorization': `Basic ${Buffer.from(`:${this.config.token}`).toString('base64')}`,
+                },
+            });
+            return {
+                valid: true,
+                message: `Connected to ADO project: ${response.data.name}`
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                message: this.formatError(error)
+            };
+        }
+    }
+    mapPriorityToAdo(priority) {
+        switch (priority) {
+            case 'critical': return 1;
+            case 'high': return 2;
+            case 'medium': return 3;
+            case 'low': return 4;
+            default: return 3;
+        }
+    }
+    mapAdoStateToGeneric(adoState) {
+        switch (adoState?.toLowerCase()) {
+            case 'active':
+            case 'new':
+            case 'approved':
+                return 'open';
+            case 'resolved':
+            case 'closed':
+            case 'done':
+                return 'closed';
+            case 'committed':
+            case 'in progress':
+                return 'in-progress';
+            default:
+                return 'open';
+        }
+    }
+    formatError(error) {
+        if (axios_1.default.isAxiosError(error)) {
+            return `ADO API Error: ${error.response?.status} - ${JSON.stringify(error.response?.data)}`;
+        }
+        else if (error instanceof Error) {
+            return `ADO Error: ${error.message}`;
+        }
+        return 'Unknown ADO error';
+    }
+}
+exports.AdoIssueProvider = AdoIssueProvider;

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

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Issue Tracking Provider Factory
+ *
+ * Creates the appropriate issue tracking provider based on configuration
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IssueTrackingFactory = void 0;
+const github_provider_1 = require("./github-provider");
+const ado_provider_1 = require("./ado-provider");
+class IssueTrackingFactory {
+    /**
+     * Create an issue tracking provider based on configuration
+     */
+    static createProvider(config) {
+        switch (config.provider) {
+            case 'github':
+                if (!config.github) {
+                    throw new Error('GitHub configuration is required when provider is "github"');
+                }
+                return new github_provider_1.GitHubIssueProvider(config.github);
+            case 'ado':
+                if (!config.ado) {
+                    throw new Error('ADO configuration is required when provider is "ado"');
+                }
+                return new ado_provider_1.AdoIssueProvider(config.ado);
+            default:
+                throw new Error(`Unsupported issue tracking provider: ${config.provider}`);
+        }
+    }
+    /**
+     * Get available providers
+     */
+    static getAvailableProviders() {
+        return ['github', 'ado'];
+    }
+    /**
+     * Validate configuration without creating provider
+     */
+    static validateConfig(config) {
+        switch (config.provider) {
+            case 'github':
+                if (!config.github) {
+                    return { valid: false, message: 'GitHub configuration is required' };
+                }
+                if (!config.github.owner || !config.github.repo || !config.github.token) {
+                    return { valid: false, message: 'GitHub configuration must include owner, repo, and token' };
+                }
+                return { valid: true };
+            case 'ado':
+                if (!config.ado) {
+                    return { valid: false, message: 'ADO configuration is required' };
+                }
+                if (!config.ado.organization || !config.ado.project || !config.ado.token) {
+                    return { valid: false, message: 'ADO configuration must include organization, project, and token' };
+                }
+                return { valid: true };
+            default:
+                return { valid: false, message: `Unsupported provider: ${config.provider}` };
+        }
+    }
+}
+exports.IssueTrackingFactory = IssueTrackingFactory;