dsh-plugin-capabilities 0.1.5 → 0.2.0

package/src/state.ts

@@ -0,0 +1,109 @@
+/**
+ * Plugin-owned state under `$DSH_HOME/dsh-plugin-capabilities/`: the custom
+ * skill repositories the user registered from the Settings page. Everything
+ * the provider mounts live (local paths, extracted GitHub checkouts) hangs
+ * off this file, so it stays small, JSON, and hand-recoverable.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+
+/** One user-registered custom skill repository. */
+export interface SkillRootEntry {
+  /** Stable id (used by the remove route and directory names). */
+  id: string
+  /** `local` — a path on this machine; `git` — extracted from a GitHub URL. */
+  kind: 'local' | 'git'
+  /** Display label (repo `owner/name` or the local path's basename). */
+  label: string
+  /** The source URL (git entries). */
+  url?: string
+  /** Branch/tag/ref the tarball was pulled from (git entries). */
+  ref?: string
+  /** Local path the user pointed at (local entries). */
+  path?: string
+  /** Scan roots this entry contributes (single-skill repos get a wrapper dir). */
+  roots: string[]
+  /** Where this entry's downloaded/junctioned material lives, if any. */
+  materialDir?: string
+  addedAt: number
+}
+
+/** On-disk state document. */
+export interface PluginState {
+  skillRoots: SkillRootEntry[]
+}
+
+/** The plugin's own directory under DSH_HOME (default `~/.dsh`). */
+export function pluginStateDir(dshHome: string | undefined = process.env.DSH_HOME): string {
+  return join(dshHome ?? join(homedir(), '.dsh'), 'dsh-plugin-capabilities')
+}
+
+function statePath(dshHome?: string): string {
+  return join(pluginStateDir(dshHome), 'state.json')
+}
+
+function emptyState(): PluginState {
+  return { skillRoots: [] }
+}
+
+/** Load the state document; missing/corrupt files yield empty state. */
+export function loadState(dshHome?: string): PluginState {
+  const path = statePath(dshHome)
+  if (!existsSync(path)) return emptyState()
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<PluginState>
+    if (!Array.isArray(parsed.skillRoots)) return emptyState()
+    const roots = parsed.skillRoots.filter((entry): entry is SkillRootEntry =>
+      typeof entry === 'object' && entry !== null && typeof entry.id === 'string' && Array.isArray(entry.roots))
+    return { skillRoots: roots }
+  } catch {
+    return emptyState()
+  }
+}
+
+/** Persist the state document (atomic-enough for a single-writer UI). */
+export function saveState(state: PluginState, dshHome?: string): void {
+  const dir = pluginStateDir(dshHome)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(statePath(dshHome), JSON.stringify(state, null, 2) + '\n', 'utf8')
+}
+
+/** New unique entry id. */
+export function newEntryId(kind: 'local' | 'git'): string {
+  return `${kind}-${randomBytes(4).toString('hex')}`
+}
+
+/** One entry's downloaded material (git extraction, junction wrappers). */
+export function materialDirFor(entryId: string, dshHome?: string): string {
+  return join(pluginStateDir(dshHome), 'repos', entryId)
+}
+
+/** Append one entry and persist. Returns the stored entry. */
+export function addSkillRoot(entry: Omit<SkillRootEntry, 'addedAt'>, dshHome?: string): SkillRootEntry {
+  const state = loadState(dshHome)
+  const stored: SkillRootEntry = { ...entry, addedAt: Date.now() }
+  state.skillRoots.push(stored)
+  saveState(state, dshHome)
+  return stored
+}
+
+/** Remove one entry by id and delete its material dir. Returns false when absent. */
+export function removeSkillRoot(id: string, dshHome?: string): boolean {
+  const state = loadState(dshHome)
+  const at = state.skillRoots.findIndex(entry => entry.id === id)
+  if (at === -1) return false
+  const [removed] = state.skillRoots.splice(at, 1)
+  saveState(state, dshHome)
+  if (removed.materialDir !== undefined) {
+    rmSync(removed.materialDir, { recursive: true, force: true, maxRetries: 2 })
+  }
+  return true
+}
+
+/** Whether a git URL is already registered (market “installed” state). */
+export function findRootByUrl(url: string, dshHome?: string): SkillRootEntry | undefined {
+  return loadState(dshHome).skillRoots.find(entry => entry.url === url)
+}

