crowgent-openapi 1.0.0 → 1.2.0

package/dist/cli.js

@@ -1,57 +1,194 @@
 #!/usr/bin/env node
 import { program } from 'commander';
-import { readFileSync, writeFileSync, readdirSync, statSync } from 'fs';
-import { join, extname, relative } from 'path';
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'fs';
+import { join, extname, relative, resolve } from 'path';
 import OpenAI from 'openai';
+import * as p from '@clack/prompts';
+import chalk from 'chalk';
+import ora from 'ora';
 const EXTENSIONS = ['.ts', '.js', '.tsx', '.jsx', '.py', '.rb', '.go', '.java', '.kt', '.rs'];
 const IGNORE = ['node_modules', '.git', 'dist', 'build', '__pycache__', '.next', 'coverage'];
 program
     .name('crowgent-openapi')
     .description('Generate OpenAPI specs from your backend code using AI')
-    .argument('<directory>', 'Backend directory to scan')
-    .option('-o, --output <file>', 'Output file', 'openapi.yaml')
+    .argument('[directory]', 'Backend directory to scan')
+    .option('-o, --output <file>', 'Output file')
     .option('-k, --api-key <key>', 'OpenAI API key (or set OPENAI_API_KEY)')
     .option('-m, --model <model>', 'Model to use', 'gpt-4o-mini')
