@wwkit/shared 1.0.28 → 1.0.30

package/src/index.js

@@ -1,5 +1,5 @@
-export { createConfigLoader, getXdgConfigDir, deepMerge, resolveEnvVars, resolvePkgVars } from './config-loader.js'
-export { Shell } from './shell.js'
-export { parseProxy, openTunnel, fetchText, downloadToFile } from './http.js'
-export { parseFlags, DEFAULT_BOOLEAN_FLAGS } from './args.js'
+export { createConfigLoader, getXdgConfigDir, deepMerge, resolveEnvVars, resolvePkgVars } from './config-loader.js'
+export { Shell } from './shell.js'
+export { parseProxy, openTunnel, fetchText, downloadToFile } from './http.js'
+export { parseFlags, DEFAULT_BOOLEAN_FLAGS } from './args.js'
 export { default as JSON5 } from 'json5'

package/src/release.js

@@ -1,215 +1,282 @@
-import { execSync } from 'node:child_process'
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-
-// ════════════════════════════ 核心 API ════════════════════════════
-
-// 发布过程错误。stage 标记失败阶段（validate|bump|publish|git）；
-// published=true 表示新版本已上 npm——此时调用方【不得】rollbackVersion，
-// 而应保留版本号并按 repair 命令手动补齐 git 记录（否则下次发布会撞 E403 重复版本）。
-export class ReleaseError extends Error {
-  constructor(message, { stage, published = false, version = null, repair = [] } = {}) {
-    super(message)
-    this.name = 'ReleaseError'
-    this.stage = stage
-    this.published = published
-    this.version = version
-    this.repair = repair
-  }
-}
-
-// patch bump，仅支持稳定版 x.y.z；预发布/异常格式直接抛错（fail-fast）。
-export function bumpPatch(version) {
-  if (!/^\d+\.\d+\.\d+$/.test(String(version))) {
-    throw new Error(`版本号格式不支持自动 bump（需 x.y.z）: ${version}`)
-  }
-  const [major, minor, patch] = version.split('.').map(Number)
-  return `${major}.${minor}.${patch + 1}`
-}
-
-// 发布前检查: git 工作区干净（不干净仅告警）+ npm 已登录（未登录抛出 Error）。
-// pkgDirs 给定时，按各包 publishConfig.registry【去重】逐一检查登录——
-// 发布实际走 publishConfig（如 npmjs.org），而非 .npmrc 里可能指向镜像的默认 registry。
-export function preflight({ pkgDirs = [] } = {}) {
-  const gitStatus = runQuiet('git status --porcelain')
-  if (gitStatus) {
-    console.warn('⚠ Git 工作区不干净（仅告警，继续发布）')
-    console.warn(gitStatus)
-  } else {
-    console.log('  ✓ Git 工作区干净')
-  }
-  const registries = [...new Set(pkgDirs.map(resolvePublishRegistry).filter(Boolean))]
-  const targets = registries.length > 0 ? registries : [null]
-  for (const registry of targets) {
-    const whoamiCmd = registry ? `npm whoami --registry=${registry}` : 'npm whoami'
-    try {
-      const who = runQuiet(whoamiCmd)
-      console.log(`  ✓ npm 已登录: ${who}${registry ? ` (${registry})` : ''}`)
-    } catch {
-      console.error('✗ 未登录 npm，请先执行 npm login')
-      if (registry) console.error(`  (检查的 registry: ${registry})`)
-      throw new Error('npm-not-logged-in')
-    }
-  }
-}
-
-// 发布门禁: 依次在各包目录跑其标准入口 `pnpm run ut`，任一失败返回 false（调用方须中止发布）。
-// dryRun 只打印计划命令，不执行。
-export function runUnitTests(pkgDirs, { dryRun = false } = {}) {
-  console.log('\n━━━ 单元测试（发布门禁） ━━━')
-  for (const pkgDir of pkgDirs) {
-    const { name } = readPackage(pkgDir)
-    if (dryRun) {
-      console.log(`    $ pnpm run ut   # ${name}`)
-      continue
-    }
-    console.log(`▶ ${name}: pnpm run ut`)
-    try {
-      execSync('pnpm run ut', { cwd: pkgDir, stdio: 'inherit' })
-    } catch {
-      console.error(`\n✗ ${name} 单元测试未通过，发布已阻止（修复测试后重试）`)
-      return false
-    }
-  }
-  if (!dryRun) console.log('  ✓ 全部包单元测试通过')
-  return true
-}
-
-// 单包发布: bump patch → publish → commit + scoped tag（不推送）。
-// 成功返回 { name, oldVersion, version, tag }；失败抛出 ReleaseError（含阶段与 published 标记）。
-export function releasePackage({ pkgDir, dryRun = false } = {}) {
-  const { pkgPath, name, version: oldVer } = readPackage(pkgDir)
-  if (!name) throw new ReleaseError(`无法从 ${pkgPath} 读取 name`, { stage: 'validate' })
-  let newVer
-  try {
-    newVer = bumpPatch(oldVer)
-  } catch (e) {
-    throw new ReleaseError(e.message, { stage: 'validate' })
-  }
-
-  console.log(`━━━ 发布 ${name}@${newVer}（原 ${oldVer}）━━━`)
-
-  // 1. bump version (no git tag — scoped tag created manually below)
-  try {
-    run('pnpm version patch --no-git-tag-version --no-git-checks', { cwd: pkgDir, dryRun })
-  } catch {
-    throw new ReleaseError(`${name} 版本号 bump 失败`, { stage: 'bump' })
-  }
-  // 以 bump 后 package.json 的【实际版本】为准（dry-run 未实际 bump，用预测值）
-  const actualVer = dryRun ? newVer : readPackage(pkgDir).version
-  const tag = `${name}@${actualVer}`
-
-  // 2. publish (prepublishOnly hook runs tests automatically)
-  try {
-    run('pnpm publish --no-git-checks', { cwd: pkgDir, dryRun })
-  } catch {
-    throw new ReleaseError(`${name}@${actualVer} 发布失败`, { stage: 'publish', version: actualVer })
-  }
-
-  // 3. commit + scoped tag —— 自此版本已在 npm 上，失败时不得再回滚版本号。
-  //    --only 仅提交该 package.json，避免把用户预先 staged 的无关改动裹进 release commit。
-  const repair = [
-    `git commit --only -m "release ${tag}" -- "${pkgPath}"`,
-    `git tag ${tag}`,
-  ]
-  try {
-    if (!dryRun) {
-      execSync(`git commit --only -m "release ${tag}" -- "${pkgPath}"`, { stdio: 'inherit' })
-      execSync(`git tag ${tag}`, { stdio: 'inherit' })
-    } else {
-      console.log(`    $ ${repair.join(' && ')}`)
-    }
-  } catch {
-    throw new ReleaseError(`${name}@${actualVer} 已发布但 git 记录失败`, {
-      stage: 'git', published: true, version: actualVer, repair,
-    })
-  }
-
-  return { name, oldVersion: oldVer, version: actualVer, tag }
-}
-
-// 回滚 package.json 版本号。仅适用于【未发布】的失败包；
-// 已发布（ReleaseError.published）的包调用本函数会造成 npm 与仓库版本撕裂。
-export function rollbackVersion(pkgDir, { dryRun = false } = {}) {
-  if (dryRun) return
-  try {
-    execSync('git checkout -- package.json', { cwd: pkgDir, stdio: 'pipe' })
-    console.log('  已回滚版本号')
-  } catch {
-    console.warn('  ⚠ 版本号回滚失败，请手动检查该包 package.json')
-  }
-}
-
-// 推送到远端同名分支 + 指定 tag(s)，并追加同步到 alsoBranches（如 develop，HEAD:<branch>）。
-// 返回 true 成功/已打印计划，false 失败或跳过（需手动推）。
-// 推送异常被捕获并打印手动命令，不向上抛裸栈。
-export function pushToRemote(tags, { dryRun = false, alsoBranches = [] } = {}) {
-  console.log('\n━━━ 推送到远端 ━━━')
-
-  let remote
-  try {
-    const remotes = runQuiet('git remote').split('\n').filter(Boolean)
-    remote = remotes.includes('origin') ? 'origin' : remotes[0]
-  } catch {
-    remote = null
-  }
-  if (!remote) {
-    console.error('  ✗ 未配置 git remote，请手动: git push && git push --tags')
-    return false
-  }
-
-  let branch
-  try {
-    branch = runQuiet('git rev-parse --abbrev-ref HEAD')
-  } catch {
-    console.error('  ✗ 无法获取当前分支，请手动: git push && git push --tags')
-    return false
-  }
-
-  const cmds = [`git push ${remote} ${branch}`]
-  if (tags.length > 0) cmds.push(`git push ${remote} ${tags.join(' ')}`)
-  // 额外分支同步（如 develop）：推当前 HEAD 到远端目标分支，跳过与当前分支同名的
-  for (const b of alsoBranches) {
-    if (b && b !== branch) cmds.push(`git push ${remote} HEAD:${b}`)
-  }
-  try {
-    for (const cmd of cmds) run(cmd, { dryRun })
-  } catch {
-    console.error('  ✗ 推送失败，请手动执行:')
-    for (const cmd of cmds) console.error(`    ${cmd}`)
-    return false
-  }
-  if (!dryRun) console.log('  ✓ 推送完成')
-  return true
-}
-
-// ════════════════════════════ 辅助方法 ════════════════════════════
-
-export function readPackage(pkgDir) {
-  const pkgPath = resolve(pkgDir, 'package.json')
-  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
-  return { pkg, pkgPath, name: pkg.name, version: pkg.version }
-}
-
-function runQuiet(cmd, opts = {}) {
-  return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], ...opts }).trim()
-}
-
-function run(cmd, { dryRun = false, ...execOpts } = {}) {
-  if (dryRun) { console.log(`    $ ${cmd}`); return }
-  execSync(cmd, { stdio: 'inherit', ...execOpts })
-}
-
-// 解析实际发布用的 registry：优先 package.json 的 publishConfig.registry，
-// 否则用该目录下 npm 配置的 registry。.npmrc 可能指向镜像，但发布走 publishConfig。
-function resolvePublishRegistry(pkgDir) {
-  try {
-    const { pkg } = readPackage(pkgDir)
-    if (pkg.publishConfig?.registry) return pkg.publishConfig.registry
-  } catch {}
-  try {
-    return runQuiet('npm config get registry', { cwd: pkgDir })
-  } catch {
-    return null
-  }
-}
+import { execSync } from 'node:child_process'
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs'
+import { resolve, join, dirname, basename } from 'node:path'
+
+// ════════════════════════════ 核心 API ════════════════════════════
+
+// 发布过程错误。stage 标记失败阶段（validate|bump|publish|git）；
+// published=true 表示新版本已上 npm——此时调用方【不得】rollbackVersion，
+// 而应保留版本号并按 repair 命令手动补齐 git 记录（否则下次发布会撞 E403 重复版本）。
+export class ReleaseError extends Error {
+  constructor(message, { stage, published = false, version = null, repair = [] } = {}) {
+    super(message)
+    this.name = 'ReleaseError'
+    this.stage = stage
+    this.published = published
+    this.version = version
+    this.repair = repair
+  }
+}
+
+// patch bump，仅支持稳定版 x.y.z；预发布/异常格式直接抛错（fail-fast）。
+export function bumpPatch(version) {
+  if (!/^\d+\.\d+\.\d+$/.test(String(version))) {
+    throw new Error(`版本号格式不支持自动 bump（需 x.y.z）: ${version}`)
+  }
+  const [major, minor, patch] = version.split('.').map(Number)
+  return `${major}.${minor}.${patch + 1}`
+}
+
+// 发布前检查: git 工作区干净（不干净仅告警）+ npm 已登录（未登录抛出 Error）。
+// pkgDirs 给定时，按各包 publishConfig.registry【去重】逐一检查登录——
+// 发布实际走 publishConfig（如 npmjs.org），而非 .npmrc 里可能指向镜像的默认 registry。
+export function preflight({ pkgDirs = [] } = {}) {
+  const gitStatus = runQuiet('git status --porcelain')
+  if (gitStatus) {
+    console.warn('⚠ Git 工作区不干净（仅告警，继续发布）')
+    console.warn(gitStatus)
+  } else {
+    console.log('  ✓ Git 工作区干净')
+  }
+  const registries = [...new Set(pkgDirs.map(resolvePublishRegistry).filter(Boolean))]
+  const targets = registries.length > 0 ? registries : [null]
+  for (const registry of targets) {
+    const whoamiCmd = registry ? `npm whoami --registry=${registry}` : 'npm whoami'
+    try {
+      const who = runQuiet(whoamiCmd)
+      console.log(`  ✓ npm 已登录: ${who}${registry ? ` (${registry})` : ''}`)
+    } catch {
+      console.error('✗ 未登录 npm，请先执行 npm login')
+      if (registry) console.error(`  (检查的 registry: ${registry})`)
+      throw new Error('npm-not-logged-in')
+    }
+  }
+}
+
+// 发布门禁: 依次在各包目录跑其标准入口 `pnpm run ut`，任一失败返回 false（调用方须中止发布）。
+// dryRun 只打印计划命令，不执行。
+export function runUnitTests(pkgDirs, { dryRun = false } = {}) {
+  console.log('\n━━━ 单元测试（发布门禁） ━━━')
+  for (const pkgDir of pkgDirs) {
+    const { name } = readPackage(pkgDir)
+    if (dryRun) {
+      console.log(`    $ pnpm run ut   # ${name}`)
+      continue
+    }
+    console.log(`▶ ${name}: pnpm run ut`)
+    try {
+      execSync('pnpm run ut', { cwd: pkgDir, stdio: 'inherit' })
+    } catch {
+      console.error(`\n✗ ${name} 单元测试未通过，发布已阻止（修复测试后重试）`)
+      return false
+    }
+  }
+  if (!dryRun) console.log('  ✓ 全部包单元测试通过')
+  return true
+}
+
+// ════════════════════════════ 发布日志 ════════════════════════════
+
+// 创建 release 日志收集器。close() 时写入 <root>/logs/release/<dirName>/<version>-<timestamp>.log。
+// dryRun 时不写文件（返回 no-op close）。在 releasePackage 内部使用，记录各阶段命令与结果。
+export function createReleaseLog(pkgDir, version, { dryRun = false } = {}) {
+  const start = new Date()
+  const lines = [
+    '# Release Log',
+    `# 包目录: ${pkgDir}`,
+    `# 目标版本: ${version}`,
+    `# 开始时间: ${start.toISOString()}`,
+    '',
+  ]
+  const ts = () => new Date().toISOString()
+  return {
+    section(title) { lines.push('', `── ${title} ──`) },
+    log(msg) { lines.push(`[${ts()}] ${msg}`) },
+    close({ success = true, error = null } = {}) {
+      if (dryRun) return null
+      const end = new Date()
+      lines.push(
+        '',
+        `# 结束时间: ${end.toISOString()}`,
+        `# 耗时: ${((end - start) / 1000).toFixed(1)}s`,
+        `# 结果: ${success ? '成功' : '失败'}`,
+      )
+      if (error) lines.push(`# 错误: ${error}`)
+      const root = findMonorepoRoot(pkgDir)
+      const dirName = basename(pkgDir)
+      const stamp = formatTimestamp(start)
+      const logPath = join(root, 'logs', 'release', dirName, `${version}-${stamp}.log`)
+      mkdirSync(dirname(logPath), { recursive: true })
+      writeFileSync(logPath, lines.join('\n') + '\n', 'utf-8')
+      return logPath
+    },
+  }
+}
+
+function findMonorepoRoot(dir) {
+  let d = dir
+  for (let i = 0; i < 10; i++) {
+    if (existsSync(join(d, 'pnpm-workspace.yaml'))) return d
+    d = dirname(d)
+  }
+  return dir
+}
+
+function formatTimestamp(d) {
+  const p = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+}
+
+// 单包发布: bump patch → publish → commit + scoped tag（不推送）。
+// 成功返回 { name, oldVersion, version, tag }；失败抛出 ReleaseError（含阶段与 published 标记）。
+export function releasePackage({ pkgDir, dryRun = false } = {}) {
+  const { pkgPath, name, version: oldVer } = readPackage(pkgDir)
+  if (!name) throw new ReleaseError(`无法从 ${pkgPath} 读取 name`, { stage: 'validate' })
+  let newVer
+  try {
+    newVer = bumpPatch(oldVer)
+  } catch (e) {
+    throw new ReleaseError(e.message, { stage: 'validate' })
+  }
+
+  console.log(`━━━ 发布 ${name}@${newVer}（原 ${oldVer}）━━━`)
+
+  const log = createReleaseLog(pkgDir, newVer, { dryRun })
+  log.section(`发布 ${name}@${newVer}（原 ${oldVer}）`)
+
+  // 1. bump version (no git tag — scoped tag created manually below)
+  log.log('阶段 1/3: bump version')
+  try {
+    run('pnpm version patch --no-git-tag-version --no-git-checks', { cwd: pkgDir, dryRun })
+    log.log('bump 完成')
+  } catch {
+    log.close({ success: false, error: 'bump 失败' })
+    throw new ReleaseError(`${name} 版本号 bump 失败`, { stage: 'bump' })
+  }
+  // 以 bump 后 package.json 的【实际版本】为准（dry-run 未实际 bump，用预测值）
+  const actualVer = dryRun ? newVer : readPackage(pkgDir).version
+  const tag = `${name}@${actualVer}`
+
+  // 2. publish (prepublishOnly hook runs tests automatically)
+  log.log('阶段 2/3: publish')
+  try {
+    run('pnpm publish --no-git-checks', { cwd: pkgDir, dryRun })
+    log.log(`publish 完成: ${tag}`)
+  } catch {
+    log.close({ success: false, error: `publish 失败: ${tag}` })
+    throw new ReleaseError(`${name}@${actualVer} 发布失败`, { stage: 'publish', version: actualVer })
+  }
+
+  // 3. commit + scoped tag —— 自此版本已在 npm 上，失败时不得再回滚版本号。
+  //    --only 仅提交该 package.json，避免把用户预先 staged 的无关改动裹进 release commit。
+  log.log('阶段 3/3: git commit + tag')
+  const repair = [
+    `git commit --only -m "release ${tag}" -- "${pkgPath}"`,
+    `git tag ${tag}`,
+  ]
+  try {
+    if (!dryRun) {
+      execSync(`git commit --only -m "release ${tag}" -- "${pkgPath}"`, { stdio: 'inherit' })
+      execSync(`git tag ${tag}`, { stdio: 'inherit' })
+      log.log(`git commit + tag 完成: ${tag}`)
+    } else {
+      console.log(`    $ ${repair.join(' && ')}`)
+      log.log(`[dry-run] ${repair.join(' && ')}`)
+    }
+  } catch {
+    log.close({ success: false, error: `git 记录失败（版本已上 npm）: ${tag}` })
+    throw new ReleaseError(`${name}@${actualVer} 已发布但 git 记录失败`, {
+      stage: 'git', published: true, version: actualVer, repair,
+    })
+  }
+
+  const logPath = log.close({ success: true })
+  if (logPath) console.log(`  📄 日志: ${logPath}`)
+  return { name, oldVersion: oldVer, version: actualVer, tag }
+}
+
+// 回滚 package.json 版本号。仅适用于【未发布】的失败包；
+// 已发布（ReleaseError.published）的包调用本函数会造成 npm 与仓库版本撕裂。
+export function rollbackVersion(pkgDir, { dryRun = false } = {}) {
+  if (dryRun) return
+  try {
+    execSync('git checkout -- package.json', { cwd: pkgDir, stdio: 'pipe' })
+    console.log('  已回滚版本号')
+  } catch {
+    console.warn('  ⚠ 版本号回滚失败，请手动检查该包 package.json')
+  }
+}
+
+// 推送到远端同名分支 + 指定 tag(s)，并追加同步到 alsoBranches（如 develop，HEAD:<branch>）。
+// 返回 true 成功/已打印计划，false 失败或跳过（需手动推）。
+// 推送异常被捕获并打印手动命令，不向上抛裸栈。
+export function pushToRemote(tags, { dryRun = false, alsoBranches = [] } = {}) {
+  console.log('\n━━━ 推送到远端 ━━━')
+
+  let remote
+  try {
+    const remotes = runQuiet('git remote').split('\n').filter(Boolean)
+    remote = remotes.includes('origin') ? 'origin' : remotes[0]
+  } catch {
+    remote = null
+  }
+  if (!remote) {
+    console.error('  ✗ 未配置 git remote，请手动: git push && git push --tags')
+    return false
+  }
+
+  let branch
+  try {
+    branch = runQuiet('git rev-parse --abbrev-ref HEAD')
+  } catch {
+    console.error('  ✗ 无法获取当前分支，请手动: git push && git push --tags')
+    return false
+  }
+
+  const cmds = [`git push ${remote} ${branch}`]
+  if (tags.length > 0) cmds.push(`git push ${remote} ${tags.join(' ')}`)
+  // 额外分支同步（如 develop）：推当前 HEAD 到远端目标分支，跳过与当前分支同名的
+  for (const b of alsoBranches) {
+    if (b && b !== branch) cmds.push(`git push ${remote} HEAD:${b}`)
+  }
+  try {
+    for (const cmd of cmds) run(cmd, { dryRun })
+  } catch {
+    console.error('  ✗ 推送失败，请手动执行:')
+    for (const cmd of cmds) console.error(`    ${cmd}`)
+    return false
+  }
+  if (!dryRun) console.log('  ✓ 推送完成')
+  return true
+}
+
+// ════════════════════════════ 辅助方法 ════════════════════════════
+
+export function readPackage(pkgDir) {
+  const pkgPath = resolve(pkgDir, 'package.json')
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+  return { pkg, pkgPath, name: pkg.name, version: pkg.version }
+}
+
+function runQuiet(cmd, opts = {}) {
+  return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], ...opts }).trim()
+}
+
+function run(cmd, { dryRun = false, ...execOpts } = {}) {
+  if (dryRun) { console.log(`    $ ${cmd}`); return }
+  execSync(cmd, { stdio: 'inherit', ...execOpts })
+}
+
+// 解析实际发布用的 registry：优先 package.json 的 publishConfig.registry，
+// 否则用该目录下 npm 配置的 registry。.npmrc 可能指向镜像，但发布走 publishConfig。
+function resolvePublishRegistry(pkgDir) {
+  try {
+    const { pkg } = readPackage(pkgDir)
+    if (pkg.publishConfig?.registry) return pkg.publishConfig.registry
+  } catch {}
+  try {
+    return runQuiet('npm config get registry', { cwd: pkgDir })
+  } catch {
+    return null
+  }
+}