crowgent-openapi 1.1.0 → 1.2.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { program } from 'commander';
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'fs';
-import { join, extname, relative } from 'path';
+import { join, extname, relative, resolve } from 'path';
 import OpenAI from 'openai';
 import * as p from '@clack/prompts';
 import chalk from 'chalk';
@@ -18,38 +18,45 @@ program
     .option('--base-url <url>', 'API base URL')
     .option('--yes', 'Skip prompts and use defaults', false)
     .action(async (directory, opts) => {
-    // Welcome
     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) {
         p.log.error('Missing OpenAI API key');
-        p.log.info('Set OPENAI_API_KEY environment variable or use --api-key flag');
+        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);
     }
-    // Ask for consent
+    // Ask for consent with explanation
     if (!opts.yes) {
         const consent = await p.confirm({
-            message: 'This will send your code to OpenAI to generate an API spec. Continue?',
+            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('Cancelled'));
+            p.outro(chalk.yellow('No problem! Run me again when you\'re ready.'));
             process.exit(0);
         }
     }
-    // Get directory
+    // 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: 'Which directory contains your backend code?',
-            placeholder: './src or ./routes',
+            message: 'Where is your backend code?',
+            placeholder: './backend or ./src/api',
             defaultValue: '.',
             validate: (value) => {
                 if (!existsSync(value))
-                    return 'Directory not found';
+                    return `Can't find "${value}" - check the path and try again`;
             },
         });
         if (p.isCancel(dirInput)) {
@@ -59,9 +66,17 @@ program
         targetDir = dirInput;
     }
     targetDir = targetDir || '.';
-    // Validate directory
+    // 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(`Directory not found: ${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);
     }
@@ -69,7 +84,7 @@ program
     let outputFile = opts.output;
     if (!outputFile && !opts.yes) {
         const outputInput = await p.text({
-            message: 'Where should we save the OpenAPI spec?',
+            message: 'Where should I save the OpenAPI spec?',
             placeholder: 'openapi.yaml',
             defaultValue: 'openapi.yaml',
         });
@@ -80,12 +95,14 @@ program
         outputFile = outputInput;
     }
     outputFile = outputFile || 'openapi.yaml';
-    // Get base URL
+    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 is your API base URL?',
-            placeholder: 'http://localhost:3000',
+            message: 'What\'s your API base URL?',
+            placeholder: 'https://api.yourapp.com or http://localhost:3000',
             defaultValue: 'http://localhost:3000',
         });
         if (p.isCancel(urlInput)) {
@@ -96,16 +113,31 @@ program
     }
     baseUrl = baseUrl || 'http://localhost:3000';
     // Scan files
-    const scanSpinner = ora('Scanning files...').start();
-    const files = collectFiles(targetDir);
-    scanSpinner.succeed(`Found ${files.length} source files`);
+    p.log.step('Scanning your code...');
+    const files = stat.isDirectory()
+        ? collectFiles(targetDir)
+        : [{
+                path: targetDir,
+                content: readFileSync(targetDir, 'utf-8'),
+            }];
     if (files.length === 0) {
         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);
     }
+    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('Generating OpenAPI spec with AI...').start();
+    const genSpinner = ora('Analyzing code and generating OpenAPI spec...').start();
     try {
         const openai = new OpenAI({ apiKey });
         const codeContext = files
@@ -131,14 +163,29 @@ Use descriptive summaries. Infer types from the code. Return ONLY valid YAML, no
         writeFileSync(outputFile, yaml);
         const tokens = response.usage?.total_tokens || 0;
         const cost = (tokens * 0.00015 / 1000).toFixed(4);
-        genSpinner.succeed('OpenAPI spec generated');
-        p.log.success(`Saved to ${chalk.cyan(outputFile)}`);
-        p.log.info(`${tokens} tokens used (~$${cost})`);
-        p.outro(chalk.green('✨ Done!'));
+        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');
-        p.log.error(error.message || 'Unknown error');
+        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);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crowgent-openapi",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Generate OpenAPI specs from your backend code using AI",
   "type": "module",
   "bin": {