birc-generator 0.5.5

package/bin/birc.js

@@ -0,0 +1,645 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const BANNER = `
+██████╗ ██╗██████╗  ██████╗
+██╔══██╗██║██╔══██╗██╔════╝
+██████╔╝██║██████╔╝██║     
+██╔══██╗██║██╔══██╗██║     
+██████╔╝██║██║  ██║╚██████╗
+╚═════╝ ╚═╝╚═╝  ╚═╝ ╚═════╝
+`;
+
+const HELP_SECTIONS = [
+  {
+    title: '專案',
+    commands: [
+      ['create', '開多模組 Spring Boot 4 專案（預設 Practice）'],
+      ['add', '往既有專案加模組；可帶名稱如 birc add email sentry'],
+      ['sync', '用目前 template 覆寫已安裝 feature 的檔'],
+      ['update', '更新本機 birc（npm 走 npm，其餘拉 GitLab main）']
+    ]
+  },
+  {
+    title: '骨架',
+    note: '寫法是 make:種類 [名稱]。預設只生引入與初稿；加 --example 才有完整範例',
+    commands: [
+      ['make', '一次生 Entity + DAO + Mapper + DTO + Service + Controller'],
+      ['make:entity', 'Entity、XxxDAO（--dto / --mapper / --soft-delete）'],
+      ['make:model', '同 make:entity；--migration / --seed / --controller / --soft-delete'],
+      ['make:mapper', 'Mapper、CreateRequest、Response'],
+      ['make:service', 'XxxService extends BaseService'],
+      ['make:controller', 'Controller'],
+      ['make:exception', '繼承 ProjectException 的例外'],
+      ['make:migration', 'Flyway SQL（檔名如 create_users_table）'],
+    ]
+  },
+  {
+    title: '資料庫',
+    commands: [
+      ['migrate', '套用待執行的遷移（flywayMigrate）'],
+      ['migrate:reset', '清 schema 再重跑（flywayClean + migrate）'],
+      ['migrate:rollback', 'Community 做不到 rollback，會印替代作法']
+    ]
+  },
+  {
+    title: '文件',
+    commands: [
+      ['docs', '補 AGENTS.md / PROJECT.md / implement.md / test.md']
+    ]
+  }
+];
+
+const FLYWAY_COMMANDS = new Set(['migrate', 'migrate:rollback', 'migrate:reset']);
+
+function allCommandNames() {
+  return HELP_SECTIONS.flatMap((section) => section.commands.map(([name]) => name));
+}
+
+const generatorRoot = path.join(__dirname, '..');
+let projectRoot = process.cwd();
+const pkg = require(path.join(generatorRoot, 'package.json'));
+
+function authorLine() {
+  const author = pkg.author;
+  if (!author) return '';
+  if (typeof author === 'string') return author;
+  if (author.email) return `${author.name} <${author.email}>`;
+  return author.name || '';
+}
+
+function formatDate(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return String(iso);
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: 'Asia/Taipei',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false
+  }).formatToParts(d);
+  const get = (type) => parts.find((part) => part.type === type)?.value;
+  return `${get('year')}-${get('month')}-${get('day')} ${get('hour')}:${get('minute')}`;
+}
+
+function lastUpdated() {
+  const gitDir = path.join(generatorRoot, '.git');
+  if (fs.existsSync(gitDir)) {
+    const result = spawnSync('git', ['log', '-1', '--format=%cI'], {
+      cwd: generatorRoot,
+      encoding: 'utf8',
+      timeout: 300
+    });
+    if (result.status === 0 && result.stdout.trim()) {
+      return formatDate(result.stdout.trim());
+    }
+  }
+  if (pkg.bircUpdatedAt) return formatDate(pkg.bircUpdatedAt);
+  return formatDate(fs.statSync(path.join(generatorRoot, 'package.json')).mtime.toISOString());
+}
+
+function displayWidth(text) {
+  let width = 0;
+  for (const ch of String(text)) {
+    const code = ch.codePointAt(0);
+    width += code <= 0x1f || (code >= 0x7f && code <= 0x9f)
+      ? 0
+      : code >= 0x1100 && (
+        code <= 0x115f
+        || code === 0x2329
+        || code === 0x232a
+        || (code >= 0x2e80 && code <= 0xa4cf)
+        || (code >= 0xac00 && code <= 0xd7a3)
+        || (code >= 0xf900 && code <= 0xfaff)
+        || (code >= 0xfe10 && code <= 0xfe19)
+        || (code >= 0xfe30 && code <= 0xfe6f)
+        || (code >= 0xff00 && code <= 0xff60)
+        || (code >= 0xffe0 && code <= 0xffe6)
+      )
+        ? 2
+        : 1;
+  }
+  return width;
+}
+
+function padDisplay(text, width) {
+  const extra = width - displayWidth(text);
+  return extra > 0 ? `${text}${' '.repeat(extra)}` : text;
+}
+
+function printBanner() {
+  const art = BANNER.trim().split('\n').map((line) => line.trimEnd());
+  const artWidth = Math.max(...art.map(displayWidth));
+  const info = [
+    'BIRC Spring Boot 4 骨架產生器',
+    `作者  ${authorLine()}`,
+    `版本  ${pkg.version}`,
+    `更新  ${lastUpdated()}`
+  ];
+  const lines = art.map((line, i) => {
+    const left = padDisplay(line, artWidth);
+    return info[i] ? `${left}   ${info[i]}` : left;
+  });
+  process.stdout.write(`${lines.join('\n')}\n\n`);
+}
+
+function printHelp() {
+  const names = HELP_SECTIONS.flatMap((section) => section.commands.map(([name]) => name));
+  const nameWidth = Math.max(...names.map((name) => name.length), 16);
+  const sections = HELP_SECTIONS.flatMap((section) => {
+    const rows = section.commands.map(
+      ([name, desc]) => `  ${name.padEnd(nameWidth + 2)}${desc}`
+    );
+    return ['', section.title, ...(section.note ? [`  ${section.note}`] : []), ...rows];
+  });
+  process.stdout.write(
+    [
+      '用法:',
+      '  birc <指令> [名稱] [選項]',
+      '  子指令接在冒號後面，例如 make:entity、migrate:reset。',
+      ...sections,
+      '',
+      '選項',
+      `  ${'-h, --help'.padEnd(nameWidth + 2)}顯示這份說明`,
+      `  ${'-v, --version'.padEnd(nameWidth + 2)}顯示版本`,
+      `  ${'--example'.padEnd(nameWidth + 2)}make:* 產出完整範例`,
+      `  ${'--dto'.padEnd(nameWidth + 2)}make:entity 順便生 Mapper 與 DTO`,
+      `  ${'--mapper'.padEnd(nameWidth + 2)}同 --dto`,
+      `  ${'--migration'.padEnd(nameWidth + 2)}make:model 順便生 create_{table}_table`,
+      `  ${'--seed'.padEnd(nameWidth + 2)}make:model 順便生 seed_{table}`,
+      `  ${'--controller'.padEnd(nameWidth + 2)}make:model 順便生 Controller`,
+      `  ${'--soft-delete'.padEnd(nameWidth + 2)}make:entity / make:model 加 deleted_at 軟刪`,
+      `  ${'--fields'.padEnd(nameWidth + 2)}make --example 的欄位，例如 title:String,startTime:LocalDateTime`,
+      `  ${'--force'.padEnd(nameWidth + 2)}migrate:reset 略過確認；add 覆寫已選的已安裝 feature；make 覆寫已有 Java`,
+      `  ${'--yes'.padEnd(nameWidth + 2)}create 其餘用預設、不要問`,
+      '',
+      '例子',
+      '  birc create',
+      '  birc create Practice tw.edu.ntub.birc.practice',
+      '  birc create Practice --yes',
+      '  birc update',
+      '  birc add',
+      '  birc add email',
+      '  birc add email sentry',
+      '  birc add file-upload',
+      '  birc add --force',
+      '  birc sync',
+      '  birc make:entity User',
+      '  birc make:entity User --dto',
+      '  birc make:entity User --mapper',
+      '  birc make:entity User --example',
+      '  birc make:entity User --example --fields title:String,startTime:LocalDateTime',
+      '  birc make:entity User --force',
+      '  birc make:model Flight --migration',
+      '  birc make:model Flight --seed',
+      '  birc make:model Flight --controller',
+      '  birc make:model Flight --soft-delete',
+      '  birc make:migration create_users_table',
+      '  birc make:migration add_votes_to_users_table',
+      '  birc migrate',
+      '',
+      'create / update 以外的指令會從目前目錄往上找 .bircrc.json。',
+      ''
+    ].join('\n')
+  );
+}
+
+function printUnknownCommand(name) {
+  const { suggestCommand } = require('./cli-util');
+  const known = allCommandNames();
+  process.stderr.write(`找不到指令: ${name}\n`);
+  const suggestion = suggestCommand(name, known);
+  if (suggestion) {
+    if (String(name).includes('::')) {
+      process.stderr.write(`你要的大概是 ${suggestion}（中間一條冒號）。\n`);
+    } else {
+      process.stderr.write(`你要的大概是 ${suggestion}。\n`);
+    }
+  }
+  process.stderr.write('看全部指令：birc --help\n');
+}
+
+async function runGenerator(name, bypassArr, flags) {
+  const { default: nodePlop } = await import('node-plop');
+  const plop = await nodePlop(path.join(generatorRoot, 'plopfile.js'), {
+    destBasePath: projectRoot,
+    force: Boolean(flags.force) || name === 'sync'
+  });
+  const names = plop.getGeneratorList().map((generator) => generator.name);
+  if (!names.includes(name)) {
+    printUnknownCommand(name);
+    process.exit(1);
+  }
+
+  if (flags.example) {
+    process.env.BIRC_EXAMPLE = '1';
+  }
+  if (flags.dto) {
+    process.env.BIRC_MAKE_DTO = '1';
+  }
+  if (flags.mapper) {
+    process.env.BIRC_MAKE_MAPPER = '1';
+  }
+  if (flags.migration) {
+    process.env.BIRC_MAKE_MIGRATION = '1';
+  }
+  if (flags.seed) {
+    process.env.BIRC_MAKE_SEED = '1';
+  }
+  if (flags.controller) {
+    process.env.BIRC_MAKE_CONTROLLER = '1';
+  }
+  if (flags.softDelete) {
+    process.env.BIRC_MAKE_SOFT_DELETE = '1';
+  }
+  if (name === 'add' && flags.force) {
+    process.env.BIRC_ADD_FORCE = '1';
+  }
+  if (name === 'sync') {
+    process.env.BIRC_ADD_FORCE = '1';
+    process.env.BIRC_ADD_SYNC = '1';
+  }
+
+  const generator = plop.getGenerator(name);
+  let promptBypass = bypassArr;
+  let addFeatures;
+  let createYes;
+  if (name === 'create') {
+    const { applyCreatePromptDefaults, applyCreateYes } = require('./cli-util');
+    applyCreatePromptDefaults(generator.prompts, bypassArr);
+    promptBypass = [];
+    if (flags.yes) {
+      const { DEFAULT_FEATURES } = require('../plopfile');
+      createYes = applyCreateYes(generator.prompts, bypassArr, [...DEFAULT_FEATURES]);
+    }
+  }
+  if (name === 'add') {
+    const { applyAddFeatureArgs } = require('./cli-util');
+    const { FEATURES } = require('../plopfile');
+    const resolved = applyAddFeatureArgs(generator.prompts, bypassArr, Object.keys(FEATURES));
+    if (resolved.error) {
+      process.stderr.write(`${resolved.error}\n`);
+      process.exit(1);
+    }
+    if (resolved.keys) {
+      addFeatures = resolved.keys;
+      promptBypass = [];
+    }
+  }
+  if (flags.fields) {
+    process.env.BIRC_MAKE_FIELDS = flags.fields;
+    const { applyMakeFieldsFlag, fieldsWithoutExampleMessage } = require('./cli-util');
+    applyMakeFieldsFlag(generator.prompts, flags.fields);
+    if (name === 'make' || String(name).startsWith('make:')) {
+      const warn = fieldsWithoutExampleMessage(flags);
+      if (warn) process.stderr.write(`${warn}\n`);
+    }
+  }
+  const answers = await generator.runPrompts(promptBypass);
+  if (createYes) {
+    Object.assign(answers, createYes);
+  }
+  if (addFeatures) {
+    answers.features = addFeatures;
+  }
+  if (flags.fields) {
+    answers.fields = flags.fields;
+  }
+  answers.example = Boolean(answers.example) || flags.example;
+  answers.dto = Boolean(answers.dto) || flags.dto;
+  answers.mapper = Boolean(answers.mapper) || flags.mapper;
+  answers.migration = Boolean(answers.migration) || flags.migration;
+  answers.seed = Boolean(answers.seed) || flags.seed;
+  answers.controller = Boolean(answers.controller) || flags.controller;
+  answers.softDelete = Boolean(answers.softDelete) || flags.softDelete;
+  answers.force = Boolean(answers.force) || flags.force || name === 'sync';
+  answers.sync = Boolean(answers.sync) || name === 'sync';
+  let failed = false;
+  let changeCount = 0;
+  await generator.runActions(answers, {
+    onSuccess(change) {
+      changeCount += 1;
+      const bits = [change.type, change.path].filter(Boolean);
+      if (bits.length) process.stdout.write(`  ${bits.join('  ')}\n`);
+    },
+    onFailure(fail) {
+      failed = true;
+      const { alreadyExistsMessage } = require('./cli-util');
+      const rewritten = alreadyExistsMessage(fail);
+      if (rewritten) {
+        process.stderr.write(`  ${rewritten}\n`);
+        return;
+      }
+      const errMsg = fail.error || fail.message || '';
+      const bits = [fail.type, fail.path, errMsg].filter(Boolean);
+      process.stderr.write(`  ${bits.join('  ')}\n`);
+    }
+  });
+  if (failed) process.exit(1);
+  if (name === 'create') {
+    printCreateNextSteps(answers);
+  }
+  if (name === 'add') {
+    const { formatAddNextSteps } = require('./cli-util');
+    process.stdout.write(`${formatAddNextSteps(answers, { changed: changeCount > 0 }).join('\n')}\n`);
+  }
+  if (name === 'make' || String(name).startsWith('make:') || name === 'migration') {
+    const { formatMakeNextSteps } = require('./cli-util');
+    const lines = formatMakeNextSteps(name, answers);
+    if (lines.length) process.stdout.write(`${lines.join('\n')}\n`);
+  }
+}
+
+function printCreateNextSteps(answers) {
+  const { toKebabName } = require('./cli-util');
+  const dir = toKebabName(answers.projectName);
+  const hasDocker = (answers.features || []).includes('docker');
+  const lines = [
+    '',
+    `專案已建立在 ${dir}/。接下來：`,
+    '',
+    `  cd ${dir}`
+  ];
+  if (hasDocker) {
+    lines.push(
+      '  docker compose up -d db     # 啟動 MySQL（已從 .env.example 複製成 .env）'
+    );
+    if (process.platform === 'win32') {
+      lines.push(
+        '  # PowerShell：把 .env 載入目前 session 後再跑',
+        '  Get-Content .env | ForEach-Object { if ($_ -match "^\\s*([^#][^=]*)=(.*)$") { Set-Item -Path "Env:$($matches[1].Trim())" -Value $matches[2].Trim().Trim(\'"\') } }',
+        '  .\\gradlew.bat bootRun'
+      );
+    } else {
+      lines.push(
+        '  set -a && source .env && set +a',
+        '  ./gradlew bootRun           # 啟動 Spring Boot'
+      );
+    }
+  } else {
+    lines.push(
+      '  # 先準備 MySQL，並設定 src/main/resources/application.yml 的連線',
+      process.platform === 'win32' ? '  .\\gradlew.bat bootRun' : '  ./gradlew bootRun'
+    );
+  }
+  lines.push(
+    '',
+    '生 CRUD 骨架（會從目前目錄往上找 .bircrc.json）：',
+    '  birc make                 # Entity + DAO + Mapper + DTO + Service + Controller',
+    '  birc make:entity          # Entity / DAO',
+    '  birc make:entity User --dto',
+    '  birc make:model Flight --migration --seed --controller',
+    '  birc make:entity User --example',
+    '  birc make:migration create_users_table',
+    '  birc add                  # 之後再補 docker / email 等功能',
+    '',
+    '打包：',
+    process.platform === 'win32' ? '  .\\gradlew.bat build -x test' : '  ./gradlew build -x test',
+    ''
+  );
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+async function confirmYes(question) {
+  const readline = require('readline/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(question);
+    return /^y(es)?$/i.test(String(answer || '').trim());
+  } finally {
+    rl.close();
+  }
+}
+
+async function confirmDefaultYes(question) {
+  const readline = require('readline/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question(question);
+    const text = String(answer || '').trim();
+    if (!text) return true;
+    return /^y(es)?$/i.test(text);
+  } finally {
+    rl.close();
+  }
+}
+
+async function offerUpdateIfNeeded(command) {
+  const {
+    compareSemver,
+    detectInstallKind,
+    shouldSkipPrompt,
+    readSnooze,
+    writeSnooze,
+    fetchLatestVersion
+  } = require('./update-check');
+
+  const tty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (shouldSkipPrompt({ env: process.env, tty, command })) {
+    return;
+  }
+
+  const kind = detectInstallKind(generatorRoot);
+  const latest = await fetchLatestVersion(kind);
+  if (!latest || compareSemver(latest, pkg.version) <= 0) {
+    return;
+  }
+  if (shouldSkipPrompt({ env: process.env, tty, command, latest, snooze: readSnooze() })) {
+    return;
+  }
+
+  process.stdout.write(`發現新版本 ${latest}（目前 ${pkg.version}）。\n`);
+  const ok = await confirmDefaultYes('要現在更新嗎？(Y/n): ');
+  if (!ok) {
+    writeSnooze(latest);
+    process.stdout.write('已略過。24 小時內不會再問同一版本。\n\n');
+    return;
+  }
+
+  if (await applyInstalledUpdate(kind, { continueOnFailure: true }) === 0) {
+    process.stdout.write('已更新。請再執行一次剛才的指令。\n');
+    process.exit(0);
+  }
+}
+
+function runGradle(args) {
+  const {
+    resolveGradleWrapper,
+    gradleWrapperMissingMessage
+  } = require('./cli-util');
+  const wrapper = resolveGradleWrapper(projectRoot);
+  if (!wrapper) {
+    throw new Error(gradleWrapperMissingMessage());
+  }
+  const result = spawnSync(wrapper.command, args, {
+    stdio: 'inherit',
+    cwd: projectRoot,
+    shell: wrapper.shell,
+    windowsHide: true
+  });
+  if (result.error) {
+    throw new Error(`執行 Gradle 失敗：${result.error.message}`);
+  }
+  return result.status === null ? 1 : result.status;
+}
+
+async function runFlyway(command, flags) {
+  if (command === 'migrate:rollback') {
+    process.stdout.write(
+      [
+        'Flyway Community 沒有 Laravel 的 migrate:rollback。',
+        'undo 只有 Flyway Teams（./gradlew flywayUndo），而且要另寫 U{version}__*.sql。',
+        'Community 請再寫一筆往前的遷移來反做，例如：',
+        '  birc make:migration remove_votes_from_users_table',
+        '  birc migrate',
+        ''
+      ].join('\n')
+    );
+    process.exit(1);
+  }
+
+  if (command === 'migrate:reset') {
+    if (!flags.force) {
+      const ok = await confirmYes('這會清掉 schema 再重跑全部遷移。確定？ [y/N] ');
+      if (!ok) {
+        process.stdout.write('已取消。\n');
+        return;
+      }
+    }
+    const cleanStatus = runGradle(['flywayClean', '-Dflyway.cleanDisabled=false']);
+    if (cleanStatus !== 0) {
+      process.exit(cleanStatus);
+    }
+    process.exit(runGradle(['flywayMigrate']));
+  }
+
+  process.exit(runGradle(['flywayMigrate']));
+}
+
+function updateViaNpm() {
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  process.stdout.write(`這份 birc 是 npm 裝的，改跑 npm install -g ${pkg.name}@latest。\n`);
+  const result = spawnSync(npmCmd, ['install', '-g', `${pkg.name}@latest`], {
+    stdio: 'inherit'
+  });
+  if (result.error) {
+    throw new Error(`更新失敗：${result.error.message}`);
+  }
+  return result.status === null ? 1 : result.status;
+}
+
+async function applyInstalledUpdate(kind, { continueOnFailure = false } = {}) {
+  const { resolveUpdateMethod } = require('./update-check');
+  if (resolveUpdateMethod(kind) === 'npm') {
+    const status = updateViaNpm();
+    if (status === 0) {
+      return 0;
+    }
+    if (continueOnFailure) {
+      process.stderr.write('更新失敗，先繼續用目前版本。\n\n');
+      return status;
+    }
+    throw new Error(`npm 更新失敗。也可改跑 npm update -g ${pkg.name}。`);
+  }
+
+  const homeInstall = require('./home-install');
+  process.stdout.write('這份 birc 不是 npm 裝的，改拉 GitLab main 到 ~/.birc-generator（curl / PowerShell 同一處）。\n');
+  try {
+    return await homeInstall.runUpdate({
+      currentRoot: generatorRoot,
+      installDir: homeInstall.defaultInstallDir(),
+      baseUrl: homeInstall.defaultBaseUrl()
+    });
+  } catch (err) {
+    if (continueOnFailure) {
+      process.stderr.write(`更新失敗：${err.message || err}\n先繼續用目前版本。\n\n`);
+      return 1;
+    }
+    throw err;
+  }
+}
+
+function commandNeedsProject(command) {
+  return Boolean(command) && command !== 'create' && command !== 'update' && command !== 'help';
+}
+
+async function main() {
+  const { findProjectRoot, projectConfigMissingMessage, shouldPrintBanner, parseArgv, createDestConflict } = require('./cli-util');
+  const parsed = parseArgv(process.argv.slice(2));
+  if (parsed.error) {
+    process.stderr.write(`${parsed.error}\n`);
+    process.exit(1);
+  }
+  const flags = parsed.flags;
+  const command = flags.positionals[0];
+
+  if (command === 'create' && !flags.help) {
+    const conflict = createDestConflict({
+      cwd: process.cwd(),
+      projectName: flags.positionals[1]
+    });
+    if (conflict) {
+      process.stderr.write(`${conflict}\n`);
+      process.exit(1);
+    }
+  }
+
+  if (
+    !flags.help
+    && !flags.version
+    && commandNeedsProject(command)
+    && (allCommandNames().includes(command) || FLYWAY_COMMANDS.has(command))
+  ) {
+    const found = findProjectRoot(process.cwd());
+    if (!found) {
+      process.stderr.write(`${projectConfigMissingMessage()}\n`);
+      process.exit(1);
+    }
+    projectRoot = found;
+  }
+
+  process.env.BIRC_PROJECT_ROOT = projectRoot;
+
+  if (shouldPrintBanner(command, flags)) {
+    printBanner();
+  }
+
+  if (flags.version && !flags.positionals.length) {
+    return;
+  }
+
+  await offerUpdateIfNeeded(command);
+
+  if (flags.help || flags.positionals.length === 0 || command === 'help') {
+    printHelp();
+    return;
+  }
+
+  if (!allCommandNames().includes(command) && !FLYWAY_COMMANDS.has(command)) {
+    printUnknownCommand(command);
+    process.exit(1);
+  }
+  if (command === 'update') {
+    const { detectInstallKind } = require('./update-check');
+    if (await applyInstalledUpdate(detectInstallKind(generatorRoot)) === 0) {
+      process.stdout.write('已更新。\n');
+    }
+    return;
+  }
+  if (FLYWAY_COMMANDS.has(command)) {
+    await runFlyway(command, flags);
+    return;
+  }
+
+  await runGenerator(command, flags.positionals.slice(1), flags);
+}
+
+main().catch((err) => {
+  console.error(err.message || err);
+  process.exit(1);
+});