@veloxts/cli 0.6.57 → 0.6.58

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @veloxts/cli
 
+## 0.6.58
+
+### Patch Changes
+
+- feat(router): add OpenAPI 3.0.3 specification generator
+- Updated dependencies
+  - @veloxts/auth@0.6.58
+  - @veloxts/core@0.6.58
+  - @veloxts/orm@0.6.58
+  - @veloxts/router@0.6.58
+  - @veloxts/validation@0.6.58
+
 ## 0.6.57
 
 ### Patch Changes

package/dist/cli.js

@@ -15,6 +15,7 @@ import { createIntrospectCommand } from './commands/introspect.js';
 import { createMakeCommand } from './commands/make.js';
 import { createMcpCommand } from './commands/mcp.js';
 import { createMigrateCommand } from './commands/migrate.js';
+import { createOpenApiCommand } from './commands/openapi.js';
 import { createProceduresCommand } from './commands/procedures.js';
 import { createScheduleCommand } from './commands/schedule.js';
 import { createTenantCommand } from './commands/tenant.js';
@@ -36,6 +37,7 @@ function createCLI() {
     program.addCommand(createMakeCommand());
     program.addCommand(createMcpCommand());
     program.addCommand(createMigrateCommand());
+    program.addCommand(createOpenApiCommand());
     program.addCommand(createProceduresCommand());
     program.addCommand(createScheduleCommand());
     program.addCommand(createTenantCommand());

package/dist/commands/openapi.d.ts

@@ -0,0 +1,11 @@
+/**
+ * OpenAPI command - Generate OpenAPI specifications
+ *
+ * Provides subcommands for generating OpenAPI documentation:
+ * - openapi:generate - Generate OpenAPI JSON specification from procedures
+ */
+import { Command } from 'commander';
+/**
+ * Create the openapi command with subcommands
+ */
+export declare function createOpenApiCommand(): Command;

package/dist/commands/openapi.js

@@ -0,0 +1,205 @@
+/**
+ * OpenAPI command - Generate OpenAPI specifications
+ *
+ * Provides subcommands for generating OpenAPI documentation:
+ * - openapi:generate - Generate OpenAPI JSON specification from procedures
+ */
+import { existsSync, 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 { Command } from 'commander';
+import { config as loadEnv } from 'dotenv';
+import pc from 'picocolors';
+/**
+ * Load environment variables from .env file if present
+ */
+function loadEnvironment() {
+    const envPath = resolve(process.cwd(), '.env');
+    if (existsSync(envPath)) {
+        loadEnv({ path: envPath });
+    }
+}
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Parse server URLs into OpenAPI Server objects
+ */
+function parseServers(servers) {
+    if (!servers || servers.length === 0) {
+        return [];
+    }
+    return servers.map((server, index) => {
+        // Support "url|description" format
+        const [url, description] = server.split('|');
+        return {
+            url: url.trim(),
+            description: description?.trim() ?? (index === 0 ? 'Primary server' : undefined),
+        };
+    });
+}
+/**
+ * Ensure directory exists for output file
+ */
+async function ensureDir(filePath) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true });
+    }
+}
+/**
+ * Print success message with summary
+ */
+function printSuccess(outputPath, spec, warnings, quiet) {
+    if (quiet) {
+        return;
+    }
+    const pathCount = Object.keys(spec.paths).length;
+    const tagCount = spec.tags?.length ?? 0;
+    console.log();
+    console.log(pc.green('✓') + pc.bold(' OpenAPI specification generated'));
+    console.log();
+    console.log(`  ${pc.dim('Output:')}  ${outputPath}`);
+    console.log(`  ${pc.dim('Title:')}   ${spec.info.title}`);
+    console.log(`  ${pc.dim('Version:')} ${spec.info.version}`);
+    console.log(`  ${pc.dim('Paths:')}   ${pathCount}`);
+    console.log(`  ${pc.dim('Tags:')}    ${tagCount}`);
+    if (spec.servers?.length) {
+        console.log(`  ${pc.dim('Servers:')} ${spec.servers.map((s) => s.url).join(', ')}`);
+    }
+    if (warnings.length > 0) {
+        console.log();
+        console.log(pc.yellow(`${warnings.length} warning(s):`));
+        for (const warning of warnings) {
+            console.log(pc.yellow(`  • ${warning}`));
+        }
+    }
+    console.log();
+}
+// ============================================================================
+// Command Implementation
+// ============================================================================
+/**
+ * Create the openapi:generate command
+ */
+function createGenerateCommand() {
+    return new Command('generate')
+        .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('-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('--validate', 'Validate generated spec for issues', true)
+        .option('--no-validate', 'Skip validation')
+        .option('-q, --quiet', 'Suppress output except errors', false)
+        .action(async (options) => {
+        // Load .env file before importing procedure files
+        loadEnvironment();
+        const proceduresPath = options.path ?? './src/procedures';
+        const outputPath = resolve(process.cwd(), options.output ?? './openapi.json');
+        const discoveryOptions = {
+            recursive: options.recursive ?? false,
+            onInvalidExport: 'warn',
+        };
+        try {
+            // Discover procedures
+            if (!options.quiet) {
+                console.log(pc.dim('Discovering procedures...'));
+            }
+            const discovery = await discoverProceduresVerbose(proceduresPath, discoveryOptions);
+            if (discovery.collections.length === 0) {
+                console.error(pc.red('Error: No procedure collections found'));
+                console.error(pc.dim(`Searched in: ${proceduresPath}`));
+                process.exit(1);
+            }
+            if (!options.quiet) {
+                console.log(pc.dim(`Found ${discovery.collections.length} collection(s) with ` +
+                    `${discovery.collections.reduce((sum, c) => sum + Object.keys(c.procedures).length, 0)} procedure(s)`));
+            }
+            // Build OpenAPI options
+            const openApiOptions = {
+                info: {
+                    title: options.title ?? 'VeloxTS API',
+                    version: options.version ?? '1.0.0',
+                    description: options.description,
+                },
+                prefix: options.prefix ?? '/api',
+                servers: parseServers(options.server),
+            };
+            // Generate spec
+            if (!options.quiet) {
+                console.log(pc.dim('Generating OpenAPI specification...'));
+            }
+            const spec = generateOpenApiSpec(discovery.collections, openApiOptions);
+            // Validate if requested
+            const warnings = [];
+            if (options.validate !== false) {
+                const validationWarnings = validateOpenApiSpec(spec);
+                warnings.push(...validationWarnings);
+            }
+            // Add discovery warnings
+            warnings.push(...discovery.warnings.map((w) => `${w.filePath}: ${w.message}`));
+            // Write output
+            await ensureDir(outputPath);
+            const jsonContent = options.pretty !== false ? JSON.stringify(spec, null, 2) : JSON.stringify(spec);
+            writeFileSync(outputPath, jsonContent, 'utf-8');
+            // Print success message
+            printSuccess(outputPath, spec, warnings, options.quiet ?? false);
+            // Exit explicitly - dynamic imports may keep event loop running
+            process.exit(0);
+        }
+        catch (error) {
+            if (isDiscoveryError(error)) {
+                console.error(pc.red(error.format()));
+                process.exit(1);
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * Collect multiple option values into array
+ */
+function collectOption(value, previous = []) {
+    return [...previous, value];
+}
+/**
+ * Create the openapi:serve command (placeholder for future Swagger UI serving)
+ */
+function createServeCommand() {
+    return new Command('serve')
+        .description('Start a local Swagger UI server (coming soon)')
+        .option('-f, --file <file>', 'OpenAPI spec file', './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);
+    });
+}
+/**
+ * Create the openapi command with subcommands
+ */
+export function createOpenApiCommand() {
+    const openapi = new Command('openapi')
+        .description('OpenAPI specification generation and management')
+        .addCommand(createGenerateCommand())
+        .addCommand(createServeCommand());
+    return openapi;
+}

package/package.json

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