dsh-plugin-capabilities 0.1.0

package/src/skills.test.ts

@@ -0,0 +1,73 @@
+import { mkdtempSync, readFileSync, rmSync, existsSync, writeFileSync, mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import { deleteSkill, serializeSkill, validateSkillInput, writeSkill, type SkillInput } from './skills.ts'
+
+const root = mkdtempSync(join(tmpdir(), 'dsh-caps-skills-'))
+afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+const base: SkillInput = {
+  name: 'my-skill',
+  description: 'Greets politely',
+  modelInvocable: true,
+  userInvocable: true,
+  content: 'Always say please.',
+}
+
+describe('serializeSkill', () => {
+  it('writes required frontmatter and omits default policy keys', () => {
+    const text = serializeSkill(base)
+    expect(text).toContain('name: my-skill')
+    expect(text).toContain(`description: "Greets politely"`)
+    expect(text).toContain('Always say please.')
+    expect(text).not.toContain('disable-model-invocation')
+    expect(text).not.toContain('user-invocable')
+  })
+  it('writes non-default policy keys and whenToUse', () => {
+    const text = serializeSkill({ ...base, modelInvocable: false, userInvocable: false, whenToUse: 'When greeting' })
+    expect(text).toContain('disable-model-invocation: true')
+    expect(text).toContain('user-invocable: false')
+    expect(text).toContain('whenToUse: "When greeting"')
+  })
+  it('escapes quotes and newlines in descriptions (YAML double-quoted)', () => {
+    const text = serializeSkill({ ...base, description: 'line1\n"quoted" \\ back' })
+    expect(text).toContain('description: "line1\\n\\"quoted\\" \\\\ back"')
+  })
+})
+
+describe('validateSkillInput', () => {
+  it('rejects bad names, empty descriptions, oversized bodies', () => {
+    expect(validateSkillInput({ ...base, name: 'Bad_Name' })).toContain('kebab')
+    expect(validateSkillInput({ ...base, name: '../escape' })).toContain('kebab')
+    expect(validateSkillInput({ ...base, description: '  ' })).toContain('description')
+    expect(validateSkillInput({ ...base, content: 'x'.repeat(256 * 1024 + 1) })).toContain('content')
+  })
+  it('accepts a valid skill', () => {
+    expect(validateSkillInput(base)).toBeNull()
+  })
+})
+
+describe('writeSkill / deleteSkill', () => {
+  it('round-trips into the user skills root and deletes by exact directory', () => {
+    const file = writeSkill(base, root)
+    expect(file).toBe(join(root, 'skills', 'my-skill', 'SKILL.md'))
+    expect(readFileSync(file, 'utf8')).toBe(serializeSkill(base))
+
+    expect(deleteSkill('my-skill', root)).toBe(true)
+    expect(existsSync(join(root, 'skills', 'my-skill'))).toBe(false)
+    expect(deleteSkill('my-skill', root)).toBe(false)
+  })
+  it('never touches sibling directories on delete', () => {
+    mkdirSync(join(root, 'skills', 'other'), { recursive: true })
+    writeFileSync(join(root, 'skills', 'other', 'SKILL.md'), '---\nname: other\ndescription: d\n---\n\nx')
+    expect(deleteSkill('my-skill', root)).toBe(false)
+    expect(existsSync(join(root, 'skills', 'other', 'SKILL.md'))).toBe(true)
+  })
+  it('rejects non-directory skill names in delete', () => {
+    mkdirSync(join(root, 'skills', 'flat'), { recursive: true })
+    writeFileSync(join(root, 'skills', 'flat.txt'), 'stray')
+    expect(deleteSkill('..', root)).toBe(false)
+    expect(existsSync(join(root, 'skills', 'flat.txt'))).toBe(true)
+  })
+})

package/src/skills.ts

@@ -0,0 +1,81 @@
+/**
+ * Skill catalog plumbing: frontmatter serialization for user-root SKILL.md
+ * files plus create/update/delete against `$DSH_HOME/skills`. Discovery is the
+ * host's business — the filesystem provider watches the directory, so writes
+ * land in the catalog without any restart.
+ */
+
+import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** Host skill name grammar (dsh-skill's SKILL_NAME). */
+export const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+/** One skill write request from the browser. */
+export interface SkillInput {
+  name: string
+  description: string
+  whenToUse?: string
+  modelInvocable: boolean
+  userInvocable: boolean
+  content: string
+}
+
+/** The user-owned skill root this plugin writes into (provider rank 400). */
+export function userSkillsDir(dshHome: string | undefined = process.env.DSH_HOME): string {
+  return join(dshHome ?? join(homedir(), '.dsh'), 'skills')
+}
+
+/** YAML double-quoted scalar (JSON string syntax is valid YAML 1.2). */
+function quote(value: string): string {
+  return JSON.stringify(value)
+}
+
+/** Frontmatter + body for one skill file. Policy keys only when non-default. */
+export function serializeSkill(input: SkillInput): string {
+  const lines = [
+    `name: ${input.name}`,
+    `description: ${quote(input.description)}`,
+  ]
+  if (input.whenToUse !== undefined && input.whenToUse !== '') lines.push(`whenToUse: ${quote(input.whenToUse)}`)
+  if (!input.modelInvocable) lines.push('disable-model-invocation: true')
+  if (!input.userInvocable) lines.push('user-invocable: false')
+  const body = input.content.replace(/\r\n/g, '\n').trim()
+  return `---\n${lines.join('\n')}\n---\n\n${body}\n`
+}
+
+/** Validate one write request; returns the rejection reason or null. */
+export function validateSkillInput(input: SkillInput): string | null {
+  if (!SKILL_NAME_RE.test(input.name)) return 'name must be kebab-case (a-z, 0-9, dashes)'
+  if (input.description.trim() === '') return 'description is required'
+  if (input.description.length > 1024) return 'description too long (max 1024)'
+  if (input.whenToUse !== undefined && input.whenToUse.length > 2048) return 'whenToUse too long (max 2048)'
+  if (input.content.length > 256 * 1024) return 'content too large (max 256 KiB)'
+  return null
+}
+
+/** Directory holding one user skill's SKILL.md; name grammar blocks traversal. */
+function skillDir(name: string, dshHome?: string): string {
+  return join(userSkillsDir(dshHome), name)
+}
+
+/** Create or update a user skill. Returns the written path. */
+export function writeSkill(input: SkillInput, dshHome?: string): string {
+  const dir = skillDir(input.name, dshHome)
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, 'SKILL.md')
+  writeFileSync(file, serializeSkill(input), 'utf8')
+  return file
+}
+
+/** Delete a user skill directory. Returns false when it does not exist. */
+export function deleteSkill(name: string, dshHome?: string): boolean {
+  if (!SKILL_NAME_RE.test(name)) return false
+  const dir = skillDir(name, dshHome)
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return false
+  // Only ever remove the exact directory this name resolves to under the
+  // skills root; the regex already pins it to one safe path segment.
+  rmSync(dir, { recursive: true, force: true })
+  return true
+}

package/src/smoke.test.ts

@@ -0,0 +1,150 @@
+/**
+ * dsh-plugin-capabilities end-to-end smoke: real source dsh, temp DSH_HOME,
+ * install this package into the web profile, boot `dsh web`, then probe the
+ * manager's routes, including a real skill write and MCP row write.
+ *
+ * Gate: DSH_DESKTOP_PLUGIN_SMOKE=1. Requires deepseek-harness checked out
+ * beside this repo and a host that permits capturing child-process output.
+ */
+
+import { spawn, execFile } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir, homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, describe, expect, it } from 'vitest'
+
+const srcDir = fileURLToPath(new URL('.', import.meta.url))
+const pluginDir = join(srcDir, '..')
+// Layout convention: this repo and deepseek-harness/ sit side by side under
+// the same parent directory (src → repo → parent).
+const repoRoot = join(srcDir, '..', '..', 'deepseek-harness')
+const guard = existsSync(join(repoRoot, 'apps', 'cli', 'src', 'bin.ts'))
+const [nodeMajor, nodeMinor] = process.version.slice(1).split('.').map(Number)
+const nodeOk = (nodeMajor === 22 && nodeMinor >= 19) || nodeMajor >= 24
+
+const smokeRoot = mkdtempSync(join(tmpdir(), 'dsh-plugin-capabilities-smoke-'))
+const dshBin = join(repoRoot, 'apps', 'cli', 'src', 'bin.ts')
+
+/** Test env with a CLEAN PATH (vitest prepends ancestor .bin dirs). */
+function smokeEnv(dshHome: string): NodeJS.ProcessEnv {
+  const systemBins = [
+    process.env.npm_config_prefix,
+    join(homedir(), 'AppData', 'Roaming', 'npm'),
+    dirname(process.execPath),
+  ].filter((value): value is string => typeof value === 'string' && value !== '')
+  const pathValue = [...systemBins, 'C:\\Windows\\system32', 'C:\\Windows'].join(';')
+  return { ...process.env, DSH_HOME: dshHome, PATH: pathValue }
+}
+
+function dsh(args: string[], env: NodeJS.ProcessEnv): Promise<{ code: number | null; out: string }> {
+  return new Promise((resolve) => {
+    execFile(process.execPath, ['--import', 'tsx/esm', dshBin, ...args], {
+      cwd: repoRoot,
+      env: { ...process.env, ...env },
+    }, (error, stdout, stderr) => {
+      const code = error === null ? 0 : typeof error.code === 'number' ? error.code : 1
+      resolve({ code, out: `${stdout}\n${stderr}` })
+    })
+  })
+}
+
+function bootWeb(dshHome: string): Promise<{ port: number }> {
+  return new Promise((resolve, reject) => {
+    // `dsh web` is a hardcoded alias for `--profile web` and rejects any
+    // parent --profile (deepseek-harness apps/cli/src/args.ts).
+    const child = spawn(process.execPath, ['--import', 'tsx/esm', dshBin, 'web', '--port', '0', '--host', '127.0.0.1'], {
+      cwd: repoRoot,
+      env: { ...smokeEnv(dshHome), DSH_DESKTOP: '' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let buffer = ''
+    const timer = setTimeout(() => {
+      child.kill()
+      reject(new Error(`timed out waiting for dsh web URL line; output:\n${buffer.slice(-4000)}`))
+    }, 120_000)
+    const onData = (chunk: Buffer): void => {
+      buffer += chunk.toString()
+      const match = /dsh web: http:\/\/127\.0\.0\.1:(\d+)/.exec(buffer)
+      if (match !== null) {
+        clearTimeout(timer)
+        child.stdout?.off('data', onData)
+        child.stderr?.off('data', onData)
+        resolve({ port: Number(match[1]) })
+      }
+    }
+    child.stdout?.on('data', onData)
+    child.stderr?.on('data', onData)
+    child.on('error', (error) => {
+      clearTimeout(timer)
+      reject(error)
+    })
+    afterAll(() => { try { child.kill() } catch { /* already gone */ } })
+  })
+}
+
+describe.skipIf(process.env.DSH_DESKTOP_PLUGIN_SMOKE !== '1' || !guard || !nodeOk)('dsh-plugin-capabilities smoke', () => {
+  afterAll(() => {
+    if (smokeRoot.startsWith(tmpdir()) && smokeRoot.includes('dsh-plugin-capabilities-smoke-')) {
+      rmSync(smokeRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('installs, boots web, lists skills, writes a skill and an MCP row', { timeout: 240_000 }, async () => {
+    const env = smokeEnv(smokeRoot)
+
+    // 1. Install this package into profile "web".
+    const install = await dsh(['plugin', '--profile', 'web', 'add', `file:${pluginDir}`], env)
+    if (install.code !== 0) console.log('[smoke] FULL dsh output:\n' + install.out)
+    expect(install.code, install.out).toBe(0)
+
+    // 2. Boot `dsh web --port 0`.
+    const { port } = await bootWeb(smokeRoot)
+    const base = `http://127.0.0.1:${port}`
+    const origin = { Origin: base, 'Content-Type': 'application/json' }
+    const post = (path: string, body: unknown): Promise<Response> =>
+      fetch(base + path, { method: 'POST', headers: origin, body: JSON.stringify(body) })
+
+    // 3. Skills list serves the catalog with the editable flag.
+    const skillsResponse = await fetch(`${base}/dsh-plugin-capabilities/skills`)
+    expect(skillsResponse.status).toBe(200)
+    const skillsBody = await skillsResponse.json() as { skills?: Array<{ name: string; source: string; editable: boolean }> }
+    expect(Array.isArray(skillsBody.skills)).toBe(true)
+
+    // 4. Write a user skill; the watched root picks it up into the catalog.
+    const save = await post('/dsh-plugin-capabilities/skill/save', {
+      name: 'smoke-skill',
+      description: 'created by the capabilities smoke',
+      modelInvocable: true,
+      userInvocable: true,
+      content: 'Say smoke.',
+    })
+    expect(save.status).toBe(200)
+    const file = join(smokeRoot, 'skills', 'smoke-skill', 'SKILL.md')
+    expect(existsSync(file)).toBe(true)
+    expect(readFileSync(file, 'utf8')).toContain('name: smoke-skill')
+    const listed = await fetch(`${base}/dsh-plugin-capabilities/skills`).then(r => r.json()) as { skills: Array<{ name: string; editable: boolean }> }
+    // Watcher invalidation is asynchronous; poll briefly for the new skill.
+    const deadline = Date.now() + 15_000
+    let seen = listed.skills.some(skill => skill.name === 'smoke-skill' && skill.editable)
+    while (!seen && Date.now() < deadline) {
+      await new Promise(resolve => setTimeout(resolve, 1000))
+      const again = await fetch(`${base}/dsh-plugin-capabilities/skills`).then(r => r.json()) as { skills: Array<{ name: string; editable: boolean }> }
+      seen = again.skills.some(skill => skill.name === 'smoke-skill' && skill.editable)
+    }
+    expect(seen).toBe(true)
+
+    // 5. MCP row lands in the profile patch and lists back.
+    const mcpSave = await post('/dsh-plugin-capabilities/mcp/save', {
+      id: '',
+      serverName: 'smokeweb',
+      transport: 'streamable-http',
+      url: 'http://127.0.0.1:9/mcp',
+    })
+    expect(mcpSave.status).toBe(200)
+    const servers = await fetch(`${base}/dsh-plugin-capabilities/mcp`).then(r => r.json()) as { servers: Array<{ serverName: string }> }
+    expect(servers.servers.some(row => row.serverName === 'smokeweb')).toBe(true)
+    const patch = readFileSync(join(smokeRoot, 'profiles', 'web', 'cordis.patch.yml'), 'utf8')
+    expect(patch).toContain('@deepseek-ai/dsh-mcp-client')
+  })
+})

package/src/types.ts

@@ -0,0 +1,34 @@
+/** Shared types across the capabilities manager modules. */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+/** The webServer service subset this plugin consumes (structural). */
+export interface WebServerService {
+  register(route: {
+    kind: 'exact' | 'prefix'
+    path: string
+    handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>
+  }): () => void
+}
+
+/** One skill as the host registry reports it (SkillSummary subset). */
+export interface HostSkill {
+  readonly name: string
+  readonly description: string
+  readonly whenToUse?: string
+  readonly invocation: { modelInvocable: boolean; userInvocable: boolean }
+  readonly source: string
+  readonly provider: string
+}
+
+/** 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 }>
+}
+
+/** Host context carrying both services this plugin injects. */
+export interface CapabilitiesHost {
+  webServer: WebServerService
+  skills: SkillsService
+}