typescript-express-starter 10.2.1 → 11.0.0

package/bin/ast-utils.js

@@ -0,0 +1,226 @@
+/**
+ * AST manipulation utilities for Swagger injection
+ */
+
+import { Project, QuoteKind } from 'ts-morph';
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+import { ProjectGenerationError, withErrorHandling } from './errors.js';
+
+/**
+ * Main Swagger injection function with proper error handling
+ */
+export async function injectSwaggerIntoApp(destDir) {
+  const appPath = path.join(destDir, 'src', 'app.ts');
+
+  if (!(await fs.pathExists(appPath))) {
+    console.log(chalk.yellow(`[inject-swagger] skip: ${appPath} not found`));
+    return;
+  }
+
+  return withErrorHandling(async () => {
+    const project = createProject();
+    const source = project.addSourceFileAtPath(appPath);
+
+    await addSwaggerImports(source);
+    await updateEnvImports(source);
+    await addSwaggerMethod(source);
+    await updateConstructor(source);
+
+    source.formatText({ indentSize: 2, convertTabsToSpaces: true });
+    await source.save();
+    console.log(chalk.green('[inject-swagger] Successfully updated app.ts'));
+  }, 'Swagger injection failed')();
+}
+
+/**
+ * Create TypeScript project instance
+ */
+function createProject() {
+  return new Project({
+    manipulationSettings: { quoteKind: QuoteKind.Single },
+    skipAddingFilesFromTsConfig: true,
+  });
+}
+
+/**
+ * Add Swagger-related imports
+ */
+async function addSwaggerImports(source) {
+  const importDecls = source.getImportDeclarations();
+  const findImport = (mod) => importDecls.find((d) => d.getModuleSpecifierValue() === mod);
+  const morganImport = findImport('morgan');
+
+  // Remove existing swagger imports for repositioning
+  const swaggerJSDocImport = findImport('swagger-jsdoc');
+  const swaggerUiImport = findImport('swagger-ui-express');
+  if (swaggerJSDocImport) swaggerJSDocImport.remove();
+  if (swaggerUiImport) swaggerUiImport.remove();
+
+  // Calculate insertion index after morgan
+  const afterMorganIndex = morganImport
+    ? importDecls.indexOf(morganImport) + 1
+    : importDecls.length;
+
+  // Insert swagger imports
+  source.insertImportDeclaration(afterMorganIndex, {
+    defaultImport: 'swaggerJSDoc',
+    moduleSpecifier: 'swagger-jsdoc',
+  });
+
+  source.insertImportDeclaration(afterMorganIndex + 1, {
+    defaultImport: 'swaggerUi',
+    moduleSpecifier: 'swagger-ui-express',
+  });
+}
+
+/**
+ * Update environment imports to include API_SERVER_URL
+ */
+async function updateEnvImports(source) {
+  const envImport = source
+    .getImportDeclarations()
+    .find((d) => d.getModuleSpecifierValue() === '@config/env');
+
+  if (!envImport) {
+    console.log(chalk.yellow('[inject-swagger] Warning: @config/env import not found'));
+    return;
+  }
+
+  // Skip if namespace import
+  if (envImport.getNamespaceImport()) return;
+
+  // Check if API_SERVER_URL is already imported
+  const hasNamed = envImport.getNamedImports().some((n) => n.getName() === 'API_SERVER_URL');
+
+  if (!hasNamed) {
+    envImport.addNamedImport('API_SERVER_URL');
+  }
+}
+
+/**
+ * Add initializeSwagger method to App class
+ */
+async function addSwaggerMethod(source) {
+  const appClass = source.getClass('App') || source.getClasses()[0];
+
+  if (!appClass) {
+    throw new ProjectGenerationError('No App class found in app.ts', 'swagger-injection');
+  }
+
+  // Check if method already exists
+  let initMethod = appClass.getInstanceMethod('initializeSwagger');
+  if (initMethod) {
+    console.log(chalk.yellow('[inject-swagger] initializeSwagger method already exists, skipping'));
+    return;
+  }
+
+  const errorMethod = appClass.getInstanceMethod('initializeErrorHandling');
+  const insertIndex = errorMethod ? errorMethod.getChildIndex() : undefined;
+
+  const methodStructure = {
+    name: 'initializeSwagger',
+    scope: 'private',
+    parameters: [{ name: 'apiPrefix', type: 'string' }],
+    statements: generateSwaggerMethodBody(),
+  };
+
+  if (insertIndex !== undefined) {
+    appClass.insertMethod(insertIndex, methodStructure);
+  } else {
+    appClass.addMethod(methodStructure);
+  }
+}
+
+/**
+ * Generate the body of the initializeSwagger method
+ */
+function generateSwaggerMethodBody() {
+  return (writer) => {
+    writer.writeLine('const options = {');
+    writer.indent(() => {
+      writer.writeLine('swaggerDefinition: {');
+      writer.indent(() => {
+        writer.writeLine(`openapi: '3.0.0',`);
+        writer.writeLine('info: {');
+        writer.indent(() => {
+          writer.writeLine(`title: 'REST API',`);
+          writer.writeLine(`version: '1.0.0',`);
+          writer.writeLine(`description: 'Example API Documentation',`);
+        });
+        writer.writeLine('},');
+        writer.writeLine('servers: [');
+        writer.indent(() => {
+          writer.writeLine('{');
+          writer.indent(() => {
+            writer.writeLine(
+              `url: API_SERVER_URL || \`http://localhost:\${this.port}\${apiPrefix}\`,`,
+            );
+            writer.writeLine(
+              `description: this.env === 'production' ? 'Production server' : 'Local server',`,
+            );
+          });
+          writer.writeLine('},');
+        });
+        writer.writeLine('],');
+        writer.writeLine('components: {');
+        writer.indent(() => {
+          writer.writeLine('securitySchemes: {');
+          writer.indent(() => {
+            writer.writeLine('bearerAuth: {');
+            writer.indent(() => {
+              writer.writeLine(`type: 'http',`);
+              writer.writeLine(`scheme: 'bearer',`);
+              writer.writeLine(`bearerFormat: 'JWT',`);
+            });
+            writer.writeLine('},');
+          });
+          writer.writeLine('},');
+        });
+        writer.writeLine('},');
+      });
+      writer.writeLine('},');
+      writer.writeLine("apis: ['swagger.yaml', 'src/controllers/*.ts'],");
+    });
+    writer.writeLine('};');
+    writer.blankLine();
+    writer.writeLine('const specs = swaggerJSDoc(options);');
+    writer.writeLine(`this.app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));`);
+  };
+}
+
+/**
+ * Update constructor to call initializeSwagger
+ */
+async function updateConstructor(source) {
+  const appClass = source.getClass('App') || source.getClasses()[0];
+  if (!appClass) return;
+
+  const constructor = appClass.getConstructors()[0];
+  if (!constructor) {
+    console.log(chalk.yellow('[inject-swagger] Warning: No constructor found'));
+    return;
+  }
+
+  const bodyText = constructor.getBodyText();
+  if (bodyText.includes('this.initializeSwagger')) {
+    console.log(chalk.yellow('[inject-swagger] Constructor already calls initializeSwagger'));
+    return;
+  }
+
+  // Find initializeErrorHandling call and insert before it
+  const statements = constructor.getBody().getStatements();
+  const errorHandlingIndex = statements.findIndex((stmt) =>
+    stmt.getText().includes('this.initializeErrorHandling'),
+  );
+
+  if (errorHandlingIndex !== -1) {
+    constructor.insertStatements(errorHandlingIndex, 'this.initializeSwagger(apiPrefix);');
+    console.log(chalk.green('[inject-swagger] Added initializeSwagger call to constructor'));
+  } else {
+    // Fallback: append to end of constructor
+    constructor.addStatements('this.initializeSwagger(apiPrefix);');
+    console.log(chalk.green('[inject-swagger] Added initializeSwagger call at end of constructor'));
+  }
+}

