dsh-skill-store 0.1.0

package/lib/index.js

@@ -0,0 +1,951 @@
+// dsh-skill-store host plugin
+// Community skill marketplace. Two sources:
+//   1. github   — the awesome-skills-cn mirror (broad coverage, no popularity data)
+//   2. clawhub  — ClawHub registry (stars / downloads / installs / topics)
+//   3. skillhub — SkillHub.cn, 131k+ skills with a bilingual 13-category taxonomy
+import { readFile, writeFile, mkdir, access, readdir, rm } from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import * as clawhub from "./clawhub.js";
+import * as skillhub from "./skillhub.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const name = "dsh-skill-store";
+
+// No inject export — all service dependencies are acquired inside apply()
+// via ctx.inject(["webServer"], callback), same as dshmarket does.
+
+const Config = null;
+
+// ── API client (in-process, not network) ───────────────────────────
+
+const DSH_HOME = process.env.DSH_HOME
+  ? resolve(process.env.DSH_HOME)
+  : join(homedir(), ".dsh");
+const SKILLS_DIR = join(DSH_HOME, "skills");
+const CACHE_DIR = join(DSH_HOME, "skill-store-cache");
+const CACHE_FILE = join(CACHE_DIR, "registry.json");
+const CACHE_TTL = 24 * 60 * 60 * 1000;
+
+async function ensureDir(dir) {
+  try { await mkdir(dir, { recursive: true }); } catch {}
+}
+
+async function fileExists(p) {
+  try { await access(p); return true; } catch { return false; }
+}
+
+// ── Registry (awesome-skills-cn via GitHub API) ────────────────────
+
+const REGISTRY_REPO = "lingxling/awesome-skills-cn";
+const API_BASE = `https://api.github.com/repos/${REGISTRY_REPO}`;
+
+// ── Collection metadata ────────────────────────────────────────────────────
+// The upstream repo ships no per-skill taxonomy (measured: `tags` present in
+// only 2% of SKILL.md, `category` in 6%), so "everything is uncategorized" is
+// a property of the data source, not a bug. We therefore derive the primary
+// category from the collection directory, and surface the upstream project's
+// GitHub stars as a collection-level popularity signal.
+const COLLECTION_META = {
+  "anthropics-skills":                  { label: "Anthropic 官方",   upstream: "anthropics/skills" },
+  "antigravity-awesome-skills":         { label: "Antigravity 社区", upstream: "sickn33/antigravity-awesome-skills" },
+  "awesome-openclaw-skills":            { label: "OpenClaw 社区",    upstream: "VoltAgent/awesome-clawdbot-skills" },
+  "claude-scientific-skills":           { label: "科学研究",         upstream: "K-Dense-AI/claude-scientific-skills" },
+  "composiohq-awesome-claude-skills":   { label: "Composio 工具集",  upstream: "ComposioHQ/awesome-claude-skills" },
+  "huggingface-skills":                 { label: "HuggingFace",      upstream: "huggingface/skills" },
+  "obsidian-skills":                    { label: "Obsidian",         upstream: "kepano/obsidian-skills" },
+  "openai-skills":                      { label: "OpenAI 官方",      upstream: "openai/skills" },
+  "ui-ux-pro-max-skill":                { label: "UI/UX 设计",       upstream: "nextlevelbuilder/ui-ux-pro-max-skill" },
+  "vercel-labs-agent-skills":           { label: "Vercel Agent",     upstream: "vercel-labs/agent-skills" },
+  "vercel-labs-skills":                 { label: "Vercel",           upstream: "vercel-labs/skills" },
+};
+
+/** collection key → upstream star count (filled lazily, cached in memory). */
+const _upstreamStars = new Map();
+
+/**
+ * Fetch upstream repo stars for every known collection. Best effort and
+ * cached; failures leave the value undefined so the UI can simply omit it.
+ */
+async function fetchUpstreamStars() {
+  const jobs = Object.entries(COLLECTION_META).map(async ([key, meta]) => {
+    if (_upstreamStars.has(key) || !meta.upstream) return;
+    try {
+      const res = await fetch(`https://api.github.com/repos/${meta.upstream}`, {
+        headers: {
+          Accept: "application/vnd.github.v3+json",
+          "User-Agent": "dsh-skill-store/0.1.0",
+          ...(GITHUB_TOKEN ? { Authorization: `token ${GITHUB_TOKEN}` } : {}),
+        },
+        signal: AbortSignal.timeout(12000),
+      });
+      if (res.ok) {
+        const d = await res.json();
+        _upstreamStars.set(key, d.stargazers_count ?? 0);
+      }
+    } catch { /* leave undefined */ }
+  });
+  await Promise.allSettled(jobs);
+}
+
+// ── Raw content mirrors ────────────────────────────────────────────────────
+// raw.githubusercontent.com is unreachable on some networks (DNS blocked).
+// jsDelivr mirrors the same repo content and is reachable from CN, so we try
+// each mirror in order and fall through on failure.
+const RAW_MIRRORS = [
+  `https://cdn.jsdelivr.net/gh/${REGISTRY_REPO}@main`,
+  `https://gcore.jsdelivr.net/gh/${REGISTRY_REPO}@main`,
+  `https://fastly.jsdelivr.net/gh/${REGISTRY_REPO}@main`,
+  `https://raw.githubusercontent.com/${REGISTRY_REPO}/main`,
+];
+// Kept for backwards compatibility with any code path referencing RAW_BASE.
+const RAW_BASE = RAW_MIRRORS[0];
+
+/** Index of the mirror that most recently succeeded; tried first next time. */
+let _activeMirror = 0;
+
+// Optional GitHub token for higher rate limit (60 → 5000/hour)
+const GITHUB_TOKEN = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "";
+
+let _lastError = null;
+
+async function githubApi(path) {
+  const headers = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "dsh-skill-store/0.1.0",
+  };
+  if (GITHUB_TOKEN) headers.Authorization = `token ${GITHUB_TOKEN}`;
+
+  const res = await fetch(`${API_BASE}${path}`, { headers });
+  if (!res.ok) {
+    const msg = res.status === 403
+      ? `GitHub API rate limit exceeded (403). Set GITHUB_TOKEN env var for 5000 req/hr, or wait ~1 hour.`
+      : res.status === 429
+      ? `GitHub API rate limit exceeded (429). Retry after ${res.headers.get("retry-after") || "a while"}.`
+      : `GitHub API ${res.status}`;
+    throw new Error(msg);
+  }
+  return res.json();
+}
+
+async function rawFetch(path) {
+  // Start from the mirror that worked last time, then walk the rest.
+  const order = [];
+  for (let i = 0; i < RAW_MIRRORS.length; i++) {
+    order.push((_activeMirror + i) % RAW_MIRRORS.length);
+  }
+
+  let lastErr = null;
+  for (const idx of order) {
+    const base = RAW_MIRRORS[idx];
+    try {
+      const res = await fetch(`${base}/${path}`, {
+        headers: { "User-Agent": "dsh-skill-store/0.1.0" },
+        signal: AbortSignal.timeout(15000),
+      });
+      if (res.ok) {
+        _activeMirror = idx;
+        return await res.text();
+      }
+      // 404 means the file genuinely does not exist — no point trying others.
+      if (res.status === 404) return null;
+      lastErr = new Error(`${base} -> HTTP ${res.status}`);
+    } catch (e) {
+      lastErr = e;
+    }
+  }
+  if (lastErr) _lastError = `rawFetch failed for ${path}: ${lastErr.message}`;
+  return null;
+}
+
+function parseFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return null;
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") { end = i; break; }
+  }
+  if (end < 0) return null;
+  const data = {};
+  let ck = "", ca = [], inA = false;
+  for (const line of lines.slice(1, end)) {
+    const t = line.trim();
+    if (!t) continue;
+    const am = t.match(/^\s*-\s+(.+)$/);
+    if (am) { if (inA) ca.push(am[1].replace(/^["']|["']$/g, "")); continue; }
+    if (inA && ck) { data[ck] = ca; ca = []; ck = ""; inA = false; }
+    const km = t.match(/^(\w[\w-]*)\s*:\s*(.+)$/);
+    if (km) {
+      let v = km[2].replace(/^["']|["']$/g, "");
+      if (v.startsWith("[") && v.endsWith("]")) {
+        v = v.slice(1,-1).split(",").map(s => s.trim().replace(/^["']|["']$/g, ""));
+      } else if (v === "" || v === "[]") { ck = km[1]; ca = []; inA = true; continue; }
+      data[km[1]] = v; ck = ""; inA = false;
+    }
+  }
+  if (inA && ck) data[ck] = ca;
+  return { data, body: lines.slice(end + 1).join("\n") };
+}
+
+let registryCache = null;
+
+/**
+ * Build the category index. Primary facet is the collection label (always
+ * present for this source); per-skill tags are added as secondary facets when
+ * the SKILL.md actually provides them.
+ */
+function buildCategories(skills) {
+  const categories = {};
+  for (const [name, s] of Object.entries(skills)) {
+    const cats = [];
+    if (s.collectionLabel) cats.push(s.collectionLabel);
+    for (const tag of s.tags || []) if (!cats.includes(tag)) cats.push(tag);
+    if (cats.length === 0) cats.push("uncategorized");
+    for (const c of cats) {
+      (categories[c] = categories[c] || []).push(name);
+    }
+  }
+  return categories;
+}
+
+async function getRegistry(force = false) {
+  if (!force && registryCache) return registryCache;
+  // Try disk cache first
+  try {
+    await access(CACHE_FILE);
+    const raw = await readFile(CACHE_FILE, "utf-8");
+    const cached = JSON.parse(raw);
+    if (Date.now() - new Date(cached.builtAt).getTime() < CACHE_TTL) {
+      registryCache = cached;
+      return cached;
+    }
+  } catch {}
+  _lastError = null;
+  try {
+  // Build from GitHub — fetch child trees so we don't time out on one
+  // giant recursive tree. awesome-skills-cn is ~60 MB; its recursive
+  // tree JSON is too large for a single request to complete reliably.
+  //
+  // Strategy: each collection tree costs 1 API call; each `skills/`
+  // sub-tree costs 1 more. We avoid per-skill tree checks (they blow
+  // through the unauthenticated rate limit of 60/hour for 7000+ skills).
+  // Instead we assume every directory inside `skills/` is a valid skill
+  // and only download SKILL.md content (raw.githubusercontent.com, no
+  // rate limit).
+  const rootTree = await githubApi("/git/trees/main");
+  const collectionTrees = rootTree.tree
+    .filter((item) => item.type === "tree");
+
+  // skillName → { rawPath: "...", collection: "..." }
+  const skillDirs = new Map();
+
+  for (const coll of collectionTrees) {
+    try {
+      const collTree = await githubApi(`/git/trees/main:${coll.path}`);
+
+      // Pattern A: coll/skills/skillName/ (e.g. anthropics-skills/skills/xxx/)
+      const skillsDir = collTree.tree.find(
+        (item) => item.type === "tree" && item.path.toLowerCase() === "skills"
+      );
+      if (skillsDir) {
+        const skillsTree = await githubApi(`/git/trees/main:${coll.path}/skills`);
+        for (const item of skillsTree.tree) {
+          if (item.type !== "tree") continue;
+          if (skillDirs.has(item.path)) continue;
+          skillDirs.set(item.path, {
+            rawPath: `${coll.path}/skills/${item.path}`,
+            collection: coll.path,
+          });
+        }
+      }
+    } catch {
+      // Collection tree fetch failed — skip this collection
+    }
+  }
+
+  // ── Build the skeleton only ───────────────────────────────────────────────
+  // Fetching 2000+ SKILL.md files up front takes many minutes and hammers the
+  // CDN. Instead we publish the directory listing immediately (name, path,
+  // collection) and enrich entries with description/tags in the background.
+  // The UI shows the full list right away; detail arrives progressively.
+  // Populate upstream stars before building so entries can carry the signal.
+  await fetchUpstreamStars();
+
+  const skills = {};
+  for (const [skillName, info] of skillDirs) {
+    const meta = COLLECTION_META[info.collection];
+    skills[skillName] = {
+      name: skillName,
+      description: skillName,          // placeholder until enriched
+      collection: info.collection,
+      collectionLabel: meta?.label ?? info.collection,   // primary category
+      upstream: meta?.upstream ?? null,
+      upstreamStars: _upstreamStars.get(info.collection), // collection-level popularity
+      source: "github",
+      stars: null,                     // no per-skill stars exist for this source
+      tags: [],                        // filled by enrichment if SKILL.md has them
+      rawPath: info.rawPath,           // stable path; URL built at fetch time
+      browseUrl: `https://github.com/${REGISTRY_REPO}/tree/main/${info.rawPath}`,
+      enriched: false,
+    };
+  }
+
+  // Restore any previously enriched metadata so we don't lose work on rebuild.
+  try {
+    const prevRaw = await readFile(CACHE_FILE, "utf-8");
+    const prev = JSON.parse(prevRaw).skills || {};
+    for (const [n, s] of Object.entries(prev)) {
+      if (skills[n] && s.enriched) {
+        skills[n] = { ...s, rawPath: skills[n].rawPath, browseUrl: skills[n].browseUrl };
+      }
+    }
+  } catch {}
+
+  // Primary categories come from the collection; per-skill tags (rare on this
+  // source) are kept as secondary facets.
+  const categories = {};
+  for (const [name, s] of Object.entries(skills)) {
+    const cats = s.collectionLabel ? [s.collectionLabel] : [];
+    for (const tag of s.tags || []) if (!cats.includes(tag)) cats.push(tag);
+    if (cats.length === 0) cats.push("uncategorized");
+    for (const c of cats) {
+      if (!categories[c]) categories[c] = [];
+      categories[c].push(name);
+    }
+  }
+
+  const collections = {};
+  for (const [key, meta] of Object.entries(COLLECTION_META)) {
+    const n = Object.values(skills).filter((s) => s.collection === key).length;
+    if (n > 0) {
+      collections[key] = {
+        label: meta.label,
+        upstream: meta.upstream,
+        stars: _upstreamStars.get(key) ?? null,
+        count: n,
+      };
+    }
+  }
+
+  const index = {
+    builtAt: new Date().toISOString(),
+    count: Object.keys(skills).length,
+    skills,
+    categories,
+    collections,
+    _debug: _lastError,
+  };
+  await ensureDir(CACHE_DIR);
+  await writeFile(CACHE_FILE, JSON.stringify(index), "utf-8");
+  registryCache = index;
+  return index;
+} catch (e) {
+  _lastError = e.message;
+  // Return empty but cached result so the UI doesn't hang
+  const fallback = { builtAt: new Date().toISOString(), count: 0, skills: {}, categories: {}, _error: e.message };
+  registryCache = fallback;
+  return fallback;
+}
+}
+
+async function getSkillEntry(name) {
+  const reg = await getRegistry();
+  return reg.skills[name] ?? null;
+}
+
+// ── Background enrichment ──────────────────────────────────────────
+// Walks the skeleton and fills in description/tags by downloading each
+// SKILL.md. Runs unattended; the cache is rewritten periodically so a
+// restart resumes where it left off.
+
+let _enriching = false;
+let _enrichedCount = 0;
+
+async function enrichRegistry() {
+  if (_enriching) return;
+  const reg = await getRegistry();
+  const pending = Object.values(reg.skills).filter((s) => !s.enriched);
+  if (pending.length === 0) return;
+
+  _enriching = true;
+  _enrichedCount = 0;
+  try {
+    const BATCH = 6;
+    for (let i = 0; i < pending.length; i += BATCH) {
+      const batch = pending.slice(i, i + BATCH);
+      const results = await Promise.allSettled(batch.map(async (entry) => {
+        const content = await rawFetch(`${entry.rawPath}/SKILL.md`);
+        if (!content) return null;
+        const parsed = parseFrontmatter(content);
+        if (!parsed) return null;
+        return { name: entry.name, parsed: parsed.data };
+      }));
+      let changed = false;
+      for (const r of results) {
+        if (r.status !== "fulfilled" || !r.value) continue;
+        const { name, parsed } = r.value;
+        const cur = reg.skills[name];
+        if (!cur) continue;
+        const tags = Array.isArray(parsed.tags) ? parsed.tags
+          : typeof parsed.tags === "string" ? [parsed.tags] : [];
+        reg.skills[name] = {
+          ...cur,
+          description: typeof parsed.description === "string" ? parsed.description : cur.description,
+          whenToUse: typeof parsed.whenToUse === "string" ? parsed.whenToUse : undefined,
+          tags,
+          author: typeof parsed.author === "string" ? parsed.author : undefined,
+          enriched: true,
+        };
+        _enrichedCount++;
+        changed = true;
+      }
+      // Persist every 10 batches (~60 skills) so progress survives a restart.
+      if (changed && (i / BATCH) % 10 === 0) {
+        reg.categories = buildCategories(reg.skills);
+        await ensureDir(CACHE_DIR);
+        await writeFile(CACHE_FILE, JSON.stringify(reg), "utf-8");
+      }
+    }
+    // Final flush
+    const categories = {};
+    reg.categories = buildCategories(reg.skills);
+    await ensureDir(CACHE_DIR);
+    await writeFile(CACHE_FILE, JSON.stringify(reg), "utf-8");
+  } catch {
+    // Enrichment is best-effort; never break the host.
+  } finally {
+    _enriching = false;
+  }
+}
+
+async function queryRegistry({ search, category, limit = 50, offset = 0 } = {}) {
+  const reg = await getRegistry();
+  let names = Object.keys(reg.skills);
+  if (category && reg.categories[category]) {
+    names = names.filter(n => reg.categories[category].includes(n));
+  }
+  if (search) {
+    const q = search.toLowerCase();
+    names = names.filter(n => n.toLowerCase().includes(q) || (reg.skills[n]?.description?.toLowerCase().includes(q)));
+  }
+  return {
+    entries: names.slice(offset, offset + limit).map(n => reg.skills[n]).filter(Boolean),
+    total: names.length,
+  };
+}
+
+// ── Install / Uninstall ────────────────────────────────────────────
+
+/**
+ * Resolve a registry entry to a repo-relative path usable by rawFetch().
+ * New entries carry `rawPath`; legacy cached entries may only have `rawUrl`,
+ * in which case we strip whichever mirror prefix it was built with.
+ */
+function resolveSkillPath(entry) {
+  if (typeof entry.rawPath === "string" && entry.rawPath) {
+    return `${entry.rawPath}/SKILL.md`;
+  }
+  if (typeof entry.rawUrl === "string") {
+    let p = entry.rawUrl;
+    for (const m of RAW_MIRRORS) {
+      if (p.startsWith(m + "/")) return p.slice(m.length + 1);
+    }
+    return p;
+  }
+  return null;
+}
+
+async function installSkill(skillName) {
+  const entry = await getSkillEntry(skillName);
+  if (!entry) throw new Error(`Skill "${skillName}" not found in registry`);
+  const skillDir = join(SKILLS_DIR, skillName);
+  const skillFile = join(skillDir, "SKILL.md");
+  const relPath = resolveSkillPath(entry);
+  if (!relPath) throw new Error(`Skill "${skillName}" has no retrievable path`);
+  const content = await rawFetch(relPath);
+  if (!content) throw new Error("Failed to download skill content");
+  await ensureDir(skillDir);
+  await writeFile(skillFile, content, "utf-8");
+  return { installed: true, path: skillFile };
+}
+
+async function uninstallSkill(skillName) {
+  const skillDir = join(SKILLS_DIR, skillName);
+  const skillFile = join(skillDir, "SKILL.md");
+  if (!(await fileExists(skillFile))) throw new Error(`Skill "${skillName}" is not installed`);
+  const trashDir = join(DSH_HOME, ".trash");
+  await ensureDir(trashDir);
+  const trashPath = join(trashDir, `skills-${skillName}-${Date.now()}`);
+  try {
+    const { rename } = await import("node:fs/promises");
+    await rename(skillDir, trashPath);
+  } catch {
+    await rm(skillDir, { recursive: true, force: true });
+  }
+  return { uninstalled: true };
+}
+
+async function listInstalled() {
+  const results = [];
+  try {
+    const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      if (await fileExists(join(SKILLS_DIR, e.name, "SKILL.md"))) {
+        results.push({ name: e.name, path: join(SKILLS_DIR, e.name, "SKILL.md"), source: "user" });
+      }
+    }
+  } catch {}
+  return results;
+}
+
+// ── HTTP helpers ───────────────────────────────────────────────────
+
+function sendJson(response, status, body) {
+  response.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  response.end(JSON.stringify(body));
+}
+
+async function readJsonBody(request, maxBytes = 65536) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    request.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > maxBytes) { reject(new Error("body too large")); request.destroy(); return; }
+      chunks.push(chunk);
+    });
+    request.on("end", () => {
+      try { resolve(chunks.length > 0 ? JSON.parse(Buffer.concat(chunks).toString("utf-8")) : {}); }
+      catch (e) { reject(e); }
+    });
+    request.on("error", reject);
+  });
+}
+
+// ── Route handlers ─────────────────────────────────────────────────
+
+async function handleList(query) {
+  const search = typeof query.search === "string" ? query.search : "";
+  const category = typeof query.category === "string" ? query.category : "";
+  const limit = Math.min(Number(query.limit) || 100, 200);
+  const offset = Math.max(Number(query.offset) || 0, 0);
+  const source = typeof query.source === "string" ? query.source : "github";
+  const sort = typeof query.sort === "string" ? query.sort : "";
+
+  if (source === "clawhub") {
+    return clawhub.query({ search, category, limit, offset, sort });
+  }
+  if (source === "skillhub") {
+    return skillhub.query({ search, category, limit, offset, sort });
+  }
+  return queryRegistry({ search, category, limit, offset });
+}
+
+/** Merge category facets from both sources. */
+async function handleCategories(source = "github") {
+  if (source === "clawhub") {
+    return (await clawhub.getRegistry()).categories;
+  }
+  if (source === "skillhub") {
+    return (await skillhub.getRegistry()).categories;
+  }
+  if (source === "all") {
+    const merged = {};
+    const gh = (await getRegistry()).categories || {};
+    const ch = (await clawhub.getRegistry()).categories || {};
+    for (const [c, names] of Object.entries(gh)) {
+      merged[`github:${c}`] = names;
+    }
+    for (const [c, names] of Object.entries(ch)) {
+      merged[`clawhub:${c}`] = names;
+    }
+    return merged;
+  }
+  return (await getRegistry()).categories;
+}
+
+/** Per-source health, useful for the UI header. */
+async function handleSources() {
+  const gh = await getRegistry();
+  const ch = await clawhub.getRegistry();
+  const sh = await skillhub.getRegistry();
+  return {
+    sources: [
+      {
+        id: "github",
+        label: "GitHub 镜像",
+        note: "awesome-skills-cn 中文翻译仓库",
+        count: gh.count,
+        hasPopularity: false,
+        collections: gh.collections || {},
+        error: gh._error || null,
+      },
+      {
+        id: "clawhub",
+        label: "ClawHub",
+        note: "OpenClaw 官方技能注册表（含星标/下载量）",
+        count: ch.count,
+        hasPopularity: true,
+        status: clawhub.status(),
+      },
+      {
+        id: "skillhub",
+        label: "SkillHub",
+        note: "腾讯云 SkillHub 中文社区（13 万+技能，中英双语分类）",
+        count: sh.count,
+        hasPopularity: true,
+        status: skillhub.status(),
+      },
+    ],
+  };
+}
+
+async function handleDetail(skillName, source = "github") {
+  // ── ClawHub: metadata is already complete, only the body needs fetching ──
+  if (source === "clawhub") {
+    const reg = await clawhub.getRegistry();
+    const entry = reg.skills?.[skillName];
+    if (!entry) {
+      const err = new Error(`Skill "${skillName}" not found in ClawHub`);
+      err.statusCode = 404;
+      throw err;
+    }
+    const file = await clawhub.fetchFile(skillName, "SKILL.md");
+    return {
+      ...entry,
+      content: file.content,
+      owner: file.owner,
+      fetchError: file.content ? null : file.error,
+    };
+  }
+
+  // ── SkillHub: same shape as ClawHub ──
+  if (source === "skillhub") {
+    const reg = await skillhub.getRegistry();
+    const entry = reg.skills?.[skillName];
+    if (!entry) {
+      const err = new Error(`Skill "${skillName}" not found in SkillHub`);
+      err.statusCode = 404;
+      throw err;
+    }
+    const file = await skillhub.fetchFile(skillName, entry.namespace);
+    return {
+      ...entry,
+      content: file.content,
+      owner: file.namespace,
+      fetchError: file.content ? null : file.error,
+    };
+  }
+
+  const entry = await getSkillEntry(skillName);
+  if (!entry) {
+    const err = new Error(`Skill "${skillName}" not found`);
+    err.statusCode = 404;
+    throw err;
+  }
+
+  const relPath = resolveSkillPath(entry);
+  if (!relPath) {
+    const err = new Error(`Skill "${skillName}" has no retrievable path`);
+    err.statusCode = 404;
+    throw err;
+  }
+
+  const content = await rawFetch(relPath);
+
+  // Opportunistically promote this entry's metadata while we have the file.
+  if (content && !entry.enriched && registryCache) {
+    const parsed = parseFrontmatter(content);
+    if (parsed) {
+      const tags = Array.isArray(parsed.data.tags) ? parsed.data.tags
+        : typeof parsed.data.tags === "string" ? [parsed.data.tags] : ["uncategorized"];
+      registryCache.skills[skillName] = {
+        ...entry,
+        description: typeof parsed.data.description === "string" ? parsed.data.description : entry.description,
+        whenToUse: typeof parsed.data.whenToUse === "string" ? parsed.data.whenToUse : undefined,
+        tags,
+        author: typeof parsed.data.author === "string" ? parsed.data.author : undefined,
+        enriched: true,
+      };
+    }
+  }
+
+  return { ...entry, content };
+}
+
+/**
+ * Install a skill coming from ClawHub. Downloads the skill body and writes it
+ * as SKILL.md, then records provenance so uninstall/list stay accurate.
+ */
+async function installClawhubSkill(skillName) {
+  const reg = await clawhub.getRegistry();
+  const entry = reg.skills?.[skillName];
+  if (!entry) throw new Error(`Skill "${skillName}" not found in ClawHub`);
+
+  const file = await clawhub.fetchFile(skillName, "SKILL.md");
+  if (!file.content) throw new Error(`Failed to download skill content (${file.error || "unknown"})`);
+
+  // Namespace by source to avoid collisions with GitHub-sourced skills.
+  const safeName = skillName.replace(/[^\w.-]/g, "_");
+  const skillDir = join(SKILLS_DIR, safeName);
+  const skillFile = join(skillDir, "SKILL.md");
+  await ensureDir(skillDir);
+  await writeFile(skillFile, file.content, "utf-8");
+
+  const metaFile = join(skillDir, ".dsh-skill-store.json");
+  await writeFile(metaFile, JSON.stringify({
+    source: "clawhub",
+    slug: skillName,
+    owner: file.owner || null,
+    version: file.version || null,
+    stars: entry.stars ?? 0,
+    downloads: entry.downloads ?? 0,
+    topics: entry.topics || [],
+    browseUrl: entry.browseUrl,
+    installedAt: new Date().toISOString(),
+  }, null, 2), "utf-8");
+
+  return { installed: true, path: skillFile, source: "clawhub", name: safeName };
+}
+
+/**
+ * Install a skill coming from SkillHub. Writes SKILL.md plus a provenance
+ * sidecar so uninstall/list stay accurate.
+ */
+async function installSkillhubSkill(skillName) {
+  const reg = await skillhub.getRegistry();
+  const entry = reg.skills?.[skillName];
+  if (!entry) throw new Error(`Skill "${skillName}" not found in SkillHub`);
+
+  const file = await skillhub.fetchFile(skillName, entry.namespace);
+  if (!file.content) throw new Error(`Failed to download skill content (${file.error || "unknown"})`);
+
+  const safeName = skillName.replace(/[^\w.-]/g, "_");
+  const skillDir = join(SKILLS_DIR, safeName);
+  const skillFile = join(skillDir, "SKILL.md");
+  await ensureDir(skillDir);
+  await writeFile(skillFile, file.content, "utf-8");
+
+  await writeFile(join(skillDir, ".dsh-skill-store.json"), JSON.stringify({
+    source: "skillhub",
+    slug: skillName,
+    namespace: entry.namespace || null,
+    canonicalName: entry.canonicalName || null,
+    version: file.version || entry.version || null,
+    stars: entry.stars ?? 0,
+    downloads: entry.downloads ?? 0,
+    category: entry.category || null,
+    categoryLabel: entry.categoryLabel || null,
+    topics: entry.topics || [],
+    browseUrl: entry.browseUrl,
+    installedAt: new Date().toISOString(),
+  }, null, 2), "utf-8");
+
+  return { installed: true, path: skillFile, source: "skillhub", name: safeName };
+}
+
+async function handleInstall(skillName, source = "github") {
+  if (source === "clawhub") return installClawhubSkill(skillName);
+  if (source === "skillhub") return installSkillhubSkill(skillName);
+  return installSkill(skillName);
+}
+
+async function handleUninstall(skillName) {
+  return uninstallSkill(skillName);
+}
+
+async function handleInstalled() {
+  const skills = await listInstalled();
+  return { skills };
+}
+
+let _building = false;
+let _buildPromise = null;
+
+async function handleRefresh() {
+  if (_building) return { refreshed: false, reason: "already building index" };
+  _building = true;
+  registryCache = null;
+  try { await rm(CACHE_FILE, { force: true }); } catch {}
+  _lastError = null;
+  // Start async build — returns immediately so the HTTP request doesn't time out.
+  // Once the skeleton is ready, kick off background enrichment of details.
+  _buildPromise = getRegistry(true).then(() => { enrichRegistry(); });
+  _buildPromise.finally(() => { _building = false; _buildPromise = null; });
+  return {
+    refreshed: false,
+    status: "building",
+    note: "Skeleton index builds in seconds; descriptions fill in progressively in the background.",
+    hint: !GITHUB_TOKEN ? "No GITHUB_TOKEN set — unauthenticated limit is 60 req/hr. Set GITHUB_TOKEN env var for 5000/hr." : undefined,
+  };
+}
+
+// ── DSH Plugin apply ───────────────────────────────────────────────
+
+function apply(ctx) {
+  ctx.inject(["webServer"], (hostCtx) => {
+    const ws = hostCtx.webServer;
+    if (!ws?.register) {
+      console.warn("dsh-skill-store: webServer service unavailable");
+      return;
+    }
+
+    const disposers = [];
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/list",
+      handler: async (req, res) => {
+        try {
+          const url = new URL(req.url ?? "/", "http://localhost");
+          sendJson(res, 200, await handleList(Object.fromEntries(url.searchParams)));
+        } catch (e) { sendJson(res, 500, { error: e.message }); }
+      },
+    }));
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/categories",
+      handler: async (req, res) => {
+        try {
+          const url = new URL(req.url ?? "/", "http://localhost");
+          const source = url.searchParams.get("source") || "github";
+          sendJson(res, 200, await handleCategories(source));
+        } catch (e) { sendJson(res, 500, { error: e.message }); }
+      },
+    }));
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/sources",
+      handler: async (req, res) => {
+        try { sendJson(res, 200, await handleSources()); }
+        catch (e) { sendJson(res, 500, { error: e.message }); }
+      },
+    }));
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/detail/",
+      handler: async (req, res) => {
+        try {
+          const url = new URL(req.url ?? "/", "http://localhost");
+          const source = url.searchParams.get("source") || "github";
+          const raw = (req.url ?? "/").split("/detail/")[1] || "";
+          const skillName = decodeURIComponent(raw.split("?")[0]);
+          sendJson(res, 200, await handleDetail(skillName, source));
+        } catch (e) { sendJson(res, e.statusCode || 500, { error: e.message }); }
+      },
+    }));
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/install",
+      handler: async (req, res) => {
+        if (req.method !== "POST") { sendJson(res, 405, { error: "POST only" }); return; }
+        try {
+          const body = await readJsonBody(req);
+          if (!body.name || typeof body.name !== "string") { sendJson(res, 400, { error: "name is required" }); return; }
+          const source = typeof body.source === "string" ? body.source : "github";
+          sendJson(res, 200, await handleInstall(body.name, source));
+        } catch (e) { sendJson(res, 500, { error: e.message }); }
+      },
+    }));
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/uninstall",
+      handler: async (req, res) => {
+        if (req.method !== "POST") { sendJson(res, 405, { error: "POST only" }); return; }
+        try {
+          const body = await readJsonBody(req);
+          if (!body.name || typeof body.name !== "string") { sendJson(res, 400, { error: "name is required" }); return; }
+          sendJson(res, 200, await handleUninstall(body.name));
+        } catch (e) { sendJson(res, 500, { error: e.message }); }
+      },
+    }));
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/installed",
+      handler: async (req, res) => {
+        try { sendJson(res, 200, await handleInstalled()); }
+        catch (e) { sendJson(res, 500, { error: e.message }); }
+      },
+    }));
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/refresh",
+      handler: async (req, res) => {
+        try { sendJson(res, 200, await handleRefresh()); }
+        catch (e) { sendJson(res, 500, { error: e.message }); }
+      },
+    }));
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/status",
+      handler: async (req, res) => {
+        try {
+          const reg = await getRegistry();
+          const total = Object.keys(reg.skills).length;
+          const done = Object.values(reg.skills).filter((s) => s.enriched).length;
+          sendJson(res, 200, {
+            github: {
+              total,
+              enriched: done,
+              pending: total - done,
+              enriching: _enriching,
+              activeMirror: RAW_MIRRORS[_activeMirror],
+              building: _building,
+              error: reg._error || reg._debug || null,
+            },
+            clawhub: clawhub.status(),
+            skillhub: skillhub.status(),
+          });
+        } catch (e) { sendJson(res, 500, { error: e.message }); }
+      },
+    }));
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/refresh-clawhub",
+      handler: async (req, res) => {
+        try {
+          // Kick off in the background; the full walk takes ~1-2 minutes.
+          clawhub.getRegistry(true);
+          sendJson(res, 200, {
+            refreshed: false,
+            status: "building",
+            note: "ClawHub registry reindex started in the background.",
+          });
+        } catch (e) { sendJson(res, 500, { error: e.message }); }
+      },
+    }));
+
+    disposers.push(ws.register({
+      kind: "prefix", path: "/api/dsh-skill-store/refresh-skillhub",
+      handler: async (req, res) => {
+        try {
+          // SkillHub has 131k+ skills, so we cap the walk and take the most
+          // downloaded ones; expect ~30-60s.
+          skillhub.getRegistry(true);
+          sendJson(res, 200, {
+            refreshed: false,
+            status: "building",
+            note: "SkillHub registry reindex started in the background.",
+          });
+        } catch (e) { sendJson(res, 500, { error: e.message }); }
+      },
+    }));
+
+    // Kick off background work shortly after startup: GitHub enrichment for
+    // descriptions, and a ClawHub reindex for popularity data.
+    const enrichTimer = setTimeout(() => { enrichRegistry(); }, 3000);
+    const clawhubTimer = setTimeout(() => { clawhub.getRegistry(false); }, 8000);
+    // SkillHub is the richest source, so start it slightly earlier than ClawHub.
+    const skillhubTimer = setTimeout(() => { skillhub.getRegistry(false); }, 6000);
+
+    return () => {
+      clearTimeout(enrichTimer);
+      clearTimeout(clawhubTimer);
+      clearTimeout(skillhubTimer);
+      for (const d of disposers) d();
+    };
+  }, "dsh-skill-store: http routes");
+}
+
+export { name, Config, apply };