@manohub/app-kit 0.1.0 → 0.2.0

package/skills/install.mjs

@@ -0,0 +1,203 @@
+/**
+ * 技能安装器：把随本包分发的 AI 技能落到消费方的技能目录。
+ *
+ * 用法（消费方工程根执行）：
+ *   node node_modules/@manohub/app-kit/skills/install.mjs
+ *   node node_modules/@manohub/app-kit/skills/install.mjs --also-claude
+ *   node node_modules/@manohub/app-kit/skills/install.mjs --target .x/skills
+ *   node node_modules/@manohub/app-kit/skills/install.mjs --dry-run
+ *
+ * 设计取舍：
+ *
+ * 1. **幂等**：每个技能「先删同名目录再整体复制」。包升级后重跑一次即刷新到新版内容，
+ *    不存在「旧文件残留」或「同名合并」的中间态。
+ * 2. **越界保护**：只允许操作 `SKILL_NAMES` 白名单内的目录名，且目标必须是白名单目录的**直接子路径**。
+ *    删除动作因此永远不可能落到用户自己的技能或其它文件上。
+ * 3. **零依赖 + 纯函数**：判定与计划部分抽成纯函数并由 `__tests__/skills-install.test.mjs`
+ *    做故障注入测试（一个对坏输入不报警的安装器等于没有安装器），落盘动作只在直接执行时发生。
+ * 4. 只复制**技能目录**，跳过本文件与 `README.md`（那是给包维护者看的），也不复制 `__tests__`。
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+/** 本技能包管理的技能目录名（白名单：只有这些名字允许被创建或清理） */
+export const SKILL_NAMES = ['app-kit', 'app-kit-migrate', 'app-kit-dev']
+
+/** 缺省的技能目录（相对消费方工程根） */
+export const TARGET_CODEXBUDDY = ['.codebuddy', 'skills']
+export const TARGET_CLAUDE = ['.claude', 'skills']
+
+/** 把源目录里「名字在白名单内、且含 SKILL.md」的目录识别为可安装技能 */
+export function listSourceSkills(sourceDir) {
+  return SKILL_NAMES.filter((name) => {
+    const dir = join(sourceDir, name)
+    return existsSync(dir) && statSync(dir).isDirectory() && existsSync(join(dir, 'SKILL.md'))
+  })
+}
+
+/** 目标目录安全校验：不允许写到文件系统根（`/`、`C:\`） */
+export function assertSafeTarget(targetDir) {
+  const resolved = resolve(targetDir)
+  if (resolved === dirname(resolved)) {
+    throw new Error(`拒绝写入文件系统根目录：${resolved}`)
+  }
+  return resolved
+}
+
+/** 越界保护：`path` 必须是 `targetDir` 的直接子路径，且名字在白名单内 */
+export function assertManagedPath(targetDir, path) {
+  const target = assertSafeTarget(targetDir)
+  const name = basename(path)
+  if (!SKILL_NAMES.includes(name)) {
+    throw new Error(`拒绝操作白名单外的目录：${path}`)
+  }
+  if (dirname(resolve(path)) !== target) {
+    throw new Error(`拒绝操作目标目录之外的路径：${path}`)
+  }
+  return join(target, name)
+}
+
+/**
+ * 解析命令行参数。未知参数直接报错 —— 静默忽略会让人以为选项生效了。
+ * （不参与单测的 IO，纯字符串处理）
+ */
+export function parseArgs(argv) {
+  const opts = { target: null, alsoClaude: false, dryRun: false, help: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--target') {
+      const value = argv[i + 1]
+      if (!value || value.startsWith('--')) throw new Error('--target 需要一个目录参数')
+      opts.target = value
+      i += 1
+    } else if (arg === '--also-claude') {
+      opts.alsoClaude = true
+    } else if (arg === '--dry-run') {
+      opts.dryRun = true
+    } else if (arg === '--help' || arg === '-h') {
+      opts.help = true
+    } else {
+      throw new Error(`未知参数：${arg}（用 --help 看用法）`)
+    }
+  }
+  return opts
+}
+
+/** 计算落盘目标目录：默认 `.codebuddy/skills`，`--target` 优先，`--also-claude` 追加 */
+export function resolveTargets({ cwd, target = null, alsoClaude = false }) {
+  if (target) {
+    const resolved = isAbsolute(target) ? target : join(cwd, target)
+    return [assertSafeTarget(resolved)]
+  }
+  const targets = [assertSafeTarget(join(cwd, ...TARGET_CODEXBUDDY))]
+  if (alsoClaude) targets.push(assertSafeTarget(join(cwd, ...TARGET_CLAUDE)))
+  return targets
+}
+
+/** 统计目录下的文件数（用于落盘摘要） */
+export function countFiles(dir) {
+  let total = 0
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    total += entry.isDirectory() ? countFiles(join(dir, entry.name)) : 1
+  }
+  return total
+}
+
+/** 生成安装计划（不落盘）；源目录里一个技能都没有时直接报错 */
+export function planInstall({ sourceDir, targetDirs }) {
+  if (!existsSync(sourceDir)) throw new Error(`技能源目录不存在：${sourceDir}`)
+  const skills = listSourceSkills(sourceDir)
+  if (skills.length === 0) {
+    throw new Error(`技能源目录里没有可安装的技能（期望 ${SKILL_NAMES.join(' / ')}）：${sourceDir}`)
+  }
+  if (targetDirs.length === 0) throw new Error('没有解析出任何目标目录')
+
+  const actions = []
+  for (const target of targetDirs) {
+    for (const skill of skills) {
+      const from = join(sourceDir, skill)
+      const to = join(assertSafeTarget(target), skill)
+      assertManagedPath(target, to)
+      actions.push({ skill, from, to, files: countFiles(from) })
+    }
+  }
+  return { sourceDir, targetDirs, skills, actions }
+}
+
+/** 落盘（`dryRun` 时只返回计划结果，不写文件系统） */
+export function applyInstall(plan, { dryRun = false } = {}) {
+  const results = []
+  for (const action of plan.actions) {
+    if (!dryRun) {
+      mkdirSync(dirname(action.to), { recursive: true })
+      // 先清理再复制：保证与包内内容完全一致（幂等）
+      rmSync(action.to, { recursive: true, force: true })
+      cpSync(action.from, action.to, { recursive: true })
+    }
+    results.push({ ...action, dryRun })
+  }
+  return results
+}
+
+export function usage() {
+  return [
+    '把 @manohub/app-kit 随包的 AI 技能安装到本工程的技能目录。',
+    '',
+    '用法：',
+    '  node node_modules/@manohub/app-kit/skills/install.mjs [选项]',
+    '',
+    '选项：',
+    '  --target <dir>    指定目标目录（缺省 <cwd>/.codebuddy/skills）',
+    '  --also-claude     同时安装到 <cwd>/.claude/skills',
+    '  --dry-run         只打印将要落盘的内容，不写文件系统',
+    '  --help, -h        显示本帮助',
+    '',
+    `管理的技能：${SKILL_NAMES.join(' / ')}（安装时先清理同名目录再复制，可反复执行）`,
+  ].join('\n')
+}
+
+function printSummary(results, plan, dryRun) {
+  const lines = ['[app-kit 技能安装]', `  源：${plan.sourceDir}`, `  技能：${plan.skills.join('、')}`]
+  for (const target of plan.targetDirs) {
+    lines.push(`  目标：${target}`)
+  }
+  for (const item of results) {
+    lines.push(`    ${dryRun ? '将写入' : '已写入'} ${item.to}（${item.files} 个文件）`)
+  }
+  if (dryRun) {
+    lines.push('  dry-run：未落盘，去掉 --dry-run 执行实际安装')
+  } else {
+    lines.push('  完成：技能目录已与包内内容对齐（包升级后重跑本命令即刷新）')
+  }
+  console.log(lines.join('\n'))
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2))
+  if (opts.help) {
+    console.log(usage())
+    return
+  }
+
+  const sourceDir = dirname(fileURLToPath(import.meta.url))
+  const targetDirs = resolveTargets({ cwd: process.cwd(), target: opts.target, alsoClaude: opts.alsoClaude })
+
+  let plan
+  try {
+    plan = planInstall({ sourceDir, targetDirs })
+  } catch (error) {
+    console.error(`[app-kit 技能安装] 失败：${error.message}`)
+    process.exitCode = 1
+    return
+  }
+
+  const results = applyInstall(plan, { dryRun: opts.dryRun })
+  printSummary(results, plan, opts.dryRun)
+}
+
+// 仅在被直接执行时落盘；被测试 import 时只取纯函数
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
+if (isDirectRun) {
+  await main()
+}