typescript-express-starter 10.2.1 → 11.0.0

package/bin/starter.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+
+/*****************************************************************
+ * TYPESCRIPT-EXPRESS-STARTER - Quick and Easy TypeScript Express Starter
+ * (c) 2020-present AGUMON (https://github.com/ljlm0402/typescript-express-starter)
+ *
+ * MIT License
+ *
+ * Made with ❤️ by AGUMON 🦖
+ *****************************************************************/
+
+import { select, text, isCancel, intro, outro, cancel, note, confirm } from '@clack/prompts';
+import chalk from 'chalk';
+import editJsonFile from 'edit-json-file';
+import { execa } from 'execa';
+import fs from 'fs-extra';
+import ora from 'ora';
+import path from 'path';
+
+// Config and constants
+import { CONFIG, getEnvironmentConfig } from './config.js';
+import { PACKAGE_MANAGER, TEMPLATES_VALUES, DEVTOOLS_VALUES } from './common.js';
+
+// Database configuration
+import { TEMPLATE_DB, generateDockerCompose } from './db-map.js';
+
+// Error handling
+import { CLIError, NetworkError, FileSystemError, printError } from './errors.js';
+
+// Validation utilities
+import {
+  validateProjectName,
+  validateProjectPath,
+  sanitizeInput,
+  validateNodeVersion,
+} from './validators.js';
+
+// Performance optimizations
+import { versionCache, PackageBatch } from './performance.js';
+
+// AST utilities
+import { injectSwaggerIntoApp } from './ast-utils.js';
+
+// ========== [공통 함수들] ==========
+
+// 최신 CLI 버전 체크 & 선택적 설치
+async function checkForUpdate() {
+  try {
+    const pkgPath = path.resolve(process.cwd(), 'package.json');
+    const localPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const pkgName = localPkg.name || 'typescript-express-stater';
+    const localVersion = localPkg.version || '0.0.0';
+
+    const latest = await versionCache.getLatestVersion(pkgName);
+    if (latest > localVersion) {
+      console.log(
+        chalk.yellow(`🔔  New version available: ${latest} (You are on ${localVersion})`),
+      );
+      const shouldUpdate = await confirm({
+        message: `Do you want to update ${pkgName} to version ${latest}?`,
+        initial: true,
+      });
+      if (shouldUpdate) {
+        console.log(chalk.gray(`  Updating to latest version...`));
+        try {
+          await execa('npm', ['install', '-g', `${pkgName}@${latest}`], { stdio: 'inherit' });
+          console.log(chalk.green(`  ✓ Updated ${pkgName} to ${latest}`));
+        } catch (err) {
+          printError(new NetworkError(`Failed to update ${pkgName}`, 'update', err.message));
+        }
+      } else {
+        console.log(chalk.gray('Skipped updating.'));
+      }
+    }
+  } catch (err) {
+    printError(new NetworkError('Failed to check latest version', 'version-check', err.message));
+  }
+}
+
+// 패키지매니저 글로벌 설치여부
+async function checkPkgManagerInstalled(pm) {
+  try {
+    await execa(pm, ['--version']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// 도구 간 의존성 자동 해결
+function resolveDependencies(selected) {
+  const all = new Set(selected);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const tool of DEVTOOLS_VALUES) {
+      if (all.has(tool.value) && tool.requires) {
+        for (const req of tool.requires) {
+          if (!all.has(req)) {
+            all.add(req);
+            changed = true;
+          }
+        }
+      }
+    }
+  }
+  return Array.from(all);
+}
+
+// 파일 복사
+async function copyDevtoolFiles(devtool, destDir) {
+  for (const file of devtool.files) {
+    const src = path.join(CONFIG.paths.devtools, devtool.value, file);
+    const dst = path.join(destDir, file);
+    if (await fs.pathExists(src)) {
+      await fs.copy(src, dst, { overwrite: true });
+      console.log(chalk.gray(`  ⎯ ${file} copied.`));
+    }
+  }
+}
+
+// 패키지 설치 (성능 최적화된 배치 처리 사용)
+async function installPackages(pkgs, pkgManager, dev = true, destDir = process.cwd()) {
+  if (!pkgs || pkgs.length === 0) return;
+
+  const batch = new PackageBatch();
+  batch.addMany(pkgs);
+  const resolved = await batch.resolve();
+
+  const installCmd =
+    pkgManager === 'npm'
+      ? ['install', dev ? '--save-dev' : '', ...resolved].filter(Boolean)
+      : pkgManager === 'yarn'
+        ? ['add', dev ? '--dev' : '', ...resolved].filter(Boolean)
+        : ['add', dev ? '-D' : '', ...resolved].filter(Boolean);
+
+  await execa(pkgManager, installCmd, { cwd: destDir, stdio: 'inherit' });
+}
+
+// package.json 수정 (스크립트 추가 등)
+async function updatePackageJson(scripts, destDir) {
+  const pkgPath = path.join(destDir, 'package.json');
+  const file = editJsonFile(pkgPath, { autosave: true });
+  Object.entries(scripts).forEach(([k, v]) => file.set(`scripts.${k}`, v));
+  if (!file.get('scripts.prepare') && fs.existsSync(path.join(destDir, '.huskyrc'))) {
+    file.set('scripts.prepare', 'husky install');
+  }
+  file.save();
+}
+
+// docker-compose 생성
+async function generateCompose(template, destDir) {
+  try {
+    const composeYml = generateDockerCompose(template);
+    const filePath = path.join(destDir, 'docker-compose.yml');
+    await fs.writeFile(filePath, composeYml, 'utf8');
+
+    const dbType = TEMPLATE_DB[template];
+    console.log(chalk.gray(`  ⎯ docker-compose.yml generated with ${dbType || 'no database'}`));
+    return dbType;
+  } catch (error) {
+    console.log(chalk.yellow(`[docker-compose] Warning: ${error.message}`));
+    return null;
+  }
+}
+
+// Git init & 첫 커밋
+async function gitInitAndFirstCommit(destDir) {
+  const doGit = await confirm({ message: 'Initialize git and make first commit?', initial: true });
+  if (!doGit) return;
+  try {
+    await execa('git', ['init'], { cwd: destDir });
+    await execa('git', ['add', '.'], { cwd: destDir });
+    await execa('git', ['commit', '-m', 'init'], { cwd: destDir });
+    console.log(chalk.green('  ✓ git initialized and first commit made!'));
+  } catch (e) {
+    printError(
+      new CLIError('git init/commit failed', 'git', 'Check git is installed and accessible.'),
+    );
+  }
+}
+
+// ========== [메인 CLI 실행 흐름] ==========
+async function main() {
+  // 1. Node 버전 체크
+  validateNodeVersion(CONFIG.minNodeVersion);
+
+  // 2. CLI 최신버전 안내
+  await checkForUpdate();
+
+  const config = getEnvironmentConfig();
+  intro(config.banner.gradient);
+
+  // 3. 패키지 매니저 선택 + 글로벌 설치 확인
+  let pkgManager;
+  while (true) {
+    pkgManager = await select({
+      message: 'Which package manager do you want to use?',
+      options: PACKAGE_MANAGER,
+      initialValue: 'npm',
+    });
+    if (isCancel(pkgManager)) return cancel('❌ Aborted.');
+    if (await checkPkgManagerInstalled(pkgManager)) break;
+    printError(`${pkgManager} is not installed globally! Please install it first.`);
+  }
+  note(`Using: ${pkgManager}`);
+
+  // 4. 템플릿 선택
+  const templateDirs = (await fs.readdir(CONFIG.paths.templates)).filter((f) =>
+    fs.statSync(path.join(CONFIG.paths.templates, f)).isDirectory(),
+  );
+  if (templateDirs.length === 0)
+    return printError(new CLIError('No templates found!', 'template-selection'));
+
+  const options = TEMPLATES_VALUES.filter((t) => t.active && templateDirs.includes(t.value)).map(
+    (t) => ({
+      label: t.name, // UI에 표시될 이름
+      value: t.value, // 선택 값
+      hint: t.desc, // 오른쪽에 표시될 설명
+    }),
+  );
+
+  const template = await select({
+    message: 'Choose a template:',
+    options: options,
+    initialValue: 'default',
+  });
+  if (isCancel(template)) return cancel('❌ Aborted.');
+
+  // 5. 프로젝트명 입력 (중복체크/덮어쓰기)
+  let projectName, destDir;
+  while (true) {
+    const rawProjectName = await text({
+      message: 'Enter your project name:',
+      initial: CONFIG.defaultProjectName,
+      validate: (val) => {
+        try {
+          validateProjectName(val);
+          return undefined;
+        } catch (error) {
+          return error.message;
+        }
+      },
+    });
+    if (isCancel(rawProjectName)) return cancel('❌ Aborted.');
+
+    projectName = sanitizeInput(rawProjectName);
+    destDir = validateProjectPath(path.resolve(process.cwd(), projectName));
+
+    if (await fs.pathExists(destDir)) {
+      const overwrite = await confirm({
+        message: `Directory "${projectName}" already exists. Overwrite?`,
+      });
+      if (overwrite) break;
+    } else break;
+  }
+
+  // 6. 개발 도구 옵션 선택 (category 기준으로 그룹화)
+  const groupedDevtools = DEVTOOLS_VALUES.reduce((acc, tool) => {
+    const cat = tool.category || 'Others';
+    if (!acc[cat]) acc[cat] = [];
+    acc[cat].push(tool);
+    return acc;
+  }, {});
+
+  // 6-1. 개발 도구 옵션 선택 (category별 하나씩만 선택하는 방식)
+  let devtoolValues = [];
+  for (const [category, tools] of Object.entries(groupedDevtools)) {
+    const picked = await select({
+      message: `Select a tool for "${category}":`,
+      options: [
+        { label: 'None', value: null },
+        ...tools.map(({ name, value, desc }) => ({
+          label: `${name} (${desc})`,
+          value,
+        })),
+      ],
+      initialValue: null,
+    });
+    if (isCancel(picked)) return cancel('❌ Aborted.');
+    if (picked) devtoolValues.push(picked);
+  }
+  devtoolValues = resolveDependencies(devtoolValues);
+
+  // === [진행] ===
+
+  // [1] 템플릿 복사
+  const spinner = ora('Copying template...').start();
+  try {
+    await fs.copy(path.join(CONFIG.paths.templates, template), destDir, { overwrite: true });
+    spinner.succeed('Template copied!');
+  } catch (e) {
+    spinner.fail('Template copy failed!');
+    printError(new FileSystemError(e.message, destDir, 'Check templates folder and permissions.'));
+    return process.exit(1);
+  }
+
+  // [1-1] Testing 도구를 선택한 경우에만 /src/test 예제 복사
+  const testDevtool = devtoolValues
+    .map((val) => DEVTOOLS_VALUES.find((d) => d.value === val))
+    .find((tool) => tool && tool.category === 'Testing');
+
+  if (testDevtool) {
+    const devtoolTestDir = path.join(CONFIG.paths.devtools, testDevtool.value, 'src', 'test');
+    const projectTestDir = path.join(destDir, 'src', 'test');
+    if (await fs.pathExists(devtoolTestDir)) {
+      await fs.copy(devtoolTestDir, projectTestDir, { overwrite: true });
+      console.log(chalk.gray(`  ⎯ test files for ${testDevtool.name} copied.`));
+    }
+  }
+
+  // [2] 개발 도구 파일/패키지/스크립트/코드패치
+  for (const val of devtoolValues) {
+    const tool = DEVTOOLS_VALUES.find((d) => d.value === val);
+    if (!tool) continue;
+
+    spinner.start(`Setting up ${tool.name}...`);
+    await copyDevtoolFiles(tool, destDir);
+
+    // [2-1] 개발 도구 - 패키지 설치
+    if (tool.pkgs?.length > 0) await installPackages(tool.pkgs, pkgManager, false, destDir);
+    if (tool.devPkgs?.length > 0) await installPackages(tool.devPkgs, pkgManager, true, destDir);
+
+    // [2-2] 개발 도구 - 스크립트 추가 등
+    if (Object.keys(tool.scripts).length) await updatePackageJson(tool.scripts, destDir);
+
+    // [2-3] 개발 도구 - Docker 선택 한 경우, docker-compose.yml 생성
+    if (tool.value === 'docker') await generateCompose(template, destDir);
+
+    // [2-4] 개발 도구 - Swagger 선택 시에만 app.ts AST 패치
+    if (tool.value === 'swagger') {
+      await injectSwaggerIntoApp(destDir);
+    }
+
+    spinner.succeed(`${tool.name} setup done.`);
+  }
+
+  // [3] 템플릿 기본 패키지 설치
+  spinner.start(`Installing base dependencies with ${pkgManager}...`);
+  await execa(pkgManager, ['install'], { cwd: destDir, stdio: 'inherit' });
+  spinner.succeed('📦 Base dependencies installed!');
+
+  // [4] git 첫 커밋 옵션
+  await gitInitAndFirstCommit(destDir);
+
+  outro(chalk.greenBright('\n🎉 Project setup complete!\n'));
+  console.log(chalk.cyan(`   $ cd ${projectName}`));
+  console.log(chalk.cyan(`   $ ${pkgManager} run dev\n`));
+  console.log(chalk.gray('✨ Happy hacking!\n'));
+}
+
+main().catch((err) => {
+  if (err instanceof CLIError) {
+    printError(err);
+  } else {
+    printError(new CLIError('Unexpected error', null, err.message));
+  }
+  process.exit(err.code || 1);
+});

package/bin/validators.js

@@ -0,0 +1,146 @@
+/**
+ * Validation utilities for user inputs and security
+ */
+
+import path from 'path';
+import { CONFIG } from './config.js';
+import { ValidationError } from './errors.js';
+
+/**
+ * Validate project name
+ */
+export function validateProjectName(name) {
+  if (!name || typeof name !== 'string') {
+    throw new ValidationError('Project name is required', 'projectName');
+  }
+
+  if (name.length > CONFIG.maxProjectNameLength) {
+    throw new ValidationError(
+      `Project name must be less than ${CONFIG.maxProjectNameLength} characters`,
+      'projectName',
+      'Use a shorter, descriptive name',
+    );
+  }
+
+  if (!CONFIG.validation.projectName.test(name)) {
+    throw new ValidationError(
+      'Project name can only contain letters, numbers, hyphens, and underscores',
+      'projectName',
+      'Use alphanumeric characters with hyphens or underscores',
+    );
+  }
+
+  // Check for reserved names
+  const reservedNames = ['node_modules', 'package.json', 'src', 'dist', 'build'];
+  if (reservedNames.includes(name.toLowerCase())) {
+    throw new ValidationError(
+      `"${name}" is a reserved name and cannot be used`,
+      'projectName',
+      'Choose a different project name',
+    );
+  }
+
+  return name;
+}
+
+/**
+ * Validate and resolve project path
+ */
+export function validateProjectPath(projectPath) {
+  if (!projectPath || typeof projectPath !== 'string') {
+    throw new ValidationError('Project path is required', 'projectPath');
+  }
+
+  const resolved = path.resolve(projectPath);
+  const cwd = process.cwd();
+
+  // Prevent path traversal attacks
+  if (!resolved.startsWith(cwd)) {
+    throw new ValidationError(
+      'Project path must be within current directory',
+      'projectPath',
+      'Use a relative path or absolute path within current directory',
+    );
+  }
+
+  // Check for dangerous paths (시스템 루트 디렉토리만 제한)
+  const dangerousPaths = ['/etc', '/usr', '/var', '/tmp'];
+  if (dangerousPaths.some((dangerous) => resolved.startsWith(dangerous))) {
+    throw new ValidationError(
+      'Cannot create project in system directories',
+      'projectPath',
+      'Choose a safe location within your workspace',
+    );
+  }
+
+  return resolved;
+}
+
+/**
+ * Check if package specifier is explicit (URL, file, etc.)
+ */
+export function isExplicitSpecifier(spec) {
+  const explicitPrefixes = ['http://', 'https://', 'git+', 'file:', 'link:', 'workspace:', 'npm:'];
+
+  return explicitPrefixes.some((prefix) => spec.startsWith(prefix));
+}
+
+/**
+ * Split package name and version from specifier
+ */
+export function splitNameAndVersion(spec) {
+  if (isExplicitSpecifier(spec)) {
+    return { name: spec, version: null };
+  }
+
+  if (spec.startsWith('@')) {
+    // Scoped package: @scope/package@version
+    const idx = spec.indexOf('@', 1);
+    if (idx === -1) {
+      return { name: spec, version: null };
+    }
+    return {
+      name: spec.slice(0, idx),
+      version: spec.slice(idx + 1),
+    };
+  } else {
+    // Regular package: package@version
+    const idx = spec.indexOf('@');
+    if (idx === -1) {
+      return { name: spec, version: null };
+    }
+    return {
+      name: spec.slice(0, idx),
+      version: spec.slice(idx + 1),
+    };
+  }
+}
+
+/**
+ * Sanitize user input
+ */
+export function sanitizeInput(input) {
+  if (typeof input !== 'string') {
+    return input;
+  }
+
+  // Remove potentially dangerous characters
+  return input.replace(/[<>:"|?*]/g, '').trim();
+}
+
+/**
+ * Validate Node.js version
+ */
+export function validateNodeVersion(required = CONFIG.minNodeVersion) {
+  const current = parseInt(process.versions.node.split('.')[0], 10);
+
+  if (current < required) {
+    throw new ValidationError(
+      `Node.js ${required}+ required. You have ${process.versions.node}`,
+      'nodeVersion',
+      `Please upgrade your Node.js to version ${required} or higher`,
+    );
+  }
+
+  return current;
+}

package/devtools/biome/.biome.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.0.0/schema.json",
+  "files": {
+    "ignore": [
+      "node_modules/**",
+      "dist/**",
+      "build/**"
+    ]
+  },
+  "formatter": {
+    "enabled": false,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 150,
+    "quoteStyle": "single",
+    "trailingComma": "all",
+    "semiColon": true,
+    "arrowParentheses": "avoid"
+  },
+  "linter": {
+    "enabled": false,
+    "rules": {
+      "recommended": true,
+      "style/noExplicitAny": "off",
+      "style/noNonNullAssertion": "off",
+      "suspicious/noExplicitAny": "off",
+      "style/noVar": "off",
+      "complexity/useArrowFunctions": "off"
+    }
+  },
+  "organizeImports": {
+    "enabled": false
+  }
+}

package/devtools/biome/.biomeignore

@@ -0,0 +1,29 @@
+# node_modules and build outputs
+node_modules/
+dist/
+build/
+coverage/
+.tmp/
+.temp/
+
+# 환경설정 및 로그
+.env
+.env.*
+*.log
+
+# TypeScript compiled output
+*.js
+*.d.ts
+*.map
+
+# OS, IDE/Editor 관련
+.DS_Store
+.vscode/
+.idea/
+*.swp
+
+# 기타 무시할 파일/폴더
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*

package/devtools/docker/.dockerignore

@@ -0,0 +1,27 @@
+# 빌드 불필요/민감 파일 차단
+node_modules/
+dist/
+.vscode/
+logs/
+coverage/
+
+# 환경설정/시크릿/포매터
+.env
+.env.*
+.eslintrc*
+.eslintignore
+.editorconfig
+.prettierrc*
+.huskyrc
+.lintstagedrc*
+jest.config.js
+
+# 도커 파일 자체
+Dockerfile
+docker-compose.yml
+
+# 시스템
+.DS_Store
+Thumbs.db
+npm-debug.log*
+yarn-error.log*

package/devtools/docker/Dockerfile.dev

@@ -0,0 +1,20 @@
+# 베이스 이미지
+FROM node:20-alpine
+
+# 작업 디렉토리 생성
+WORKDIR /app
+
+# 패키지 설치(캐시 활용)
+COPY package.json pnpm-lock.yaml* yarn.lock* package-lock.json* ./
+RUN if [ -f yarn.lock ]; then yarn install; \
+    elif [ -f pnpm-lock.yaml ]; then corepack enable && pnpm install; \
+    else npm install; fi
+
+# 전체 코드 복사 (단, node_modules는 제외됨)
+COPY . .
+
+# 개발용 포트 (예: 3000)
+EXPOSE 3000
+
+# 개발용 명령어: nodemon, ts-node-dev 등
+CMD [ "npm", "run", "dev"]

package/devtools/docker/Dockerfile.prod

@@ -0,0 +1,35 @@
+# 1. Build Stage
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+COPY package.json pnpm-lock.yaml* yarn.lock* package-lock.json* ./
+RUN if [ -f yarn.lock ]; then yarn install --production=false; \
+    elif [ -f pnpm-lock.yaml ]; then corepack enable && pnpm install --prod=false; \
+    else npm install --production=false; fi
+
+COPY . .
+
+# TypeScript 빌드
+RUN npx tsc
+
+# 2. Run Stage (더 가벼운 이미지 사용 가능)
+FROM node:20-alpine
+
+WORKDIR /app
+
+# 의존성(production only)
+COPY package.json pnpm-lock.yaml* yarn.lock* package-lock.json* ./
+RUN if [ -f yarn.lock ]; then yarn install --production=true --frozen-lockfile; \
+    elif [ -f pnpm-lock.yaml ]; then corepack enable && pnpm install --prod --frozen-lockfile; \
+    else npm install --production --frozen-lockfile; fi
+
+# 빌드된 코드만 복사 (node_modules, dist)
+COPY --from=builder /app/dist ./dist
+
+# 환경설정 등 추가 복사 (필요시)
+# COPY .env ./
+
+EXPOSE 3000
+
+CMD [ "npm", "start" ]

package/{lib/default → devtools/docker}/Makefile

@@ -40,3 +40,6 @@ clean: ## Clean the images
 
 remove: ## Remove the volumes
 	docker volume rm -f ${APP_NAME}
+
+logs: ## Show container logs
+	docker logs -f ${APP_NAME}