package/src/tar.test.ts

@@ -0,0 +1,100 @@
+import { gzipSync } from 'node:zlib'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import { extractTarGz } from './tar.ts'
+
+const root = mkdtempSync(join(tmpdir(), 'dsh-caps-tar-'))
+afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+/** One USTAR entry (the shape GitHub codeload emits); body null = directory. */
+function tarEntry(name: string, body: Buffer | null, type = body === null ? '5' : '0'): Buffer {
+  const header = Buffer.alloc(512)
+  const size = body === null ? 0 : body.length
+  header.write(name, 0, 'utf8')
+  header.write('0000644\0', 100, 'utf8')
+  header.write('0000000\0', 108, 'utf8')
+  header.write('0000000\0', 116, 'utf8')
+  header.write(size.toString(8).padStart(11, '0') + '\0', 124, 'utf8')
+  header.write('00000000000\0', 136, 'utf8')
+  header.write('        ', 148, 'utf8')
+  header.write(type, 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 - (size % 512)) % 512
+  return Buffer.concat([header, body === null ? Buffer.alloc(0) : body, Buffer.alloc(pad)])
+}
+
+function tarGz(entries: Buffer[]): Buffer {
+  return gzipSync(Buffer.concat([...entries, Buffer.alloc(1024)]))
+}
+
+describe('extractTarGz', () => {
+  it('extracts files and directories with stripComponents', () => {
+    const target = join(root, 'basic')
+    const archive = tarGz([
+      tarEntry('owner-repo-abc123/', null),
+      tarEntry('owner-repo-abc123/SKILL.md', Buffer.from('---\nname: x\n---\n')),
+      tarEntry('owner-repo-abc123/docs/', null),
+      tarEntry('owner-repo-abc123/docs/a.md', Buffer.from('hello')),
+    ])
+    const written = extractTarGz(archive, target, { stripComponents: 1 })
+    expect(written).toBe(4)
+    expect(readFileSync(join(target, 'SKILL.md'), 'utf8')).toContain('name: x')
+    expect(readFileSync(join(target, 'docs', 'a.md'), 'utf8')).toBe('hello')
+  })
+
+  it('rejects entries that escape the target directory', () => {
+    const target = join(root, 'escape')
+    mkdirSync(target, { recursive: true })
+    const guard = join(root, 'escape-guard.txt')
+    writeFileSync(guard, 'keep')
+    const archive = tarGz([tarEntry('../../escape-guard.txt', Buffer.from('pwn'))])
+    expect(() => extractTarGz(archive, target)).toThrow(/unsafe/)
+    expect(readFileSync(guard, 'utf8')).toBe('keep')
+  })
+
+  it('rejects absolute paths', () => {
+    const archive = tarGz([tarEntry('/etc/pwned', Buffer.from('x'))])
+    expect(() => extractTarGz(archive, join(root, 'absolute'))).toThrow(/unsafe/)
+  })
+
+  it('handles a long name delivered via the GNU L entry', () => {
+    const target = join(root, 'longname')
+    const long = `deep/${'a'.repeat(120)}/SKILL.md`
+    const archive = tarGz([
+      tarEntry('././@LongLink', Buffer.from(`${long}\0`), 'L'),
+      tarEntry('placeholder', Buffer.from('---\nname: long\n---\n')),
+    ])
+    extractTarGz(archive, target, { stripComponents: 1 })
+    expect(readFileSync(join(target, 'a'.repeat(120), 'SKILL.md'), 'utf8')).toContain('long')
+  })
+
+  it('skips symlink entries without writing them', () => {
+    const target = join(root, 'links')
+    const archive = tarGz([
+      tarEntry('pkg/', null),
+      tarEntry('pkg/link', null, '2'),
+    ])
+    extractTarGz(archive, target, { stripComponents: 1 })
+    expect(existsSync(join(target, 'link'))).toBe(false)
+  })
+
+  it('rejects a truncated archive', () => {
+    const archive = tarGz([tarEntry('pkg/SKILL.md', Buffer.from('x'.repeat(600)))])
+    const cut = archive.subarray(0, archive.length - 700)
+    expect(() => extractTarGz(cut, join(root, 'truncated'))).toThrow(/truncated|too large|end of file/)
+  })
+
+  it('handles multi-block file bodies', () => {
+    const target = join(root, 'big')
+    const body = Buffer.from('y'.repeat(1025))
+    const archive = tarGz([tarEntry('pkg/data.md', body)])
+    extractTarGz(archive, target, { stripComponents: 1 })
+    expect(readFileSync(join(target, 'data.md'), 'utf8')).toHaveLength(1025)
+  })
+})

