@nanmicoder/dsh-skills-hub 0.0.1 → 0.0.2

package/lib/types/config.d.ts

@@ -29,6 +29,8 @@ export interface SkillsHubConfig {
     allowUninstall: boolean;
     /** Default `limit` for `GET /skills` when the request omits one (clamped to 1…100). */
     pageSize: number;
+    /** Lifetime of persisted market snapshots in minutes (1…1440). */
+    cacheTtlMinutes: number;
 }
 /**
  * Shipped defaults. Exported so `apply()` can fill in a partially resolved

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

@@ -1,5 +1,5 @@
 /**
- * Skills Market — in-memory TTL cache with stale-while-error support, plus
+ * Skills Market — memory + persistent TTL cache with stale-while-error support, plus
  * per-source health tracking.
  *
  * Only *upstream* data is cached here (list pages, details, file bodies).
@@ -7,11 +7,11 @@
  * and is deliberately never cached: a skill installed a second ago must show up
  * as installed on the very next list call.
  *
- * Everything lives in module scope, so the module needs no DSH service and no
- * filesystem — a unit test can drive it with plain `node --test`.
+ * The host configures disk storage at activation. Without a directory the
+ * cache stays memory-only, so provider tests never touch a user's Harness home.
  */
 import type { MarketSource, SourceHealthStatus, SourceStatusInfo } from './types.ts';
