@nanmicoder/dsh-skills-hub 0.0.1 → 0.0.3

package/lib/types/market/types.d.ts

@@ -16,6 +16,8 @@ export type SecurityReport = {
     status: string;
     statusText: string;
     reportUrl?: string;
+    /** The scanner's own explanation of its verdict, when it gives one */
+    summary?: string;
 };
 export type NormalizedSkill = {
     /** `${source}:${slug}` — globally unique */
@@ -35,7 +37,10 @@ export type NormalizedSkill = {
         stars?: number;
     };
     tags: string[];
+    /** Curated-catalogue category key, e.g. `dev` (absent for live upstream results) */
     category?: string;
+    /** Editor's pick in the curated catalogue */
+    featured?: boolean;
     version?: string;
     updatedAt?: number;
     iconUrl?: string;
@@ -47,6 +52,7 @@ export type NormalizedSkill = {
     upstream?: {
         source: MarketSource;
         slug: string;
+        owner?: string;
     };
     /** After dedupe: ids of merged duplicate entries from other sources */
     mirrors?: string[];
@@ -75,6 +81,14 @@ export type NormalizedSkillDetail = NormalizedSkill & {
     license?: string;
     files: MarketFileMeta[];
     totalSize: number;
+    /** Release note of the latest version, when upstream has a meaningful one */
+    changelog?: {
+        version?: string;
+        text: string;
+        publishedAt?: number;
+    };
+    /** The skill's page on its registry (http(s) only) */
+    pageUrl?: string;
 };
 export type MarketFileContent = {
     path: string;
@@ -89,9 +103,24 @@ export type SourceStatusInfo = {
     fromCache?: boolean;
     error?: string;
 };
+/** One curated-catalogue category. */
+export type MarketCategory = {
+    key: string;
+    name: string;
+    nameEn?: string;
+    sortOrder: number;
+    /** Skills the catalogue holds in this category */
+    count?: number;
+};
+export type MarketCategoriesResult = {
+    items: MarketCategory[];
+    status: SourceStatusInfo;
+};
 export type MarketListResult = {
     items: NormalizedSkill[];
     nextCursor: string | null;
+    /** Matching skills in total, when known (the curated catalogue always knows) */
+    total?: number;
     sources: Record<MarketSource, SourceStatusInfo>;
 };
 export type ProviderListPage = {

package/lib/types/skills/installed.d.ts

@@ -30,6 +30,8 @@ export interface InstalledMetaFile {
     id: string;
     source: MarketSource;
     slug: string;
+    /** Registry author (ClawHub slugs are shared across authors); absent in older sidecars. */
+    owner?: string;
     version?: string;
     installedAt: string;
     files: Array<{
@@ -47,6 +49,8 @@ export interface InstalledSkillRecord {
     id: string;
     source: MarketSource | 'local';
     slug: string;
+    /** Registry author recorded at install time, when known */
+    owner?: string;
     name: string;
     dirName: string;
     /**

package/lib/types/skills/management.d.ts

@@ -1,7 +1,68 @@
+/**
+ * Local skill management: one discovered entry at a time.
+ *
+ * Every function here starts from a key, never from a client-supplied path: the
+ * roots are re-scanned on each call, and only an entry that scan just produced
+ * can be read or removed. A path that arrives from the browser is therefore
+ * always interpreted *inside* an entry this process has already vouched for.
+ *
+ * The detail read is what the panel's local skill page renders: the SKILL.md
+ * document, its raw frontmatter block and a bounded inventory of the skill's own
+ * files. Nothing here consults a market provider — an installed skill stays
+ * readable with the network down.
+ */
 import { type InstalledSkillRecord } from './installed.ts';
-export declare function readInstalledSkill(roots: string[], key: string): Promise<{
+/** One file of an installed skill, relative to the entry. */
+export interface InstalledFileEntry {
+    path: string;
+    size: number;
+    language: string;
+}
+/** `GET /installed/detail` body. */
+export interface InstalledSkillDetail {
     item: InstalledSkillRecord;
+    /** Full SKILL.md text, frontmatter included: the browser strips it. */
     markdown: string;
-}>;
+    /** Verbatim YAML header without its fences, or `null` when the file has none. */
+    frontmatter: string | null;
+    files: InstalledFileEntry[];
+}
+/** `GET /installed/file` body; the shape mirrors the market file preview. */
+export interface InstalledFileContent {
+    path: string;
+    content: string;
+    language: string;
+    size: number;
+    truncated: boolean;
+}
+/**
+ * Raw frontmatter block, kept as YAML text.
+ *
+ * Parsing it into structure would mean shipping a YAML reader for a panel that
+ * only needs to *show* the header, and the market detail's structured panel is
+ * fed by upstream JSON this plugin does not have for a hand-written skill. The
+ * verbatim block is also what the file actually contains, so nothing is lost.
+ */
+export declare function extractFrontmatter(markdown: string): string | null;
+/**
+ * Inventory one entry's own files.
+ *
+ * The walk never leaves the entry: directories are descended, symlinked entries
+ * are listed as nothing at all, and the provenance sidecar (a dot-file, like
+ * every other dot-entry) is skipped because it is plugin bookkeeping rather than
+ * installed payload. A flat skill is a single file and reports itself.
+ */
+export declare function listEntryFiles(item: InstalledSkillRecord): Promise<InstalledFileEntry[]>;
+/** Read the SKILL.md document plus the entry inventory the local detail page renders. */
+export declare function readInstalledSkill(roots: string[], key: string): Promise<InstalledSkillDetail>;
+/**
+ * Read one file of one entry.
+ *
+ * A flat skill exposes exactly itself — never its siblings in the same root —
+ * and a directory bundle exposes only what resolves back inside its own real
+ * path, so a symlink planted in the tree cannot turn this endpoint into an
+ * arbitrary-file reader.
+ */
+export declare function readInstalledFile(roots: string[], key: string, requested: string): Promise<InstalledFileContent>;
 /** Rename the selected entry out of discovery before deletion. Symlink targets are never removed. */
 export declare function removeInstalledSkill(roots: string[], key: string, allowUninstall: boolean): Promise<InstalledSkillRecord>;

package/lib/types/skills/root.d.ts

@@ -20,6 +20,14 @@
  * explicit path → `DSH_HOME` (blank treated as unset) → `~/.dsh`, plus the
  * `~`, `~/`, `~\` tilde expansion of `expandHomePath`.
  */
+/**
+ * Resolve the single-root harness home.
+ *
+ * Precedence, highest first: an explicit path, `$DSH_HOME`, then `~/.dsh`. A
+ * blank `$DSH_HOME` is treated as unset so a stray empty variable can never
+ * resolve the harness home to the current working directory.
+ */
+export declare function resolveDshHome(configured?: string | null): string;
 /**
  * Absolute skills directory skills are installed into, created on demand.
  *

package/lib/types/web-routes.d.ts

@@ -1,7 +1,7 @@
 /**
  * Skills Hub HTTP surface.
  *
- * One `prefix` route (`/api/skills-hub`) owns the seven endpoints the panel
+ * One `prefix` route (`/api/skills-hub`) owns the endpoints the panel
  * needs; every response is JSON with `Cache-Control: no-store`, because the
  * panel polls and every payload is either live upstream data or live disk state.
  *
@@ -30,6 +30,8 @@ export interface SkillsHubRoutesDeps {
     skillsRoot: () => Promise<string>;
     allowUninstall: () => boolean;
     rescan: () => Promise<void>;
+    /** Initial local inventory scan, required before annotating persisted data. */
+    ready?: () => Promise<void>;
 }
 /**
  * Browser-trust gate, structurally equal to the frozen contract's predicate.

package/lib/web-routes.js

@@ -1,7 +1,7 @@
 /**
  * Skills Hub HTTP surface.
  *
- * One `prefix` route (`/api/skills-hub`) owns the seven endpoints the panel
+ * One `prefix` route (`/api/skills-hub`) owns the endpoints the panel
  * needs; every response is JSON with `Cache-Control: no-store`, because the
  * panel polls and every payload is either live upstream data or live disk state.
  *
@@ -16,8 +16,10 @@
  *    otherwise be reachable by a cross-site request or a DNS-rebound page.
  */
 import { installMarketSkill, MarketInstallError, uninstallMarketSkill, } from "./market/install-service.js";
-import { getMarketFileContent, getMarketSkillDetail, getMarketStatus, isValidMarketFilePath, listMarketSkills, } from "./market/market-service.js";
-import { readInstalledSkill, removeInstalledSkill } from "./skills/management.js";
+import { getMarketFileContent, getMarketSkillDetail, getMarketStatus, isValidMarketFilePath, listMarketCategories, listMarketSkills, } from "./market/market-service.js";
+import { getMarketStats } from "./market/cache.js";
+import { CLAWHUB_OWNER_PATTERN } from "./market/clawhub-provider.js";
+import { readInstalledFile, readInstalledSkill, removeInstalledSkill } from "./skills/management.js";
 import { scanInstalledSkills } from "./skills/installed.js";
 import { resolveSkillsScanRoots } from "./skills/root.js";
 import { MARKET_ERROR_CODES, MARKET_SOURCES, MarketUpstreamError, parseSkillId, } from "./market/types.js";
@@ -247,6 +249,30 @@ function enumQuery(url, name, allowed, fallback) {
         return raw;
     throw new RouteError(400, 'BAD_REQUEST', `Invalid ${name} filter: ${raw}`);
 }
+/** Shape of a catalogue category key. */
+const CATEGORY_KEY_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** `category` query parameter: a catalogue category key, shape-checked only. */
+function parseCategory(url) {
+    const raw = url.searchParams.get('category');
+    if (raw === null || raw === '' || raw === 'all')
+        return undefined;
+    if (!CATEGORY_KEY_PATTERN.test(raw))
+        throw new RouteError(400, 'BAD_REQUEST', `Invalid category: ${raw}`);
+    return raw;
+}
+/**
+ * Optional registry owner. ClawHub slugs are shared across authors, so the
+ * panel names the author of the card it opened; a malformed owner is refused
+ * rather than silently dropped (that would fall back to guessing).
+ */
+function parseOwner(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    if (typeof raw !== 'string' || !CLAWHUB_OWNER_PATTERN.test(raw)) {
+        throw new RouteError(400, 'BAD_REQUEST', `Invalid owner: ${String(raw)}`);
+    }
+    return raw;
+}
 /** `limit` query parameter, clamped into the documented range. */
 function parseLimit(url) {
     const raw = url.searchParams.get('limit');
@@ -265,30 +291,59 @@ function parseBodyId(body) {
         throw new RouteError(400, 'BAD_REQUEST', `Invalid skill id: ${id === '' ? '(missing)' : id}`);
     return parsed;
 }
+/**
+ * `refresh` query parameter.
+ *
+ * A reader who presses refresh means "do not answer me from your cache". Before
+ * this existed the request looked exactly like the automatic one, so the panel
+ * re-rendered the same cached page and presented it as fresh. Only the explicit
+ * spellings are accepted; anything else is a bad request rather than a silently
+ * ignored intent.
+ */
+function parseRefresh(url) {
+    const raw = url.searchParams.get('refresh');
+    if (raw === null || raw === '' || raw === '0' || raw === 'false')
+        return false;
+    if (raw === '1' || raw === 'true')
+        return true;
+    throw new RouteError(400, 'BAD_REQUEST', `Invalid refresh flag: ${raw}`);
+}
 async function handleStatus(res) {
     sendJson(res, 200, { sources: getMarketStatus() });
 }
+/** Cache and upstream counters: the evidence behind every traffic claim. */
+async function handleStats(res) {
+    sendJson(res, 200, { stats: getMarketStats() });
+}
 async function handleList(url, res) {
     const params = {
         q: optionalQuery(url, 'q', MAX_QUERY_LENGTH),
+        scope: enumQuery(url, 'scope', ['catalog', 'market'], 'catalog'),
+        category: parseCategory(url),
         source: enumQuery(url, 'source', ['all', ...MARKET_SOURCES], 'all'),
         security: enumQuery(url, 'security', ['all', ...SECURITY_FILTERS], 'all'),
         installed: enumQuery(url, 'installed', INSTALLED_FILTERS, 'all'),
         cursor: optionalQuery(url, 'cursor', MAX_CURSOR_LENGTH),
         limit: parseLimit(url),
+        refresh: parseRefresh(url),
     };
     const result = await listMarketSkills(params);
     sendJson(res, 200, result);
 }
-async function handleDetail(source, slug, res) {
-    sendJson(res, 200, await getMarketSkillDetail(source, slug));
+async function handleCategories(res) {
+    sendJson(res, 200, listMarketCategories());
+}
+async function handleDetail(source, slug, url, res) {
+    const owner = parseOwner(url.searchParams.get('owner'));
+    sendJson(res, 200, await getMarketSkillDetail(source, slug, { force: parseRefresh(url), owner }));
 }
 async function handleFile(source, slug, url, res) {
     const filePath = url.searchParams.get('path') ?? '';
     if (!isValidMarketFilePath(filePath)) {
         throw new RouteError(400, 'BAD_REQUEST', `Invalid file path: ${filePath}`);
     }
-    sendJson(res, 200, { file: await getMarketFileContent(source, slug, filePath) });
+    const owner = parseOwner(url.searchParams.get('owner'));
+    sendJson(res, 200, { file: await getMarketFileContent(source, slug, filePath, owner) });
 }
 /**
  * List installed skills from disk.
@@ -303,10 +358,12 @@ async function handleInstalled(deps, res) {
     sendJson(res, 200, { items: (await scanInstalledSkills(roots)).map(item => ({ ...item, removable: deps.allowUninstall() })) });
 }
 async function handleInstall(req, deps, res) {
-    const { source, slug } = parseBodyId(await readJsonBody(req));
+    const body = await readJsonBody(req);
+    const { source, slug } = parseBodyId(body);
     const result = await installMarketSkill(source, slug, {
         skillsRoot: await deps.skillsRoot(),
         allowUninstall: deps.allowUninstall(),
+        owner: parseOwner(body['owner']),
     });
     // Refresh before answering, so the next /skills or /installed call is correct.
     await deps.rescan().catch(() => undefined);
@@ -335,6 +392,7 @@ async function handle(req, res, gate, deps) {
             return;
         }
     }
+    await deps.ready?.();
     const url = new URL(req.url ?? '/', 'http://localhost');
     const segments = parseSegments(url.pathname);
     const method = req.method ?? 'GET';
@@ -344,12 +402,31 @@ async function handle(req, res, gate, deps) {
         await handleStatus(res);
         return;
     }
+    if (head === 'categories' && segments.length === 1) {
+        requireMethod(method, 'GET');
+        await handleCategories(res);
+        return;
+    }
+    if (head === 'stats' && segments.length === 1) {
+        requireMethod(method, 'GET');
+        await handleStats(res);
+        return;
+    }
     if (head === 'installed' && segments.length === 2 && second === 'detail') {
         requireMethod(method, 'GET');
         const roots = await resolveSkillsScanRoots(await deps.skillsRoot());
         sendJson(res, 200, await readInstalledSkill(roots, url.searchParams.get('key') ?? ''));
         return;
     }
+    if (head === 'installed' && segments.length === 2 && second === 'file') {
+        requireMethod(method, 'GET');
+        const roots = await resolveSkillsScanRoots(await deps.skillsRoot());
+        // Both parameters are validated inside: a key must resolve to a freshly
+        // discovered entry, and the path must stay inside that entry.
+        const file = await readInstalledFile(roots, url.searchParams.get('key') ?? '', url.searchParams.get('path') ?? '');
+        sendJson(res, 200, { file });
+        return;
+    }
     if (head === 'installed' && segments.length === 2 && second === 'uninstall') {
         requireMethod(method, 'POST');
         const body = await readJsonBody(req);
@@ -387,7 +464,7 @@ async function handle(req, res, gate, deps) {
             const slug = parseSlug(third);
             requireMethod(method, 'GET');
             if (segments.length === 3) {
-                await handleDetail(source, slug, res);
+                await handleDetail(source, slug, url, res);
             }
             else {
                 await handleFile(source, slug, url, res);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanmicoder/dsh-skills-hub",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Skills Hub for DeepSeek Harness: browse, preview, install and remove third-party skills from ClawHub and SkillHub inside the DSH Web GUI.",
   "type": "module",
   "main": "lib/index.js",

package/release-notes/v0.0.1.md

@@ -8,4 +8,4 @@ Initial release of `@nanmicoder/dsh-skills-hub` for DeepSeek Harness's 0.2.0 des
 - Atomic installation, existing-directory conflict protection and restricted filesystem removal.
 - Scoped npm package, bilingual documentation, pinned compatibility metadata and reproducible build/package/release checks.
 
-Install: `dsh plugin --profile desktop add @nanmicoder/dsh-skills-hub@0.0.1`, then fully restart the desktop app. Installing the plugin does not migrate or delete existing skills.
+Install in **DeepSeek Harness desktop → Plugins → Add plugin**. Paste `https://github.com/NanmiCoder/dsh-skills-hub` (recommended) or `@nanmicoder/dsh-skills-hub`, click **Install**, then **Enable now**. Open **Skills Hub** from the sidebar. Installing the plugin does not migrate or delete existing skills.

package/release-notes/v0.0.2.md

@@ -0,0 +1,12 @@
+# Skills Hub 0.0.2
+
+`@nanmicoder/dsh-skills-hub` for DeepSeek Harness **0.2.0-rc.2**.
+
+- Persist browsed catalogue pages, searches, skill details and file previews across desktop restarts. The default cache lifetime is 60 minutes, configurable through `cacheTtlMinutes`.
+- Preserve snapshot timestamps and each page's provenance. Reopening a detail checks the Host's cache lifetime and current local installation state.
+- Keep installation manifests fresh: actual installs bypass cached details and refuse stale fallback when upstream fails.
+- Bound and validate disk snapshots, recover abandoned temporary writes, and keep provider configurations isolated during reloads.
+- Show installed skills in a full detail page, with rendered Markdown previews, structured frontmatter and a source view for file contents.
+- Prefetch the next catalogue page near the end of the current view, and show snapshot age with an explicit refresh action.
+
+Install in **DeepSeek Harness desktop → Plugins → Add plugin** using `@nanmicoder/dsh-skills-hub@0.0.2`, then enable the plugin. Existing skills remain in place. Advanced cache settings are documented in [CONFIGURATION.md](../docs/CONFIGURATION.md).

package/release-notes/v0.0.3.md

@@ -0,0 +1,12 @@
+# Skills Hub 0.0.3
+
+`@nanmicoder/dsh-skills-hub` for DeepSeek Harness **0.2.0-rc.2**.
+
+- **Curated catalogue.** The home page now opens on 398 hand-picked skills from ClawHub and SkillHub, grouped into 13 categories (agents, research, development, office, productivity, content, media, data, marketing, finance, professional, life, security) with editor's picks first. The list ships with the plugin, so it renders instantly and offline; details, files and installs are still read live from upstream and cached. Searching switches to live results from both marketplaces.
+- **Redesigned detail page.** Header with downloads, installs, stars and file count; Overview, Files, Security and Changelog tabs; a rule-based "what this skill will do" panel (shell commands, hooks, secrets, network hosts, workspace writes, required binaries) and "when it triggers" list, both derived from the skill's own files; per-scanner security reports from upstream.
+- **Install confirmation.** The dialog lists what the skill will be able to do, where it will be installed, and requires an explicit acknowledgement for skills that are unscanned or flagged by upstream scanners.
+- **Same-name skills resolved by author.** ClawHub slugs can be shared by several authors. Details, file previews and installs are now pinned to the author shown on the card, live search shows one entry per slug, and a mirror is only folded into an original by the same author. Installed skills record their author.
+- **Unified look.** Marketplace home, detail pages and Installed share one visual system, and fit the docked 720px panel in light and dark themes.
+- Copy now states plainly that Skills Hub is a community plugin, not a DeepSeek product, and that the curated list is a recommendation rather than a security guarantee.
+
+Install in **DeepSeek Harness desktop → Plugins → Add plugin** using `@nanmicoder/dsh-skills-hub@0.0.3`, then enable the plugin. Existing skills and cache settings remain in place. Catalogue policy is documented in [CATALOG.md](../docs/CATALOG.md).

package/lib/types/client/components/InstallStateBadge.d.ts

@@ -1,11 +0,0 @@
-import type { InstallState } from '../../market/types.ts';
-/**
- * Local install state chip.
- *
- * The three labels come from dictionary keys the contract already fixes —
- * `installed`, `installed.installable` and `notInstallable` — so this badge
- * adds no vocabulary of its own.
- */
-export declare function InstallStateBadge(props: {
-    state: InstallState;
-}): JSX.Element;

package/lib/types/client/components/SecurityBadge.d.ts

@@ -1,16 +0,0 @@
-import type { SecurityReport, SecurityStatus } from '../../market/types.ts';
-/**
- * Audit verdict chip.
- *
- * Shows a shield for every verdict except `flagged`, which uses the warning
- * triangle: a scan that found something must not look like a scan that merely
- * ran, and shape reads faster than color alone.
- *
- * `reports` supplies the upstream status line for the hover title, so the chip
- * can stay a two-word summary without hiding what the vendor actually said.
- */
-export declare function SecurityBadge(props: {
-    status: SecurityStatus;
-    reports?: SecurityReport[];
-    compact?: boolean;
-}): JSX.Element;

package/lib/types/client/components/SkillDetailView.d.ts

@@ -1,21 +0,0 @@
-import type { NormalizedSkillDetail } from '../../market/types.ts';
-import type { MarketController, MarketState } from '../state.ts';
-/**
- * Skill detail page.
- *
- * Like the home page this component owns no data: the tab, the selected file
- * and the file contents all live in `MarketState`, so switching tabs or
- * re-opening a skill does not lose its place.
- *
- * The bundled GFM renderer handles catalogue Markdown without relying on a
- * host renderer delegate. Raw HTML is disabled and URLs use its safe default.
- */
-export declare function SkillDetailView(props: {
-    detail: NormalizedSkillDetail;
-    state: MarketState;
-    controller: MarketController;
-}): JSX.Element;
-/** Keeps the detail layout stable while its network request is in flight. */
-export declare function SkillDetailSkeleton({ onBack }: {
-    onBack: () => void;
-}): JSX.Element;