dsh-skill-picker 0.5.21 → 0.5.23

package/src/client/shared-state.js

@@ -0,0 +1,189 @@
+/**
+ * Shared picker state — the pinned list and the usage history, kept in ONE place
+ * instead of per browser origin.
+ *
+ * `localStorage` is scoped to an origin, so the desktop app (`dsh-app://app`),
+ * the web UI (`http://127.0.0.1:3080`) and a phone each kept a private copy: pin
+ * a skill on the desktop and the web UI never saw it. The host stores the list
+ * once per DSH home (`$DSH_HOME/dsh-skill-picker-state.json`) and this module
+ * mirrors it into `localStorage`.
+ *
+ * Why mirror instead of replacing `localStorage`: the ranking runs during render
+ * and reads its inputs SYNCHRONOUSLY, so the data path has to stay synchronous.
+ * The mirror keeps that true — the host copy is the source of truth, and
+ * `localStorage` is the synchronous cache of it. Every local write is pushed
+ * back, so both ends converge.
+ *
+ * Every function here is best-effort: a missing route or an offline host must
+ * leave the picker working exactly as it did before, on local data alone.
+ */
+
+/** Same keys the panel reads synchronously. */
+export const PINNED_KEY = 'dsh-skill-picker:pinned'
+export const USAGE_KEY = 'dsh-skill-picker:usage'
+
+/**
+ * Set once this browser has completed a sync against the shared file.
+ *
+ * The first sync of a browser that already had pins MUST union instead of
+ * adopting: whichever client happens to boot first would otherwise overwrite
+ * the file, and the next client would adopt that and silently lose its own
+ * pins. After the first sync this browser follows the file, so a pin removed
+ * on one client really disappears from the others.
+ */
+const SYNCED_KEY = 'dsh-skill-picker:shared-synced'
+
+/** Host route (same origin as the GUI in both the desktop app and the web UI). */
+const ENDPOINT = '/dsh-skill-picker/state'
+
+/** Fired after a pull changes the mirror, so open surfaces re-read it. */
+export const SHARED_STATE_EVENT = 'dsh-skill-picker:shared-state'
+
+/** Read the mirrored pinned list; never throws. */
+function readLocalPinned() {
+  try {
+    const parsed = JSON.parse(localStorage.getItem(PINNED_KEY) ?? '[]')
+    return Array.isArray(parsed) ? parsed.filter((name) => typeof name === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+/** Read the mirrored usage history; never throws. */
+function readLocalUsage() {
+  try {
+    const parsed = JSON.parse(localStorage.getItem(USAGE_KEY) ?? '{}')
+    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/** Write the mirror; never throws. */
+function writeLocal(state) {
+  try {
+    localStorage.setItem(PINNED_KEY, JSON.stringify(state?.pinned ?? []))
+    localStorage.setItem(USAGE_KEY, JSON.stringify(state?.usage ?? {}))
+  } catch {
+    /* storage unavailable — the host copy is still authoritative */
+  }
+}
+
+/** Whether a state object carries anything worth adopting. */
+function isEmptyState(state) {
+  if (state === null || state === undefined || typeof state !== 'object') return true
+  const pinned = Array.isArray(state.pinned) ? state.pinned : []
+  const usage = state.usage !== null && typeof state.usage === 'object' ? state.usage : {}
+  return pinned.length === 0 && Object.keys(usage).length === 0
+}
+
+/** Whether this browser has ever completed a sync. */
+function hasSynced() {
+  try {
+    return localStorage.getItem(SYNCED_KEY) === '1'
+  } catch {
+    return false
+  }
+}
+
+/** Remember that this browser is now following the shared file. */
+function markSynced() {
+  try {
+    localStorage.setItem(SYNCED_KEY, '1')
+  } catch {
+    /* private mode: it simply unions again next time, which is the safe side */
+  }
+}
+
+/** Push the local mirror to the shared file.
+ *
+ * @param options.migrate - first-run mode: the host unions the incoming state
+ *   with whatever is already stored (instead of overwriting it) and returns the
+ *   result, which is then adopted locally. Use it only when the shared file is
+ *   known to be absent.
+ * @returns whether the host accepted the write.
+ */
+export async function pushSharedState({ migrate = false } = {}) {
+  try {
+    const response = await fetch(`${ENDPOINT}${migrate ? '?migrate=1' : ''}`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ pinned: readLocalPinned(), usage: readLocalUsage() }),
+    })
+    if (!response.ok) return false
+    const body = await response.json()
+    if (body?.ok !== true) return false
+    if (migrate) writeLocal(body.state)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Pull the shared file into the local mirror.
+ *
+ * When this browser has never synced before and already holds pins/usage, the
+ * pull goes through the UNIONING migration instead of a plain adopt — otherwise
+ * whichever client boots first overwrites the file and the next one silently
+ * loses its own pins. Once a browser has synced, it follows the file, so a pin
+ * removed on another client really disappears here too.
+ *
+ * @returns whether the mirror was refreshed from the host.
+ */
+export async function pullSharedState() {
+  try {
+    const response = await fetch(ENDPOINT, { headers: { accept: 'application/json' } })
+    if (!response.ok) return false
+    const body = await response.json()
+    if (body?.ok !== true) return false
+
+    const localHasData = !isEmptyState({ pinned: readLocalPinned(), usage: readLocalUsage() })
+
+    // Nothing shared yet: this browser seeds it.
+    if (body.state === null || body.state === undefined) {
+      const pushed = await pushSharedState({ migrate: true })
+      if (pushed) markSynced()
+      return true
+    }
+
+    // First sync on a browser that has its own data: union, never overwrite.
+    if (!hasSynced() && localHasData) {
+      const pushed = await pushSharedState({ migrate: true })
+      if (pushed) {
+        markSynced()
+        return true
+      }
+    }
+
+    // The shared file exists but is empty, and this browser is the only one
+    // still holding data: push it rather than blanking the mirror.
+    if (isEmptyState(body.state) && localHasData) {
+      const pushed = await pushSharedState({ migrate: true })
+      if (pushed) markSynced()
+      return true
+    }
+
+    writeLocal(body.state)
+    markSynced()
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Pull, then tell open surfaces to re-read the mirror.
+ * @returns whether anything was pulled.
+ */
+export async function syncSharedState() {
+  const pulled = await pullSharedState()
+  if (pulled) {
+    try {
+      window.dispatchEvent(new Event(SHARED_STATE_EVENT))
+    } catch {
+      /* an environment without window cannot have listeners either */
+    }
+  }
+  return pulled
+}

package/src/index.js

@@ -18,12 +18,23 @@
  * @module dsh-skill-picker
  */
 
-import { readFile, readdir } from 'node:fs/promises'
+import { mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 
 import { isDirectoryEntry } from './dir-entry.js'
-import { healUiSkillPatches, revertUiSkillPatches } from './patch-ui-skill.js'
+import { dshHome, healUiSkillPatches, revertUiSkillPatches } from './patch-ui-skill.js'
+import {
+  CLIENT_HEADER,
+  DISABLED_ENTRY,
+  ENTRY,
+  listSkillBackups,
+  resolveSkillPath,
+  restoreSkillBackup,
+  revealSkill,
+  setSkillDisabled,
+  uninstallSkill,
+} from './skill-ops.js'
 
 /** Required services: the route registry and the prompt band. */
 export const inject = ['webServer', 'systemPrompt']
@@ -163,10 +174,21 @@ async function scanSkillsDirInto(map, dir) {
     if (!(await isDirectoryEntry(dir, entry))) continue
     const skillDir = path.join(dir, entry.name)
     let content
+    let entryFile = ENTRY
+    let disabled = false
     try {
-      content = await readFile(path.join(skillDir, 'SKILL.md'), 'utf8')
+      content = await readFile(path.join(skillDir, ENTRY), 'utf8')
     } catch {
-      continue
+      // A disabled skill keeps its entry under a different name, which the
+      // official provider ignores entirely. The panel still has to list it, or
+      // there would be no way to switch it back on.
+      try {
+        content = await readFile(path.join(skillDir, DISABLED_ENTRY), 'utf8')
+        entryFile = DISABLED_ENTRY
+        disabled = true
+      } catch {
+        continue
+      }
     }
     const meta = parseFrontmatter(content)
     // The picker is a human-facing surface, so honour the invocation policy:
@@ -181,6 +203,8 @@ async function scanSkillsDirInto(map, dir) {
       name: meta.name ?? entry.name,
       description: meta.description ?? '',
       path: skillDir,
+      entry: entryFile,
+      disabled,
     })
   }
 }
@@ -253,6 +277,216 @@ export function reportUiSkillPatches(report, io = console) {
   }
 }
 
+/**
+ * Shared picker state: the pinned list and the usage history, stored ONCE per
+ * DSH home instead of per browser origin.
+ *
+ * Why it exists: `localStorage` is scoped to an origin, so the desktop app
+ * (`dsh-app://app`), the web UI (`http://127.0.0.1:3080`) and a phone all kept
+ * their own copy — pin a skill on the desktop and the web UI never sees it.
+ * Both halves now read and write this one file.
+ *
+ * @returns the absolute path of the shared state file.
+ */
+function sharedStateFile() {
+  return path.join(dshHome(), 'dsh-skill-picker-state.json')
+}
+
+/** Coerce anything into `{ pinned: string[], usage: {name: {count, lastUsed}} }`. */
+function normalizeSharedState(value) {
+  const source = value !== null && typeof value === 'object' ? value : {}
+  const pinned = Array.isArray(source.pinned)
+    ? [...new Set(source.pinned.filter((name) => typeof name === 'string' && name !== ''))]
+    : []
+  const usage = {}
+  const rawUsage = source.usage !== null && typeof source.usage === 'object' ? source.usage : {}
+  for (const [name, entry] of Object.entries(rawUsage)) {
+    if (typeof name !== 'string' || name === '') continue
+    const record = entry !== null && typeof entry === 'object' ? entry : {}
+    const count = Number.isFinite(record.count) ? Math.max(0, Math.trunc(record.count)) : 0
+    const lastUsed = Number.isFinite(record.lastUsed) ? Math.max(0, Math.trunc(record.lastUsed)) : 0
+    if (count === 0 && lastUsed === 0) continue
+    usage[name] = { count, lastUsed }
+  }
+  return { pinned, usage }
+}
+
+/** Read the shared state, or null when the file does not exist yet. */
+async function readSharedState() {
+  try {
+    return normalizeSharedState(JSON.parse(await readFile(sharedStateFile(), 'utf8')))
+  } catch {
+    return null
+  }
+}
+
+/** Write the shared state atomically (temp + rename), creating the home if needed. */
+async function writeSharedState(state) {
+  const normal = normalizeSharedState(state)
+  const file = sharedStateFile()
+  await mkdir(path.dirname(file), { recursive: true })
+  const tmp = `${file}.tmp`
+  await writeFile(tmp, `${JSON.stringify(normal, null, 2)}\n`, 'utf8')
+  await rename(tmp, file)
+  return normal
+}
+
+/**
+ * First-run migration: union both ends instead of letting whichever browser
+ * happened to write first win, so nobody silently loses their pins.
+ */
+function mergeSharedState(a, b) {
+  const left = normalizeSharedState(a)
+  const right = normalizeSharedState(b)
+  const pinned = [...left.pinned]
+  for (const name of right.pinned) if (!pinned.includes(name)) pinned.push(name)
+  const usage = { ...left.usage }
+  for (const [name, entry] of Object.entries(right.usage)) {
+    const previous = usage[name]
+    usage[name] = previous === undefined
+      ? entry
+      : { count: Math.max(previous.count, entry.count), lastUsed: Math.max(previous.lastUsed, entry.lastUsed) }
+  }
+  return normalizeSharedState({ pinned, usage })
+}
+
+/** Read a JSON request body with a hard cap, so a bad client cannot grow memory. */
+async function readJsonBody(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > 1_000_000) throw new Error('shared state body too large')
+    chunks.push(chunk)
+  }
+  if (chunks.length === 0) return {}
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+/**
+ * `GET /dsh-skill-picker/state` → `{ ok, state }` (`state: null` before the
+ * first write). `PUT` with `{ pinned, usage }` → the stored state; `?migrate=1`
+ * unions the incoming state with the stored one and returns the result.
+ */
+async function handleSharedState(req, res, url) {
+  const json = (code, payload) => {
+    res.writeHead(code, { 'content-type': 'application/json; charset=utf-8' })
+    res.end(JSON.stringify(payload))
+  }
+  try {
+    if (req.method === 'PUT' || req.method === 'POST') {
+      const incoming = normalizeSharedState(await readJsonBody(req))
+      const migrate = url.searchParams.get('migrate') === '1'
+      const stored = migrate ? await readSharedState() : null
+      const next = stored === null ? await writeSharedState(incoming) : await writeSharedState(mergeSharedState(stored, incoming))
+      json(200, { ok: true, state: next })
+      return
+    }
+    json(200, { ok: true, state: await readSharedState() })
+  } catch (error) {
+    json(500, { ok: false, error: String(error?.message ?? error) })
+  }
+}
+
+/**
+ * Every root a skill may live in, in the order the scanner reads them.
+ * Single source of truth: `skill-ops` must not re-derive these.
+ */
+function allSkillRoots(cwd) {
+  const roots = [userAgentsSkillsDir(), userSkillsDir()]
+  if (typeof cwd === 'string' && cwd !== '') {
+    roots.push(path.join(cwd, '.agents', 'skills'), path.join(cwd, '.dsh', 'skills'))
+  }
+  return roots
+}
+
+/**
+ * `POST /dsh-skill-picker/skill` — disable / enable / reveal / uninstall /
+ * restore a skill, and list the uninstall backups.
+ *
+ * Three guards, in order:
+ *
+ *  1. The request must carry `x-dsh-skill-picker: 1`. Plugin routes bypass the
+ *     web server's auth gate (they are reachable without a cookie), and these
+ *     actions rename and move files. A cross-site `fetch` cannot set a custom
+ *     header without a CORS preflight the host does not answer, so this header
+ *     is what keeps an arbitrary web page out.
+ *  2. The target path must resolve inside a known skill root. Anything else —
+ *     the root itself, a file nested inside a skill, `../..`, or an absolute
+ *     path elsewhere — is refused before any filesystem call.
+ *  3. Nothing is ever deleted. "Uninstall" moves the skill into
+ *     `$DSH_HOME/skill-backups/` beside a manifest, and `restore` moves it back.
+ */
+async function handleSkillOp(req, res, url) {
+  const json = (code, payload) => {
+    res.writeHead(code, { 'content-type': 'application/json; charset=utf-8' })
+    res.end(JSON.stringify(payload))
+  }
+  if (req.method !== 'POST') {
+    json(405, { ok: false, error: 'POST only' })
+    return
+  }
+  if (req.headers[CLIENT_HEADER] !== '1') {
+    json(403, { ok: false, error: 'missing client header' })
+    return
+  }
+  try {
+    const body = await readJsonBody(req)
+    const cwd = url.searchParams.get('cwd') ?? undefined
+    const roots = allSkillRoots(cwd)
+    const action = String(body?.action ?? '')
+
+    if (action === 'backups') {
+      json(200, { ok: true, backups: await listSkillBackups(roots) })
+      return
+    }
+    if (action === 'restore') {
+      json(200, { ok: true, ...(await restoreSkillBackup(body?.id, roots)) })
+      return
+    }
+
+    // Resolve by NAME through the host's own scan, never by a path the browser
+    // supplied: the panel's primary source is the official `skills/list` RPC,
+    // whose DTO is not guaranteed to carry a filesystem path — and a name the
+    // host looks up itself cannot point outside the skill roots at all.
+    const name = String(body?.name ?? '')
+    if (name === '') {
+      json(400, { ok: false, error: 'name is required' })
+      return
+    }
+    const known = (await scanSkills(cwd)).find((skill) => skill.name === name)
+    if (known === undefined) {
+      json(404, { ok: false, error: `no skill named "${name}"` })
+      return
+    }
+    const target = resolveSkillPath(known.path, roots)
+    if (target === undefined) {
+      json(403, { ok: false, error: 'that skill lives outside the skill roots' })
+      return
+    }
+
+    if (action === 'disable') {
+      json(200, { ok: true, ...(await setSkillDisabled(target, true)) })
+      return
+    }
+    if (action === 'enable') {
+      json(200, { ok: true, ...(await setSkillDisabled(target, false)) })
+      return
+    }
+    if (action === 'reveal') {
+      json(200, { ok: true, revealed: revealSkill(target) })
+      return
+    }
+    if (action === 'uninstall') {
+      json(200, { ok: true, ...(await uninstallSkill(target)) })
+      return
+    }
+    json(400, { ok: false, error: `unknown action: ${action}` })
+  } catch (error) {
+    json(500, { ok: false, error: String(error?.message ?? error) })
+  }
+}
+
 /**
  * Mount the skills route and the prompt section.
  * @param ctx - context carrying webServer and systemPrompt.
@@ -261,8 +495,17 @@ export function apply(ctx) {
   ctx.effect(() => {
     const handler = async (req, res) => {
       try {
+        const url = new URL(req.url ?? '/', 'http://dsh')
+        if (url.pathname === '/dsh-skill-picker/state') {
+          await handleSharedState(req, res, url)
+          return
+        }
+        if (url.pathname === '/dsh-skill-picker/skill') {
+          await handleSkillOp(req, res, url)
+          return
+        }
         // cwd query carries the active session's workspace root from the client.
-        const cwd = req.url !== undefined ? new URL(req.url, 'http://dsh').searchParams.get('cwd') ?? undefined : undefined
+        const cwd = url.searchParams.get('cwd') ?? undefined
         const skills = await scanSkills(cwd)
         res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
         res.end(JSON.stringify({ ok: true, complete: true, skills }))