@veloxts/cli 0.6.85 → 0.6.86

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @veloxts/cli
 
+## 0.6.86
+
+### Patch Changes
+
+- updated documentation
+- Updated dependencies
+  - @veloxts/auth@0.6.86
+  - @veloxts/core@0.6.86
+  - @veloxts/orm@0.6.86
+  - @veloxts/router@0.6.86
+  - @veloxts/validation@0.6.86
+
 ## 0.6.85
 
 ### Patch Changes

package/GUIDE.md

@@ -111,6 +111,105 @@ Supported platforms:
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 - Linux: `~/.config/Claude/claude_desktop_config.json`
 
+### velox openapi generate
+
+Generate OpenAPI 3.0.3 specification from procedure definitions:
+
+```bash
+# Basic usage - JSON to ./openapi.json
+velox openapi generate
+
+# YAML output (auto-detected from extension)
+velox openapi generate -o ./docs/api.yaml
+
+# Full configuration
+velox openapi generate \
+  --path ./src/procedures \
+  --output ./docs/openapi.json \
+  --title "My API" \
+  --version "2.0.0" \
+  --description "Production API documentation" \
+  --server "http://localhost:3030|Development" \
+  --server "https://api.example.com|Production" \
+  --prefix /api \
+  --recursive \
+  --pretty
+```
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --path <path>` | Procedures directory | `./src/procedures` |
+| `-o, --output <file>` | Output file path | `./openapi.json` |
+| `-f, --format <format>` | Output format: `json` or `yaml` | Auto-detected from extension |
+| `-t, --title <title>` | API title | `VeloxTS API` |
+| `-V, --version <version>` | API version | `1.0.0` |
+| `-d, --description <desc>` | API description | None |
+| `-s, --server <url>` | Server URL (repeatable, format: `url\|description`) | None |
+| `--prefix <prefix>` | API route prefix | `/api` |
+| `-r, --recursive` | Scan subdirectories for procedures | `false` |
+| `--pretty` / `--no-pretty` | Pretty-print or minify output | `true` |
+| `--validate` / `--no-validate` | Validate generated spec for issues | `true` |
+| `-q, --quiet` | Suppress output except errors | `false` |
+
+**Server URL Format:**
+
+You can specify multiple server URLs using the `url|description` format:
+
+```bash
+velox openapi generate \
+  -s "http://localhost:3030|Local development" \
+  -s "https://staging.example.com|Staging environment" \
+  -s "https://api.example.com|Production"
+```
+
+**Output:**
+
+The command generates a complete OpenAPI 3.0.3 specification including:
+- Auto-generated paths from procedure naming conventions
+- Request/response schemas from Zod definitions
+- Security schemes from guards (JWT, API keys, etc.)
+- Deprecation warnings from `.deprecated()` procedures
+- Field descriptions from Zod `.describe()` calls
+
+### velox openapi serve
+
+Start a local Swagger UI server to preview OpenAPI documentation:
+
+```bash
+# Serve with default settings
+velox openapi serve
+
+# Custom spec file and port
+velox openapi serve -f ./docs/api.yaml --port 9000
+
+# Enable hot-reload on file changes
+velox openapi serve --watch
+
+# Bind to all interfaces (accessible from network)
+velox openapi serve --host 0.0.0.0
+```
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-f, --file <file>` | OpenAPI spec file (JSON or YAML) | `./openapi.json` |
+| `--port <port>` | Server port | `8080` |
+| `--host <host>` | Host to bind | `localhost` |
+| `-w, --watch` | Watch for file changes and hot-reload | `false` |
+
+**Features:**
+- Interactive Swagger UI interface
+- Try out API endpoints directly from the browser
+- Auto-reload when spec file changes (with `--watch`)
+- CORS enabled for development
+
+The server provides two endpoints:
+- `/` - Swagger UI interface
+- `/openapi.json` - Raw OpenAPI specification (always JSON, regardless of source format)
+
 ## Database Seeding
 
 ### Creating Seeders

package/dist/commands/openapi.d.ts

