refactor(tbk): update OpenAPI and SDK generation commands

muneebhashone · muneebhashone · commit 6b1a903966bb · 2025-11-02T01:24:01.000+05:00
- Replaced `pnpm openapi` and `pnpm gen-sdk` commands with `pnpm tbk docs:openapi` and `pnpm tbk docs:sdk` for better organization.
- Removed deprecated scripts for OpenAPI and seeding, consolidating functionality within the `@tbk/cli`.
- Updated documentation across multiple files to reflect the new command structure and usage.
- Added new actions for generating OpenAPI specifications and TypeScript SDKs within the CLI tool.
diff --git a/AGENTS.md b/AGENTS.md
@@ -14,7 +14,7 @@
 - `pnpm build` — compile TypeScript via `tsup` to `dist/`.
 - `pnpm start` | `pnpm start:dev|:prod|:local` — run compiled or env-specific entry via `dotenv-cli`.
 - `pnpm typecheck` — strict type checks without emit. `pnpm lint` | `pnpm lint:fix` — ESLint with Prettier.
-- Useful: `pnpm openapi` (generate spec), `pnpm seed` (dev seed), `pnpm email:dev` (preview emails).
+- Useful: `pnpm tbk docs:openapi` (generate spec), `pnpm tbk seed` (dev seed), `pnpm email:dev` (preview emails).
 
 ## Coding Style & Naming Conventions
 
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -35,8 +35,12 @@ pnpm tbk seed                                       # Run database seeders
 
 ### OpenAPI Documentation
 ```bash
-pnpm openapi             # Generate OpenAPI spec (public/openapi.yml)
-pnpm gen-sdk             # Generate TypeScript SDK from OpenAPI spec
+pnpm tbk docs:openapi    # Generate OpenAPI spec (public/openapi.yml)
+pnpm tbk docs:sdk        # Generate TypeScript SDK from OpenAPI spec
+
+# Or use convenience aliases:
+pnpm openapi             # Alias for tbk docs:openapi
+pnpm gen-sdk             # Alias for tbk docs:sdk
 ```
 
 Visit `http://localhost:3000/docs` for live Swagger UI.
diff --git a/README.md b/README.md
@@ -154,9 +154,10 @@ pnpm lint             # ESLint + Prettier
 pnpm tbk g:module <name>   # Generate complete module
 pnpm tbk g:plugin <name>   # Generate plugin
 pnpm tbk seed              # Run database seeders
+pnpm tbk docs:openapi      # Generate OpenAPI spec
+pnpm tbk docs:sdk          # Generate TypeScript SDK
 
-# Documentation
-pnpm openapi          # Generate OpenAPI spec
+# Other Tools
 pnpm email:dev        # Preview email templates
 ```
 
diff --git a/package.json b/package.json
@@ -12,11 +12,8 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
-    "openapi": "dotenv -e .env.development -- tsx scripts/gen-openapi.ts",
-    "seed": "dotenv -e .env.development -- tsx scripts/seed.ts",
     "email:dev": "email dev --dir ./src/email/templates",
-    "tbk": "dotenv -e .env.development -- @tbk/cli",
-    "gen-sdk": "npx swagger-typescript-api generate --path ./public/openapi.yml --output ./src/generated"
+    "tbk": "tbk"
   },
   "devDependencies": {
     "@eslint/js": "^9.4.0",
diff --git a/packages/create-tbk-app/README.md b/packages/create-tbk-app/README.md
@@ -220,7 +220,8 @@ pnpm build            # Build for production
 pnpm start:prod       # Run production build
 pnpm typecheck        # Type check without building
 pnpm lint             # Run ESLint
-pnpm openapi          # Generate OpenAPI spec
+pnpm tbk docs:openapi # Generate OpenAPI spec
+pnpm tbk docs:sdk     # Generate TypeScript SDK
 
 # CLI tool (module generation)
 pnpm tbk generate:module <name>        # Generate CRUD module
diff --git a/packages/create-tbk-app/TEMPLATE_EXTRACTION.md b/packages/create-tbk-app/TEMPLATE_EXTRACTION.md
@@ -403,12 +403,12 @@ templates/base/src/middlewares/can-access.ts
 
 #### 6.1 Scripts
 ```bash
-# Always copy
-templates/base/scripts/gen-openapi.ts
+# Note: gen-openapi.ts is now part of the tbk CLI (tbk docs:openapi)
+# No standalone scripts needed unless custom functionality is required
 
