dsh-skill-hub 0.3.20 → 0.3.22

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
+}

package/src/routes.test.ts

@@ -4,7 +4,7 @@ import { dirname, join } from 'node:path'
 import type { IncomingMessage } from 'node:http'
 import type { SkillDefinition, SkillSummary } from '@deepseek-ai/dsh-skill'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { makeRoutes, type SkillHubRouteDeps } from './routes.ts'
+import { hostTrustFence, makeRoutes, type SkillHubRouteDeps } from './routes.ts'
 import { lastMarketCheck } from './routes/route-state.ts'
 import { SkillHubStore, statePath } from './store.ts'
 import { SKILL_HUB_API, SKILL_HUB_API_ROOT, type CatalogResponse, type ConfigResponse, type ErrorResponse, type HubConfig } from './protocol.ts'
@@ -27,12 +27,12 @@ class FakeResponse {
 }
 
 /** Minimal request double (loopback by default; body available for POST). */
-function fakeReq(method: string, url = '/', body?: unknown, remoteAddress = '127.0.0.1'): IncomingMessage {
+function fakeReq(method: string, url = '/', body?: unknown, remoteAddress = '127.0.0.1', host = '127.0.0.1:3080'): IncomingMessage {
   const chunks = body === undefined ? [] : [Buffer.from(JSON.stringify(body))]
   return {
     method,
     url,
-    headers: { host: '127.0.0.1:3080' },
+    headers: { host },
     socket: { remoteAddress },
     async *[Symbol.asyncIterator]() {
       for (const chunk of chunks) yield chunk
@@ -105,10 +105,76 @@ describe('skill-hub routes', () => {
     return route
   }
 
-  it('rejects non-loopback requests', async () => {
+  it('rejects non-loopback requests with the literal fallback when no host fence is wired', async () => {
+    // deps 里没有 fence（非 web 宿主、单测）⇒ 退回历史的字面回环判定。
     const res = new FakeResponse()
     await routeFor(SKILL_HUB_API.catalog).handler(fakeReq('GET', SKILL_HUB_API.catalog, undefined, '10.0.0.5'), res as never)
     expect(res.status).toBe(403)
+    expect(res.json()).toEqual({ error: 'forbidden: untrusted authority' })
+  })
+
+  it('delegates to the host fence and passes its verdict through verbatim (issue #17)', async () => {
+    // 反代形态：socket 是网关地址、Host 是公开域名。宿主栅栏认它，本插件不许再挡一道。
+    const seen: string[] = []
+    deps.fence = (request) => {
+      seen.push(String(request.headers.host))
+      return undefined
+    }
+    const ok = new FakeResponse()
+    await routeFor(SKILL_HUB_API.catalog)
+      .handler(fakeReq('GET', SKILL_HUB_API.catalog, undefined, '172.19.0.1', 'dsh.example.com'), ok as never)
+    expect(seen).toEqual(['dsh.example.com'])
+    expect(ok.status).toBe(200)
+
+    // 宿主判定「栅栏过了但没有浏览器会话」时，401 同样原样透传。
+    deps.fence = () => 401
+    const unauth = new FakeResponse()
+    await routeFor(SKILL_HUB_API.catalog).handler(fakeReq('GET', SKILL_HUB_API.catalog), unauth as never)
+    expect(unauth.status).toBe(401)
+    expect(unauth.json()).toEqual({ error: 'unauthorized: browser session required' })
+  })
+
+  it('hostTrustFence: literal fallback without Connection, delegation with it, fail closed when it throws', () => {
+    const remote = fakeReq('GET', '/', undefined, '10.0.0.5')
+    expect(hostTrustFence(() => undefined)(remote)).toBe(403)
+    expect(hostTrustFence(() => undefined)(fakeReq('GET', '/'))).toBeUndefined()
+
+    let calls = 0
+    const delegated = hostTrustFence(() => ({
+      requestRejection: () => { calls += 1; return 401 },
+    } as never))
+    expect(delegated(remote)).toBe(401)
+    expect(calls).toBe(1)
+
+    const broken = hostTrustFence(() => ({
+      requestRejection: () => { throw new Error('fence unavailable') },
+    } as never))
+    expect(broken(remote)).toBe(403)
+  })
+
+  it('hostTrustFence: a service appearing later un-latches the fallback, and onMissing fires once (issue #17)', () => {
+    const remote = fakeReq('GET', '/', undefined, '10.0.0.5')
+    let connection: import('@deepseek-ai/dsh-client-connection').HostConnectionHandle | undefined
+    let misses = 0
+    const fence = hostTrustFence(
+      () => connection,
+      () => { misses += 1 },
+    )
+
+    // 启动早于 Connection：前几次请求走降级，且只报一次缺失。
+    expect(fence(remote)).toBe(403)
+    expect(fence(remote)).toBe(403)
+    expect(misses).toBe(1)
+
+    // Connection 上线后同一 fence 立即切换，不锁死在降级分支。
+    connection = { requestRejection: () => undefined } as unknown as import('@deepseek-ai/dsh-client-connection').HostConnectionHandle
+    expect(fence(remote)).toBeUndefined()
+    expect(misses).toBe(1)
+
+    // 服务再次消失（理论上不该发生）不重复报警，判定回到降级。
+    connection = undefined
+    expect(fence(remote)).toBe(403)
+    expect(misses).toBe(1)
   })
 
   it('reports stats unavailable without a reader, or when all usage displays are off', async () => {
@@ -1117,6 +1183,238 @@ describe('skill-hub routes', () => {
     expect(invalidate).toHaveBeenCalledTimes(1)
   })
 
+  // --------------------------- 同名双形态 / 陈旧禁用记录（issue #16 类，实测 G5/G7/G8）
+  it('self-heals a stale disabled record by pointing it at the surviving placeholder', async () => {
+    // 记录指目录形态，磁盘上只剩扁平占位 —— 导入让位/L2 迁移后的典型残留。
+    await writeFile(join(home, 'skills', 'code-review.md.disabled'), '---\nname: code-review\ndescription: stub\n---', 'utf8')
+    await store.addDisabled({ name: 'code-review', description: 'stub', path: join(home, 'skills', 'code-review', 'SKILL.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.toggle).handler(fakeReq('POST', SKILL_HUB_API.toggle, { name: 'code-review', enabled: true }), res as never)
+    expect(res.status).toBe(200)
+    await expect(access(join(home, 'skills', 'code-review.md'))).resolves.toBeUndefined()
+    expect(await store.getDisabled('code-review')).toBeUndefined()
+  })
+
+  it('drops a fully stale disabled record so the name becomes usable again', async () => {
+    await store.addDisabled({ name: 'ghost', description: 'x', path: join(home, 'skills', 'ghost', 'SKILL.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    // 记录还在时，新建同名技能被 409 挡住。
+    const blocked = new FakeResponse()
+    await routeFor(SKILL_HUB_API.create).handler(fakeReq('POST', SKILL_HUB_API.create, { name: 'ghost', description: 'x' }), blocked as never)
+    expect(blocked.status).toBe(409)
+    // 启用报「记录已失效」并把记录清掉，而不是留下一条谁都动不了的死记录。
+    const enable = new FakeResponse()
+    await routeFor(SKILL_HUB_API.toggle).handler(fakeReq('POST', SKILL_HUB_API.toggle, { name: 'ghost', enabled: true }), enable as never)
+    expect(enable.status).toBe(409)
+    expect(String((enable.json() as { error: string }).error)).toContain('stale')
+    expect(await store.getDisabled('ghost')).toBeUndefined()
+    // 名字已释放：新建成功，再次启用则报「不是禁用态」。
+    const created = new FakeResponse()
+    await routeFor(SKILL_HUB_API.create).handler(fakeReq('POST', SKILL_HUB_API.create, { name: 'ghost', description: 'x' }), created as never)
+    expect(created.status).toBe(201)
+    await expect(access(join(home, 'skills', 'ghost', 'SKILL.md'))).resolves.toBeUndefined()
+    const again = new FakeResponse()
+    await routeFor(SKILL_HUB_API.toggle).handler(fakeReq('POST', SKILL_HUB_API.toggle, { name: 'ghost', enabled: true }), again as never)
+    expect(again.status).toBe(404)
+  })
+
+  it('deletes a stale disabled record instead of failing on the missing file', async () => {
+    const tag = await store.saveTag({ name: 'scene-x' })
+    await store.setTagMembers(tag.id, ['ghost'])
+    await store.addDisabled({ name: 'ghost', description: 'x', path: join(home, 'skills', 'ghost', 'SKILL.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.skillDelete).handler(fakeReq('POST', SKILL_HUB_API.skillDelete, { name: 'ghost' }), res as never)
+    expect(res.status).toBe(200)
+    expect(await store.getDisabled('ghost')).toBeUndefined()
+    expect((await store.getTag(tag.id))?.skillNames).toEqual([])
+  })
+
+  it('flags two discovery forms occupying the same skill name in one root', async () => {
+    // 目录包与扁平文件同名：注册表只给一个，另一个静默不可达 → 必须报诊断。
+    await writeFile(join(home, 'skills', 'dup-skill.md'), '---\nname: dup-skill\ndescription: flat one\n---', 'utf8')
+    await mkdir(join(home, 'skills', 'dup-skill'), { recursive: true })
+    await writeFile(join(home, 'skills', 'dup-skill', 'SKILL.md'), '---\nname: dup-skill\ndescription: bundle one\n---', 'utf8')
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.catalog).handler(fakeReq('GET', SKILL_HUB_API.catalog), res as never)
+    expect(res.status).toBe(200)
+    const body = res.json() as CatalogResponse
+    const collisions = body.diagnostics.filter((d) => d.reason.includes('registers the same name'))
+    expect(collisions.map((d) => d.path).sort()).toEqual([
+      join(home, 'skills', 'dup-skill.md'),
+      join(home, 'skills', 'dup-skill', 'SKILL.md'),
+    ].sort())
+    expect(collisions[0].reason).toContain('"dup-skill"')
+  })
+
+  it('reclaims unreferenced trash directories when clearing the trash', async () => {
+    const trash = join(home, 'skills', '.trash')
+    await mkdir(join(trash, 'foo-1'), { recursive: true })
+    await mkdir(join(trash, 'foo-2'), { recursive: true })
+    // 名字索引只剩最新那条；foo-1 已经没有任何记录指得到它。
+    await store.addTrash({ name: 'foo', path: join(trash, 'foo-2'), movedAt: 2, sourcePath: join(home, 'skills', 'foo') })
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.sourceTrashClear).handler(fakeReq('POST', SKILL_HUB_API.sourceTrashClear), res as never)
+    expect(res.status).toBe(200)
+    const body = res.json() as import('./protocol.ts').SourceTrashClearResponse
+    expect(body.deleted).toEqual(['foo'])
+    expect(body.orphans).toEqual([join(trash, 'foo-1')])
+    await expect(access(join(trash, 'foo-1'))).rejects.toThrow()
+    await expect(access(join(trash, 'foo-2'))).rejects.toThrow()
+  })
+
+  // ------------------------- 导入/同步/删除/新建 遇到扁平形态（issue #16 类，实测 G1–G4）
+  /** 造一个「扁平已禁用占位」：`<name>.md.disabled` + 指向它的 sidecar 记录。 */
+  async function seedFlatDisabledPlaceholder(name: string) {
+    const flat = join(home, 'skills', name + '.md.disabled')
+    await writeFile(flat, `---\nname: ${name}\ndescription: stub\n---\n`, 'utf8')
+    await store.addDisabled({ name, description: 'stub', path: flat, root: 'user-dsh', disabledAt: Date.now() })
+    return flat
+  }
+
+  it('imports over a flat disabled placeholder instead of leaving it behind', async () => {
+    const flat = await seedFlatDisabledPlaceholder('code-review')
+    const skillMd = '---\nname: code-review\ndescription: Reviews code\n---\n\nbody'
+    stubFetch([
+      ['repos/example/repo/git/trees/main', jsonResponse({ tree: [
+        { path: 'skills/code-review/SKILL.md', type: 'blob', size: 60 },
+      ] })],
+      ['repos/example/repo/commits', jsonResponse({ sha: 'abc123', commit: { tree: { sha: 'tree1' } } })],
+      ['repos/example/repo', jsonResponse({ default_branch: 'main' })],
+      ['raw.githubusercontent.com/example/repo/main/skills/code-review/SKILL.md', new Response(skillMd, { status: 200 })],
+    ])
+    try {
+      const res = new FakeResponse()
+      await routeFor(SKILL_HUB_API.repoImport).handler(fakeReq('POST', SKILL_HUB_API.repoImport, { repo: 'example/repo', paths: ['skills/code-review/SKILL.md'] }), res as never)
+      const created = res.json() as import('./protocol.ts').RepoImportResponse
+      let prog: import('./protocol.ts').RepoImportProgressResponse | undefined
+      for (let i = 0; i < 30; i++) {
+        await new Promise((r) => setTimeout(r, 40))
+        const p = new FakeResponse()
+        await routeFor(SKILL_HUB_API.repoImportProgress).handler(fakeReq('GET', `${SKILL_HUB_API.repoImportProgress}?jobId=${created.jobId}`), p as never)
+        prog = p.json() as import('./protocol.ts').RepoImportProgressResponse
+        if (prog.status !== 'running') break
+      }
+      expect(prog!.status).toBe('done')
+      expect(prog!.skipped).toEqual([])
+      expect(prog!.imported.map((r) => r.name)).toEqual(['code-review'])
+      // 关键差异：扁平占位不再「看不见」——它被移入回收站、如实上报，真技能落地。
+      expect(prog!.replaced).toEqual(['code-review'])
+      await expect(access(flat)).rejects.toThrow()
+      await expect(readFile(join(home, 'skills', 'code-review', 'SKILL.md'), 'utf8')).resolves.toContain('name: code-review')
+      expect(await store.listDisabled()).toEqual([])
+      expect((await store.listTrash()).map((entry) => entry.name)).toEqual(['code-review'])
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  /** 同步一个已跟踪技能所需的 fetch 桩（tree + commit + raw）。 */
+  function stubSyncFetch(): void {
+    stubFetch([
+      ['repos/example/repo/git/trees/tree1', jsonResponse({ tree: [
+        { path: 'skills/code-review/SKILL.md', type: 'blob', size: 60 },
+      ] })],
+      ['repos/example/repo/commits', jsonResponse({ sha: 'abc123', commit: { tree: { sha: 'tree1' } } })],
+      ['raw.githubusercontent.com/example/repo/abc123/skills/code-review/SKILL.md', new Response('---\nname: code-review\ndescription: upstream\n---\n', { status: 200 })],
+    ])
+  }
+
+  it('syncs a flat-stored skill into the bundle slot instead of leaving both', async () => {
+    await writeFile(join(home, 'skills', 'code-review.md'), '---\nname: code-review\ndescription: flat\n---\n', 'utf8')
+    await store.addSourceSkill('example/repo', 'skills', '', 'main', 'code-review')
+    stubSyncFetch()
+    try {
+      const res = new FakeResponse()
+      await routeFor(SKILL_HUB_API.sourceSync).handler(fakeReq('POST', SKILL_HUB_API.sourceSync, { repo: 'example/repo' }), res as never)
+      expect(res.status).toBe(200)
+      expect((res.json() as import('./protocol.ts').SourceSyncResponse).synced).toEqual(['code-review'])
+      // 旧扁平文件必须先让开，否则同名两形态并存（注册表只会给一个）。
+      await expect(access(join(home, 'skills', 'code-review.md'))).rejects.toThrow()
+      await expect(readFile(join(home, 'skills', 'code-review', 'SKILL.md'), 'utf8')).resolves.toContain('description: upstream')
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('syncs a flat hub-disabled skill and repoints its record at the new bundle', async () => {
+    const flat = await seedFlatDisabledPlaceholder('code-review')
+    await store.addSourceSkill('example/repo', 'skills', '', 'main', 'code-review')
+    stubSyncFetch()
+    try {
+      const res = new FakeResponse()
+      await routeFor(SKILL_HUB_API.sourceSync).handler(fakeReq('POST', SKILL_HUB_API.sourceSync, { repo: 'example/repo' }), res as never)
+      expect(res.status).toBe(200)
+      // 禁用态要保持，但记录必须改指新形态 —— 否则「启用」会去动那个已被替换掉的旧文件。
+      const bundleDisabled = join(home, 'skills', 'code-review', 'SKILL.md.disabled')
+      await expect(access(bundleDisabled)).resolves.toBeUndefined()
+      await expect(access(flat)).rejects.toThrow()
+      expect((await store.getDisabled('code-review'))?.path).toBe(bundleDisabled)
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('keeps a bundle-disabled skill disabled after syncing it again', async () => {
+    // 记录本来就指向目录包形态（`<name>/SKILL.md.disabled`）：让位步骤会把记录删掉，
+    // 若只在「path 变了」时写回，这里就会连禁用状态和记录一起丢掉（活体实测抓到过）。
+    const dir = join(home, 'skills', 'code-review')
+    await mkdir(dir, { recursive: true })
+    const bundleDisabled = join(dir, 'SKILL.md.disabled')
+    await writeFile(bundleDisabled, '---\nname: code-review\ndescription: old\n---\n', 'utf8')
+    await store.addDisabled({ name: 'code-review', description: 'old', path: bundleDisabled, root: 'user-dsh', disabledAt: 1 })
+    await store.addSourceSkill('example/repo', 'skills', '', 'main', 'code-review')
+    stubSyncFetch()
+    try {
+      const res = new FakeResponse()
+      await routeFor(SKILL_HUB_API.sourceSync).handler(fakeReq('POST', SKILL_HUB_API.sourceSync, { repo: 'example/repo' }), res as never)
+      expect((res.json() as import('./protocol.ts').SourceSyncResponse).synced).toEqual(['code-review'])
+      await expect(access(bundleDisabled)).resolves.toBeUndefined()
+      expect((await store.getDisabled('code-review'))?.path).toBe(bundleDisabled)
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('follows an upstream delete for a flat-stored skill', async () => {
+    const flat = join(home, 'skills', 'code-review.md')
+    await writeFile(flat, '---\nname: code-review\ndescription: flat\n---\n', 'utf8')
+    await store.addSourceSkill('example/repo', 'skills', 'abc', undefined, 'code-review')
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.sourceDelete).handler(fakeReq('POST', SKILL_HUB_API.sourceDelete, { repo: 'example/repo', skills: ['code-review'] }), res as never)
+    expect(res.status).toBe(200)
+    const body = res.json() as import('./protocol.ts').SourceDeleteResponse
+    expect(body.failed).toEqual([])
+    expect(body.trashed).toEqual(['code-review'])
+    await expect(access(flat)).rejects.toThrow()
+    expect((await store.listTrash())[0]?.sourcePath).toBe(flat)
+  })
+
+  it('refuses to create a skill whose name is taken by a flat file on disk', async () => {
+    // frontmatter 坏 → 注册表看不见它，但名字确实被占了；建目录会立刻造出同名两形态。
+    await writeFile(join(home, 'skills', 'foo.md'), 'not a frontmatter file', 'utf8')
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.create).handler(fakeReq('POST', SKILL_HUB_API.create, { name: 'foo', description: 'x' }), res as never)
+    expect(res.status).toBe(409)
+    expect(String((res.json() as { error: string }).error)).toContain('occupies this name on disk')
+    await expect(access(join(home, 'skills', 'foo'))).rejects.toThrow()
+  })
+
+  it('refuses to create a skill whose name is held by a disabled placeholder', async () => {
+    // 有 sidecar 记录时走既有的「先重新启用」提示；没有记录（记录丢失/手改过）
+    // 时以前会直接建档造出同名两形态，现在由磁盘占位检查兜住。
+    await writeFile(join(home, 'skills', 'foo.md.disabled'), '---\nname: foo\ndescription: stub\n---\n', 'utf8')
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.create).handler(fakeReq('POST', SKILL_HUB_API.create, { name: 'foo', description: 'x' }), res as never)
+    expect(res.status).toBe(409)
+    expect(String((res.json() as { error: string }).error)).toContain('disabled placeholder')
+    await expect(access(join(home, 'skills', 'foo'))).rejects.toThrow()
+    // 有记录时保持原有提示口径。
+    await seedFlatDisabledPlaceholder('bar')
+    const withRecord = new FakeResponse()
+    await routeFor(SKILL_HUB_API.create).handler(fakeReq('POST', SKILL_HUB_API.create, { name: 'bar', description: 'x' }), withRecord as never)
+    expect(withRecord.status).toBe(409)
+    expect(String((withRecord.json() as { error: string }).error)).toContain('re-enable it from the disabled list first')
+  })
+
   it('patches display toggles on the config route', async () => {
     const res = new FakeResponse()
     await routeFor(SKILL_HUB_API.config).handler(fakeReq('POST', SKILL_HUB_API.config, { showUseCount: false }), res as never)

package/src/routes.ts

@@ -3,18 +3,22 @@
  * official registry + hub-disabled skills + discovery diagnostics), skill
  * detail, enable/disable toggle, new-skill scaffold, user groups (tags +
  * origin collections), and upstream source tracking (check/sync/follow
- * upstream deletion into a restorable trash). Every route carries a
- * loopback-only trust fence — these endpoints rename files under the user's
- * skill roots, so LAN-exposed dsh web deployments must not serve them.
+ * upstream deletion into a restorable trash). Every route carries the host's
+ * own `/api` trust fence (loopback, the listener's bind address, each
+ * `--trusted-host` authority, then the browser session) — these endpoints
+ * rename files under the user's skill roots, so they must never be laxer than
+ * the GUI around them (issue #17).
  *
  * 按域拆分后的聚合入口：各域 handler 在 ./routes/<domain>.ts，共享围栏在
  * ./routes/helpers.ts，节流/任务状态在 ./routes/route-state.ts。
  * 老 `from './routes.ts'`（makeRoutes + SkillHubRouteDeps）保持可用。
  */
 
+import type { HostConnectionHandle } from '@deepseek-ai/dsh-client-connection'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { SKILL_HUB_API_ROOT } from './protocol.ts'
 import { createRoute, writeError, type SkillHubRouteDeps } from './routes/helpers.ts'
+import { loopbackOnlyFence, type RouteFence } from './routes/http.ts'
 import { catalogRoutes } from './routes/catalog.ts'
 import { configRoutes } from './routes/config.ts'
 import { marketRoutes } from './routes/market.ts'
@@ -23,14 +27,54 @@ import { groupRoutes } from './routes/groups.ts'
 import { sourceRoutes } from './routes/sources.ts'
 
 export type { SkillHubRouteDeps, SkillLookupLike } from './routes/helpers.ts'
+export type { RouteFence } from './routes/http.ts'
+
+/**
+ * Build the family's trust fence from the host's `/api` model.
+ *
+ * `ctx.connection.requestRejection` is the documented hook for fencing another
+ * Web route; with no Connection service (a webserver-only composition, or a
+ * unit test) the literal-loopback check stands in, so the fallback is the old
+ * behaviour rather than an open route family.
+ *
+ * The service is read **per request**, not once at mount: plugins start in
+ * composition order, so a one-shot read at `apply()` time would latch the
+ * fallback whenever this plugin happens to come up before Connection. A
+ * persistent absence is almost certainly an upstream composition change rather
+ * than a transient startup order, so the first miss fires `onMissing` once —
+ * without that signal the fallback would silently reproduce issue #17 after
+ * any future upstream rename of the service.
+ * @param read - resolves `ctx.connection`, or `undefined` when absent.
+ * @param onMissing - called once, the first time the service reads absent.
+ * @returns the fence every route in this family runs first.
+ */
+export function hostTrustFence(read: () => HostConnectionHandle | undefined, onMissing?: () => void): RouteFence {
+  let missingReported = false
+  return (request) => {
+    const connection = read()
+    if (connection === undefined) {
+      if (!missingReported) {
+        missingReported = true
+        onMissing?.()
+      }
+      return loopbackOnlyFence(request)
+    }
+    try {
+      return connection.requestRejection(request)
+    } catch {
+      // Fail closed: a broken fence must never open file-mutating routes.
+      return 403
+    }
+  }
+}
 
 /**
  * Build every /api/skill-hub route.
- * @param deps - skill registry view + sidecar store.
+ * @param deps - skill registry view + sidecar store + trust fence.
  * @returns the exact-path routes plus the family's 404 catch-all.
  */
 export function makeRoutes(deps: SkillHubRouteDeps): WebRoute[] {
-  // 各域返回裸 spec，统一在这里包上请求围栏（回环信任 → 方法 → 总开关
+  // 各域返回裸 spec，统一在这里包上请求围栏（信任栅栏 → 方法 → 总开关
   // → JSON 体 → 统一错误映射），新路由不会漏掉围栏。
   const specs = [
     ...catalogRoutes(deps),