create-dwy 0.16.1 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # create-dwy
 
+## 0.17.1
+
+### Patch Changes
+
+- `dwy --help` 正式列出 `dwy skills install` / `dwy skills --help`，不再标成隐藏命令。`dwy skills` 无参数时打印 skills 子命令说明。
+
+---
+
+## 0.17.0
+
+### Minor Changes
+
+- `dwy` 交互同步开头增加「同步范围」：完整同步（默认）或仅 Skills。仅 Skills 不写、不删 Rules / Commands / Hooks。
+- 最后增加「Skill 同步位置」：默认仅项目目录；可另选 Claude / Grok / Codex / Cursor / OpenCode 全局目录，并勾选要额外拷贝的 skill。只覆盖点名 skill，不删用户 home 里其它个人 skill。选择写入 `/.dwy/sync-state.json` 的 `skillScope` / `syncMode`。
+
+---
+
 ## 0.16.1
 
 ### Patch Changes

package/bin/index.js

@@ -5,36 +5,40 @@ import { fileURLToPath } from 'url'
 import { dirname, resolve } from 'path'
 import { syncAll } from '../src/sync-all.js'
 import { installSkills } from '../src/skills-install.js'
+import { buildHelpText, buildSkillsHelpText } from '../src/cli-help.js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkg = JSON.parse(readFileSync(resolve(__dirname, '..', 'package.json'), 'utf-8'))
 const argv = process.argv.slice(2)
 
+/** 是否请求帮助（含 -h / --help / help） */
+function wantsHelp(args) {
+  return args.includes('--help') || args.includes('-h') || args[0] === 'help'
+}
+
 function printHelp() {
-  const lines = [
-    `dwy ${pkg.version}`,
-    '',
-    'Usage:',
-    '  dwy               运行交互式同步（自动更新全局外部 skill）',
-    '  dwy --help        显示本说明',
-    '  dwy -h            显示本说明',
-    '  dwy --version     显示当前版本',
-    '  dwy -V            显示当前版本',
-    '',
-    '以下为隐藏命令（向后兼容保留，日常无需手动调用）：',
-    '  dwy sync          同上的别名',
-    '  dwy skills install  强制刷新全局外部 skill',
-    '',
-  ]
-  console.log(lines.join('\n'))
+  console.log(buildHelpText(pkg.version))
+}
+
+function printSkillsHelp() {
+  console.log(buildSkillsHelpText())
 }
 