-# Only if AUTH (for seeding)
+# Only if AUTH (for seeding - deprecated, use tbk seed instead)
 {{#if AUTH}}
-templates/base/scripts/seed.ts
+templates/base/scripts/seed.ts (DEPRECATED - use tbk seed)
 {{/if}}
 ```
 
diff --git a/packages/create-tbk-app/src/constants/dependencies.ts b/packages/create-tbk-app/src/constants/dependencies.ts
@@ -18,6 +18,7 @@ export const CORE_DEPENDENCIES = {
 };
 
 export const CORE_DEV_DEPENDENCIES = {
+  '@tbk/cli': '^0.0.1',
   typescript: '^5.1.6',
   '@types/express': '^4.17.15',
   '@types/node': '^18.11.18',
@@ -156,7 +157,10 @@ export function resolveDependencies(config: ProjectConfig): {
   // Helper to merge feature dependencies
   const addFeature = (feature: keyof typeof FEATURE_DEPENDENCIES) => {
     Object.assign(dependencies, FEATURE_DEPENDENCIES[feature].dependencies);
-    Object.assign(devDependencies, FEATURE_DEPENDENCIES[feature].devDependencies);
+    Object.assign(
+      devDependencies,
+      FEATURE_DEPENDENCIES[feature].devDependencies,
+    );
   };
 
   // Security plugin (always included for standard and full presets)
@@ -231,19 +235,18 @@ export function resolveDependencies(config: ProjectConfig): {
 
 export function generateScripts(config: ProjectConfig): Record<string, string> {
   const scripts: Record<string, string> = {
-    dev: config.email !== 'none'
-      ? 'concurrently "pnpm start:dev" "pnpm email:dev"'
-      : 'pnpm start:dev',
+    dev:
+      config.email !== 'none'
+        ? 'concurrently "pnpm start:dev" "pnpm email:dev"'
+        : 'pnpm start:dev',
     'start:dev': 'dotenv -e .env.development -- tsx --watch ./src/main.ts',
     build: 'tsup --config build.ts',
     'start:prod': 'dotenv -e .env.production -- node ./dist/main.js',
     'start:local': 'dotenv -e .env.local -- node ./dist/main.js',
     typecheck: 'tsc --noEmit',
     lint: 'eslint',
     'lint:fix': 'eslint --fix',
-    openapi: 'dotenv -e .env.development -- tsx scripts/gen-openapi.ts',
-    tbk: 'dotenv -e .env.development -- tsx bin/tbk',
-    'gen-sdk': 'npx swagger-typescript-api generate --path ./public/openapi.yml --output ./src/generated',
+    tbk: 'tbk',
   };
 
   // Add email dev script if email is enabled
diff --git a/packages/create-tbk-app/templates/base/AGENTS.md b/packages/create-tbk-app/templates/base/AGENTS.md
@@ -14,7 +14,7 @@
 - `pnpm build` — compile TypeScript via `tsup` to `dist/`.
 - `pnpm start` | `pnpm start:dev|:prod|:local` — run compiled or env-specific entry via `dotenv-cli`.
 - `pnpm typecheck` — strict type checks without emit. `pnpm lint` | `pnpm lint:fix` — ESLint with Prettier.
-- Useful: `pnpm openapi` (generate spec), `pnpm seed` (dev seed), `pnpm email:dev` (preview emails).
+- Useful: `pnpm tbk docs:openapi` (generate spec), `pnpm tbk seed` (dev seed), `pnpm email:dev` (preview emails).
 
 ## Coding Style & Naming Conventions
 
diff --git a/packages/create-tbk-app/templates/base/CLAUDE.md b/packages/create-tbk-app/templates/base/CLAUDE.md
@@ -35,8 +35,12 @@ pnpm tbk seed                                       # Run database seeders
 
 ### OpenAPI Documentation
 ```bash
-pnpm openapi             # Generate OpenAPI spec (public/openapi.yml)
-pnpm gen-sdk             # Generate TypeScript SDK from OpenAPI spec
+pnpm tbk docs:openapi    # Generate OpenAPI spec (public/openapi.yml)
+pnpm tbk docs:sdk        # Generate TypeScript SDK from OpenAPI spec
+
+# Or use convenience aliases:
+pnpm openapi             # Alias for tbk docs:openapi
+pnpm gen-sdk             # Alias for tbk docs:sdk
 ```
 
 Visit `http://localhost:3000/docs` for live Swagger UI.
diff --git a/packages/tbk/package.json b/packages/tbk/package.json
@@ -38,7 +38,9 @@
   },
   "license": "MIT",
   "dependencies": {
-    "commander": "^14.0.1"
+    "commander": "^14.0.1",
+    "dotenv": "^16.4.5",
+    "execa": "^9.5.2"
   },
   "devDependencies": {
     "@types/node": "^18.11.18",
diff --git a/packages/tbk/src/actions/genSdk.ts b/packages/tbk/src/actions/genSdk.ts
@@ -0,0 +1,35 @@
+import { execa } from 'execa';
+import path from 'path';
+
+export const createGenSdkAction = async () => {
+  try {
+    console.log('Generating TypeScript SDK from OpenAPI spec...');
+
+    const projectRoot = process.cwd();
+    const openapiPath = path.join(projectRoot, 'public', 'openapi.yml');
+    const outputPath = path.join(projectRoot, 'src', 'generated');
+
+    // Run swagger-typescript-api generate
+    await execa(
+      'npx',
+      [
+        'swagger-typescript-api',
+        'generate',
+        '--path',
+        openapiPath,
+        '--output',
+        outputPath,
+      ],
+      {
+        stdio: 'inherit',
+      },
+    );
+
+    console.log('✓ TypeScript SDK generated successfully at:', outputPath);
+
+    process.exit(0);
+  } catch (error) {
+    console.error('Failed to generate SDK:', error);
+    process.exit(1);
+  }
+};
diff --git a/packages/tbk/src/actions/openapi.ts b/packages/tbk/src/actions/openapi.ts
@@ -0,0 +1,75 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import dotenv from 'dotenv';
+
+export const createOpenApiAction = async (opts: { env?: string }) => {
+  try {
+    // Load environment file if specified
+    const envFile = opts.env || '.env.development';
+    const envPath = path.join(process.cwd(), envFile);
+
+    try {
+      const result = dotenv.config({ path: envPath });
+      if (result.error) {
+        console.warn(`⚠ Could not load ${envFile}, continuing without it...`);
+      } else {
+        console.log(`✓ Loaded environment from ${envFile}`);
+      }
+    } catch (error) {
+      console.warn(`⚠ Could not load ${envFile}, continuing without it...`);
+    }
+
+    console.log('Generating OpenAPI specification...');
+
+    const projectRoot = process.cwd();
+
+    // Import zod-extend to register OpenAPI extensions
+    const zodExtendPath = path.join(
+      projectRoot,
+      'src',
+      'plugins',
+      'magic',
+      'zod-extend.ts',
+    );
+    await import(pathToFileURL(zodExtendPath).href);
+
+    // Import routes to register all endpoints
+    const routesPath = path.join(projectRoot, 'src', 'routes', 'routes.ts');
+    await import(pathToFileURL(routesPath).href);
+
+    // Import swagger doc generator
+    const swaggerGenPath = path.join(
+      projectRoot,
+      'src',
+      'plugins',
+      'magic',
+      'swagger-doc-generator.ts',
+    );
+    const swaggerModule = await import(pathToFileURL(swaggerGenPath).href);
+
+    const { convertDocumentationToYaml } = swaggerModule;
+
+    if (!convertDocumentationToYaml) {
+      throw new Error(
+        'Could not find convertDocumentationToYaml. Make sure src/plugins/magic/swagger-doc-generator.ts exists.',
+      );
+    }
+
+    const yamlContent = convertDocumentationToYaml(
+      "Robust backend boilerplate designed for scalability, flexibility, and ease of development. It's packed with modern technologies and best practices to kickstart your next backend project",
+      [{ url: '/api' }],
+    );
+
+    const outputPath = path.join(projectRoot, 'public', 'openapi.yml');
+    await fs.writeFile(outputPath, yamlContent, 'utf-8');
+
+    console.log(`✓ OpenAPI spec generated successfully at: ${outputPath}`);
+
+    process.exit(0);
+  } catch (error) {
+    console.error('Failed to generate OpenAPI spec:', error);
+    process.exit(1);
+  }
+};
+
diff --git a/packages/tbk/src/cli.ts b/packages/tbk/src/cli.ts
@@ -7,6 +7,8 @@ import { createModuleAction } from './actions/module.js';
 import { createSeedAction } from './actions/seed.js';
 import { createMakeSeederAction } from './actions/makeSeeder.js';
 import { createMakeFactoryAction } from './actions/makeFactory.js';
+import { createOpenApiAction } from './actions/openapi.js';
+import { createGenSdkAction } from './actions/genSdk.js';
 
 const program = new Command();
 
@@ -75,4 +77,18 @@ program
   .option('--id-type <string|objectId>', 'Hint for _id type when ambiguous')
   .action(createMakeFactoryAction);
 
+// Documentation commands
+program
+  .command('docs:openapi')
+  .alias('d:openapi')
+  .description('Generate OpenAPI specification from routes')
+  .option('--env <file>', 'Environment file to load', '.env.development')
+  .action(createOpenApiAction);
+
+program
+  .command('docs:sdk')
+  .alias('d:sdk')
+  .description('Generate TypeScript SDK from OpenAPI spec')
+  .action(createGenSdkAction);
+
 program.parse();
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/scripts/gen-openapi.ts b/scripts/gen-openapi.ts
diff --git a/scripts/seed.ts b/scripts/seed.ts
