dsh-skill-hub 0.3.19 → 0.3.21

package/src/routes/repo-import.ts

@@ -3,8 +3,7 @@
  * cancel 取消。从 routes.ts 原样搬出，handler 逻辑不变。
  */
 
-import { mkdir, rename } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
+import { mkdir } from 'node:fs/promises'
 import { randomUUID } from 'node:crypto'
 import {
   SKILL_HUB_API,
@@ -28,12 +27,11 @@ import {
   skillManifest,
   skillPathIn,
 } from '../repo.ts'
-import { rootPath } from '../skillfs.ts'
+import { occupancyOf, rootPath } from '../skillfs.ts'
 import { errorText } from '../error-text.ts'
 import {
   homeOf,
   knownSkillNames,
-  pathExists,
   queryParam,
   readString,
   readStrings,
@@ -42,32 +40,20 @@ import {
   type RouteSpec,
   type SkillHubRouteDeps,
 } from './helpers.ts'
-import { gcImportJobs, importJobs, type ImportJob } from './route-state.ts'
+import { gcImportJobs, importJobs, retireNamePlaceholders, type ImportJob } from './route-state.ts'
 
 /**
- * 导入去重只认「已启用」的目录，但磁盘上仍可能躺着一个已禁用的同名占位 ——
- * 禁用只是把 SKILL.md 改名成 SKILL.md.disabled，目录本身还在。这种占位不该
- * 堵住真技能：把它连同禁用记录一起移入回收站让位（issue #16）。
+ * 导入让位（issue #16）：磁盘上已有同名占位但**没有启用的技能**时，把占位移入
+ * 回收站，把名字让给即将导入的真技能。占位有两种 —— 已禁用的发现文件（目录包或
+ * 扁平，后者曾长期漏处理：`clearDisabledPlaceholder` 只认 `<name>` 这个目录，
+ * 扁平占位占的是 `<name>.md.disabled`，判据为假，分支根本进不去）和没有 `SKILL.md`
+ * 的空壳目录。判据统一走 `occupancyOf`，形态判断集中在 `retireNamePlaceholders`。
  *
- * 只有「禁用记录确实指向 `targetRoot/<name>` 的整目录禁用」才处理，且该目录
- * 必须已经没有 SKILL.md；其余不确定情形一律返回 false，交回原本的「跳过」。
+ * 返回 false = 磁盘上有启用的同名技能（真货），一律不动，交回原本的「跳过」。
  */
 async function clearDisabledPlaceholder(deps: SkillHubRouteDeps, targetRoot: string, name: string): Promise<boolean> {
-  const record = await deps.store.getDisabled(name)
-  if (record === undefined) return false
-  const dir = join(targetRoot, name)
-  const sourceToTrash = record.path.endsWith('SKILL.md.disabled') ? dirname(record.path) : record.path
-  if (sourceToTrash !== dir) return false
-  // 目录里还有 SKILL.md 说明它其实是启用态的真实技能，不动。
-  if (await pathExists(join(dir, 'SKILL.md'))) return false
-  // 与 skill/delete 的回收站语义一致：同级 .trash/ 下按「名字-时间戳」落盘，可恢复。
-  const trashDir = join(targetRoot, '.trash')
-  await mkdir(trashDir, { recursive: true })
-  const target = join(trashDir, name + '-' + Date.now())
-  await rename(sourceToTrash, target)
-  await deps.store.addTrash({ name, path: target, movedAt: Date.now(), sourcePath: sourceToTrash })
-  await deps.store.removeDisabled(name)
-  return true
+  if ((await occupancyOf(targetRoot, name)).enabled.length > 0) return false
+  return (await retireNamePlaceholders(deps, targetRoot, name)) !== undefined
 }
 
 /** 仓库导入域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
@@ -195,10 +181,11 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
               job.done += 1
               continue
             }
-            // 磁盘上有同名目录。若它只是一个已禁用的占位（目录里只剩
-            // SKILL.md.disabled），先把旧目录移入回收站再继续导入；移不动或
-            // 不是这种形态时退回原本的「跳过」（issue #16）。
-            if (await pathExists(join(targetRoot, entry.name))) {
+            // 磁盘上有同名占位。若它只是一个已禁用的占位（目录包或扁平）或一个空壳
+            // 目录，先把旧东西移入回收站再继续导入；有启用的同名技能时退回「跳过」
+            // （issue #16）。
+            const occupancy = await occupancyOf(targetRoot, entry.name)
+            if (occupancy.enabled.length > 0 || occupancy.disabled.length > 0 || occupancy.bareDir !== undefined) {
               let cleared = false
               try {
                 cleared = await clearDisabledPlaceholder(deps, targetRoot, entry.name)
@@ -211,7 +198,7 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
                 job.done += 1
                 continue
               }
-              // 旧目录已经进了回收站（可恢复）。即使随后的下载失败也必须如实
+              // 占位已经进了回收站（可恢复）。即使随后的下载失败也必须如实
               // 上报，否则用户不知道自己的占位被挪走了。
               job.replaced.push(entry.name)
             }

package/src/routes/route-state.test.ts

@@ -2,7 +2,7 @@ import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
-import { IMPORT_JOB_MAX, gcImportJobs, importJobs, replaceSkillDir, type ImportJob } from './route-state.ts'
+import { IMPORT_JOB_MAX, gcImportJobs, importJobs, replaceInPlace, type ImportJob } from './route-state.ts'
 
 /** One import job with sane defaults; override what the test cares about. */
 function job(jobId: string, createdAt: number, status: ImportJob['status'] = 'done'): ImportJob {
@@ -50,7 +50,7 @@ describe('gcImportJobs', () => {
   })
 })
 
-describe('replaceSkillDir', () => {
+describe('replaceInPlace', () => {
   let dir: string
 
   afterEach(async () => { await rm(dir, { recursive: true, force: true }) })
@@ -60,7 +60,7 @@ describe('replaceSkillDir', () => {
     const target = join(dir, 'skill')
     await mkdir(target, { recursive: true })
     await writeFile(join(target, 'old.txt'), 'old', 'utf8')
-    await replaceSkillDir(target, async () => {
+    await replaceInPlace(target, async () => {
       // 下载方负责重建目标目录（downloadRepoSkill 就是这么做的）。
       await mkdir(target, { recursive: true })
       await writeFile(join(target, 'new.txt'), 'new', 'utf8')
@@ -76,7 +76,7 @@ describe('replaceSkillDir', () => {
     const target = join(dir, 'skill')
     await mkdir(target, { recursive: true })
     await writeFile(join(target, 'old.txt'), 'old', 'utf8')
-    await expect(replaceSkillDir(target, async () => { throw new Error('download failed') })).rejects.toThrow('download failed')
+    await expect(replaceInPlace(target, async () => { throw new Error('download failed') })).rejects.toThrow('download failed')
     expect(await readFile(join(target, 'old.txt'), 'utf8')).toBe('old')
     expect((await readdir(dir)).filter((name) => name.startsWith('.'))).toEqual([])
   })

package/src/routes/route-state.ts

@@ -6,6 +6,7 @@
 import { rm, rename } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 import { errorText } from '../error-text.ts'
+import { moveIntoTrash, occupancyOf, trashSourceOf } from '../skillfs.ts'
 import type { SkillHubRouteDeps } from './helpers.ts'
 
 /** Minimum interval between network update checks per source (GitHub rate limits). */
@@ -79,21 +80,55 @@ export function gcImportJobs(): void {
   }
 }
 
-/** Replace one skill directory with a fresh download; restores the old dir on failure. */
-export async function replaceSkillDir(targetDir: string, download: () => Promise<void>): Promise<void> {
-  // 点前缀：发现扫描跳过点开头的目录（与导入临时目录 .<name>.import- 同一
-  // 约定），备份即使删除失败残留下来，也不会混进目录/发现诊断，更不会
-  // 造成同名技能重复注册。
-  const backup = join(dirname(targetDir), '.' + basename(targetDir) + '.sync-bak-' + Date.now())
-  await rename(targetDir, backup)
+/**
+ * Replace whatever currently occupies a skill slot with a fresh download;
+ * restores the previous state on failure.
+ *
+ * `target` is the entry to move aside — a bundle **directory** or a flat
+ * `<name>.md` file, whichever the download is replacing (the rename/rm below
+ * are form-neutral). The backup is dot-prefixed (discovery skips dot entries),
+ * so even a failed cleanup can never register as a duplicate skill.
+ */
+export async function replaceInPlace(target: string, download: () => Promise<unknown>): Promise<void> {
+  const backup = join(dirname(target), '.' + basename(target) + '.sync-bak-' + Date.now())
+  await rename(target, backup)
   try {
     await download()
   } catch (error) {
-    await rename(backup, targetDir).catch((rollbackError) => {
-      // 回滚失败会让技能只剩点前缀的备份目录（发现扫描会跳过它）：必须留痕。
-      console.warn('[dsh-skill-hub] restoring ' + targetDir + ' from ' + backup + ' failed:', errorText(rollbackError))
+    await rename(backup, target).catch((rollbackError) => {
+      // 回滚失败会让技能只剩点前缀的备份：必须留痕。
+      console.warn('[dsh-skill-hub] restoring ' + target + ' from ' + backup + ' failed:', errorText(rollbackError))
     })
     throw error
   }
   await rm(backup, { recursive: true, force: true })
 }
+
+/**
+ * 让位：把一个名字下的「非启用态占位」移入回收站并清掉它的 sidecar 禁用记录。
+ * 只动这两类，**启用的技能一律不碰**：
+ * - 禁用发现文件（`<name>/SKILL.md.disabled` 或 `<name>.md.disabled`，两种形态都认）；
+ * - 同名目录存在但既无 `SKILL.md` 也无 `SKILL.md.disabled`（导入中断/手工删除的空壳）。
+ *
+ * 回收站按名字索引，所以多形态只会记下最后一条的恢复指针；其余的那份会在
+ * 「清空回收站」时被孤儿回收扫掉（见 sourceTrashClear）。
+ *
+ * @returns 被移入回收站的路径列表，没有可让位的东西时 undefined。
+ */
+export async function retireNamePlaceholders(deps: SkillHubRouteDeps, base: string, name: string): Promise<string[] | undefined> {
+  const occupancy = await occupancyOf(base, name)
+  // trashSourceOf 让「目录包禁用件」与「空壳目录」自然去重（同一个目录只搬一次）。
+  const sources = [...new Set([
+    ...occupancy.disabled.map((path) => trashSourceOf(path)),
+    ...(occupancy.bareDir !== undefined ? [occupancy.bareDir] : []),
+  ])]
+  if (sources.length === 0) return undefined
+  const trashed: string[] = []
+  for (const source of sources) {
+    const moved = await moveIntoTrash(source)
+    await deps.store.addTrash({ name, path: moved.path, movedAt: Date.now(), sourcePath: moved.source })
+    trashed.push(moved.path)
+  }
+  await deps.store.removeDisabled(name)
+  return trashed
+}

package/src/routes/sources.ts

@@ -4,7 +4,7 @@
  * handler 逻辑不变。
  */
 
-import { mkdir, rename } from 'node:fs/promises'
+import { mkdir, readdir, rename, rm } from 'node:fs/promises'
 import { join } from 'node:path'
 import { isSkillName } from '@deepseek-ai/dsh-skill'
 import {
@@ -30,7 +30,7 @@ import {
   skillFileAt,
   skillManifest,
 } from '../repo.ts'
-import { clearTrash, restoreSkill, rootOfPath, rootPath, trashSkill } from '../skillfs.ts'
+import { clearTrash, occupancyOf, restoreSkill, rootOfPath, rootPath, trashSkill, trashSourceOf, WRITABLE_ROOTS } from '../skillfs.ts'
 import { errorText } from '../error-text.ts'
 import {
   buildCollections,
@@ -43,7 +43,7 @@ import {
   type RouteSpec,
   type SkillHubRouteDeps,
 } from './helpers.ts'
-import { MIN_CHECK_INTERVAL_MS, lastSourceCheck, replaceSkillDir } from './route-state.ts'
+import { MIN_CHECK_INTERVAL_MS, lastSourceCheck, replaceInPlace, retireNamePlaceholders } from './route-state.ts'
 
 /** 来源跟踪域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
@@ -149,18 +149,28 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
             const files = collectRepoSkillFiles(tree, entry.dir)
             if (files.length === 0) { failed.push({ name, error: 'skill missing upstream' }); continue }
             const targetDir = join(targetRoot, name)
-            const wasDisabled = (await deps.store.getDisabled(name)) !== undefined
-            if (await pathExists(targetDir)) {
-              await replaceSkillDir(targetDir, async () => {
-                await downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot)
-              })
+            const record = await deps.store.getDisabled(name)
+            const occupancy = await occupancyOf(targetRoot, name)
+            // 落盘位置永远是目录包，所以本地无论是目录包还是扁平文件（启用或禁用）
+            // 都得先让开，否则同名两形态会并存（issue #16 类）。
+            const download = () => downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot)
+            // 1) 禁用件与空壳让位（顺带清掉 sidecar 禁用记录）。
+            await retireNamePlaceholders(deps, targetRoot, name)
+            // 2) 启用件按「替换」语义处理：先挪到点前缀备份，下载失败则原样恢复。
+            const enabled = occupancy.enabled[0]
+            if (enabled !== undefined) {
+              await replaceInPlace(trashSourceOf(enabled), download)
             } else {
-              await downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot)
+              await download()
             }
-            if (wasDisabled) {
+            if (record !== undefined) {
               // Preserve the disabled state: the fresh SKILL.md must not
-              // re-enter discovery.
-              await rename(join(targetDir, 'SKILL.md'), join(targetDir, 'SKILL.md.disabled'))
+              // re-enter discovery. 记录必须**无条件写回** —— 上面的
+              // retireNamePlaceholders 已经把它删过一遍，只按「path 变了才写」
+              // 判断会让「同步一个已禁用的技能」丢掉禁用状态与记录（活体实测过）。
+              const disabledPath = join(targetDir, 'SKILL.md.disabled')
+              await rename(join(targetDir, 'SKILL.md'), disabledPath)
+              await deps.store.addDisabled({ ...record, path: disabledPath })
             } else {
               await deps.store.removeDisabled(name)
             }
@@ -206,24 +216,29 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
             failed.push({ name, error: 'skill is not tracked by this source' })
             continue
           }
-          const sourcePath = join(rootPath('user-dsh', home), name)
-          if (rootOfPath(sourcePath, home) === undefined) {
-            failed.push({ name, error: 'skill path is outside the hub writable roots' })
+          // Resolve the on-disk occupation instead of assuming a `<root>/<name>`
+          // directory: the tracked skill can equally be a flat `<name>.md` file
+          // or a hub-disabled placeholder (issue #16 类).
+          const base = rootPath('user-dsh', home)
+          const occupancy = await occupancyOf(base, name)
+          const existing = occupancy.enabled[0] ?? occupancy.disabled[0] ?? occupancy.bareDir
+          if (existing === undefined) {
+            failed.push({ name, error: 'skill not found on disk' })
             continue
           }
-          if (!await pathExists(sourcePath)) {
-            failed.push({ name, error: 'skill directory not found' })
+          if (rootOfPath(existing, home) === undefined) {
+            failed.push({ name, error: 'skill path is outside the hub writable roots' })
             continue
           }
           try {
             // 入回收站前快照来源与场景归属，恢复时挂回（见 sourceRestore）。
             const tagIds = (await deps.store.listTags()).filter((tag) => tag.skillNames.includes(name)).map((tag) => tag.id)
-            const { path } = await trashSkill(sourcePath)
+            const { path, source: trashSource } = await trashSkill(existing)
             await deps.store.addTrash({
               name,
               path,
               movedAt: Date.now(),
-              sourcePath,
+              sourcePath: trashSource,
               origin: { repo: source.repo, root: source.root, ...(source.ref !== undefined && source.ref !== '' ? { ref: source.ref } : {}), commitSha: source.commitSha },
               ...(tagIds.length > 0 ? { tagIds } : {}),
             })
@@ -267,7 +282,7 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         for (const tagId of entry.tagIds ?? []) {
           await deps.store.addSkillToTag(tagId, name)
         }
-        await deps.store.removeTrash(name)
+        await deps.store.removeTrash(entry.path)
         deps.invalidate?.()
         writeJson(res, 200, { ok: true, name, path } satisfies SourceRestoreResponse)
       },
@@ -281,6 +296,7 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         const home = homeOf(deps)
         const entries = await deps.store.listTrash()
         const deleted: string[] = []
+        const removedPaths: string[] = []
         const failed: Array<{ name: string; error: string }> = []
         for (const entry of entries) {
           try {
@@ -288,14 +304,54 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
             // A permanently deleted skill must not linger in user groups.
             await deps.store.removeSkillFromTags(entry.name)
             deleted.push(entry.name)
+            removedPaths.push(entry.path)
           } catch (error) {
             failed.push({ name: entry.name, error: errorText(error) })
           }
         }
-        for (const name of deleted) await deps.store.removeTrash(name)
-        if (deleted.length > 0) deps.invalidate?.()
-        writeJson(res, 200, { ok: true, deleted, failed } satisfies SourceTrashClearResponse)
+        for (const path of removedPaths) await deps.store.removeTrash(path)
+        // 回收站记录按名字索引：同名技能先后两次入站时旧记录被覆盖，但它的
+        // `<name>-<时间戳>` 目录还留在盘上，任何记录都指不到它 → 永久孤儿。
+        // 「清空回收站」正是它的回收时机，顺手扫掉并如实上报。
+        const orphans = await sweepOrphanTrash(deps, home, failed)
+        if (deleted.length > 0 || orphans.length > 0) deps.invalidate?.()
+        writeJson(res, 200, {
+          ok: true,
+          deleted,
+          failed,
+          ...(orphans.length > 0 ? { orphans } : {}),
+        } satisfies SourceTrashClearResponse)
       },
     },
   ]
 }
+
+/**
+ * 删除两个可写根 `.trash` 下不被任何回收站记录引用的残留目录。
+ * 只扫 `.trash` 的直接子项、跳过点开头项，失败项并入 `failed`（保留可重试）。
+ */
+async function sweepOrphanTrash(deps: SkillHubRouteDeps, home: string, failed: Array<{ name: string; error: string }>): Promise<string[]> {
+  const referenced = new Set((await deps.store.listTrash()).map((entry) => entry.path))
+  const orphans: string[] = []
+  for (const root of WRITABLE_ROOTS) {
+    const trashDir = join(rootPath(root, home), '.trash')
+    let names: string[]
+    try {
+      names = await readdir(trashDir)
+    } catch {
+      continue // 该根没有回收站目录
+    }
+    for (const name of names) {
+      if (name.startsWith('.')) continue
+      const full = join(trashDir, name)
+      if (referenced.has(full)) continue
+      try {
+        await rm(full, { recursive: true, force: true })
+        orphans.push(full)
+      } catch (error) {
+        failed.push({ name, error: errorText(error) })
+      }
+    }
+  }
+  return orphans
+}