fraim-framework 2.0.67 → 2.0.69

package/dist/registry/scripts/openapi-generator.js

@@ -1,664 +0,0 @@
-#!/usr/bin/env node
-"use strict";
-/**
- * FRAIM OpenAPI Generator
- *
- * Auto-generates OpenAPI specification, instructions.txt, KB files, and MCP server structure
- * for any project using FRAIM.
- *
- * Usage:
- *   npx tsx scripts/openapi-generator.ts
- *
- * This will:
- * 1. Generate openapi.json based on project routes
- * 2. Generate instructions.txt for ChatGPT
- * 3. Create KB-*.txt files for detailed documentation
- * 4. Generate MCP server structure
- * 5. Set up build-time validation
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateOpenAPI = generateOpenAPI;
-exports.generateInstructions = generateInstructions;
-exports.generateKBFiles = generateKBFiles;
-exports.generateMCPServer = generateMCPServer;
-exports.generateAll = generateAll;
-const fs_1 = require("fs");
-const path_1 = require("path");
-const config_loader_js_1 = require("../../src/fraim/config-loader.js");
-const INSTRUCTIONS_LIMIT = 8000;
-const OPENAPI_ENDPOINT_LIMIT = 35;
-const OPENAPI_DESC_LIMIT = 300;
-/**
- * Generate OpenAPI specification from project routes
- */
-function generateOpenAPI(config) {
-    const projectName = config.project.name || 'My Project';
-    const projectDescription = config.project.description || 'API for ' + projectName;
-    const baseUrl = config.api?.baseUrl || 'https://api.example.com';
-    // Start with base OpenAPI structure
-    const openapi = {
-        openapi: '3.1.1',
-        info: {
-            title: `${projectName} API`,
-            description: projectDescription,
-            version: config.project.version || '1.0.0',
-            contact: {
-                name: projectName,
-                email: config.project.contactEmail || 'support@example.com'
-            }
-        },
-        servers: [
-            {
-                url: baseUrl,
-                description: projectName
-            }
-        ],
-        security: [
-            {
-                BearerAuth: []
-            }
-        ],
-        components: {
-            securitySchemes: {
-                BearerAuth: {
-                    type: 'http',
-                    scheme: 'bearer',
-                    bearerFormat: 'JWT',
-                    description: 'JWT token obtained from OAuth authentication'
-                }
-            },
-            schemas: {
-                Error: {
-                    type: 'object',
-                    properties: {
-                        success: {
-                            type: 'boolean',
-                            example: false
-                        },
-                        error: {
-                            type: 'string',
-                            description: 'Error message'
-                        },
-                        message: {
-                            type: 'string',
-                            description: 'Human-readable error message'
-                        }
-                    },
-                    required: ['success', 'error']
-                },
-                Success: {
-                    type: 'object',
-                    properties: {
-                        success: {
-                            type: 'boolean',
-                            example: true
-                        },
-                        message: {
-                            type: 'string',
-                            description: 'Success message'
-                        },
-                        data: {
-                            type: 'object',
-                            description: 'Response data'
-                        }
-                    },
-                    required: ['success']
-                }
-            }
-        },
-        paths: {}
-    };
-    // Add issue filing endpoint (generic, always included)
-    openapi.paths['/issues/create'] = {
-        post: {
-            operationId: 'createIssue',
-            summary: 'Create a GitHub issue',
-            description: 'Create a new issue in the project repository. Can be invoked through ChatGPT OpenAPI or MCP.',
-            'x-openai-isConsequential': false,
-            tags: ['Issues'],
-            security: [{ BearerAuth: [] }],
-            requestBody: {
-                required: true,
-                content: {
-                    'application/json': {
-                        schema: {
-                            type: 'object',
-                            properties: {
-                                title: {
-                                    type: 'string',
-                                    description: 'Issue title',
-                                    example: 'Bug: Feature not working'
-                                },
-                                body: {
-                                    type: 'string',
-                                    description: 'Issue description',
-                                    example: 'Detailed description of the issue'
-                                },
-                                labels: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Optional labels for the issue',
-                                    example: ['bug', 'high-priority']
-                                }
-                            },
-                            required: ['title', 'body']
-                        }
-                    }
-                }
-            },
-            responses: {
-                '200': {
-                    description: 'Issue created successfully',
-                    content: {
-                        'application/json': {
-                            schema: {
-                                allOf: [
-                                    { $ref: '#/components/schemas/Success' },
-                                    {
-                                        type: 'object',
-                                        properties: {
-                                            issueNumber: {
-                                                type: 'integer',
-                                                description: 'GitHub issue number'
-                                            },
-                                            issueUrl: {
-                                                type: 'string',
-                                                format: 'uri',
-                                                description: 'URL to the created issue'
-                                            }
-                                        }
-                                    }
-                                ]
-                            }
-                        }
-                    }
-                },
-                '400': {
-                    description: 'Bad request',
-                    content: {
-                        'application/json': {
-                            schema: { $ref: '#/components/schemas/Error' }
-                        }
-                    }
-                },
-                '401': {
-                    description: 'Unauthorized',
-                    content: {
-                        'application/json': {
-                            schema: { $ref: '#/components/schemas/Error' }
-                        }
-                    }
-                },
-                '500': {
-                    description: 'Internal server error',
-                    content: {
-                        'application/json': {
-                            schema: { $ref: '#/components/schemas/Error' }
-                        }
-                    }
-                }
-            }
-        }
-    };
-    return openapi;
-}
-/**
- * Generate instructions.txt for ChatGPT
- */
-function generateInstructions(config) {
-    const projectName = config.project.name || 'My Project';
-    const projectDescription = config.project.description || 'API for ' + projectName;
-    let instructions = `# Intent
-You are an AI assistant for ${projectName} - ${projectDescription}
-
-# Personality
-Helpful, friendly, professional. Put the user first and manage their time efficiently.
-
-# Communication
-Use plain ASCII only. No en dashes, em dashes, curly quotes, or ellipses. Use hyphens, straight quotes, and three dots instead.
-
-# Key Rules
-- Never claim to complete actions without verified tool/API use
-- Always get confirmation before performing destructive actions
-- See KB files for details on various aspects of operation
-
-## Authentication
-Most endpoints require Bearer token authentication. Exception: Public endpoints (if any).
-
-**When User Asks to Log In/Sign In/Authenticate:**
-- Call authentication endpoint. If it returns 401 Unauthorized, ChatGPT's OAuth system will automatically present the login button/redirect.
-- NO explanations about OAuth, NO lists of steps, NO instructions. Just call the endpoint - ChatGPT's OAuth handles the rest automatically.
-
-## Core Commands
-
-### 1. POST /issues/create - Create GitHub Issue
-**MUST be available for all FRAIM projects.** Create a new issue in the project repository. Can be invoked through ChatGPT OpenAPI or MCP.
-
-**Request Body:**
-- \`title\` (string, required): Issue title
-- \`body\` (string, required): Issue description
-- \`labels\` (array of strings, optional): Labels for the issue
-
-**Response:**
-- \`success\` (boolean): Whether the issue was created
-- \`issueNumber\` (integer): GitHub issue number
-- \`issueUrl\` (string): URL to the created issue
-
-**Usage:** When user reports a bug, requests a feature, or needs to file an issue, use this endpoint.
-
-## Response Format
-All responses: \`{"success": true/false, "message": "Description", "data": {}}\`
-
-## KB Files
-See KB-*.txt files for detailed information on:
-- KB-issues.txt: Issue filing and management
-- KB-authentication.txt: Authentication and authorization
-- KB-api-overview.txt: API overview and common patterns
-
-## Next Steps
-1. Read KB files for detailed workflows
-2. Use endpoints as described
-3. Always confirm with user before destructive actions
-`;
-    // Ensure instructions are within limit
-    if (instructions.length > INSTRUCTIONS_LIMIT) {
-        console.warn(`⚠️  Instructions exceed ${INSTRUCTIONS_LIMIT} character limit (${instructions.length} chars)`);
-        console.warn('   Consider moving detailed content to KB files');
-    }
-    return instructions;
-}
-/**
- * Generate KB files
- */
-function generateKBFiles(config, outputDir) {
-    if (!(0, fs_1.existsSync)(outputDir)) {
-        (0, fs_1.mkdirSync)(outputDir, { recursive: true });
-    }
-    // KB-issues.txt - Issue filing
-    const kbIssues = `# Issue Filing and Management
-
-## Overview
-This project includes a generic issue filing endpoint that can be invoked through ChatGPT OpenAPI or MCP.
-
-## Endpoint: POST /issues/create
-
-### Purpose
-Create a new GitHub issue in the project repository.
-
-### Authentication
-Requires Bearer token authentication.
-
-### Request Format
-\`\`\`json
-{
-  "title": "Issue title",
-  "body": "Detailed description",
-  "labels": ["bug", "high-priority"]
-}
-\`\`\`
-
-### Response Format
-\`\`\`json
-{
-  "success": true,
-  "message": "Issue created successfully",
-  "issueNumber": 123,
-  "issueUrl": "https://github.com/owner/repo/issues/123"
-}
-\`\`\`
-
-### Usage Examples
-
-**From ChatGPT:**
-- User: "I found a bug where the login doesn't work"
-- Assistant: Calls POST /issues/create with title and description
-
-**From MCP:**
-- Tool: create_issue
-- Parameters: title, body, labels
-
-### Configuration
-The endpoint uses GitHub token from environment variables:
-- GITHUB_TOKEN (preferred)
-- GIT_TOKEN
-- GITHUB_PAT
-
-Repository owner and name are configured in project settings.
-
-### Labels
-Common labels:
-- bug: Something isn't working
-- feature: New feature request
-- enhancement: Improvement to existing feature
-- question: Further information is requested
-- help wanted: Extra attention is needed
-`;
-    // KB-authentication.txt
-    const kbAuth = `# Authentication and Authorization
-
-## Overview
-Most endpoints require Bearer token authentication.
-
-## Getting a Token
-1. User logs in through OAuth
-2. ChatGPT automatically handles OAuth flow
-3. Token is included in Authorization header
-
-## Token Format
-\`Authorization: Bearer <token>\`
-
-## Public Endpoints
-Some endpoints may be public (no authentication required). Check endpoint documentation.
-
-## Error Responses
-- 401 Unauthorized: Token missing or invalid
-- 403 Forbidden: Token valid but insufficient permissions
-`;
-    // KB-api-overview.txt
-    const kbApi = `# API Overview
-
-## Base URL
-${config.api?.baseUrl || 'https://api.example.com'}
-
-## Common Patterns
-
-### Success Response
-\`\`\`json
-{
-  "success": true,
-  "message": "Operation completed",
-  "data": {}
-}
-\`\`\`
-
-### Error Response
-\`\`\`json
-{
-  "success": false,
-  "error": "Error code",
-  "message": "Human-readable error message"
-}
-\`\`\`
-
-## Rate Limiting
-Check response headers for rate limit information.
-
-## Pagination
-List endpoints may support pagination:
-- \`limit\`: Number of items per page
-- \`offset\`: Number of items to skip
-`;
-    (0, fs_1.writeFileSync)((0, path_1.join)(outputDir, 'KB-issues.txt'), kbIssues);
-    (0, fs_1.writeFileSync)((0, path_1.join)(outputDir, 'KB-authentication.txt'), kbAuth);
-    (0, fs_1.writeFileSync)((0, path_1.join)(outputDir, 'KB-api-overview.txt'), kbApi);
-    console.log(`✅ Generated KB files in ${outputDir}`);
-}
-/**
- * Generate MCP server structure
- */
-function generateMCPServer(config, outputDir) {
-    const mcpServerDir = (0, path_1.join)(outputDir, '..', 'src', 'mcp-server.ts');
-    const mcpServerContent = `#!/usr/bin/env node
-
-import express from 'express';
-import cors from 'cors';
-
-/**
- * ${config.project.name} MCP Server
- * 
- * MCP server that exposes project API endpoints as MCP tools.
- * Auto-generated by FRAIM.
- */
-
-class ProjectMCPServer {
-  private app: express.Application;
-  private apiBaseUrl: string;
-
-  constructor(apiBaseUrl?: string) {
-    this.app = express();
-    this.app.use(cors());
-    this.app.use(express.json());
-    
-    this.apiBaseUrl = apiBaseUrl || '${config.api?.baseUrl || 'http://localhost:3000'}';
-    this.setupRoutes();
-  }
-
-  private setupRoutes() {
-    // Health check
-    this.app.get('/health', (req, res) => {
-      res.json({ 
-        status: 'healthy', 
-        server: 'project-mcp-server',
-        api_url: this.apiBaseUrl
-      });
-    });
-
-    // MCP endpoint
-    this.app.post('/mcp', async (req, res): Promise<void> => {
-      return this.handleMCPRequest(req, res);
-    });
-  }
-
-  private async handleMCPRequest(req: any, res: any): Promise<void> {
-    try {
-      const { jsonrpc, method, params, id } = req.body;
-      
-      if (jsonrpc !== '2.0') {
-        res.status(400).json({
-          jsonrpc: '2.0',
-          id: id || null,
-          error: {
-            code: -32600,
-            message: 'Invalid Request - jsonrpc must be "2.0"'
-          }
-        });
-        return;
-      }
-
-      let result;
-
-      switch (method) {
-        case 'initialize':
-          result = this.handleInitialize(params);
-          break;
-          
-        case 'tools/list':
-          result = this.getToolsList();
-          break;
-
-        case 'tools/call':
-          result = await this.handleToolCall(params);
-          break;
-
-        default:
-          throw new Error(\`Unknown method: \${method}\`);
-      }
-
-      if (id !== undefined) {
-        res.json({
-          jsonrpc: '2.0',
-          id,
-          result
-        });
-        return;
-      } else {
-        res.status(202).send();
-        return;
-      }
-
-    } catch (error) {
-      res.json({
-        jsonrpc: '2.0',
-        id: req.body?.id || null,
-        error: {
-          code: -32603,
-          message: error instanceof Error ? error.message : 'Internal error'
-        }
-      });
-      return;
-    }
-  }
-
-  public handleInitialize(params: any) {
-    return {
-      protocolVersion: '2024-11-05',
-      capabilities: {
-        tools: {
-          listChanged: false
-        },
-        logging: {}
-      },
-      serverInfo: {
-        name: 'project-mcp-server',
-        version: '1.0.0'
-      }
-    };
-  }
-
-  public getToolsList() {
-    return {
-      tools: [
-        {
-          name: 'create_issue',
-          description: 'Create a new GitHub issue in the project repository',
-          inputSchema: {
-            type: 'object',
-            properties: {
-              title: {
-                type: 'string',
-                description: 'Issue title'
-              },
-              body: {
-                type: 'string',
-                description: 'Issue description'
-              },
-              labels: {
-                type: 'array',
-                items: { type: 'string' },
-                description: 'Optional labels for the issue'
-              }
-            },
-            required: ['title', 'body']
-          }
-        }
-      ]
-    };
-  }
-
-  public async handleToolCall(params: any): Promise<any> {
-    const { name: toolName, arguments: toolArgs } = params;
-
-    switch (toolName) {
-      case 'create_issue':
-        return await this.createIssue(toolArgs);
-      
-      default:
-        throw new Error(\`Unknown tool: \${toolName}\`);
-    }
-  }
-
-  private async createIssue(args: any): Promise<any> {
-    try {
-      const response = await fetch(\`\${this.apiBaseUrl}/issues/create\`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'Authorization': \`Bearer \${args.token || ''}\`
-        },
-        body: JSON.stringify({
-          title: args.title,
-          body: args.body,
-          labels: args.labels || []
-        })
-      });
-
-      const data = await response.json();
-
-      if (!response.ok) {
-        throw new Error(data.error || 'Failed to create issue');
-      }
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: \`Issue created successfully: #\${data.issueNumber}\\nURL: \${data.issueUrl}\`
-          }
-        ]
-      };
-    } catch (error) {
-      throw new Error(\`Failed to create issue: \${error instanceof Error ? error.message : 'Unknown error'}\`);
-    }
-  }
-
-  async start(port: number = 3001) {
-    // Basic express app setup usually goes here or is passed in
-    // For this generator script, we'll just log
-    console.log(\`🚀 MCP Server running on port \${port}\`);
-    console.log(\`📡 MCP endpoint: http://localhost:\${port}/mcp\`);
-  }
-}
-
-// Start server if run directly
-if (import.meta.url === \`file://\${process.argv[1]}\`) {
-  const server = new ProjectMCPServer();
-  server.start().catch((error) => {
-    console.error('Failed to start MCP Server:', error);
-    process.exit(1);
-  });
-}
-
-export { ProjectMCPServer };
-`;
-    // Ensure directory exists
-    const mcpDir = (0, path_1.dirname)(mcpServerDir);
-    if (!(0, fs_1.existsSync)(mcpDir)) {
-        (0, fs_1.mkdirSync)(mcpDir, { recursive: true });
-    }
-    (0, fs_1.writeFileSync)(mcpServerDir, mcpServerContent);
-    console.log(`✅ Generated MCP server at ${mcpServerDir} `);
-}
-/**
- * Main generator function
- */
-function generateAll(config, outputDir = 'src/openapi') {
-    console.log('🚀 FRAIM OpenAPI Generator\n');
-    console.log(`📁 Output directory: ${outputDir} \n`);
-    // Ensure output directory exists
-    if (!(0, fs_1.existsSync)(outputDir)) {
-        (0, fs_1.mkdirSync)(outputDir, { recursive: true });
-    }
-    // Generate OpenAPI spec
-    console.log('📝 Generating OpenAPI specification...');
-    const openapi = generateOpenAPI(config);
-    const openapiPath = (0, path_1.join)(outputDir, 'openapi.json');
-    (0, fs_1.writeFileSync)(openapiPath, JSON.stringify(openapi, null, 2));
-    console.log(`✅ Generated OpenAPI spec at ${openapiPath} `);
-    // Generate instructions.txt
-    console.log('\n📝 Generating instructions.txt...');
-    const instructions = generateInstructions(config);
-    const instructionsPath = (0, path_1.join)(outputDir, 'instructions.txt');
-    (0, fs_1.writeFileSync)(instructionsPath, instructions);
-    console.log(`✅ Generated instructions.txt at ${instructionsPath} `);
-    console.log(`   Length: ${instructions.length} characters(limit: ${INSTRUCTIONS_LIMIT})`);
-    // Generate KB files
-    console.log('\n📝 Generating KB files...');
-    generateKBFiles(config, outputDir);
-    // Generate MCP server
-    console.log('\n📝 Generating MCP server...');
-    generateMCPServer(config, outputDir);
-    console.log('\n✅ FRAIM generation complete!');
-    console.log('\n📋 Next steps:');
-    console.log('1. Review and customize generated files');
-    console.log('2. Add project-specific endpoints to openapi.json');
-    console.log('3. Update instructions.txt with project-specific details');
-    console.log('4. Add more KB files as needed');
-    console.log('5. Run build-time validation: npm run validate:openapi');
-}
-// Run if executed directly
-// Run if executed directly
-// @ts-ignore
-if (import.meta.url === `file://${process.argv[1]}`) {
-    const config = (0, config_loader_js_1.loadFraimConfig)();
-    generateAll(config);
-}