fraim-framework 2.0.64 → 2.0.65

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;

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 {};
+    }
+}