-/** Per-payload TTLs: cheap-to-refetch list pages expire sooner than file bodies. */
+/** Default snapshot lifetime; activation can override it with cacheTtlMinutes. */
 export declare const MARKET_TTL: {
     readonly list: number;
     readonly search: number;
@@ -19,18 +19,67 @@ export declare const MARKET_TTL: {
     readonly files: number;
     readonly fileContent: number;
 };
-declare class MarketCache {
+export interface MarketCacheOptions {
+    directory?: string;
+    ttlMs?: number;
+    onError?: (error: unknown) => void;
+}
+/** One fresh hit, together with the moment its payload was actually fetched. */
+export interface MarketCacheRecord<T> {
+    value: T;
+    /** Epoch millis of the upstream read this payload came from. */
+    storedAt: number;
+}
+/**
+ * Counters describing what the cache actually did.
+ *
+ * "How much traffic does the cache save" used to be an argument. Every claim
+ * about hits, misses and needless upstream reads can now be checked against
+ * these numbers on a real machine instead of reasoned about.
+ */
+export interface MarketCacheStats {
+    /** Answers served from a fresh memory or disk entry. */
+    hits: number;
+    /** Lookups that had to go upstream (including forced refreshes). */
+    misses: number;
+    /** Answers served from an expired entry because the source failed. */
+    staleServed: number;
+    /** Upstream page/detail requests actually issued. */
+    upstreamRequests: number;
+    /** Refreshes a reader explicitly asked for. */
+    forcedRefreshes: number;
+}
+/** Record one cache event. Kept tiny so it can sit on the request path. */
+export declare function noteMarketStat(entry: keyof MarketCacheStats): void;
+/** Snapshot of the counters; the caller cannot mutate the live object. */
+export declare function getMarketStats(): MarketCacheStats;
+export declare class MarketCache {
+    private options;
     private entries;
-    get<T>(key: string): T | undefined;
+    private disk?;
+    private warned;
+    private ttlMs;
+    constructor(options?: MarketCacheOptions);
+    private warn;
+    private remember;
+    private read;
+    /**
+     * Read a fresh entry.
+     *
+     * The record carries `storedAt` on purpose: a hit is a *snapshot*, and the
+     * caller must be able to say how old it is. Returning only the payload is how
+     * the panel ended up reporting "fetched just now" for data it had not touched
+     * in ten minutes.
+     */
+    getRecord<T>(key: string): Promise<MarketCacheRecord<T> | undefined>;
     /** Returns the entry even when expired — used for the stale-while-error fallback. */
-    getStale<T>(key: string): {
-        value: T;
-        storedAt: number;
-    } | undefined;
-    set(key: string, value: unknown, ttlMs: number): void;
+    getStale<T>(key: string): Promise<MarketCacheRecord<T> | undefined>;
+    set(key: string, value: unknown, ttlMs?: number): Promise<number>;
     clear(): void;
 }
-export declare const marketCache: MarketCache;
+export declare let marketCache: MarketCache;
+/** Replace memory state when activating a profile; disk entries are read lazily. */
+export declare function configureMarketCache(options: MarketCacheOptions): void;
 /**
  * Record the outcome of one upstream interaction.
  *
@@ -44,6 +93,5 @@ export declare function markSourceHealth(source: MarketSource, status: SourceHea
 export declare function getSourceHealth(source: MarketSource): SourceStatusInfo;
 /** Test hook: forget every recorded success/failure. */
 export declare function resetSourceHealth(): void;
-/** Test hook: drop cached payloads and reset source health. */
+/** Test hook: drop memory payloads, reset source health and the counters. */
 export declare function resetMarketCache(): void;
-export {};

package/lib/types/market/disk-cache.d.ts

@@ -0,0 +1,16 @@
+export interface CacheEntry {
+    value: unknown;
+    expiresAt: number;
+    storedAt: number;
+}
+export declare const MAX_CACHE_ENTRIES = 500;
+export declare const MAX_STALE_AGE_MS: number;
+export declare class DiskMarketCache {
+    private directory;
+    private writes;
+    constructor(directory: string);
+    private filename;
+    read(key: string): Promise<CacheEntry | undefined>;
+    write(key: string, entry: CacheEntry): Promise<void>;
+    private prune;
+}

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

@@ -5,7 +5,7 @@
  * cross-source dedupe, per-source health/degradation reporting, TTL caching
  * (stale-while-error) and locally-computed install state.
  *
- * The module is deliberately free of DSH services and of the filesystem: the
+ * The module is deliberately free of DSH services: the
  * "what is installed locally" question is answered by an injected
  * `InstalledLookup` (see `setInstalledLookup`), so this file can be unit-tested
  * by pointing the providers at a stub server.
@@ -60,15 +60,27 @@ export interface ListMarketSkillsParams {
     installed: 'all' | 'installed' | 'installable';
     cursor?: string;
     limit: number;
+    /** Reader-requested refresh: ignore fresh entries (they are still rewritten). */
+    refresh?: boolean;
 }
 export declare function listMarketSkills(params: ListMarketSkillsParams): Promise<MarketListResult>;
-export declare function getMarketSkillDetail(source: MarketSource, slug: string): Promise<{
+export declare function getMarketSkillDetail(source: MarketSource, slug: string, options?: {
+    force?: boolean;
+    allowStale?: boolean;
+}): Promise<{
     skill: NormalizedSkillDetail;
     sourceStatus: SourceStatusInfo;
 }>;
 export declare function isValidMarketFilePath(filePath: string): boolean;
 export declare function getMarketFileContent(source: MarketSource, slug: string, filePath: string): Promise<MarketFileContent>;
 export declare function getMarketStatus(): Record<MarketSource, SourceStatusInfo>;
-/** Look up a single skill (used by install) — the detail path, bypassing list. */
+/**
+ * Look up a single skill for an install (the detail path, bypassing the list).
+ *
+ * Always forced: a cached manifest is a snapshot of the *catalogue*, and
+ * installing is the one action that has to be authorized by what upstream says
+ * right now — the file bytes are fetched fresh and hash-verified against the
+ * list, so the list must come from the same generation as those bytes.
+ */
 export declare function resolveMarketSkill(source: MarketSource, slug: string): Promise<NormalizedSkillDetail>;
 export {};

package/lib/types/market/provider-fetch.d.ts

@@ -18,6 +18,8 @@ export interface ProviderEndpointConfig {
     retries: number;
     userAgent: string;
 }
+/** Keep cache keys and all chained upstream reads on one configuration snapshot. */
+export declare function withProviderConfiguration<T>(operation: () => Promise<T>): Promise<T>;
 /**
  * Point the providers at different hosts / limits. Called by the plugin with the
  * resolved Config; tests call it to aim the providers at a local stub server.

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

@@ -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

@@ -17,7 +17,8 @@
  */
 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 { getMarketStats } from "./market/cache.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";
@@ -265,9 +266,30 @@ 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),
@@ -276,12 +298,13 @@ async function handleList(url, res) {
         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 handleDetail(source, slug, url, res) {
+    sendJson(res, 200, await getMarketSkillDetail(source, slug, { force: parseRefresh(url) }));
 }
 async function handleFile(source, slug, url, res) {
     const filePath = url.searchParams.get('path') ?? '';
@@ -335,6 +358,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 +368,26 @@ async function handle(req, res, gate, deps) {
         await handleStatus(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 +425,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.2",
   "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).