dsh-plugin-capabilities 0.1.6 → 0.2.1

package/src/repos.test.ts

@@ -0,0 +1,213 @@
+import { gzipSync } from 'node:zlib'
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import { addGitRepo, addLocalRepo, detectSkillRoots, parseGitHubSource } from './repos.ts'
+import { loadState, removeSkillRoot } from './state.ts'
+
+const root = mkdtempSync(join(tmpdir(), 'dsh-caps-repos-'))
+afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+const skill = (name: string): string => `---\nname: ${name}\ndescription: d ${name}\n---\n\nbody\n`
+
+/** Tar a staging directory (with one top-level component) like codeload. */
+function tarballOf(staging: string): Buffer {
+  const files: Array<{ name: string; body: Buffer; dir: boolean }> = []
+  const walk = (dir: string, prefix: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const child = join(dir, entry.name)
+      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`
+      if (entry.isDirectory()) {
+        files.push({ name: `${rel}/`, body: Buffer.alloc(0), dir: true })
+        walk(child, rel)
+      } else {
+        files.push({ name: rel, body: readFileSync(child), dir: false })
+      }
+    }
+  }
+  walk(staging, '')
+  const blocks: Buffer[] = []
+  for (const entry of files) {
+    const header = Buffer.alloc(512)
+    header.write(entry.name, 0, 'utf8')
+    header.write('0000644\0', 100, 'utf8')
+    header.write('0000000\0', 108, 'utf8')
+    header.write('0000000\0', 116, 'utf8')
+    header.write(entry.body.length.toString(8).padStart(11, '0') + '\0', 124, 'utf8')
+    header.write('00000000000\0', 136, 'utf8')
+    header.write('        ', 148, 'utf8')
+    header.write(entry.dir ? '5' : '0', 156, 'utf8')
+    header.write('ustar\0', 257, 'utf8')
+    header.write('00', 263, 'utf8')
+    let sum = 0
+    for (const byte of header) sum += byte
+    header.write(sum.toString(8).padStart(6, '0') + '\0 ', 148, 'utf8')
+    const pad = (512 - (entry.body.length % 512)) % 512
+    blocks.push(Buffer.concat([header, entry.body, Buffer.alloc(pad)]))
+  }
+  blocks.push(Buffer.alloc(1024))
+  return gzipSync(Buffer.concat(blocks))
+}
+
+describe('parseGitHubSource', () => {
+  it('accepts the common URL shapes', () => {
+    expect(parseGitHubSource('https://github.com/anthropics/skills')).toMatchObject({ owner: 'anthropics', repo: 'skills', label: 'anthropics/skills' })
+    expect(parseGitHubSource('https://github.com/anthropics/skills.git')).toMatchObject({ repo: 'skills' })
+    expect(parseGitHubSource('anthropics/skills')).toMatchObject({ owner: 'anthropics' })
+    expect(parseGitHubSource('https://github.com/anthropics/skills/tree/v2')).toMatchObject({ ref: 'v2' })
+    expect(parseGitHubSource('https://github.com/anthropics/skills#dev')).toMatchObject({ ref: 'dev' })
+    expect(parseGitHubSource('https://github.com/anthropics/skills/tree/v2')?.tarballUrl).toBe('https://codeload.github.com/anthropics/skills/tar.gz/v2')
+    expect(parseGitHubSource('https://github.com/anthropics/skills')?.tarballUrl).toBe('https://codeload.github.com/anthropics/skills/tar.gz/HEAD')
+  })
+  it('rejects non-GitHub input', () => {
+    expect(parseGitHubSource('https://gitlab.com/a/b')).toBeNull()
+    expect(parseGitHubSource('not a url')).toBeNull()
+    expect(parseGitHubSource('')).toBeNull()
+  })
+})
+
+describe('detectSkillRoots', () => {
+  it('detects a single skill at the checkout root', () => {
+    const dir = join(root, 'single')
+    mkdirSync(dir, { recursive: true })
+    writeFileSync(join(dir, 'SKILL.md'), skill('single'))
+    expect(detectSkillRoots(dir)).toEqual({ roots: [], single: true })
+  })
+
+  it('detects skills as immediate children', () => {
+    const dir = join(root, 'collection')
+    mkdirSync(join(dir, 'one'), { recursive: true })
+    writeFileSync(join(dir, 'one', 'SKILL.md'), skill('one'))
+    expect(detectSkillRoots(dir)).toEqual({ roots: [dir], single: false })
+  })
+
+  it('detects a nested skills/ wrapper and mixed layouts', () => {
+    const dir = join(root, 'nested')
+    mkdirSync(join(dir, 'skills', 'alpha'), { recursive: true })
+    writeFileSync(join(dir, 'skills', 'alpha', 'SKILL.md'), skill('alpha'))
+    mkdirSync(join(dir, 'top'), { recursive: true })
+    writeFileSync(join(dir, 'top', 'SKILL.md'), skill('top'))
+    writeFileSync(join(dir, 'README.md'), 'not a skill')
+    const detected = detectSkillRoots(dir)
+    expect(detected.single).toBe(false)
+    // top/ is discovered through the checkout root; skills/ registers on its own.
+    expect(detected.roots).toContain(dir)
+    expect(detected.roots).toContain(join(dir, 'skills'))
+  })
+
+  it('returns empty for a repo without skills', () => {
+    const dir = join(root, 'empty')
+    mkdirSync(join(dir, 'src'), { recursive: true })
+    writeFileSync(join(dir, 'src', 'main.ts'), 'x')
+    expect(detectSkillRoots(dir)).toEqual({ roots: [], single: false })
+  })
+})
+
+describe('addLocalRepo', () => {
+  it('registers a collection folder in place', async () => {
+    const home = join(root, 'home-local')
+    const source = join(root, 'local-collection')
+    mkdirSync(join(source, 'greet'), { recursive: true })
+    writeFileSync(join(source, 'greet', 'SKILL.md'), skill('greet'))
+    const entry = await addLocalRepo(source, home)
+    expect(entry.kind).toBe('local')
+    expect(entry.roots).toEqual([source])
+    expect(loadState(home).skillRoots).toHaveLength(1)
+    expect(existsSync(join(home, 'dsh-plugin-capabilities', 'state.json'))).toBe(true)
+  })
+
+  it('wraps a single-skill folder in a junction material dir', async () => {
+    const home = join(root, 'home-single')
+    const source = join(root, 'local-single')
+    mkdirSync(source, { recursive: true })
+    writeFileSync(join(source, 'SKILL.md'), skill('solo'))
+    const entry = await addLocalRepo(source, home)
+    expect(entry.roots).toHaveLength(1)
+    // The scan root is the material dir; its single child is a link to source.
+    const children = readdirSync(entry.roots[0])
+    expect(children).toHaveLength(1)
+    expect(readFileSync(join(entry.roots[0], children[0], 'SKILL.md'), 'utf8')).toContain('solo')
+
+    // Removing the entry deletes the material dir but never the source.
+    expect(removeSkillRoot(entry.id, home)).toBe(true)
+    expect(existsSync(entry.roots[0])).toBe(false)
+    expect(existsSync(join(source, 'SKILL.md'))).toBe(true)
+  })
+
+  it('rejects a path without skills', async () => {
+    const source = join(root, 'no-skills')
+    mkdirSync(source, { recursive: true })
+    writeFileSync(join(source, 'notes.txt'), 'x')
+    await expect(addLocalRepo(source, join(root, 'home-noskills'))).rejects.toThrow(/no SKILL\.md/)
+  })
+})
+
+describe('addGitRepo', () => {
+  /** Fake codeload: serves a tarball built from a callback-defined checkout. */
+  const fakeFetcher = (build: (checkout: string) => void): typeof fetch => {
+    return (async () => {
+      const staging = join(root, `staging-${Math.random().toString(36).slice(2)}`)
+      mkdirSync(join(staging, 'owner-repo-sha'), { recursive: true })
+      build(join(staging, 'owner-repo-sha'))
+      const archive = tarballOf(staging)
+      rmSync(staging, { recursive: true, force: true })
+      return {
+        ok: true,
+        arrayBuffer: async () => archive.buffer.slice(archive.byteOffset, archive.byteOffset + archive.byteLength),
+      } as unknown as Response
+    }) as unknown as typeof fetch
+  }
+
+  it('downloads, extracts, detects, and persists a collection repo', async () => {
+    const home = join(root, 'home-git')
+    const fetcher = fakeFetcher((checkout) => {
+      mkdirSync(join(checkout, 'brainstorming'), { recursive: true })
+      writeFileSync(join(checkout, 'brainstorming', 'SKILL.md'), skill('brainstorming'))
+    })
+    const entry = await addGitRepo('https://github.com/obra/superpowers', { dshHome: home, fetcher })
+    expect(entry.kind).toBe('git')
+    expect(entry.label).toBe('obra/superpowers')
+    expect(entry.roots).toHaveLength(1)
+    expect(readFileSync(join(entry.roots[0], 'brainstorming', 'SKILL.md'), 'utf8')).toContain('brainstorming')
+    expect(loadState(home).skillRoots.map(row => row.label)).toContain('obra/superpowers')
+  })
+
+  it('registers a single-skill repo through the material dir', async () => {
+    const home = join(root, 'home-git-single')
+    const fetcher = fakeFetcher((checkout) => {
+      writeFileSync(join(checkout, 'SKILL.md'), skill('solo-repo'))
+    })
+    const entry = await addGitRepo('someone/solorepo', { dshHome: home, fetcher })
+    expect(entry.roots).toHaveLength(1)
+    // The material dir is the scan root; the checkout is its one child.
+    const children = readdirSync(entry.roots[0])
+    expect(children).toEqual(['repo'])
+    expect(readFileSync(join(entry.roots[0], 'repo', 'SKILL.md'), 'utf8')).toContain('solo-repo')
+  })
+
+  it('rejects re-registering the same repo', async () => {
+    const home = join(root, 'home-git-dup')
+    const fetcher = fakeFetcher((checkout) => {
+      mkdirSync(join(checkout, 'a'), { recursive: true })
+      writeFileSync(join(checkout, 'a', 'SKILL.md'), skill('a'))
+    })
+    await addGitRepo('anthropics/skills', { dshHome: home, fetcher })
+    await expect(addGitRepo('https://github.com/anthropics/skills', { dshHome: home, fetcher })).rejects.toThrow(/already registered/)
+  })
+
+  it('fails cleanly when the repo holds no skills', async () => {
+    const home = join(root, 'home-git-empty')
+    const fetcher = fakeFetcher((checkout) => {
+      writeFileSync(join(checkout, 'README.md'), 'no skills here')
+    })
+    await expect(addGitRepo('someone/noskills', { dshHome: home, fetcher })).rejects.toThrow(/no SKILL\.md/)
+    // The failed attempt leaves no entry behind.
+    expect(loadState(home).skillRoots).toHaveLength(0)
+  })
+
+  it('propagates download failures', async () => {
+    const failing = (async () => ({ ok: false, status: 404 })) as unknown as typeof fetch
+    await expect(addGitRepo('a/missing', { dshHome: join(root, 'home-git-404'), fetcher: failing })).rejects.toThrow(/HTTP 404/)
+  })
+})

package/src/repos.ts

@@ -0,0 +1,207 @@
+/**
+ * Custom skill repositories the user registers from the Settings page:
+ * a local directory (scanned in place, zero-copy) or a GitHub repo (tarball
+ * download into the plugin's state dir, no git dependency). Detection adapts
+ * to the three layouts skill collections actually use — one skill at the
+ * repo root, skills as immediate children, or a nested `skills/`-style
+ * folder — and registers the matching scan roots for the filesystem
+ * provider.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync } from 'node:fs'
+import { basename, join, resolve } from 'node:path'
+import { addSkillRoot, findRootByUrl, materialDirFor, newEntryId, type SkillRootEntry } from './state.ts'
+import { extractTarGz } from './tar.ts'
+
+/** One GitHub source, parsed from whatever URL shape the user pasted. */
+export interface GitHubSource {
+  owner: string
+  repo: string
+  ref?: string
+  /** `owner/repo`, the display label and dedupe key. */
+  label: string
+  tarballUrl: string
+}
+
+const GITHUB_URL_RE = /^(?:https?:\/\/)?github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?(?:\/(?:tree|archive)\/([^/#?]+?)(?:\.tar\.gz)?)?(?:#([^/?#]+))?(?:[/?#].*)?$/
+const GITHUB_SHORT_RE = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/
+
+/** Parse a GitHub reference; returns null for anything unrecognizable. */
+export function parseGitHubSource(input: string): GitHubSource | null {
+  const trimmed = input.trim()
+  if (trimmed === '') return null
+  let owner = ''
+  let repo = ''
+  let ref: string | undefined
+  let match = GITHUB_URL_RE.exec(trimmed)
+  if (match !== null) {
+    // Capture order: owner, repo, /tree/<ref>, #<ref>.
+    const treeRef = match[3] !== undefined ? match[3] : undefined
+    const hashRef = match[4] !== undefined ? match[4] : undefined
+    owner = match[1]
+    repo = match[2]
+    ref = treeRef ?? hashRef
+  } else {
+    match = GITHUB_SHORT_RE.exec(trimmed)
+    if (match === null) return null
+    ;[, owner, repo] = match
+    ref = undefined
+  }
+  // `owner/repo/tree/<ref>` may URL-encode slashes in the ref — keep as-is;
+  // codeload addresses refs by name, branches with slashes included.
+  const decodedRef = ref !== undefined ? decodeURIComponent(ref) : undefined
+  const label = `${owner}/${repo}`
+  const tarballUrl = `https://codeload.github.com/${owner}/${repo}/tar.gz/${decodedRef ?? 'HEAD'}`
+  return { owner, repo, ref: decodedRef, label, tarballUrl }
+}
+
+/** Where skill layouts were found inside one checkout. */
+export interface DetectedRoots {
+  /** Scan roots to register (empty + single=false means “no skills”). */
+  roots: string[]
+  /** The checkout itself is one skill (SKILL.md at its root). */
+  single: boolean
+}
+
+/** A plausible flat skill file: markdown with frontmatter. */
+function looksLikeSkillFile(file: string): boolean {
+  try {
+    return readFileSync(file, 'utf8').startsWith('---')
+  } catch {
+    return false
+  }
+}
+
+/** Does one directory directly hold skills (bundle children or flat .md)? */
+function holdsSkills(dir: string): boolean {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return false
+  }
+  if (existsSync(join(dir, 'SKILL.md'))) return true
+  for (const name of entries) {
+    if (name.endsWith('.md') && looksLikeSkillFile(join(dir, name))) return true
+  }
+  for (const name of entries) {
+    const child = join(dir, name)
+    try {
+      if (statSync(child).isDirectory() && existsSync(join(child, 'SKILL.md'))) return true
+    } catch {
+      // racing deletion or unreadable entry: ignore
+    }
+  }
+  return false
+}
+
+/**
+ * Find the scan roots for one checkout: the checkout itself when its
+ * immediate children are skills, plus any child directory that only makes
+ * sense as a collection wrapper (`skills/`, `document-skills/`, …). A
+ * checkout with SKILL.md at its own root is one single skill — the caller
+ * must give the provider its PARENT as the scan root.
+ */
+export function detectSkillRoots(checkout: string): DetectedRoots {
+  if (existsSync(join(checkout, 'SKILL.md'))) return { roots: [], single: true }
+  const roots: string[] = []
+  if (holdsSkills(checkout)) roots.push(checkout)
+  let entries: string[]
+  try {
+    entries = readdirSync(checkout)
+  } catch {
+    return { roots, single: false }
+  }
+  for (const name of entries) {
+    if (name.startsWith('.')) continue
+    const child = join(checkout, name)
+    try {
+      if (!statSync(child).isDirectory()) continue
+    } catch {
+      continue
+    }
+    if (existsSync(join(child, 'SKILL.md'))) continue // already covered by the parent root
+    if (holdsSkills(child)) roots.push(child)
+  }
+  return { roots, single: false }
+}
+
+/** Register a local directory as a skill repository. */
+export async function addLocalRepo(path: string, dshHome?: string): Promise<SkillRootEntry> {
+  const resolved = resolve(path.trim().replace(/^"|"$/g, ''))
+  if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+    throw new Error(`not a directory: ${resolved}`)
+  }
+  const detected = detectSkillRoots(resolved)
+  if (!detected.single && detected.roots.length === 0) {
+    throw new Error('no SKILL.md found under that path (expected a skill folder or a folder of skill folders)')
+  }
+  if (detected.single) {
+    // One skill living at the given path: the provider scans a ROOT, so wrap
+    // the path in a dedicated directory holding a single link to it.
+    const id = newEntryId('local')
+    const material = materialDirFor(id, dshHome)
+    rmSync(material, { recursive: true, force: true })
+    mkdirSync(material, { recursive: true })
+    try {
+      symlinkSync(resolved, join(material, 'skill'), process.platform === 'win32' ? 'junction' : 'dir')
+    } catch {
+      rmSync(material, { recursive: true, force: true })
+      throw new Error('single-skill local folders need a directory link; try adding their parent folder instead')
+    }
+    return addSkillRoot({ id, kind: 'local', label: basename(resolved), path: resolved, roots: [material], materialDir: material }, dshHome)
+  }
+  return addSkillRoot({ id: newEntryId('local'), kind: 'local', label: basename(resolved), path: resolved, roots: detected.roots }, dshHome)
+}
+
+/** Download cap for a repo tarball. */
+const TARBALL_MAX_BYTES = 256 * 1024 * 1024
+
+/** Register a GitHub repo: tarball download → extract → detect → persist. */
+export async function addGitRepo(
+  url: string,
+  options: { dshHome?: string; fetcher?: typeof fetch } = {},
+): Promise<SkillRootEntry> {
+  const source = parseGitHubSource(url)
+  if (source === null) throw new Error('expected a GitHub repository URL or owner/repo')
+  const existing = findRootByUrl(source.label, options.dshHome)
+  if (existing !== undefined) throw new Error(`${source.label} is already registered`)
+
+  const doFetch = options.fetcher ?? fetch
+  const response = await doFetch(source.tarballUrl, { signal: AbortSignal.timeout(60_000) })
+  if (!response.ok) throw new Error(`download failed (HTTP ${response.status}) for ${source.tarballUrl}`)
+  const archive = Buffer.from(await response.arrayBuffer())
+  if (archive.byteLength > TARBALL_MAX_BYTES) throw new Error('repository tarball too large')
+
+  const id = newEntryId('git')
+  const material = materialDirFor(id, options.dshHome)
+  rmSync(material, { recursive: true, force: true })
+  const checkout = join(material, 'repo')
+  try {
+    mkdirSync(checkout, { recursive: true })
+    extractTarGz(archive, checkout, { stripComponents: 1 })
+    const detected = detectSkillRoots(checkout)
+    if (!detected.single && detected.roots.length === 0) {
+      throw new Error('no SKILL.md found in that repository')
+    }
+    // A single-skill repo is discovered through the material dir itself; a
+    // collection registers the checkout (plus nested collection wrappers).
+    const roots = detected.single ? [material] : detected.roots
+    return addSkillRoot(
+      { id, kind: 'git', label: source.label, url: source.label, ref: source.ref, roots, materialDir: material },
+      options.dshHome,
+    )
+  } catch (error) {
+    rmSync(material, { recursive: true, force: true })
+    throw error
+  }
+}
+
+/** Validate one scan root still exists; entries can go stale on disk. */
+export function rootExists(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}