@@ -1,8 +1,9 @@
 /**
- * OpenAPI command - Generate OpenAPI specifications
+ * OpenAPI command - Generate and serve OpenAPI specifications
  *
- * Provides subcommands for generating OpenAPI documentation:
- * - openapi:generate - Generate OpenAPI JSON specification from procedures
+ * Provides subcommands for generating and serving OpenAPI documentation:
+ * - openapi generate - Generate OpenAPI JSON/YAML specification from procedures
+ * - openapi serve - Start a local Swagger UI server
  */
 import { Command } from 'commander';
 /**

package/dist/commands/openapi.js

@@ -1,16 +1,19 @@
 /**
- * OpenAPI command - Generate OpenAPI specifications
+ * OpenAPI command - Generate and serve OpenAPI specifications
  *
- * Provides subcommands for generating OpenAPI documentation:
- * - openapi:generate - Generate OpenAPI JSON specification from procedures
+ * Provides subcommands for generating and serving OpenAPI documentation:
+ * - openapi generate - Generate OpenAPI JSON/YAML specification from procedures
+ * - openapi serve - Start a local Swagger UI server
  */
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, watch, writeFileSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
-import { discoverProceduresVerbose, generateOpenApiSpec, isDiscoveryError, validateOpenApiSpec, } from '@veloxts/router';
+import { createServer } from 'node:http';
+import { dirname, extname, resolve } from 'node:path';
+import { discoverProceduresVerbose, generateOpenApiSpec, generateSwaggerUIHtml, isDiscoveryError, validateOpenApiSpec, } from '@veloxts/router';
 import { Command } from 'commander';
 import { config as loadEnv } from 'dotenv';
 import pc from 'picocolors';
+import YAML from 'yaml';
 /**
  * Load environment variables from .env file if present
  */