-    .option('--base-url <url>', 'API base URL', 'http://localhost:3000')
+    .option('--base-url <url>', 'API base URL')
+    .option('--yes', 'Skip prompts and use defaults', false)
     .action(async (directory, opts) => {
+    console.log();
+    p.intro(chalk.bgCyan.black(' 🐦 Crowgent OpenAPI Generator '));
+    // Friendly explanation
+    p.note(`I'll help you generate an OpenAPI specification from your backend code.\n\n` +
+        `${chalk.dim('What is this for?')}\n` +
+        `An OpenAPI spec describes your API endpoints, parameters, and responses.\n` +
+        `Upload it to ${chalk.cyan('Crow')} to give your AI agent the ability to call your APIs.`, 'Welcome');
     const apiKey = opts.apiKey || process.env.OPENAI_API_KEY;
+    // Check API key
     if (!apiKey) {
-        console.error('❌ Missing API key. Set OPENAI_API_KEY or use --api-key');
+        p.log.error('Missing OpenAI API key');
+        p.log.message(`${chalk.dim('To fix this, run:')}\n` +
+            `${chalk.cyan('export OPENAI_API_KEY="sk-..."')}\n\n` +
+            `${chalk.dim('Get your key at:')} ${chalk.underline('https://platform.openai.com/api-keys')}`);
+        p.outro(chalk.red('Setup incomplete'));
         process.exit(1);
     }
-    console.log('📂 Scanning files...');
-    const files = collectFiles(directory);
-    console.log(`   Found ${files.length} source files`);
+    // Ask for consent with explanation
+    if (!opts.yes) {
+        const consent = await p.confirm({
+            message: `I'll scan your code and send it to OpenAI to generate the spec. This typically costs < $0.01. Continue?`,
+            initialValue: true,
+        });
+        if (p.isCancel(consent) || !consent) {
+            p.outro(chalk.yellow('No problem! Run me again when you\'re ready.'));
+            process.exit(0);
+        }
+    }
+    // Get directory with helpful guidance
+    let targetDir = directory;
+    if (!targetDir && !opts.yes) {
+        p.log.message(chalk.dim('Tip: Point me at the folder containing your API routes (e.g., ./src, ./routes, ./api)'));
+        const dirInput = await p.text({
+            message: 'Where is your backend code?',
+            placeholder: './backend or ./src/api',
+            defaultValue: '.',
+            validate: (value) => {
+                if (!existsSync(value))
+                    return `Can't find "${value}" - check the path and try again`;
+            },
+        });
+        if (p.isCancel(dirInput)) {
+            p.outro(chalk.yellow('Cancelled'));
+            process.exit(0);
+        }
+        targetDir = dirInput;
+    }
+    targetDir = targetDir || '.';
+    // Handle single file vs directory
+    const targetPath = resolve(targetDir);
+    const stat = statSync(targetPath);
+    if (!stat.isDirectory()) {
+        // It's a file - use its parent directory but only include this file
+        p.log.warn(`"${targetDir}" is a file, not a directory. I'll analyze just this file.`);
+    }
+    // Validate
+    if (!existsSync(targetDir)) {
+        p.log.error(`Can't find "${targetDir}"`);
+        p.log.message(chalk.dim('Make sure the path exists and try again.'));
+        p.outro(chalk.red('Failed'));
+        process.exit(1);
+    }
+    // Get output file
+    let outputFile = opts.output;
+    if (!outputFile && !opts.yes) {
+        const outputInput = await p.text({
+            message: 'Where should I save the OpenAPI spec?',
+            placeholder: 'openapi.yaml',
+            defaultValue: 'openapi.yaml',
+        });
+        if (p.isCancel(outputInput)) {
+            p.outro(chalk.yellow('Cancelled'));
+            process.exit(0);
+        }
+        outputFile = outputInput;
+    }
+    outputFile = outputFile || 'openapi.yaml';
+    const outputPath = resolve(outputFile);
+    // Get base URL with explanation
+    let baseUrl = opts.baseUrl;
+    if (!baseUrl && !opts.yes) {
+        p.log.message(chalk.dim('This is the URL where your API is hosted (used in the spec\'s "servers" field)'));
+        const urlInput = await p.text({
+            message: 'What\'s your API base URL?',
+            placeholder: 'https://api.yourapp.com or http://localhost:3000',
+            defaultValue: 'http://localhost:3000',
+        });
+        if (p.isCancel(urlInput)) {
+            p.outro(chalk.yellow('Cancelled'));
+            process.exit(0);
+        }
+        baseUrl = urlInput;
+    }
+    baseUrl = baseUrl || 'http://localhost:3000';
+    // Scan files
+    p.log.step('Scanning your code...');
+    const files = stat.isDirectory()
+        ? collectFiles(targetDir)
+        : [{
+                path: targetDir,
+                content: readFileSync(targetDir, 'utf-8'),
+            }];
     if (files.length === 0) {
-        console.error('❌ No source files found');
+        p.log.error('No source files found');
+        p.log.message(chalk.dim(`I look for these file types: ${EXTENSIONS.join(', ')}\n`) +
+            chalk.dim(`Make sure your backend code is in "${targetDir}"`));
+        p.outro(chalk.red('Failed'));
         process.exit(1);
     }
-    console.log('🤖 Generating OpenAPI spec...');
-    const openai = new OpenAI({ apiKey });
-    const codeContext = files
-        .map(f => `### ${f.path}\n\`\`\`\n${f.content}\n\`\`\``)
-        .join('\n\n');
-    const response = await openai.chat.completions.create({
-        model: opts.model,
-        messages: [{
-                role: 'system',
-                content: `You are an expert at generating OpenAPI 3.0 specifications. 
+    p.log.success(`Found ${files.length} source file${files.length > 1 ? 's' : ''}`);
+    // Show which files we found
+    if (files.length <= 5) {
+        files.forEach(f => p.log.message(chalk.dim(`  • ${f.path}`)));
+    }
+    else {
+        files.slice(0, 3).forEach(f => p.log.message(chalk.dim(`  • ${f.path}`)));
+        p.log.message(chalk.dim(`  • ... and ${files.length - 3} more`));
+    }
+    // Generate spec
+    const genSpinner = ora('Analyzing code and generating OpenAPI spec...').start();
+    try {
+        const openai = new OpenAI({ apiKey });
+        const codeContext = files
+            .map(f => `### ${f.path}\n\`\`\`\n${f.content}\n\`\`\``)
+            .join('\n\n');
+        const response = await openai.chat.completions.create({
+            model: opts.model,
+            messages: [{
+                    role: 'system',
+                    content: `You are an expert at generating OpenAPI 3.0 specifications. 
 Analyze the provided backend code and generate a complete, valid OpenAPI 3.0.3 YAML spec.
 Include: all endpoints, HTTP methods, path/query parameters, request bodies, response schemas with properties.
 Use descriptive summaries. Infer types from the code. Return ONLY valid YAML, no markdown or explanation.`
-            }, {
-                role: 'user',
-                content: `Generate an OpenAPI spec for this backend code. Base URL: ${opts.baseUrl}\n\n${codeContext}`
-            }],
-        max_tokens: 16000,
-        temperature: 0.2,
-    });
-    let yaml = response.choices[0].message.content || '';
-    // Strip markdown fences if present
-    yaml = yaml.replace(/^```ya?ml\n?/i, '').replace(/\n?```$/i, '').trim();
-    writeFileSync(opts.output, yaml);
-    console.log(`✅ Saved to ${opts.output}`);
-    console.log(`   ${response.usage?.total_tokens || '?'} tokens used`);
+                }, {
+                    role: 'user',
+                    content: `Generate an OpenAPI spec for this backend code. Base URL: ${baseUrl}\n\n${codeContext}`
+                }],
+            max_tokens: 16000,
+            temperature: 0.2,
+        });
+        let yaml = response.choices[0].message.content || '';
+        yaml = yaml.replace(/^```ya?ml\n?/i, '').replace(/\n?```$/i, '').trim();
+        writeFileSync(outputFile, yaml);
+        const tokens = response.usage?.total_tokens || 0;
+        const cost = (tokens * 0.00015 / 1000).toFixed(4);
+        genSpinner.succeed('OpenAPI spec generated!');
+        // Success summary
+        console.log();
+        p.note(`${chalk.green('✓')} Saved to: ${chalk.cyan(outputPath)}\n` +
+            `${chalk.green('✓')} Tokens used: ${tokens} (~$${cost})\n\n` +
+            `${chalk.dim('Next step:')}\n` +
+            `Upload this file to ${chalk.cyan('Crow')} at Integration → OpenAPI\n` +
+            `to give your AI agent access to your API tools.`, 'Done!');
+        p.outro(chalk.green('Happy building! 🚀'));
+    }
+    catch (error) {
+        genSpinner.fail('Generation failed');
+        if (error.message?.includes('401')) {
+            p.log.error('Invalid API key');
+            p.log.message(chalk.dim('Check that your OPENAI_API_KEY is correct and has credits.'));
+        }
+        else if (error.message?.includes('429')) {
+            p.log.error('Rate limited - too many requests');
+            p.log.message(chalk.dim('Wait a minute and try again.'));
+        }
+        else {
+            p.log.error(error.message || 'Unknown error');
+        }
+        p.outro(chalk.red('Failed'));
+        process.exit(1);
+    }
 });
 function collectFiles(dir, root = dir) {
     const files = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crowgent-openapi",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Generate OpenAPI specs from your backend code using AI",
   "type": "module",
   "bin": {
@@ -12,10 +12,16 @@
     "dev": "tsx src/cli.ts",
     "prepublishOnly": "npm run build"
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "chalk": "^5.3.0",
     "commander": "^12.0.0",
-    "openai": "^4.0.0"
+    "openai": "^4.0.0",
+    "ora": "^8.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -25,7 +31,16 @@
   "engines": {
     "node": ">=18"
   },
-  "keywords": ["openapi", "swagger", "api", "generator", "ai", "llm", "gpt", "documentation"],
+  "keywords": [
+    "openapi",
+    "swagger",
+    "api",
+    "generator",
+    "ai",
+    "llm",
+    "gpt",
+    "documentation"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/usecrow/crowgent-openapi"
@@ -33,4 +48,3 @@
   "author": "Crow",
   "license": "MIT"
 }
-