-if (argv.includes('--help') || argv.includes('-h') || argv[0] === 'help') {
+if (argv[0] === 'skills') {
+  const rest = argv.slice(1)
+  if (rest.length === 0 || wantsHelp(rest) || rest[0] === 'help') {
+    printSkillsHelp()
+  } else if (rest[0] === 'install') {
+    await installSkills()
+  } else {
+    console.error(`未知命令: dwy skills ${rest.join(' ')}`)
+    printSkillsHelp()
+    process.exitCode = 1
+  }
+} else if (wantsHelp(argv)) {
   printHelp()
 } else if (argv.includes('--version') || argv.includes('-V')) {
   console.log(pkg.version)
-} else if (argv[0] === 'skills' && argv[1] === 'install') {
-  await installSkills()
 } else if (argv.length === 0 || argv[0] === 'sync') {
   await syncAll()
 } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dwy",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "description": "项目脚手架与多平台 AI 配置同步工具",
   "type": "module",
   "bin": {

package/src/cli-help.js

@@ -0,0 +1,44 @@
+/**
+ * dwy 命令行帮助文案。
+ * 已实现的入口必须出现在这里；禁止把可用命令藏进「隐藏」段。
+ */
+
+/**
+ * 主帮助：`dwy --help`。
+ * version 来自 package.json，调用方传入，避免本模块读盘。
+ *
+ * @param {string} version
+ */
+export function buildHelpText(version) {
+  return [
+    `dwy ${version}`,
+    '',
+    'Usage:',
+    '  dwy                  交互同步：选范围（完整/仅 Skills）、平台、skill 落点',
+    '  dwy sync             同上',
+    '  dwy skills install   强制刷新全局外部 skill 到 ~/.dwy/skills',
+    '  dwy skills --help    显示 skills 子命令',
+    '  dwy --help           显示本说明',
+    '  dwy -h               显示本说明',
+    '  dwy --version        显示当前版本',
+    '  dwy -V               显示当前版本',
+    '',
+    'Skills:',
+    '  dwy skills install   按清单安装/覆盖更新 pm-skills、superpowers（一台机一份）',
+    '',
+  ].join('\n')
+}
+
+/**
+ * skills 子命令帮助：`dwy skills` / `dwy skills --help`。
+ */
+export function buildSkillsHelpText() {
+  return [
+    'dwy skills',
+    '',
+    'Usage:',
+    '  dwy skills install   强制刷新全局外部 skill 到 ~/.dwy/skills',
+    '  dwy skills --help    显示本说明',
+    '',
+  ].join('\n')
+}

package/src/sync-all.js

@@ -1,7 +1,15 @@
 import fs from 'fs-extra'
 import path from 'path'
 import { confirm, isCancel } from '@clack/prompts'
-import { SEARCH_PLACEHOLDER, searchableMultiselect } from './searchable-select.js'
+import { SEARCH_PLACEHOLDER, searchableMultiselect, searchableSelect } from './searchable-select.js'
+import {
+  DEFAULT_SKILL_DESTINATIONS,
+  copySkillsToGlobalDirs,
+  copySkillsToProjectPlatforms,
+  listSkillDestOptions,
+  normalizeSkillScope,
+  resolveProjectSkillDir,
+} from './sync-global-skills.js'
 import { chalk } from './utils.js'
 import {
   interactiveSelect,
@@ -55,6 +63,24 @@ const TYPE_LABELS = {
   hooks: 'hooks',
 }
 
+/** 完整同步：skills / rules / commands / hooks 都走平台写入 */
+export const SYNC_MODE_ALL = 'all'
+/** 仅 Skills：不写、不删 rules / commands / hooks */
+export const SYNC_MODE_SKILLS = 'skills'
+export const DEFAULT_SYNC_MODE = SYNC_MODE_ALL
+
+const SKILL_ONLY_CATEGORIES = [{ key: 'skills', label: 'Skills' }]
+
+/**
+ * 规范化同步范围。未知值回退完整同步，避免误进仅 Skills 删不该删的东西。
+ *
+ * @param {unknown} raw
+ * @returns {'all' | 'skills'}
+ */
+export function normalizeSyncMode(raw) {
+  return raw === SYNC_MODE_SKILLS ? SYNC_MODE_SKILLS : DEFAULT_SYNC_MODE
+}
+
 function unionSets(...sets) {
   return new Set(sets.flatMap(set => [...set]))
 }
@@ -144,6 +170,132 @@ export async function buildPlatformDefaultsFromLocalState(projectDir) {
   return defaults.length > 0 ? defaults : ['claude', 'codex']
 }
 
+/**
+ * 开头选同步范围。仅 Skills 时后面不再问 rules / commands / hooks。
+ *
+ * @param {'all' | 'skills'} initialValue
+ * @returns {Promise<'all' | 'skills' | null>}
+ */
+async function promptSyncMode(initialValue) {
+  const result = await searchableSelect({
+    message: '选择同步范围',
+    options: [
+      {
+        value: SYNC_MODE_ALL,
+        label: '完整同步',
+        description: '同步 Skills / Rules / Commands / Hooks',
+      },
+      {
+        value: SYNC_MODE_SKILLS,
+        label: '仅 Skills',
+        description: '只处理 skill，不改动已有 Rules / Commands / Hooks',
+      },
+    ],
+    initialValue,
+    placeholder: SEARCH_PLACEHOLDER,
+  })
+  if (isCancel(result)) return null
+  return normalizeSyncMode(result)
+}
+
+/**
+ * 仅 Skills 模式：只写项目/全局 skill，并清理未选中的模板 skill。
+ * 禁止调用完整平台 sync，否则空 rules/commands 会删掉项目已有项。
+ *
+ * @param {{ projectDir: string, selectedPlatforms: string[], skills: Array<{ name: string, sourcePath: string }>, templateSkillNames: Set<string>, staleSkillNames: Set<string>, skillScope: { destinations: string[] } }} opts
+ */
+async function syncSkillsOnly({
+  projectDir,
+  selectedPlatforms,
+  skills,
+  templateSkillNames,
+  staleSkillNames,
+  skillScope,
+}) {
+  const writeProject = skillScope.destinations.includes('project')
+  if (!writeProject) return
+
+  const skillPlatforms = selectedPlatforms.filter(platform => resolveProjectSkillDir(projectDir, platform))
+  if (skillPlatforms.length === 0) {
+    console.log(chalk.yellow('已选平台不支持项目内 skills，跳过项目写入。'))
+    return
+  }
+
+  console.log(chalk.blue('\nSyncing skills only (rules / commands / hooks untouched)...\n'))
+  await copySkillsToProjectPlatforms({
+    projectDir,
+    platforms: skillPlatforms,
+    skills,
+  })
+
+  const selectedNames = new Set(skills.map(item => item.name))
+  const toRemove = new Set(
+    [...templateSkillNames, ...staleSkillNames].filter(name => !selectedNames.has(name)),
+  )
+  for (const platform of skillPlatforms) {
+    const destRoot = resolveProjectSkillDir(projectDir, platform)
+    const existingNames = await scanExisting(path.dirname(destRoot), 'skills')
+    await removeManagedItems(
+      destRoot,
+      existingNames,
+      toRemove,
+      path.relative(projectDir, destRoot),
+    )
+  }
+}
+
+/**
+ * 交互最后一步：选 skill 同步位置，默认仅项目。
+ * 勾了全局 dest 后再问哪些 skill 额外拷到全局；不删用户 home 里其它 skill。
+ *
+ * @param {{ selectedSkills: Array<{ name: string }>, syncState: { skillScope?: object } }} args
+ * @returns {Promise<{ destinations: string[], globalSkills: string[] } | null>}
+ */
+async function promptSkillScope({ selectedSkills, syncState }) {
+  const previous = normalizeSkillScope(syncState.skillScope)
+  const destInitial = previous.destinations.length > 0
+    ? previous.destinations
+    : [...DEFAULT_SKILL_DESTINATIONS]
+
+  console.log(chalk.gray('\nSkill 默认同步到项目目录。勾选全局目录可把部分 skill 额外拷到本机 home。'))
+
+  const destResult = await searchableMultiselect({
+    message: '选择 skill 同步位置（默认项目）',
+    options: listSkillDestOptions(),
+    initialValues: destInitial,
+    required: true,
+    maxItems: 8,
+    placeholder: SEARCH_PLACEHOLDER,
+  })
+  if (isCancel(destResult)) return null
+
+  const destinations = destResult
+  const globalDests = destinations.filter(id => id !== 'project')
+  if (globalDests.length === 0 || selectedSkills.length === 0) {
+    return { destinations, globalSkills: [] }
+  }
+
+  const selectedNames = selectedSkills.map(item => item.name)
+  const globalInitial = previous.globalSkills.filter(name => selectedNames.includes(name))
+  const globalResult = await searchableMultiselect({
+    message: '哪些 skill 额外同步到全局？',
+    options: selectedSkills.map(item => ({
+      value: item.name,
+      label: item.name,
+      description: item.description,
+    })),
+    initialValues: globalInitial,
+    required: false,
+    placeholder: SEARCH_PLACEHOLDER,
+  })
+  if (isCancel(globalResult)) return null
+
+  return {
+    destinations,
+    globalSkills: globalResult,
+  }
+}
+
 async function selectPlatforms(projectDir) {
   const initialValues = await buildPlatformDefaultsFromLocalState(projectDir)
 
@@ -197,6 +349,8 @@ async function loadSyncState(projectDir) {
     return {
       version: 1,
       platforms: {},
+      skillScope: normalizeSkillScope(undefined),
+      syncMode: DEFAULT_SYNC_MODE,
     }
   }
 
@@ -204,6 +358,8 @@ async function loadSyncState(projectDir) {
   return {
     version: 1,
     platforms: state.platforms || {},
+    skillScope: normalizeSkillScope(state.skillScope),
+    syncMode: normalizeSyncMode(state.syncMode),
   }
 }
 
@@ -328,6 +484,19 @@ async function promptStaleRemovals(staleEntries) {
   return approvals
 }
 
+/**
+ * 仅 Skills 模式：陈旧项提示只保留 skills，避免问 rules/commands/hooks。
+ *
+ * @param {Record<string, Record<string, string[]>>} staleEntries
+ */
+function retainSkillStaleEntries(staleEntries) {
+  const next = createEmptyRemovalState()
+  for (const [platform, types] of Object.entries(staleEntries)) {
+    if (types.skills?.length) next[platform] = { skills: types.skills }
+  }
+  return next
+}
+
 function getPreservedStaleNames(staleEntries, approvedRemovals, platform, type) {
   const staleNames = staleEntries[platform]?.[type] || []
   const approvedNames = approvedRemovals[platform]?.[type] || new Set()
@@ -556,6 +725,12 @@ export async function syncAll({
   selected: selectedOverride,
   selectedPlatforms: selectedPlatformsOverride,
   staleRemovals: staleRemovalsOverride,
+  // 测试/脚本可注入；交互模式在平台选择之后再问
+  skillScope: skillScopeOverride,
+  // all = 完整同步；skills = 只写 skill，测试/脚本可注入
+  syncMode: syncModeOverride,
+  // 全局 skill 写入的 home，测试注入假目录，禁止默认写真实 $HOME
+  homeDir,
 } = {}) {
   const sourceDir = sourceDirOverride || await resolveSourceDir()
   if (!await fs.pathExists(sourceDir)) {
@@ -605,7 +780,20 @@ export async function syncAll({
     console.log(chalk.gray('首次同步，进入交互式选择...\n'))
   }
 
-  const selected = selectedOverride || await interactiveSelect(scans, selectionDefaults)
+  const skipInteractive = !!(selectedOverride || selectedPlatformsOverride)
+  const syncMode = syncModeOverride
+    ? normalizeSyncMode(syncModeOverride)
+    : (skipInteractive
+      ? normalizeSyncMode(syncState.syncMode)
+      : await promptSyncMode(normalizeSyncMode(syncState.syncMode)))
+  if (syncMode === null) {
+    console.log(chalk.yellow('\n已取消同步。'))
+    return
+  }
+
+  const selected = selectedOverride || await interactiveSelect(scans, selectionDefaults, {
+    categories: syncMode === SYNC_MODE_SKILLS ? SKILL_ONLY_CATEGORIES : undefined,
+  })
   if (selected === null) {
     console.log(chalk.yellow('\n已取消同步。'))
     return
@@ -617,7 +805,10 @@ export async function syncAll({
     return
   }
 
-  const staleEntries = await collectStaleEntries(projectDir, scans, syncState, selectedPlatforms)
+  const staleEntriesRaw = await collectStaleEntries(projectDir, scans, syncState, selectedPlatforms)
+  const staleEntries = syncMode === SYNC_MODE_SKILLS
+    ? retainSkillStaleEntries(staleEntriesRaw)
+    : staleEntriesRaw
   const approvedStaleRemovals = staleRemovalsOverride
     ? normalizeRemovalInput(staleRemovalsOverride)
     : await promptStaleRemovals(staleEntries)
@@ -626,79 +817,132 @@ export async function syncAll({
     return
   }
 
+  const skillScope = skillScopeOverride
+    ? normalizeSkillScope(skillScopeOverride)
+    : (selectedOverride
+      ? normalizeSkillScope(syncState.skillScope)
+      : await promptSkillScope({ selectedSkills: selected.skills || [], syncState }))
+  if (skillScope === null) {
+    console.log(chalk.yellow('\n已取消同步。'))
+    return
+  }
+
+  const selectedSkillNames = new Set((selected.skills || []).map(item => item.name))
+  const skillsToWrite = scans.skills.filter(item => selectedSkillNames.has(item.name))
   let syncedAnySupportedPlatform = false
 
-  if (selectedPlatforms.includes('claude')) {
-    syncedAnySupportedPlatform = true
-    console.log(chalk.blue('\nSyncing Claude Code configuration...\n'))
-    await syncClaude({
-      sourceDir,
+  if (syncMode === SYNC_MODE_SKILLS) {
+    const staleSkillNames = new Set()
+    for (const platform of selectedPlatforms) {
+      for (const name of approvedStaleRemovals[platform]?.skills || []) staleSkillNames.add(name)
+    }
+    await syncSkillsOnly({
       projectDir,
-      selected,
-      staleRemovals: approvedStaleRemovals.claude,
+      selectedPlatforms,
+      skills: skillsToWrite,
+      templateSkillNames: new Set(scans.skills.map(item => item.name)),
+      staleSkillNames,
+      skillScope,
     })
-  }
+    syncedAnySupportedPlatform = selectedPlatforms.some(platform => resolveProjectSkillDir(projectDir, platform))
+      || skillScope.destinations.some(id => id !== 'project')
+  } else {
+    if (selectedPlatforms.includes('claude')) {
+      syncedAnySupportedPlatform = true
+      console.log(chalk.blue('\nSyncing Claude Code configuration...\n'))
+      await syncClaude({
+        sourceDir,
+        projectDir,
+        selected,
+        staleRemovals: approvedStaleRemovals.claude,
+      })
+    }
 
-  if (selectedPlatforms.includes('codex')) {
-    syncedAnySupportedPlatform = true
-    console.log(chalk.blue('\nSyncing Codex configuration...\n'))
-    await syncCodex({
-      sourceDir,
-      projectDir,
-      selected,
-      staleRemovals: approvedStaleRemovals.codex,
-      preserveMissingRules: getPreservedStaleNames(staleEntries, approvedStaleRemovals, 'codex', 'rules'),
-    })
-  }
+    if (selectedPlatforms.includes('codex')) {
+      syncedAnySupportedPlatform = true
+      console.log(chalk.blue('\nSyncing Codex configuration...\n'))
+      await syncCodex({
+        sourceDir,
+        projectDir,
+        selected,
+        staleRemovals: approvedStaleRemovals.codex,
+        preserveMissingRules: getPreservedStaleNames(staleEntries, approvedStaleRemovals, 'codex', 'rules'),
+      })
+    }
 
-  if (selectedPlatforms.includes('cursor')) {
-    syncedAnySupportedPlatform = true
-    await syncCursor({
-      sourceDir,
-      projectDir,
-      selected,
-      staleRemovals: approvedStaleRemovals.cursor,
-    })
-  }
+    if (selectedPlatforms.includes('cursor')) {
+      syncedAnySupportedPlatform = true
+      await syncCursor({
+        sourceDir,
+        projectDir,
+        selected,
+        staleRemovals: approvedStaleRemovals.cursor,
+      })
+    }
 
-  if (selectedPlatforms.includes('opencode')) {
-    syncedAnySupportedPlatform = true
-    await syncOpenCode({
-      sourceDir,
-      projectDir,
-      selected,
-      staleRemovals: approvedStaleRemovals.opencode,
-      preserveMissingRules: getPreservedStaleNames(staleEntries, approvedStaleRemovals, 'opencode', 'rules'),
-    })
-  }
+    if (selectedPlatforms.includes('opencode')) {
+      syncedAnySupportedPlatform = true
+      await syncOpenCode({
+        sourceDir,
+        projectDir,
+        selected,
+        staleRemovals: approvedStaleRemovals.opencode,
+        preserveMissingRules: getPreservedStaleNames(staleEntries, approvedStaleRemovals, 'opencode', 'rules'),
+      })
+    }
 
-  if (!selectedPlatforms.includes('codex') && !selectedPlatforms.includes('opencode')) {
-    await clearProjectAgentsMd(projectDir)
-  }
+    if (!selectedPlatforms.includes('codex') && !selectedPlatforms.includes('opencode')) {
+      await clearProjectAgentsMd(projectDir)
+    }
 
-  if (!selectedPlatforms.includes('claude')) {
-    await cleanupClaudePlatform(projectDir, scans, claudeManagedHookNames, baseline)
-  }
+    if (!selectedPlatforms.includes('claude')) {
+      await cleanupClaudePlatform(projectDir, scans, claudeManagedHookNames, baseline)
+    }
 
-  if (!selectedPlatforms.includes('cursor')) {
-    await cleanupCursorPlatform(projectDir, scans, baseline)
-  }
+    if (!selectedPlatforms.includes('cursor')) {
+      await cleanupCursorPlatform(projectDir, scans, baseline)
+    }
 
-  if (!selectedPlatforms.includes('codex')) {
-    await cleanupCodexPlatform(projectDir, scans, codexManagedHookNames)
+    if (!selectedPlatforms.includes('codex')) {
+      await cleanupCodexPlatform(projectDir, scans, codexManagedHookNames)
+    }
+
+    if (!selectedPlatforms.includes('opencode')) {
+      await cleanupOpenCodePlatform(projectDir, scans)
+    }
   }
 
-  if (!selectedPlatforms.includes('opencode')) {
-    await cleanupOpenCodePlatform(projectDir, scans)
+  const globalSkillNameSet = new Set(skillScope.globalSkills)
+  const globalSkills = scans.skills.filter(item => globalSkillNameSet.has(item.name))
+  if (globalSkills.length > 0 && skillScope.destinations.some(id => id !== 'project')) {
+    console.log(chalk.blue('\nSyncing selected skills to global directories...\n'))
+    await copySkillsToGlobalDirs({
+      skills: globalSkills,
+      destIds: skillScope.destinations,
+      homeDir,
+    })
   }
 
-  for (const platform of Object.keys(PLATFORM_SYNC_TYPES)) {
-    if (selectedPlatforms.includes(platform)) {
-      syncState.platforms[platform] = buildNextPlatformState(selected, staleEntries, approvedStaleRemovals, platform)
-    } else {
-      syncState.platforms[platform] = createEmptyPlatformState()
+  if (syncMode === SYNC_MODE_SKILLS) {
+    for (const platform of selectedPlatforms) {
+      const previous = syncState.platforms[platform] || createEmptyPlatformState()
+      const skillsOnlySelected = { skills: selected.skills || [], rules: [], commands: [], hooks: [] }
+      syncState.platforms[platform] = {
+        ...previous,
+        skills: buildNextPlatformState(skillsOnlySelected, staleEntries, approvedStaleRemovals, platform).skills,
+      }
+    }
+  } else {
+    for (const platform of Object.keys(PLATFORM_SYNC_TYPES)) {
+      if (selectedPlatforms.includes(platform)) {
+        syncState.platforms[platform] = buildNextPlatformState(selected, staleEntries, approvedStaleRemovals, platform)
+      } else {
+        syncState.platforms[platform] = createEmptyPlatformState()
+      }
     }
   }
+  syncState.skillScope = skillScope
+  syncState.syncMode = syncMode
   await saveSyncState(projectDir, syncState)
 
   if (!syncedAnySupportedPlatform) {