birc-generator 0.5.5

package/bin/home-install.js

@@ -0,0 +1,346 @@
+const fs = require('fs');
+const https = require('https');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const DEFAULT_BASE_URL = 'https://gitlab.ntubimdbirc.tw/lucashsu95/birc-generator';
+
+function npmCmd(platform = process.platform) {
+  return platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function defaultInstallDir(homedir = os.homedir()) {
+  return path.join(homedir, '.birc-generator');
+}
+
+function defaultBaseUrl() {
+  return (process.env.BIRC_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, '');
+}
+
+function canWrite(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.accessSync(dir, fs.constants.W_OK);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function readNpmPrefix(platform = process.platform) {
+  const result = spawnSync(npmCmd(platform), ['config', 'get', 'prefix'], {
+    encoding: 'utf8',
+    timeout: 8000,
+    shell: platform === 'win32'
+  });
+  if (result.status !== 0) {
+    return '';
+  }
+  return String(result.stdout || '').trim();
+}
+
+function npmBinDir(prefix, platform = process.platform, exists = fs.existsSync) {
+  if (!prefix) {
+    return '';
+  }
+  if (platform === 'win32') {
+    return prefix;
+  }
+  const nested = path.join(prefix, 'bin');
+  return exists(nested) ? nested : prefix;
+}
+
+function detectBinDir({
+  platform = process.platform,
+  homedir = os.homedir(),
+  prefix,
+  exists = fs.existsSync,
+  writable = canWrite
+} = {}) {
+  if (prefix === undefined) {
+    prefix = readNpmPrefix(platform);
+  }
+  const localBin = path.join(homedir, '.local', 'bin');
+  const candidates = platform === 'win32'
+    ? [npmBinDir(prefix, platform, exists), localBin]
+    : ['/usr/local/bin', npmBinDir(prefix, platform, exists), localBin];
+
+  for (const dir of candidates) {
+    if (dir && writable(dir)) {
+      return dir;
+    }
+  }
+  throw new Error('找不到可寫入的 bin 目錄。請先確認 npm 可用，或自行把 ~/.local/bin 加進 PATH。');
+}
+
+function installCommand(jsPath, {
+  platform = process.platform,
+  binDir,
+  homedir = os.homedir()
+} = {}) {
+  const resolved = path.resolve(jsPath);
+  const dir = binDir || detectBinDir({ platform, homedir });
+  fs.mkdirSync(dir, { recursive: true });
+
+  if (platform === 'win32') {
+    fs.writeFileSync(path.join(dir, 'birc.cmd'), `@echo off\r\nnode "${resolved}" %*\r\n`);
+    fs.writeFileSync(
+      path.join(dir, 'birc.ps1'),
+      `& node "${resolved.replace(/\\/g, '/')}" @args\n`
+    );
+    return dir;
+  }
+
+  const escaped = resolved.replace(/'/g, `'\\''`);
+  const shim = path.join(dir, 'birc');
+  fs.writeFileSync(
+    shim,
+    `#!/usr/bin/env bash
+_birc_js='${escaped}'
+if command -v cygpath >/dev/null 2>&1; then
+    exec node "$(cygpath -w "$_birc_js")" "$@"
+fi
+exec node "$_birc_js" "$@"
+`
+  );
+  fs.chmodSync(shim, 0o755);
+  return dir;
+}
+
+function spawnOrThrow(command, args, options) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    ...options
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || '').trim();
+    throw new Error(detail || `${command} 結束狀態 ${result.status}`);
+  }
+  return result;
+}
+
+function downloadFile(url, dest, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    const req = https.get(
+      url,
+      { headers: { 'User-Agent': 'birc-generator' } },
+      (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location && redirects < 5) {
+          res.resume();
+          const next = new URL(res.headers.location, url).toString();
+          downloadFile(next, dest, redirects + 1).then(resolve, reject);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          reject(new Error(`下載失敗 HTTP ${res.statusCode}`));
+          return;
+        }
+        const out = fs.createWriteStream(dest);
+        res.pipe(out);
+        out.on('finish', () => out.close((err) => (err ? reject(err) : resolve(dest))));
+        out.on('error', reject);
+      }
+    );
+    req.on('error', reject);
+  });
+}
+
+function moveDir(from, to) {
+  try {
+    fs.renameSync(from, to);
+  } catch (err) {
+    if (err.code !== 'EXDEV') {
+      throw err;
+    }
+    fs.cpSync(from, to, { recursive: true });
+    fs.rmSync(from, { recursive: true, force: true });
+  }
+}
+
+function extractTarball(archive, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+  spawnOrThrow('tar', ['-xzf', archive, '-C', destDir, '--strip-components=1'], {
+    timeout: 60_000
+  });
+}
+
+// 解壓前先驗壓縮檔清單，擋 tar slip。
+function assertSafeTarEntries(archive, listTar = listTarEntries) {
+  const entries = listTar(archive);
+  const unsafe = entries.filter((name) => isUnsafeEntryName(name));
+  if (unsafe.length > 0) {
+    throw new Error(`壓縮檔含不安全的路徑（可能為 tar slip 攻擊），拒絕解壓:\n${unsafe.join('\n')}`);
+  }
+}
+
+function listTarEntries(archive) {
+  const result = spawnSync('tar', ['-tzf', archive], { encoding: 'utf8', timeout: 60_000 });
+  if (result.error || result.status !== 0) {
+    throw new Error('無法讀取下載的壓縮檔內容。');
+  }
+  return String(result.stdout || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+// 任何一段是 .. 都拒絕：第一層若就是 ..，會被 --strip-components=1 剝掉而漏判。
+// strip 只用來抓「剝完變絕對路徑」的名字（如 //x）。
+function isUnsafeEntryName(name) {
+  if (name.split('/').includes('..')) {
+    return true;
+  }
+  if (name.startsWith('/')) {
+    return true;
+  }
+  return name.replace(/^[^/]+\//, '').startsWith('/');
+}
+
+// 符號／硬連結可能指向解壓目錄外；官方 tarball 不該出現，直接拒絕。
+function assertNoLinkEntries(archive) {
+  const result = spawnSync('tar', ['-tvzf', archive], { encoding: 'utf8', timeout: 60_000 });
+  if (result.error || result.status !== 0) {
+    throw new Error('無法讀取下載的壓縮檔內容。');
+  }
+  const links = String(result.stdout || '')
+    .split('\n')
+    .filter((line) => /^[lh]/.test(line.trim()))
+    .join('\n');
+  if (links) {
+    throw new Error(`壓縮檔內含符號或硬連結項目，拒絕解壓:\n${links}`);
+  }
+}
+
+async function confirmCustomBase(baseUrl) {
+  if (baseUrl === DEFAULT_BASE_URL) {
+    return true;
+  }
+  process.stdout.write(`警告：偵測到自訂下載來源 ${baseUrl}\n`);
+  process.stdout.write('會從這個來源下載並執行程式碼，有資安風險。\n');
+  if (process.env.BIRC_ALLOW_CUSTOM_BASE === '1') {
+    process.stdout.write('BIRC_ALLOW_CUSTOM_BASE=1，繼續使用自訂來源\n');
+    return true;
+  }
+  if (!process.stdin.isTTY) {
+    process.stderr.write('非互動環境不接受自訂來源。要強制使用請設 BIRC_ALLOW_CUSTOM_BASE=1。\n');
+    return false;
+  }
+  const readline = require('readline/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await rl.question('確定要從自訂來源更新嗎？(y/N): ');
+    return /^y(es)?$/i.test(String(answer || '').trim());
+  } finally {
+    rl.close();
+  }
+}
+
+function npmInstall(cwd, platform = process.platform) {
+  spawnOrThrow(npmCmd(platform), ['install'], {
+    cwd,
+    stdio: 'inherit',
+    shell: platform === 'win32',
+    timeout: 180_000
+  });
+}
+
+async function updateViaTarball({ installDir, baseUrl = defaultBaseUrl(), platform = process.platform }) {
+  if (!(await confirmCustomBase(baseUrl))) {
+    throw new Error('已取消更新。');
+  }
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), 'birc-update-'));
+  const archive = path.join(staging, 'birc-generator-main.tar.gz');
+  const unpacked = path.join(staging, 'src');
+  process.stdout.write('下載最新版...\n');
+  await downloadFile(`${baseUrl}/-/archive/main/birc-generator-main.tar.gz`, archive);
+  assertNoLinkEntries(archive);
+  assertSafeTarEntries(archive);
+  extractTarball(archive, unpacked);
+  process.stdout.write('安裝依賴...\n');
+  npmInstall(unpacked, platform);
+
+  const backup = `${installDir}.bak`;
+  fs.rmSync(backup, { recursive: true, force: true });
+  if (fs.existsSync(installDir)) {
+    moveDir(installDir, backup);
+  }
+  fs.mkdirSync(path.dirname(installDir), { recursive: true });
+  moveDir(unpacked, installDir);
+  fs.rmSync(staging, { recursive: true, force: true });
+  fs.rmSync(backup, { recursive: true, force: true });
+  return installDir;
+}
+
+async function runUpdate({
+  currentRoot,
+  installDir = defaultInstallDir(),
+  baseUrl = defaultBaseUrl(),
+  platform = process.platform
+} = {}) {
+  const root = currentRoot || installDir;
+  process.stdout.write('更新 birc 到最新版（main）\n');
+  if (fs.existsSync(path.join(root, '.git'))) {
+    process.stdout.write(`用 git pull 更新 ${root}\n`);
+    spawnOrThrow('git', ['-C', root, 'pull', '--ff-only'], { stdio: 'inherit' });
+    npmInstall(root, platform);
+    const binDir = installCommand(path.join(root, 'bin', 'birc.js'), { platform });
+    process.stdout.write(`已安裝指令: ${path.join(binDir, platform === 'win32' ? 'birc.cmd' : 'birc')}\n`);
+    return 0;
+  }
+
+  const dest = await updateViaTarball({ installDir, baseUrl, platform });
+  const binDir = installCommand(path.join(dest, 'bin', 'birc.js'), { platform });
+  process.stdout.write(`已安裝指令: ${path.join(binDir, platform === 'win32' ? 'birc.cmd' : 'birc')}\n`);
+  return 0;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const command = argv[0];
+  if (command === 'install-command') {
+    const jsPath = argv[1];
+    if (!jsPath) {
+      throw new Error('用法: node bin/home-install.js install-command <birc.js 路徑>');
+    }
+    const binDir = installCommand(jsPath);
+    process.stdout.write(`已安裝指令: ${path.join(binDir, process.platform === 'win32' ? 'birc.cmd' : 'birc')}\n`);
+    return 0;
+  }
+  if (command === 'update') {
+    return runUpdate({
+      currentRoot: process.env.BIRC_CURRENT_ROOT,
+      installDir: process.env.BIRC_INSTALL_DIR || defaultInstallDir(),
+      baseUrl: defaultBaseUrl()
+    });
+  }
+  throw new Error('用法: node bin/home-install.js <install-command|update>');
+}
+
+if (require.main === module) {
+  Promise.resolve()
+    .then(() => main())
+    .then((status) => process.exit(status || 0))
+    .catch((err) => {
+      process.stderr.write(`${err.message || err}\n`);
+      process.exit(1);
+    });
+}
+
+module.exports = {
+  DEFAULT_BASE_URL,
+  defaultInstallDir,
+  defaultBaseUrl,
+  detectBinDir,
+  npmBinDir,
+  installCommand,
+  confirmCustomBase,
+  assertSafeTarEntries,
+  assertNoLinkEntries,
+  isUnsafeEntryName,
+  runUpdate,
+  main
+};

package/bin/update-check.js

@@ -0,0 +1,153 @@
+const fs = require('fs');
+const https = require('https');
+const os = require('os');
+const path = require('path');
+
+const pkg = require(path.join(__dirname, '..', 'package.json'));
+
+const NPM_LATEST = `https://registry.npmjs.org/${pkg.name}/latest`;
+const GITLAB_PACKAGE =
+  'https://gitlab.ntubimdbirc.tw/lucashsu95/birc-generator/-/raw/main/package.json';
+const SNOOZE_FILE = path.join(os.homedir(), '.birc-update-check.json');
+const FETCH_TIMEOUT_MS = 2500;
+const MAX_REDIRECTS = 5;
+const SNOOZE_MS = 24 * 60 * 60 * 1000;
+
+// 只跟 https 的 redirect；location 相對於原 URL 解析，解析失敗或降級成
+// http/file 等一律回 null（呼叫端放棄本次版本檢查）。
+function resolveRedirectTarget(base, location) {
+  try {
+    const next = new URL(String(location), base);
+    return next.protocol === 'https:' ? next.toString() : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function compareSemver(a, b) {
+  const left = String(a || '').split('.').map((part) => parseInt(part, 10) || 0);
+  const right = String(b || '').split('.').map((part) => parseInt(part, 10) || 0);
+  const len = Math.max(left.length, right.length, 3);
+  for (let i = 0; i < len; i += 1) {
+    const l = left[i] || 0;
+    const r = right[i] || 0;
+    if (l > r) return 1;
+    if (l < r) return -1;
+  }
+  return 0;
+}
+
+function detectInstallKind(generatorRoot, homedir = os.homedir()) {
+  const root = path.resolve(generatorRoot);
+  if (root.split(path.sep).includes('node_modules')) {
+    return 'npm';
+  }
+  if (root === path.resolve(homedir, '.birc-generator')) {
+    return 'home';
+  }
+  return 'git';
+}
+
+function resolveUpdateMethod(kind) {
+  return kind === 'npm' ? 'npm' : 'home';
+}
+
+function shouldSkipPrompt({ env, tty, command, latest, snooze, now = Date.now() }) {
+  if (env && env.BIRC_SKIP_UPDATE_CHECK === '1') return true;
+  if (!tty) return true;
+  if (command === 'update') return true;
+  if (snooze && latest && snooze.latest === latest && Number(snooze.skippedUntil) > now) {
+    return true;
+  }
+  return false;
+}
+
+function readSnooze() {
+  try {
+    return JSON.parse(fs.readFileSync(SNOOZE_FILE, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeSnooze(latest) {
+  fs.writeFileSync(
+    SNOOZE_FILE,
+    `${JSON.stringify({ latest, skippedUntil: Date.now() + SNOOZE_MS })}\n`
+  );
+}
+
+function fetchJson(url, timeoutMs = FETCH_TIMEOUT_MS, redirects = 0) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    let req;
+    try {
+      req = https.get(
+        url,
+        { timeout: timeoutMs, headers: { 'User-Agent': pkg.name } },
+        (res) => {
+          if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+            res.resume();
+            // 無上限的 redirect 會被拿來打內部網段或把 process 打掛。
+            const next =
+              redirects < MAX_REDIRECTS ? resolveRedirectTarget(url, res.headers.location) : null;
+            if (!next) {
+              finish(null);
+              return;
+            }
+            fetchJson(next, timeoutMs, redirects + 1).then(finish);
+            return;
+          }
+          if (res.statusCode !== 200) {
+            res.resume();
+            finish(null);
+            return;
+          }
+          const chunks = [];
+          res.on('data', (chunk) => chunks.push(chunk));
+          res.on('end', () => {
+            try {
+              finish(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+            } catch (_) {
+              finish(null);
+            }
+          });
+        }
+      );
+    } catch (_) {
+      finish(null);
+      return;
+    }
+    req.on('error', () => finish(null));
+    req.on('timeout', () => {
+      req.destroy();
+      finish(null);
+    });
+  });
+}
+
+async function fetchLatestVersion(kind) {
+  const url = kind === 'npm' ? NPM_LATEST : GITLAB_PACKAGE;
+  const body = await fetchJson(url);
+  const version = body && body.version;
+  return typeof version === 'string' && version ? version : null;
+}
+
+module.exports = {
+  compareSemver,
+  detectInstallKind,
+  resolveUpdateMethod,
+  shouldSkipPrompt,
+  readSnooze,
+  writeSnooze,
+  resolveRedirectTarget,
+  fetchLatestVersion,
+  FETCH_TIMEOUT_MS,
+  MAX_REDIRECTS
+};

package/implement.md

@@ -0,0 +1,76 @@
+# implement
+
+把**已經決定**的工作做成可合併的 diff。不重開計畫、不另提做法。
+
+對齊 [aihero `/implement`](https://www.aihero.dev/skills-implement)：讀 ticket → 在已約定 seam 做 TDD → 跑完整測試 → 人要求時再 commit。一次一張 ticket。
+
+## 跟其它文件
+
+| 先讀 | 再做 |
+| --- | --- |
+| [ponytail](https://github.com/DietrichGebert/ponytail/blob/main/skills/ponytail/SKILL.md) | 決定這次寫哪些檔、寫多短。手感在這裡，不在這份。 |
+| [PROJECT.md](PROJECT.md) | 對齊 seam 與慣例。 |
+| [test.md](test.md) | 步驟走到「寫測試」時打開。怎麼圍、什麼算假綠燈。 |
+
+梯子說「這次不做」的東西，不要為了湊測試硬做。
+
+## 何時用
+
+人叫「照 implement 做」，或把已定案的 ticket / spec 丟過來。計畫還不存在就先問，不要用這份開寫。
+
+## 步驟
+
+### 1. 讀輸入，點名 seam
+
+讀已定案的行為。對照 [PROJECT.md](PROJECT.md) 的 seam 表，寫下要觀察的公開邊界。
+
+完成條件：列得出 seam，沒有順便重做相鄰層。
+
+### 2. 用 ponytail 收斂 diff
+
+能登記 `FEATURES` 就不要新 generator；能接 anchor 就不要重寫整份設定。產出專案慣例改 `project-docs/`，不要抄回這個 repo。
+
+完成條件：預期改動的檔列得完，沒有「以後會用到」的模組。
+
+### 3. 寫測試再寫碼
+
+打法見 [test.md](test.md)。一條紅 → 剛好夠綠 → 下一條。
+
+完成條件：每條新關鍵行為都先紅過再綠。
+
+### 4. 跑完整測試再停
+
+過程只跑正在寫的那一個 `node --test --test-name-pattern=...`。最後跑 `npm run test:coverage`。改到 `bin/cli-util.js` 時再跑 `npm run test:mutation`。
+
+完成條件：完整套件綠、覆蓋率達標。不重開範圍。
+
+### 5. Commit
+
+人要求 commit、或這次明確說「做完並提交」才做。沒說就停在回報。
+
+格式用 Conventional Commits，標題與本文一律中文：
+
+- 類型：`feat:` / `fix:` / `refactor:` / `chore:` / `test:` / `docs:`
+- 標題寫為什麼，一行。本文用編號列做了什麼。
+- 不要加 `Ultraworked by AI`、`Co-authored-by:` 或其它 AI 後綴。
+
+```text
+feat: 新增使用者驗證功能
+
+1. 使用 JWT 實作 Token 管理
+2. 加入密碼強度驗證 (Model Validator)
+3. 補充 Unit Tests，覆蓋率達 85%
+```
+
+完成條件：一筆 commit、類型正確、全文中文、沒有 AI 後綴。
+
+## 回報
+
+```text
+seam: …
+測試檔: …
+圍住: …
+人工突變: 改了 X，Y 測試轉紅
+仍需人看: …
+跳過: …（ponytail 判定不做）
+```