fraim-framework 2.0.30 → 2.0.33

package/registry/scripts/openapi-generator.ts

@@ -1,695 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * 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
- */
-
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
-import { join, dirname } from 'path';
-import { loadFraimConfig } from '../../src/fraim/config-loader.js';
-import type { FraimConfig } from '../../src/fraim/types.js';
-
-const INSTRUCTIONS_LIMIT = 8000;
-const OPENAPI_ENDPOINT_LIMIT = 35;
-const OPENAPI_DESC_LIMIT = 300;
-
-interface EndpointInfo {
-  path: string;
-  method: string;
-  description: string;
-  operationId: string;
-  requiresAuth: boolean;
-  isConsequential: boolean;
-}
-
-/**
- * Generate OpenAPI specification from project routes
- */
-export function generateOpenAPI(config: any): any {
-  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: any = {
-    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
- */
-export function generateInstructions(config: any): string {
-  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
- */
-export function generateKBFiles(config: any, outputDir: string): void {
-  if (!existsSync(outputDir)) {
-    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
-`;
-
-  writeFileSync(join(outputDir, 'KB-issues.txt'), kbIssues);
-  writeFileSync(join(outputDir, 'KB-authentication.txt'), kbAuth);
-  writeFileSync(join(outputDir, 'KB-api-overview.txt'), kbApi);
-
-  console.log(`✅ Generated KB files in ${outputDir}`);
-}
-
-/**
- * Generate MCP server structure
- */
-export function generateMCPServer(config: any, outputDir: string): void {
-  const mcpServerDir = 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 = dirname(mcpServerDir);
-  if (!existsSync(mcpDir)) {
-    mkdirSync(mcpDir, { recursive: true });
-  }
-
-  writeFileSync(mcpServerDir, mcpServerContent);
-  console.log(`✅ Generated MCP server at ${mcpServerDir} `);
-}
-
-/**
- * Main generator function
- */
-export function generateAll(config: any, outputDir: string = 'src/openapi'): void {
-  console.log('🚀 FRAIM OpenAPI Generator\n');
-  console.log(`📁 Output directory: ${outputDir} \n`);
-
-  // Ensure output directory exists
-  if (!existsSync(outputDir)) {
-    mkdirSync(outputDir, { recursive: true });
-  }
-
-  // Generate OpenAPI spec
-  console.log('📝 Generating OpenAPI specification...');
-  const openapi = generateOpenAPI(config);
-  const openapiPath = join(outputDir, 'openapi.json');
-  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 = join(outputDir, 'instructions.txt');
-  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 = loadFraimConfig();
-  generateAll(config);
-}