@@ -23,6 +26,28 @@ function loadEnvironment() {
 // ============================================================================
 // Helper Functions
 // ============================================================================
+/**
+ * Detect output format from file extension
+ */
+function detectFormat(outputPath, explicitFormat) {
+    if (explicitFormat) {
+        return explicitFormat;
+    }
+    const ext = extname(outputPath).toLowerCase();
+    if (ext === '.yaml' || ext === '.yml') {
+        return 'yaml';
+    }
+    return 'json';
+}
+/**
+ * Serialize OpenAPI spec to string
+ */
+function serializeSpec(spec, format, pretty) {
+    if (format === 'yaml') {
+        return YAML.stringify(spec, { indent: 2 });
+    }
+    return pretty ? JSON.stringify(spec, null, 2) : JSON.stringify(spec);
+}
 /**
  * Parse server URLs into OpenAPI Server objects
  */
@@ -51,7 +76,7 @@ async function ensureDir(filePath) {
 /**
  * Print success message with summary
  */
-function printSuccess(outputPath, spec, warnings, quiet) {
+function printSuccess(outputPath, spec, warnings, quiet, format = 'json') {
     if (quiet) {
         return;
     }
@@ -61,6 +86,7 @@ function printSuccess(outputPath, spec, warnings, quiet) {
     console.log(pc.green('✓') + pc.bold(' OpenAPI specification generated'));
     console.log();
     console.log(`  ${pc.dim('Output:')}  ${outputPath}`);
+    console.log(`  ${pc.dim('Format:')}  ${format.toUpperCase()}`);
     console.log(`  ${pc.dim('Title:')}   ${spec.info.title}`);
     console.log(`  ${pc.dim('Version:')} ${spec.info.version}`);
     console.log(`  ${pc.dim('Paths:')}   ${pathCount}`);
@@ -88,14 +114,15 @@ function createGenerateCommand() {
         .description('Generate OpenAPI specification from procedures')
         .option('-p, --path <path>', 'Path to procedures directory', './src/procedures')
         .option('-o, --output <file>', 'Output file path', './openapi.json')
+        .option('-f, --format <format>', 'Output format (json or yaml), auto-detected from file extension if not specified')
         .option('-t, --title <title>', 'API title', 'VeloxTS API')
         .option('-V, --version <version>', 'API version', '1.0.0')
         .option('-d, --description <desc>', 'API description')
         .option('-s, --server <url>', 'Server URL (can be specified multiple times)', collectOption)
         .option('--prefix <prefix>', 'API route prefix', '/api')
         .option('-r, --recursive', 'Scan subdirectories for procedures', false)
-        .option('--pretty', 'Pretty-print JSON output', true)
-        .option('--no-pretty', 'Minify JSON output')
+        .option('--pretty', 'Pretty-print output', true)
+        .option('--no-pretty', 'Minify output')
         .option('--validate', 'Validate generated spec for issues', true)
         .option('--no-validate', 'Skip validation')
         .option('-q, --quiet', 'Suppress output except errors', false)
@@ -146,12 +173,14 @@ function createGenerateCommand() {
             }
             // Add discovery warnings
             warnings.push(...discovery.warnings.map((w) => `${w.filePath}: ${w.message}`));
+            // Determine output format
+            const format = detectFormat(outputPath, options.format);
             // Write output
             await ensureDir(outputPath);
-            const jsonContent = options.pretty !== false ? JSON.stringify(spec, null, 2) : JSON.stringify(spec);
-            writeFileSync(outputPath, jsonContent, 'utf-8');
+            const content = serializeSpec(spec, format, options.pretty !== false);
+            writeFileSync(outputPath, content, 'utf-8');
             // Print success message
-            printSuccess(outputPath, spec, warnings, options.quiet ?? false);
+            printSuccess(outputPath, spec, warnings, options.quiet ?? false, format);
             // Exit explicitly - dynamic imports may keep event loop running
             process.exit(0);
         }
@@ -171,28 +200,134 @@ function collectOption(value, previous = []) {
     return [...previous, value];
 }
 /**
- * Create the openapi:serve command (placeholder for future Swagger UI serving)
+ * Create the openapi:serve command
  */
 function createServeCommand() {
     return new Command('serve')
-        .description('Start a local Swagger UI server (coming soon)')
-        .option('-f, --file <file>', 'OpenAPI spec file', './openapi.json')
+        .description('Start a local Swagger UI server to preview OpenAPI documentation')
+        .option('-f, --file <file>', 'OpenAPI spec file (JSON or YAML)', './openapi.json')
         .option('--port <port>', 'Server port', '8080')
-        .action((_options) => {
-        console.log(pc.yellow('The serve command will be available in a future version.'));
-        console.log(pc.dim('For now, use the swaggerUIPlugin in your Fastify app:'));
-        console.log();
-        console.log(pc.cyan(`  import { swaggerUIPlugin } from '@veloxts/router';`));
-        console.log();
-        console.log(pc.cyan(`  app.register(swaggerUIPlugin, {`));
-        console.log(pc.cyan(`    routePrefix: '/docs',`));
-        console.log(pc.cyan(`    collections: [userProcedures],`));
-        console.log(pc.cyan(`    openapi: { info: { title: 'My API', version: '1.0.0' } },`));
-        console.log(pc.cyan(`  });`));
-        console.log();
-        process.exit(0);
+        .option('--host <host>', 'Host to bind', 'localhost')
+        .option('-w, --watch', 'Watch for file changes and hot-reload', false)
+        .action(async (options) => {
+        const filePath = resolve(process.cwd(), options.file ?? './openapi.json');
+        const port = parseInt(options.port ?? '8080', 10);
+        const host = options.host ?? 'localhost';
+        const watchMode = options.watch ?? false;
+        // Validate port number
+        if (Number.isNaN(port) || port < 1 || port > 65535) {
+            console.error(pc.red(`Error: Invalid port number: ${options.port}. Must be between 1-65535.`));
+            process.exit(1);
+        }
+        // Verify spec file exists
+        if (!existsSync(filePath)) {
+            console.error(pc.red(`Error: OpenAPI spec file not found: ${filePath}`));
+            console.log(pc.dim('Run `velox openapi generate` first to create the spec.'));
+            process.exit(1);
+        }
+        // Load spec file
+        let spec;
+        try {
+            spec = loadSpecFile(filePath);
+        }
+        catch (error) {
+            console.error(pc.red(`Error: Failed to parse OpenAPI spec: ${error.message}`));
+            process.exit(1);
+        }
+        // Generate Swagger UI HTML
+        const title = spec.info?.title ?? 'API Documentation';
+        let htmlContent = generateSwaggerUIHtml({
+            specUrl: '/openapi.json',
+            title,
+            config: { tryItOutEnabled: true },
+        });
+        // Create HTTP server
+        const server = createServer((req, res) => {
+            // Handle CORS
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            if (req.url === '/' || req.url === '/index.html') {
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(htmlContent);
+            }
+            else if (req.url === '/openapi.json') {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(spec, null, 2));
+            }
+            else {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('Not Found');
+            }
+        });
+        // Watch for file changes
+        let watcher;
+        let debounceTimer;
+        if (watchMode) {
+            watcher = watch(filePath, () => {
+                // Debounce rapid changes
+                if (debounceTimer) {
+                    clearTimeout(debounceTimer);
+                }
+                debounceTimer = setTimeout(() => {
+                    try {
+                        spec = loadSpecFile(filePath);
+                        htmlContent = generateSwaggerUIHtml({
+                            specUrl: '/openapi.json',
+                            title: spec.info?.title ?? 'API Documentation',
+                            config: { tryItOutEnabled: true },
+                        });
+                        console.log(pc.green('✓') + pc.dim(' Spec reloaded'));
+                    }
+                    catch (error) {
+                        console.error(pc.yellow('⚠') + pc.dim(` Failed to reload spec: ${error.message}`));
+                    }
+                    finally {
+                        debounceTimer = undefined;
+                    }
+                }, 100);
+            });
+        }
+        // Handle graceful shutdown
+        const shutdown = () => {
+            console.log();
+            console.log(pc.dim('Shutting down...'));
+            if (debounceTimer) {
+                clearTimeout(debounceTimer);
+            }
+            watcher?.close();
+            server.close(() => {
+                process.exit(0);
+            });
+        };
+        process.on('SIGINT', shutdown);
+        process.on('SIGTERM', shutdown);
+        // Start server
+        server.listen(port, host, () => {
+            console.log();
+            console.log(pc.green('✓') + pc.bold(' Swagger UI server started'));
+            console.log();
+            console.log(`  ${pc.dim('URL:')}     http://${host}:${port}`);
+            console.log(`  ${pc.dim('Spec:')}    ${filePath}`);
+            console.log(`  ${pc.dim('Title:')}   ${title}`);
+            if (watchMode) {
+                console.log(`  ${pc.dim('Watch:')}   ${pc.green('enabled')}`);
+            }
+            console.log();
+            console.log(pc.dim('Press Ctrl+C to stop'));
+            console.log();
+        });
     });
 }
+/**
+ * Load and parse an OpenAPI spec file (JSON or YAML)
+ */
+function loadSpecFile(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    const ext = extname(filePath).toLowerCase();
+    if (ext === '.yaml' || ext === '.yml') {
+        return YAML.parse(content);
+    }
+    return JSON.parse(content);
+}
 /**
  * Create the openapi command with subcommands
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/cli",
-  "version": "0.6.85",
+  "version": "0.6.86",
   "description": "Developer tooling and CLI commands for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -40,11 +40,12 @@
     "picocolors": "1.1.1",
     "pluralize": "8.0.0",
     "tsx": "4.21.0",
-    "@veloxts/orm": "0.6.85",
-    "@veloxts/auth": "0.6.85",
-    "@veloxts/router": "0.6.85",
-    "@veloxts/validation": "0.6.85",
-    "@veloxts/core": "0.6.85"
+    "yaml": "2.8.0",
+    "@veloxts/orm": "0.6.86",
+    "@veloxts/router": "0.6.86",
+    "@veloxts/validation": "0.6.86",
+    "@veloxts/auth": "0.6.86",
+    "@veloxts/core": "0.6.86"
   },
   "peerDependencies": {
     "@prisma/client": ">=7.0.0"