package/bin/common.js

@@ -0,0 +1,312 @@
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+export const PACKAGE_MANAGER = [
+  { label: 'npm', value: 'npm' },
+  { label: 'pnpm', value: 'pnpm' },
+  { label: 'yarn', value: 'yarn' },
+];
+
+export const TEMPLATES_VALUES = [
+  {
+    name: 'Default',
+    value: 'default',
+    desc: 'Basic Express + TypeScript project',
+    active: true,
+    tags: ['express', 'typescript', 'starter'],
+    version: 'v1.0.0',
+    maintainer: 'core',
+    lastUpdated: '2025-08-27',
+  },
+  {
+    name: 'GraphQL',
+    value: 'graphql',
+    desc: 'GraphQL API template based on Apollo Server',
+    active: false,
+    tags: ['graphql', 'apollo', 'api'],
+    version: 'v1.2.0',
+    maintainer: 'core',
+    lastUpdated: '2025-08-10',
+  },
+  {
+    name: 'Knex',
+    value: 'knex',
+    desc: 'SQL query builder template using Knex.js',
+    active: false,
+    tags: ['sql', 'knex', 'database'],
+    version: 'v0.95.x',
+    maintainer: 'db-team',
+    lastUpdated: '2025-07-30',
+  },
+  {
+    name: 'Mikro-ORM',
+    value: 'mikro-orm',
+    desc: 'TypeScript ORM template based on Mikro-ORM',
+    active: false,
+    tags: ['orm', 'typescript', 'database'],
+    version: 'v6.x',
+    maintainer: 'orm-team',
+    lastUpdated: '2025-07-25',
+  },
+  {
+    name: 'Mongoose',
+    value: 'mongoose',
+    desc: 'MongoDB ODM template using Mongoose',
+    active: false,
+    tags: ['mongodb', 'odm', 'database'],
+    version: 'v7.x',
+    maintainer: 'nosql-team',
+    lastUpdated: '2025-08-01',
+  },
+  {
+    name: 'Node-Postgres',
+    value: 'node-postgres',
+    desc: 'PostgreSQL template using pg library',
+    active: false,
+    tags: ['postgres', 'sql', 'database'],
+    version: 'v8.x',
+    maintainer: 'db-team',
+    lastUpdated: '2025-07-20',
+  },
+  {
+    name: 'Prisma',
+    value: 'prisma',
+    desc: 'SQL/NoSQL ORM template based on Prisma',
+    active: false,
+    tags: ['orm', 'prisma', 'database'],
+    version: 'v5.x',
+    maintainer: 'orm-team',
+    lastUpdated: '2025-08-05',
+  },
+  {
+    name: 'Routing-Controllers',
+    value: 'routing-controllers',
+    desc: 'Express controller structure with TypeScript decorators',
+    active: false,
+    tags: ['decorator', 'controller', 'express'],
+    version: 'v0.10.x',
+    maintainer: 'core',
+    lastUpdated: '2025-07-15',
+  },
+  {
+    name: 'Sequelize',
+    value: 'sequelize',
+    desc: 'SQL ORM template based on Sequelize',
+    active: false,
+    tags: ['orm', 'sequelize', 'database'],
+    version: 'v6.x',
+    maintainer: 'orm-team',
+    lastUpdated: '2025-07-28',
+  },
+  {
+    name: 'Typegoose',
+    value: 'typegoose',
+    desc: 'TypeScript-friendly MongoDB ODM using Typegoose',
+    active: false,
+    tags: ['mongodb', 'typegoose', 'odm'],
+    version: 'v11.x',
+    maintainer: 'nosql-team',
+    lastUpdated: '2025-08-08',
+  },
+  {
+    name: 'TypeORM',
+    value: 'typeorm',
+    desc: 'SQL/NoSQL ORM template based on TypeORM',
+    active: false,
+    tags: ['orm', 'typeorm', 'database'],
+    version: 'v0.3.x',
+    maintainer: 'orm-team',
+    lastUpdated: '2025-07-18',
+  },
+];
+
+export const DEVTOOLS_VALUES = [
+  // == [Linter] == //
+  {
+    name: 'Biome',
+    value: 'biome',
+    category: 'Linter',
+    files: ['.biome.json', '.biomeignore'],
+    pkgs: [],
+    devPkgs: ['@biomejs/biome@2.1.4'],
+    scripts: {
+      lint: 'biome lint .',
+      check: 'biome check .',
+      format: 'biome format . --write',
+    },
+    desc: 'All-in-one formatter and linter',
+  },
+  {
+    name: 'ESLint & Prettier',
+    value: 'eslint',
+    category: 'Linter',
+    files: ['.prettierrc', 'eslint.config.cjs'],
+    pkgs: [],
+    devPkgs: [
+      'eslint@^9.33.0',
+      'eslint-config-prettier@^10.1.1',
+      'globals@^15.10.0',
+      'prettier@3.6.2',
+      'typescript-eslint@^8.39.0',
+    ],
+    scripts: {
+      lint: 'eslint --ext .ts src/',
+      'lint:fix': 'npm run lint -- --fix',
+      format: 'prettier --check .',
+      'format:fix': 'prettier --write .',
+    },
+    desc: 'Separate formatter and linter setup',
+  },
+  {
+    name: 'Oxlint',
+    value: 'oxlint',
+    category: 'Linter',
+    files: ['.oxlintrc.json', '.prettierrc'],
+    pkgs: [],
+    devPkgs: ['oxlint@^1.14.0', '@oxlint/migrate@^1.14.0', 'prettier@3.6.2'],
+    scripts: {
+      lint: 'oxlint .',
+      'lint:fix': 'oxlint . --fix',
+      format: 'prettier --check .',
+      'format:fix': 'prettier --write .',
+    },
+    desc: 'Ultra-fast Rust linter for JS/TS',
+  },
+
+  // == [Compiler] == //
+  {
+    name: 'tsup',
+    value: 'tsup',
+    category: 'Compiler',
+    files: ['tsup.config.ts'],
+    pkgs: [],
+    devPkgs: ['tsup@8.5.0'],
+    scripts: {
+      'start:tsup': 'node -r tsconfig-paths/register dist/server.js',
+      'build:tsup': 'tsup --config tsup.config.ts',
+    },
+    desc: 'Fast bundler for TypeScript',
+  },
+  {
+    name: 'SWC',
+    value: 'swc',
+    category: 'Compiler',
+    files: ['.swcrc'],
+    pkgs: [],
+    devPkgs: ['@swc/cli@0.7.8', '@swc/core@1.13.3'],
+    scripts: {
+      'start:swc': 'node dist/server.js',
+      'build:swc': 'swc src -d dist --strip-leading-paths --copy-files --delete-dir-on-start',
+    },
+    desc: 'Rust-based TypeScript compiler',
+  },
+
+  // == [Testing] == //
+  {
+    name: 'Jest',
+    value: 'jest',
+    category: 'Testing',
+    files: ['jest.config.cjs', 'jest.config.ts'],
+    pkgs: [],
+    devPkgs: [
+      '@types/supertest@6.0.3',
+      'supertest@7.1.4',
+      '@types/jest@30.0.0',
+      'jest@30.0.5',
+      'ts-jest@29.4.1',
+      'ts-node@10.9.2',
+    ],
+    scripts: {
+      test: 'jest --config jest.config.cjs --watch',
+      'test:e2e': 'jest --config jest.config.cjs --testPathPatterns=e2e --watch',
+      'test:unit': 'jest --config jest.config.cjs --testPathPatterns=unit --watch',
+    },
+    desc: 'Industry-standard test runner for Node.js',
+  },
+  {
+    name: 'Vitest',
+    value: 'vitest',
+    category: 'Testing',
+    files: ['vitest.config.ts'],
+    pkgs: [],
+    devPkgs: [
+      '@types/supertest@6.0.3',
+      'supertest@7.1.4',
+      'vite-tsconfig-paths@5.1.4',
+      'vitest@3.2.4',
+    ],
+    scripts: {
+      test: 'vitest',
+      'test:unit': 'vitest src/test/unit',
+      'test:e2e': 'vitest src/test/e2e',
+      'test:ci': 'vitest run --coverage',
+      'test:ci:unit': 'vitest run src/test/unit --coverage',
+      'test:ci:e2e': 'vitest run src/test/e2e --coverage',
+    },
+    desc: 'Fast Vite-powered unit/e2e test framework',
+  },
+
+  // == [API development] == //
+  {
+    name: 'Swagger',
+    value: 'swagger',
+    category: 'API development',
+    files: ['swagger.yaml'],
+    pkgs: ['swagger-jsdoc@^6.2.8', 'swagger-ui-express@^5.0.1'],
+    devPkgs: ['@types/swagger-jsdoc@^6.0.4', '@types/swagger-ui-express@^4.1.8'],
+    scripts: {},
+    desc: 'Simplify your API development with our open-source and professional tools',
+  },
+
+  // == [Infrastructure] == //
+  {
+    name: 'Docker',
+    value: 'docker',
+    category: 'Infrastructure',
+    files: ['.dockerignore', 'Dockerfile.dev', 'Dockerfile.prod', 'nginx.conf', 'Makefile'],
+    pkgs: [],
+    devPkgs: [],
+    scripts: {},
+    desc: 'Containerized dev & prod environment',
+  },
+
+  // == [Git Tools] == //
+  {
+    name: 'Husky',
+    value: 'husky',
+    category: 'Git Tools',
+    files: ['.husky'],
+    pkgs: [],
+    devPkgs: ['husky'],
+    scripts: { prepare: 'husky install' },
+    requires: [],
+    desc: 'Git hooks for automation',
+  },
+
+  // == [Deployment] == //
+  {
+    name: 'PM2',
+    value: 'pm2',
+    category: 'Deployment',
+    files: ['ecosystem.config.js'],
+    pkgs: ['pm2'],
+    devPkgs: [],
+    scripts: {
+      'deploy:prod': 'pm2 start ecosystem.config.js --only prod',
+      'deploy:dev': 'pm2 start ecosystem.config.js --only dev',
+    },
+    desc: 'Process manager for Node.js',
+  },
+
+  // == [CI/CD] == //
+  {
+    name: 'GitHub Actions',
+    value: 'github',
+    category: 'CI/CD',
+    files: ['.github/workflows/ci.yml'],
+    pkgs: [],
+    devPkgs: [],
+    scripts: {},
+    desc: 'CI/CD workflow automation',
+  },
+];

