dsh-skill-hub 0.3.19 → 0.3.20

package/src/skillfs/scan.ts

@@ -4,8 +4,9 @@ import { load } from 'js-yaml'
 import { parseFrontmatter, repairFrontmatterFileText } from './frontmatter.ts'
 import { rootPath } from './paths.ts'
 import { errorText } from '../error-text.ts'
+import { mapConcurrent } from '../concurrency.ts'
 import { dshHome } from '../store.ts'
-import type { DiagnosticEntry, WritableRoot } from '../protocol.ts'
+import { HEX_COLOR_RE, type DiagnosticEntry, type WritableRoot } from '../protocol.ts'
 
 /** One discoverable skill file in a scanned root. */
 export interface SkillEntry {
@@ -130,7 +131,9 @@ export async function readSkillInterface(directory: string): Promise<SkillInterf
   const hexColor = (value: unknown): string | undefined => {
     if (typeof value !== 'string') return undefined
     const trimmed = value.trim()
-    return /^#[0-9a-fA-F]{6}$/.test(trimmed) ? trimmed : undefined
+    // Shared with the settings card and the config route: one definition, so a
+    // change to the accepted color format cannot land in only some of them.
+    return HEX_COLOR_RE.test(trimmed) ? trimmed : undefined
   }
   const iconPath = (value: unknown): string | undefined => {
     if (typeof value !== 'string' || value.trim() === '') return undefined
@@ -167,33 +170,40 @@ export async function findProjectRoot(cwd: string): Promise<string> {
 }
 
 /**
- * Scan one writable root for files the provider ignores, so the GUI can
- * show why a skill never appears — a
- * missing frontmatter must be visible, not silent). .disabled files belong
- * to the hub and are skipped.
+ * Scan one writable root for files the provider ignores, so the GUI can show
+ * why a skill never appears — a missing frontmatter, a name that disagrees
+ * with the discovery path, and the like must be visible, not silent. Files the
+ * hub itself disabled (`.disabled`) are skipped: they are a toggle state, not
+ * a defect.
  */
 export async function scanDiagnostics(root: WritableRoot, home = dshHome()): Promise<DiagnosticEntry[]> {
-  const diagnostics: DiagnosticEntry[] = []
-  for (const entry of await listSkillEntries(root, home)) {
+  const entries = await listSkillEntries(root, home)
+  // Each entry is read and parsed independently, and the panel polls /catalog
+  // every 5 seconds. A serial read would make the response time grow linearly
+  // with the skill count — the same reason the per-skill `stat` collection in
+  // routes/catalog-data.ts is already parallel. Bounded, not a bare
+  // Promise.all: a root can hold hundreds of entries.
+  const perEntry = await mapConcurrent(entries, 8, async (entry): Promise<DiagnosticEntry[]> => {
+    const found: DiagnosticEntry[] = []
     let text: string
     try {
       text = await readFile(entry.path, 'utf8')
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-        diagnostics.push({ path: entry.path, root, reason: 'unreadable: ' + (errorText(error)) })
+        found.push({ path: entry.path, root, reason: 'unreadable: ' + (errorText(error)) })
       }
-      continue
+      return found
     }
     const parsed = parseFrontmatter(text)
     if ('error' in parsed) {
       const fixable = repairFrontmatterFileText(text) !== null
-      diagnostics.push({ path: entry.path, root, reason: parsed.error, ...(fixable ? { fixable: true } : {}) })
-      continue
+      found.push({ path: entry.path, root, reason: parsed.error, ...(fixable ? { fixable: true } : {}) })
+      return found
     }
     // File was auto-repaired in memory (e.g. unquoted `:`); surface a fixable hint so the user can persist it.
     const repaired = repairFrontmatterFileText(text)
     if (repaired !== null) {
-      diagnostics.push({ path: entry.path, root, reason: 'frontmatter contains unquoted colon/bracket (auto-repaired in memory; click Fix to persist)', fixable: true })
+      found.push({ path: entry.path, root, reason: 'frontmatter contains unquoted colon/bracket (auto-repaired in memory; click Fix to persist)', fixable: true })
     }
     const { value } = parsed
     // The provider registers a skill by its discovery path (directory name or
@@ -201,13 +211,16 @@ export async function scanDiagnostics(root: WritableRoot, home = dshHome()): Pro
     // the skill show up under a different identity than its metadata claims.
     const pathName = entry.kind === 'directory' ? basename(entry.directory) : basename(entry.path, '.md')
     if (value.name !== pathName) {
-      diagnostics.push({ path: entry.path, root, reason: `frontmatter name "${value.name}" does not match the discovery path "${pathName}" (the provider registers by path)` })
+      found.push({ path: entry.path, root, reason: `frontmatter name "${value.name}" does not match the discovery path "${pathName}" (the provider registers by path)` })
     }
     // Agents decide to auto-activate a skill from its one-line description, so
     // a too-short description leaves the skill hard to discover automatically.
     if (value.description.length < 10) {
-      diagnostics.push({ path: entry.path, root, reason: `description is only ${value.description.length} chars; write a one-line description so agents can auto-activate this skill` })
+      found.push({ path: entry.path, root, reason: `description is only ${value.description.length} chars; write a one-line description so agents can auto-activate this skill` })
     }
-  }
-  return diagnostics
+    return found
+  })
+  // mapConcurrent preserves index order, so flattening keeps the previous
+  // per-entry ordering of the diagnostics.
+  return perEntry.flat()
 }

package/src/skillfs.test.ts

@@ -1,8 +1,8 @@
-import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { access, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { clearTrash, createSkill, disableSkill, enableSkill, parseFrontmatter, restoreSkill, rootOfPath, scanDiagnostics, trashSkill } from './skillfs.ts'
+import { clearTrash, createSkill, disableSkill, enableSkill, fixDiagnosticFile, parseFrontmatter, restoreSkill, rootOfPath, scanDiagnostics, trashSkill } from './skillfs.ts'
 
 describe('parseFrontmatter', () => {
   it('parses a healthy frontmatter', () => {
@@ -260,6 +260,20 @@ describe('scanDiagnostics', () => {
     expect(await scanDiagnostics('user-dsh', join(dir, 'missing'))).toEqual([])
   })
 
+  // 并发化（读盘 + 解析从串行改为有界并发）不得让输出变得不确定：
+  // 诊断顺序必须仍然等于发现顺序（按路径排序）。
+  it('keeps diagnostics in discovery order now that the scan is concurrent', async () => {
+    await writeFile(join(skills, 'b-bad.md'), '# nope', 'utf8')
+    await writeFile(join(skills, 'a-bad.md'), '# nope', 'utf8')
+    await writeFile(join(skills, 'c-bad.md'), '# nope', 'utf8')
+    const entries = await scanDiagnostics('user-dsh', home)
+    expect(entries.map((entry) => entry.path)).toEqual([
+      join(skills, 'a-bad.md'),
+      join(skills, 'b-bad.md'),
+      join(skills, 'c-bad.md'),
+    ])
+  })
+
   it('flags a frontmatter name that diverges from the discovery path', async () => {
     await mkdir(join(skills, 'folder-name'))
     await writeFile(join(skills, 'folder-name', 'SKILL.md'), '---\nname: other-name\ndescription: A decent longer description\n---', 'utf8')
@@ -277,6 +291,53 @@ describe('scanDiagnostics', () => {
   })
 })
 
+describe('fixDiagnosticFile', () => {
+  let dir: string
+  let home: string
+  let skills: string
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'dsh-skill-hub-fixdiag-'))
+    home = join(dir, 'home')
+    skills = join(home, 'skills')
+    await mkdir(skills, { recursive: true })
+  })
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('persists the repair atomically and leaves no temp file behind', async () => {
+    const path = join(skills, 'needs-fix', 'SKILL.md')
+    await mkdir(dirname(path), { recursive: true })
+    // Unquoted colon in the description: parseable only after an in-memory
+    // repair, which is exactly what the "Fix" action persists.
+    await writeFile(path, '---\nname: needs-fix\ndescription: Build for AWS: ECS\n---\nbody', 'utf8')
+    const before = await scanDiagnostics('user-dsh', home)
+    expect(before).toHaveLength(1)
+    expect(before[0]).toMatchObject({ path, fixable: true })
+
+    expect(await fixDiagnosticFile(path, home)).toBe(path)
+
+    const parsed = parseFrontmatter(await readFile(path, 'utf8'))
+    if ('error' in parsed) throw new Error('repaired file should parse: ' + parsed.error)
+    expect(parsed.value.description).toBe('Build for AWS: ECS')
+    expect(await scanDiagnostics('user-dsh', home)).toEqual([])
+    // Atomic write = sibling temp file + rename, so no .tmp may survive.
+    expect(await readdir(dirname(path))).toEqual(['SKILL.md'])
+  })
+
+  it('refuses paths outside the writable roots and files that need no repair', async () => {
+    await expect(fixDiagnosticFile(join(dir, 'outside', 'SKILL.md'), home)).rejects.toThrow(/not a hub writable skill path/)
+
+    const healthy = join(skills, 'fine', 'SKILL.md')
+    await mkdir(dirname(healthy), { recursive: true })
+    await writeFile(healthy, '---\nname: fine\ndescription: A perfectly fine description\n---\nbody', 'utf8')
+    await expect(fixDiagnosticFile(healthy, home)).rejects.toThrow(/not auto-fixable/)
+    expect(await readdir(dirname(healthy))).toEqual(['SKILL.md'])
+  })
+})
+
 describe('rootOfPath', () => {
   it('recognizes the writable roots', async () => {
     const dir = await mkdtemp(join(tmpdir(), 'dsh-skill-hub-root-'))

package/src/skillfs.ts

@@ -83,14 +83,18 @@ export async function enableSkill(disabledPath: string): Promise<string> {
 }
 
 /**
- * Move a skill (directory bundle or flat .md file) into the root's trash.
- * The skill stays recoverable: the source is renamed into
- * <root>/.trash/<name>-<timestamp>. A directory bundle is addressed by its
- * SKILL.md path and moved as a whole directory.
+ * Move one already-resolved skill (a bundle directory or a flat .md file) into
+ * its root's trash as `<root>/.trash/<name>-<timestamp>`.
+ *
+ * The layout is the restore contract, not an implementation detail:
+ * `restoreSkill` renames the entry back and only proves the parent is `.trash`,
+ * and `clearTrash` deletes in place. Every producer of a trash entry must go
+ * through here — skill delete, the hub-disabled whole-group delete, and repo
+ * import's placeholder replacement all move skills for the same recovery flow.
+ *
  * @returns the trashed path plus the original path that was moved.
  */
-export async function trashSkill(sourcePath: string): Promise<{ path: string; source: string }> {
-  const source = basename(sourcePath) === 'SKILL.md' ? dirname(sourcePath) : sourcePath
+export async function moveIntoTrash(source: string): Promise<{ path: string; source: string }> {
   const trashDir = join(dirname(source), '.trash')
   await mkdir(trashDir, { recursive: true })
   const target = join(trashDir, basename(source) + '-' + Date.now())
@@ -98,6 +102,17 @@ export async function trashSkill(sourcePath: string): Promise<{ path: string; so
   return { path: target, source }
 }
 
+/**
+ * Move a skill (directory bundle or flat .md file) into the root's trash.
+ * The skill stays recoverable: the source is renamed into
+ * <root>/.trash/<name>-<timestamp>. A directory bundle is addressed by its
+ * SKILL.md path and moved as a whole directory.
+ * @returns the trashed path plus the original path that was moved.
+ */
+export async function trashSkill(sourcePath: string): Promise<{ path: string; source: string }> {
+  return moveIntoTrash(basename(sourcePath) === 'SKILL.md' ? dirname(sourcePath) : sourcePath)
+}
+
 /** Restore a trashed skill (directory or flat file) to its original location. */
 export async function restoreSkill(entry: TrashEntry, home = dshHome()): Promise<string> {
   if (basename(dirname(entry.path)) !== '.trash') {
@@ -127,7 +142,15 @@ function skillFileKind(path: string): 'directory' | 'flat' | undefined {
   return undefined
 }
 
-/** Repair one file on disk when its frontmatter is auto-fixable. Returns the new text. */
+/**
+ * Repair one file on disk when its frontmatter is auto-fixable. Returns the new text.
+ *
+ * The write is atomic (sibling temp file + rename), matching the sidecar's
+ * persist path: this rewrites a real skill file in place, and a crash midway
+ * through a plain write would leave a truncated SKILL.md — exactly the failure
+ * the store layer already guards against. The `.tmp` sibling is never picked
+ * up by discovery (only `SKILL.md` and `*.md` are scanned).
+ */
 export async function fixDiagnosticFile(path: string, home = dshHome()): Promise<string> {
   const root = rootOfPath(path, home)
   if (root === undefined) throw new TypeError('not a hub writable skill path: ' + path)
@@ -137,6 +160,14 @@ export async function fixDiagnosticFile(path: string, home = dshHome()): Promise
   // Validate the repaired text parses as a legal skill (prevents writing a still-broken file).
   const parsed = parseFrontmatter(repairedText)
   if ('error' in parsed) throw new TypeError('repaired frontmatter still invalid: ' + parsed.error)
-  await writeFile(path, repairedText, 'utf8')
+  const tmp = path + '.tmp'
+  await writeFile(tmp, repairedText, 'utf8')
+  try {
+    await rename(tmp, path)
+  } catch (error) {
+    // Never leave a stray temp file behind when the rename is what failed.
+    await rm(tmp, { force: true }).catch(() => {})
+    throw error
+  }
   return path
 }

package/src/update.ts

@@ -9,7 +9,7 @@
 
 import { createRequire } from 'node:module'
 import { errorText } from './error-text.ts'
-import { apiHeaders } from './repo.ts'
+import { apiHeaders, rateLimitResetAt } from './repo.ts'
 import type { UpdateCheckResponse } from './protocol.ts'
 
 /** Repository checked for releases. Keep in sync with package.json. */
@@ -63,11 +63,11 @@ export async function checkLatestRelease(repo = UPDATE_REPO, fetchImpl: typeof f
 
   if (!response.ok) {
     // Rate-limit exhaustion gets a friendlier message with the reset time.
-    const remaining = response.headers.get('x-ratelimit-remaining')
-    const reset = response.headers.get('x-ratelimit-reset')
-    if ((response.status === 403 || response.status === 429) && remaining === '0' && reset !== null) {
-      const at = new Date(Number(reset) * 1000)
-      return failure('github rate limit reached; retry after ' + at.toLocaleTimeString() + ' or set GITHUB_TOKEN')
+    // The header parsing lives in github-client so the repo layer and this
+    // check can never disagree on what counts as exhaustion.
+    const resetAt = rateLimitResetAt(response)
+    if (resetAt !== undefined) {
+      return failure('github rate limit reached; retry after ' + resetAt.toLocaleTimeString() + ' or set GITHUB_TOKEN')
     }
     return failure('GitHub HTTP ' + response.status)
   }