package/src/tar.ts

@@ -0,0 +1,154 @@
+/**
+ * Minimal pure-JS tar.gz extraction (node zlib + a USTAR/GNU/PAX-path
+ * reader). GitHub codeload tarballs are all we ever unpack — regular files
+ * and directories, no links — so unsupported entry types are skipped rather
+ * than rejected, and every name is checked against escape before it touches
+ * the filesystem. No subprocess: the dsh sidecar must not spawn tar.
+ */
+
+import { gunzipSync } from 'node:zlib'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** Guard rails for untrusted archives. */
+const LIMITS = {
+  /** Per-entry cap (a skill repo holds markdown and small assets). */
+  entryBytes: 64 * 1024 * 1024,
+  /** Whole-archive content cap. */
+  totalBytes: 256 * 1024 * 1024,
+  /** Entry count cap (also bounds loop time on corrupt input). */
+  entries: 20_000,
+} as const
+
+function octal(block: Buffer, offset: number, length: number): number {
+  const raw = block.toString('utf8', offset, offset + length).replace(/[\0 ]+$/, '')
+  return raw === '' ? 0 : Number.parseInt(raw, 8)
+}
+
+function field(block: Buffer, offset: number, length: number): string {
+  const at = block.indexOf(0, offset)
+  return block.toString('utf8', offset, Math.min(at === -1 ? offset + length : at, offset + length))
+}
+
+/** One parsed tar header. */
+interface TarHeader {
+  name: string
+  size: number
+  type: string
+}
+
+function readHeader(block: Buffer): TarHeader | null {
+  // A zeroed block ends the archive (the checksum of an empty block is 0).
+  if (block.every(byte => byte === 0)) return null
+  const checksum = octal(block, 148, 8)
+  let sum = 0
+  for (let at = 0; at < 512; at++) sum += at >= 148 && at < 156 ? 32 : block[at]
+  if (sum !== checksum) return null
+  const magic = block.toString('utf8', 257, 257 + 6)
+  let name = field(block, 0, 100)
+  if (magic.startsWith('ustar')) {
+    const prefix = field(block, 345, 155)
+    if (prefix !== '') name = `${prefix}/${name}`
+  }
+  return { name, size: octal(block, 124, 12), type: block.toString('utf8', 156, 157) }
+}
+
+/** Resolve one entry name under the target, rejecting escapes. */
+function safeJoin(target: string, name: string): string | null {
+  const normalized = name.replace(/\\/g, '/')
+  if (normalized.startsWith('/') || /^[A-Za-z]:/.test(normalized)) return null
+  const parts: string[] = []
+  for (const part of normalized.split('/')) {
+    if (part === '' || part === '.') continue
+    if (part === '..') return null
+    parts.push(part)
+  }
+  if (parts.length === 0) return null
+  return join(target, ...parts)
+}
+
+/** PAX extended header records (`<len> key=value\n` lines) → key/value map. */
+function paxRecords(content: Buffer): Map<string, string> {
+  const out = new Map<string, string>()
+  let cursor = 0
+  while (cursor < content.length) {
+    const spaceAt = content.indexOf(' ', cursor)
+    if (spaceAt === -1) break
+    const length = Number.parseInt(content.toString('utf8', cursor, spaceAt), 10)
+    if (!Number.isInteger(length) || length <= 0 || cursor + length > content.length) break
+    const record = content.toString('utf8', spaceAt + 1, cursor + length).trimEnd()
+    const eq = record.indexOf('=')
+    if (eq > 0) out.set(record.slice(0, eq), record.slice(eq + 1))
+    cursor += length
+  }
+  return out
+}
+
+/** Number of leading path components to drop (GitHub tarballs wrap one). */
+export interface ExtractOptions {
+  stripComponents?: number
+}
+
+/**
+ * Extract a gzip'd tar buffer into `target` (created when absent). Returns
+ * the entry count written. Throws on structure errors and oversize archives.
+ */
+export function extractTarGz(archive: Buffer, target: string, options: ExtractOptions = {}): number {
+  const tar = gunzipSync(archive)
+  const strip = options.stripComponents ?? 0
+  let offset = 0
+  let written = 0
+  let total = 0
+  let pendingLongName: string | undefined
+  let pendingPath: string | undefined
+  while (offset + 512 <= tar.length) {
+    const header = readHeader(tar.subarray(offset, offset + 512))
+    if (header === null) break
+    offset += 512
+    const contentEnd = offset + header.size
+    if (contentEnd > tar.length) throw new Error('truncated tar entry')
+    const content = tar.subarray(offset, contentEnd)
+    offset += Math.ceil(header.size / 512) * 512
+    if (header.size > LIMITS.entryBytes) throw new Error('tar entry too large')
+    total += header.size
+    if (total > LIMITS.totalBytes) throw new Error('tar archive too large')
+    if (++written > LIMITS.entries) throw new Error('too many tar entries')
+
+    // Metadata entries carry the name for the entry that follows.
+    if (header.type === 'L') {
+      pendingLongName = field(content, 0, content.length)
+      continue
+    }
+    if (header.type === 'x' || header.type === 'X') {
+      pendingPath = paxRecords(content).get('path')
+      continue
+    }
+    if (header.type === 'g') continue // global pax: nothing we need
+
+    let name = pendingLongName ?? pendingPath ?? header.name
+    pendingLongName = undefined
+    pendingPath = undefined
+
+    const parts = name.split('/')
+    if (parts.length <= strip) continue // nothing left after stripping
+    name = parts.slice(strip).join('/')
+    // The stripped top-level directory itself ("pkg/" → "") owns nothing.
+    if (name === '' || name === '/') continue
+
+    // Directories: type '5' or a trailing slash. Symlinks/hardlinks/other
+    // types are skipped — skill repos that depend on them degrade loudly
+    // elsewhere instead of planting links from untrusted input.
+    const isDir = header.type === '5' || (header.type === '0' || header.type === '\0') && name.endsWith('/')
+    if (header.type !== '0' && header.type !== '\0' && header.type !== '5') continue
+
+    const resolved = safeJoin(target, name)
+    if (resolved === null) throw new Error(`unsafe tar entry name: ${name}`)
+    if (isDir) {
+      mkdirSync(resolved, { recursive: true })
+      continue
+    }
+    mkdirSync(dirname(resolved), { recursive: true })
+    writeFileSync(resolved, content)
+  }
+  return written
+}

package/src/types.ts

@@ -19,12 +19,22 @@ export interface HostSkill {
   readonly invocation: { modelInvocable: boolean; userInvocable: boolean }
   readonly source: string
   readonly provider: string
+  /** Provider-specific base (directory skills carry their folder here). */
+  readonly resourceBase?: { kind: 'directory'; path: string } | { kind: 'url'; url: string } | { kind: 'opaque'; description: string }
+}
+
+/** Loaded skill definition subset the routes consume. */
+export interface HostSkillDefinition {
+  readonly name: string
+  readonly content: string
+  readonly path?: string
+  readonly resourceBase?: HostSkill['resourceBase']
 }
 
 /** The skills service subset this plugin consumes (structural). */
 export interface SkillsService {
   list(options?: { cwd?: string }): Promise<HostSkill[]>
-  get(name: string, options?: { cwd?: string }): Promise<{ name: string; content: string }>
+  get(name: string, options?: { cwd?: string }): Promise<HostSkillDefinition | undefined>
 }
 
 /** Host context carrying both services this plugin injects. */