package/bin/config.js

@@ -0,0 +1,80 @@
+/**
+ * Configuration constants and settings for the CLI
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export const CONFIG = {
+  // Version and compatibility
+  minNodeVersion: 16,
+
+  // Default values
+  defaultProjectName: 'my-app',
+  maxProjectNameLength: 50,
+
+  // Network settings
+  registryUrl: 'https://registry.npmjs.org/',
+  timeout: {
+    packageInstall: 30000,
+    versionCheck: 5000,
+    networkRequest: 10000,
+  },
+
+  // File paths
+  paths: {
+    templates: path.join(__dirname, '../templates'),
+    devtools: path.join(__dirname, '../devtools'),
+  },
+
+  // Validation patterns
+  validation: {
+    projectName: /^[a-zA-Z0-9-_]+$/,
+    packageName: /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/,
+    version: /^\d+\.\d+\.\d+(-[a-zA-Z0-9]+)?$/,
+  },
+
+  // UI settings
+  ui: {
+    spinnerInterval: 100,
+    maxRetries: 3,
+  },
+
+  // Banner configuration
+  banner: {
+    gradient:
+      '\x1B[38;2;91;192;222m📘\x1B[39m\x1B[38;2;91;192;222m \x1B[39m\x1B[38;2;91;192;222mT\x1B[39m\x1B[38;2;82;175;222my\x1B[39m\x1B[38;2;74;159;222mp\x1B[39m\x1B[38;2;66;143;210me\x1B[39m\x1B[38;2;58;128;198mS\x1B[39m\x1B[38;2;54;124;190mc\x1B[39m\x1B[38;2;52;118;180mr\x1B[39m\x1B[38;2;50;115;172mi\x1B[39m\x1B[38;2;49;120;198mp\x1B[39m\x1B[38;2;47;110;168mt\x1B[39m\x1B[38;2;45;105;160m \x1B[39m\x1B[38;2;43;100;152mE\x1B[39m\x1B[38;2;41;95;144mx\x1B[39m\x1B[38;2;39;90;136mp\x1B[39m\x1B[38;2;37;85;128mr\x1B[39m\x1B[38;2;35;80;120me\x1B[39m\x1B[38;2;33;75;112ms\x1B[39m\x1B[38;2;30;72;106ms\x1B[39m\x1B[38;2;28;70;100m \x1B[39m\x1B[38;2;26;68;96mS\x1B[39m\x1B[38;2;25;68;94mt\x1B[39m\x1B[38;2;25;69;92ma\x1B[39m\x1B[38;2;25;70;91mr\x1B[39m\x1B[38;2;25;70;150mt\x1B[39m\x1B[38;2;25;70;150me\x1B[39m\x1B[38;2;25;70;150mr\x1B[39m',
+  },
+};
+
+/**
+ * Environment-specific configuration
+ */
+export const getEnvironmentConfig = () => {
+  const env = process.env.NODE_ENV || 'production';
+
+  const envConfigs = {
+    development: {
+      verbose: true,
+      dryRun: false,
+      skipVersionCheck: false,
+    },
+    test: {
+      verbose: false,
+      dryRun: true,
+      skipVersionCheck: true,
+    },
+    production: {
+      verbose: false,
+      dryRun: false,
+      skipVersionCheck: false,
+    },
+  };
+
+  return {
+    ...CONFIG,
+    env: envConfigs[env] || envConfigs.production,
+  };
+};