deepseek-harness-skill-mcp 0.1.0

package/src/skills.js

@@ -0,0 +1,187 @@
+/** Filesystem inventory and focused authoring operations for managed Skill sources. */
+import { createHash, randomUUID } from 'node:crypto'
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { basename, dirname, extname, join, relative, resolve } from 'node:path'
+import { parseDocument, stringify } from 'yaml'
+
+const skillNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function splitSkill(content) {
+  const match = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content)
+  if (!match) throw new Error('missing-frontmatter')
+  return { yaml: match[1], body: content.slice(match[0].length) }
+}
+
+function frontmatterBoolean(value, fallback) {
+  if (value === undefined) return fallback
+  if (typeof value === 'boolean') return value
+  if (typeof value === 'number' && (value === 0 || value === 1)) return value === 1
+  if (typeof value === 'string') {
+    const normalized = value.toLowerCase()
+    if (['true', 'yes', 'on', '1'].includes(normalized)) return true
+    if (['false', 'no', 'off', '0'].includes(normalized)) return false
+  }
+  throw new Error('invalid-invocation')
+}
+
+function parseFrontmatter(content) {
+  const parts = splitSkill(content)
+  const document = parseDocument(parts.yaml)
+  if (document.errors.length) throw new Error('invalid-yaml')
+  const data = document.toJS()
+  if (!data || typeof data !== 'object' || Array.isArray(data)) throw new Error('invalid-frontmatter')
+  const issues = []
+  if (typeof data.name !== 'string' || !skillNamePattern.test(data.name)) issues.push('invalid-name')
+  if (typeof data.description !== 'string' || !data.description.trim()) issues.push('missing-description')
+  let modelInvocable = true
+  let userInvocable = true
+  try {
+    modelInvocable = !frontmatterBoolean(data['disable-model-invocation'], false)
+    userInvocable = frontmatterBoolean(data['user-invocable'], true)
+  } catch { issues.push('invalid-invocation') }
+  return {
+    data,
+    body: parts.body,
+    issues,
+    name: typeof data.name === 'string' ? data.name : '',
+    description: typeof data.description === 'string' ? data.description.trim() : '',
+    whenToUse: typeof data.whenToUse === 'string' ? data.whenToUse.trim() : '',
+    modelInvocable,
+    userInvocable,
+  }
+}
+
+async function listResources(directory) {
+  const resources = []
+  async function walk(current, depth) {
+    if (depth > 3 || resources.length >= 100) return
+    const entries = await readdir(current, { withFileTypes: true })
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (resources.length >= 100) break
+      if (entry.isSymbolicLink()) continue
+      const path = join(current, entry.name)
+      if (entry.isDirectory()) await walk(path, depth + 1)
+      else if (entry.isFile() && entry.name !== 'SKILL.md') resources.push(relative(directory, path).replaceAll('\\', '/'))
+    }
+  }
+  await walk(directory, 0)
+  return resources
+}
+
+async function inspectSkill(source, path, format) {
+  const relativePath = relative(source.location, path).replaceAll('\\', '/')
+  try {
+    const content = await readFile(path, 'utf8')
+    const parsed = parseFrontmatter(content)
+    const resources = format === 'bundle' ? await listResources(dirname(path)) : []
+    return {
+      sourceId: source.id,
+      sourceEnabled: source.enabled,
+      relativePath,
+      format,
+      name: parsed.name || basename(path, extname(path)),
+      description: parsed.description,
+      whenToUse: parsed.whenToUse,
+      modelInvocable: parsed.modelInvocable,
+      userInvocable: parsed.userInvocable,
+      valid: parsed.issues.length === 0,
+      issues: parsed.issues,
+      resources,
+      revision: createHash('sha256').update(content).digest('hex'),
+    }
+  } catch (error) {
+    const issue = ['missing-frontmatter', 'invalid-yaml', 'invalid-frontmatter'].includes(error.message)
+      ? error.message : 'unreadable'
+    return {
+      sourceId: source.id, sourceEnabled: source.enabled, relativePath, format,
+      name: basename(path, extname(path)), description: '', whenToUse: '',
+      modelInvocable: false, userInvocable: false, valid: false, issues: [issue], resources: [], revision: '',
+    }
+  }
+}
+
+/** Inspect direct Skill entries in every managed source without loading instructions into a session. */
+export async function inspectSkills(rows) {
+  const sources = rows.filter(row => !row.config.serverName).map(row => ({
+    id: row.id, enabled: !row.disabled, location: row.config.customSkillDirs[0],
+    group: typeof row.config.extensionManagerGroup === 'string' ? row.config.extensionManagerGroup : '',
+  }))
+  const skills = []
+  for (const source of sources) {
+    try {
+      const entries = await readdir(source.location, { withFileTypes: true })
+      for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.isDirectory()) {
+          const path = join(source.location, entry.name, 'SKILL.md')
+          try { if ((await stat(path)).isFile()) skills.push(await inspectSkill(source, path, 'bundle')) } catch { /* not a Skill bundle */ }
+        } else if (entry.isFile() && extname(entry.name).toLowerCase() === '.md') {
+          skills.push(await inspectSkill(source, join(source.location, entry.name), 'flat'))
+        }
+      }
+      source.issue = ''
+    } catch { source.issue = 'source-unreadable' }
+  }
+  const winners = new Set()
+  for (const skill of skills) {
+    skill.shadowed = skill.valid && winners.has(skill.name)
+    if (skill.valid && !skill.shadowed) winners.add(skill.name)
+  }
+  return { sources, skills }
+}
+
+function skillSource(rows, sourceId) {
+  const row = rows.find(row => row.id === sourceId && !row.config.serverName)
+  if (!row) throw new Error('Unknown Skill source.')
+  return row.config.customSkillDirs[0]
+}
+
+/** Create an atomic directory Skill bundle inside one managed source. */
+export async function createSkill(rows, input) {
+  if (!skillNamePattern.test(input.name)) throw new Error('Invalid Skill name.')
+  if (!input.description.trim()) throw new Error('Skill description is required.')
+  if (!['minimal', 'standard'].includes(input.structure)) throw new Error('Invalid Skill structure.')
+  const root = skillSource(rows, input.sourceId)
+  const target = resolve(root, input.name)
+  if (dirname(target) !== resolve(root)) throw new Error('Skill path escapes its source.')
+  const temporary = resolve(root, `.${input.name}.${randomUUID()}.tmp`)
+  const frontmatter = {
+    name: input.name,
+    description: input.description.trim(),
+    ...(input.whenToUse.trim() ? { whenToUse: input.whenToUse.trim() } : {}),
+    ...(input.modelInvocable ? {} : { 'disable-model-invocation': true }),
+    ...(input.userInvocable ? {} : { 'user-invocable': false }),
+  }
+  await mkdir(temporary)
+  try {
+    await writeFile(join(temporary, 'SKILL.md'), `---\n${stringify(frontmatter)}---\n\n# ${input.name}\n\n${input.description.trim()}\n`)
+    if (input.structure === 'standard') {
+      await Promise.all(['scripts', 'references', 'assets'].map(name => mkdir(join(temporary, name))))
+    }
+    await rename(temporary, target)
+  } catch (error) {
+    await rm(temporary, { recursive: true, force: true })
+    throw error
+  }
+}
+
+/** Update only invocation frontmatter after checking the exact inspected file revision. */
+export async function setSkillInvocation(rows, input) {
+  const root = skillSource(rows, input.sourceId)
+  const inventory = await inspectSkills(rows)
+  const skill = inventory.skills.find(item => item.sourceId === input.sourceId && item.relativePath === input.relativePath)
+  if (!skill?.valid) throw new Error('Unknown or invalid Skill.')
+  const path = resolve(root, input.relativePath)
+  if (relative(root, path).startsWith('..')) throw new Error('Skill path escapes its source.')
+  const content = await readFile(path, 'utf8')
+  if (createHash('sha256').update(content).digest('hex') !== input.skillRevision) {
+    throw Object.assign(new Error('Skill changed. Refresh before saving.'), { code: 'CONFLICT' })
+  }
+  const parsed = parseFrontmatter(content)
+  if (input.modelInvocable) delete parsed.data['disable-model-invocation']
+  else parsed.data['disable-model-invocation'] = true
+  if (input.userInvocable) delete parsed.data['user-invocable']
+  else parsed.data['user-invocable'] = false
+  const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`)
+  await writeFile(temporary, `---\n${stringify(parsed.data)}---\n${parsed.body}`)
+  await rename(temporary, path)
+}

package/src/store.js

@@ -0,0 +1,216 @@
+/** Owns a marked block inside a profile Cordis patch while retaining legacy JSON stores. */
+import { open, readFile, rename, unlink, stat } from 'node:fs/promises'
+import { basename, isAbsolute, resolve, win32 } from 'node:path'
+import { randomUUID, createHash } from 'node:crypto'
+import { Config as McpConfig } from '@deepseek-ai/dsh-mcp-client'
+import { Config as SkillConfig } from '@deepseek-ai/dsh-skill-filesystem'
+import { parse, stringify } from 'yaml'
+
+const moduleNames = {
+  skill: '@deepseek-ai/dsh-skill-filesystem',
+  mcp: '@deepseek-ai/dsh-mcp-client',
+}
+const managerModule = new URL('./index.js', import.meta.url).href
+const resolvedModules = Object.fromEntries(Object.entries(moduleNames).map(([kind, name]) => [kind, import.meta.resolve(name)]))
+const isModule = (value, kind) => [moduleNames[kind], resolvedModules[kind], new URL('../src/index.ts', resolvedModules[kind]).href, new URL('../lib/index.js', resolvedModules[kind]).href].includes(value)
+const idPattern = /^[A-Za-z0-9_-]{1,32}$/
+const groupField = 'extensionManagerGroup'
+const blockStart = '# dsh-skill-mcp:managed-start'
+const blockEnd = '# dsh-skill-mcp:managed-end'
+
+function normalizeWindowsPath(value) {
+  const trimmed = value.trim()
+  return /^[A-Za-z]:[\\/]/.test(trimmed) ? win32.normalize(trimmed) : trimmed
+}
+
+function samePath(left, right) {
+  const windows = value => /^[A-Za-z]:[\\/]/.test(value)
+  if (windows(left) && windows(right)) return win32.normalize(left).toLowerCase() === win32.normalize(right).toLowerCase()
+  return resolve(left) === resolve(right)
+}
+
+export function revisionOf(rows) {
+  return createHash('sha256').update(JSON.stringify(rows)).digest('hex')
+}
+
+function validateId(id) {
+  if (typeof id !== 'string' || !idPattern.test(id)) throw new Error('Id must contain 1–32 letters, digits, underscores or hyphens.')
+}
+
+function parsePatch(value) {
+  if (!Array.isArray(value) || value.length !== 1 || !Array.isArray(value[0]?.insert)
+    || Object.keys(value[0]).join() !== 'insert') throw new Error('Expected one managed insert operation.')
+  const ids = new Set()
+  const managed = []
+  const preserved = []
+  for (const row of value[0].insert) {
+    if (row?.id === 'extension-manager' && row.name === managerModule) {
+      if (ids.has(row.id)) throw new Error('Duplicate extension id.')
+      ids.add(row.id)
+      preserved.push(row)
+      continue
+    }
+    if (!row || typeof row !== 'object' || Object.keys(row).sort().join() !== 'config,disabled,id,name') throw new Error('Invalid managed row.')
+    validateId(row.id)
+    if (ids.has(row.id)) throw new Error('Duplicate extension id.')
+    ids.add(row.id)
+    if (typeof row.disabled !== 'boolean') throw new Error('Invalid enabled state.')
+    if (isModule(row.name, 'skill')) {
+      SkillConfig(row.config)
+      if (row.config.providerName !== `managed-${row.id}` || row.config.includeDefaultRoots !== false
+        || row.config.customSkillDirs?.length !== 1 || !isAbsolute(row.config.customSkillDirs[0])) throw new Error('Invalid managed skill source.')
+    } else if (isModule(row.name, 'mcp')) {
+      McpConfig(row.config)
+      if (row.config.serverName !== row.id) throw new Error('MCP namespace must match its id.')
+    } else throw new Error('Unknown managed plugin module.')
+    managed.push(row)
+  }
+  return { managed, preserved }
+}
+
+/** Validate the patch and return only extension rows owned by the manager. */
+export function validatePatch(value) {
+  return parsePatch(value).managed
+}
+
+function markedRows(content) {
+  const start = content.indexOf(blockStart)
+  const end = content.indexOf(blockEnd)
+  if (start < 0 && end < 0) return undefined
+  if (start < 0 || end < start || content.indexOf(blockStart, start + blockStart.length) >= 0
+    || content.indexOf(blockEnd, end + blockEnd.length) >= 0) throw new Error('Invalid dsh-skill-mcp managed block.')
+  const bodyStart = start + blockStart.length
+  return { start, end: end + blockEnd.length, rows: validatePatch(parse(content.slice(bodyStart, end))) }
+}
+
+function legacyPatch(content) {
+  try { return parsePatch(JSON.parse(content)) } catch { return undefined }
+}
+
+function renderBlock(rows) {
+  validatePatch([{ insert: rows }])
+  return `${blockStart}\n${stringify([{ insert: rows }]).trimEnd()}\n${blockEnd}`
+}
+
+function writeManagedRows(content, rows) {
+  const marked = markedRows(content)
+  const block = renderBlock(rows)
+  if (marked) return `${content.slice(0, marked.start)}${block}${content.slice(marked.end)}`
+  const legacy = legacyPatch(content)
+  if (legacy) return `${JSON.stringify([{ insert: [...legacy.preserved, ...rows] }], null, 2)}\n`
+  if (/^[ \t]*\[\][ \t]*$/m.test(content)) return content.replace(/^[ \t]*\[\][ \t]*$/m, block)
+  return `${content.trimEnd()}\n\n${block}\n`
+}
+
+/** A store uses an exclusive cross-process lock and atomically replaces its patch. */
+export class ExtensionStore {
+  constructor(path) {
+    if (!isAbsolute(path)) throw new Error('patchPath must be absolute.')
+    this.path = path
+  }
+
+  async read() {
+    const content = await readFile(this.path, 'utf8')
+    return markedRows(content)?.rows ?? legacyPatch(content)?.managed ?? []
+  }
+
+  async update(change, signal, expectedRevision) {
+    signal?.throwIfAborted()
+    const lockPath = `${this.path}.lock`
+    const lock = await open(lockPath, 'wx', 0o600)
+    const temp = `${this.path}.${randomUUID()}.tmp`
+    let tempExists = false
+    try {
+      const content = await readFile(this.path, 'utf8')
+      const rows = markedRows(content)?.rows ?? legacyPatch(content)?.managed ?? []
+      if (expectedRevision !== undefined && revisionOf(rows) !== expectedRevision) {
+        throw Object.assign(new Error('Configuration changed. Refresh before saving.'), { code: 'CONFLICT' })
+      }
+      await change(rows)
+      const document = writeManagedRows(content, rows)
+      signal?.throwIfAborted()
+      const file = await open(temp, 'wx', 0o600)
+      tempExists = true
+      try {
+        await file.writeFile(document)
+        await file.sync()
+      } finally { await file.close() }
+      signal?.throwIfAborted()
+      await rename(temp, this.path)
+      tempExists = false
+    } finally {
+      try { if (tempExists) await unlink(temp) }
+      finally { await lock.close(); await unlink(lockPath) }
+    }
+    return { saved: true, activation: 'pending-profile-reload', patchPath: this.path }
+  }
+
+  async addSkill(id, directory, signal, expectedRevision) {
+    validateId(id)
+    const normalizedDirectory = normalizeWindowsPath(directory)
+    if (!isAbsolute(normalizedDirectory) || !(await stat(normalizedDirectory)).isDirectory()) throw new Error('Skill root must be an existing absolute directory containing skill bundles.')
+    return this.add({ id, name: moduleNames.skill, disabled: true, config: {
+      providerName: `managed-${id}`, includeDefaultRoots: false, customSkillDirs: [normalizedDirectory],
+    } }, signal, expectedRevision)
+  }
+
+  async addSkillPath(directory, group, signal, expectedRevision) {
+    const normalizedDirectory = normalizeWindowsPath(directory)
+    if (!isAbsolute(normalizedDirectory) || !(await stat(normalizedDirectory)).isDirectory()) throw new Error('Skill root must be an existing absolute directory containing skill bundles.')
+    return this.update(rows => {
+      if (rows.some(row => !row.config.serverName && samePath(row.config.customSkillDirs[0], normalizedDirectory))) {
+        throw new Error('Skill path already exists.')
+      }
+      const stem = basename(normalizedDirectory).replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'skills'
+      let id = stem
+      for (let suffix = 2; rows.some(row => row.id === id); suffix++) id = `${stem.slice(0, 27)}-${suffix}`
+      const normalizedGroup = typeof group === 'string' ? group.trim().slice(0, 64) : ''
+      rows.push({ id, name: moduleNames.skill, disabled: true, config: {
+        providerName: `managed-${id}`, includeDefaultRoots: false, customSkillDirs: [normalizedDirectory],
+        ...(normalizedGroup ? { [groupField]: normalizedGroup } : {}),
+      } })
+    }, signal, expectedRevision)
+  }
+
+  async setSkillGroup(id, group, signal, expectedRevision) {
+    return this.update(rows => {
+      const row = rows.find(row => row.id === id && !row.config.serverName)
+      if (!row) throw new Error('Unknown Skill path.')
+      const normalized = group.trim().slice(0, 64)
+      if (normalized) row.config[groupField] = normalized
+      else delete row.config[groupField]
+    }, signal, expectedRevision)
+  }
+
+  async addMcp(id, input, signal, expectedRevision) {
+    validateId(id)
+    // Authentication values belong in the host credential setup, not tool arguments or logs.
+    if (input.env || input.headers) throw new Error('This version does not accept environment values or authentication headers.')
+    const normalized = input.transport === 'stdio' ? {
+      ...input,
+      command: typeof input.command === 'string' ? normalizeWindowsPath(input.command) : input.command,
+      cwd: typeof input.cwd === 'string' && input.cwd ? normalizeWindowsPath(input.cwd) : input.cwd,
+    } : input
+    const config = McpConfig({ ...normalized, serverName: id, failOnStartupError: true })
+    if (config.transport === 'streamable-http') {
+      const url = new URL(config.url)
+      if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('Use an HTTP(S) endpoint without credentials, query or fragment.')
+    } else if (!config.command.trim()) throw new Error('MCP command cannot be empty.')
+    return this.add({ id, name: moduleNames.mcp, disabled: true, config }, signal, expectedRevision)
+  }
+
+  async add(row, signal, expectedRevision) {
+    return this.update(rows => {
+      if (rows.some(existing => existing.id === row.id)) throw new Error('Extension id already exists.')
+      rows.push(row)
+    }, signal, expectedRevision)
+  }
+
+  async setEnabled(id, enabled, signal, expectedRevision) {
+    return this.update(rows => {
+      const row = rows.find(row => row.id === id)
+      if (!row) throw new Error('Unknown extension id.')
+      row.disabled = !enabled
+    }, signal, expectedRevision)
+  }
+}

package/src/web.js

@@ -0,0 +1,78 @@
+/** Authenticated Connection channel for the independent extension settings page. */
+import Schema from '@deepseek-ai/schemastery'
+import { revisionOf } from './store.js'
+import { createSkill, inspectSkills, setSkillInvocation } from './skills.js'
+
+const text = Schema.string().required()
+const schemas = {
+  list: Schema.object({}),
+  'add-skill': Schema.object({ directory: text, group: Schema.string().required(), revision: text }),
+  'add-mcp': Schema.object({ id: text, configuration: text, revision: text }),
+  enable: Schema.object({ id: text, enabled: Schema.boolean().required(), revision: text }),
+  'set-skill-group': Schema.object({ id: text, group: Schema.string().required(), revision: text }),
+  'create-skill': Schema.object({
+    sourceId: text, name: text, description: text, whenToUse: Schema.string().required(),
+    modelInvocable: Schema.boolean().required(), userInvocable: Schema.boolean().required(),
+    structure: text, revision: text,
+  }),
+  'set-skill-invocation': Schema.object({
+    sourceId: text, relativePath: text, skillRevision: text,
+    modelInvocable: Schema.boolean().required(), userInvocable: Schema.boolean().required(), revision: text,
+  }),
+}
+
+/** Return redacted configuration and observed global tool availability. */
+export async function describeExtensions(store, ctx) {
+  const rows = await store.read()
+  const toolNames = ctx.tools.schemas().map(tool => tool.name)
+  const inventory = await inspectSkills(rows)
+  return {
+    revision: revisionOf(rows),
+    ...inventory,
+    extensions: rows.map(row => ({
+      id: row.id,
+      kind: row.config.serverName ? 'mcp' : 'skill',
+      enabled: !row.disabled,
+      location: row.config.transport === 'stdio' ? row.config.command
+        : row.config.transport === 'streamable-http' ? new URL(row.config.url).origin
+          : row.config.customSkillDirs[0],
+      transport: row.config.transport ?? '',
+      tools: row.config.serverName
+        ? toolNames.filter(name => name.startsWith(`mcp__${row.id}__`)).sort() : [],
+    })),
+  }
+}
+
+/** All writes carry the exact revision shown to the user. */
+export function createWebHandler(store, ctx) {
+  return async (endpoint, payload, signal) => {
+    try {
+      if (!Object.hasOwn(schemas, endpoint)) throw new Error('Unknown operation.')
+      const args = schemas[endpoint](payload)
+      signal.throwIfAborted()
+      if (endpoint === 'add-skill') await store.addSkillPath(args.directory, args.group, signal, args.revision)
+      if (endpoint === 'add-mcp') {
+        const input = JSON.parse(args.configuration)
+        if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Expected an MCP configuration object.')
+        await store.addMcp(args.id, input, signal, args.revision)
+      }
+      if (endpoint === 'enable') await store.setEnabled(args.id, args.enabled, signal, args.revision)
+      if (endpoint === 'set-skill-group') await store.setSkillGroup(args.id, args.group, signal, args.revision)
+      if (endpoint === 'create-skill' || endpoint === 'set-skill-invocation') {
+        const rows = await store.read()
+        if (revisionOf(rows) !== args.revision) {
+          throw Object.assign(new Error('Configuration changed. Refresh before saving.'), { code: 'CONFLICT' })
+        }
+        if (endpoint === 'create-skill') await createSkill(rows, args)
+        else await setSkillInvocation(rows, args)
+      }
+      return { ok: true, value: await describeExtensions(store, ctx) }
+    } catch (error) {
+      return { ok: false, error: {
+        code: error.code === 'CONFLICT' ? 'extensions/conflict' : 'extensions/rejected',
+        // Validation errors can quote the submitted configuration; keep it off the response.
+        message: 'Extension operation failed.', details: {},
+      } }
+    }
+  }
+}