@nanmicoder/dsh-skills-hub 0.0.1 → 0.0.2

package/lib/config.js

@@ -27,6 +27,7 @@ export const SKILLS_HUB_DEFAULTS = {
     requestRetries: 1,
     allowUninstall: true,
     pageSize: 24,
+    cacheTtlMinutes: 60,
 };
 /**
  * `null` must stay a legal value for `skillsRoot` (it is the "use the DSH
@@ -48,4 +49,5 @@ export const Config = z.object({
     requestRetries: z.natural().default(SKILLS_HUB_DEFAULTS.requestRetries),
     allowUninstall: z.boolean().default(SKILLS_HUB_DEFAULTS.allowUninstall),
     pageSize: z.natural().min(1).max(100).default(SKILLS_HUB_DEFAULTS.pageSize),
+    cacheTtlMinutes: z.natural().min(1).max(1440).default(SKILLS_HUB_DEFAULTS.cacheTtlMinutes),
 });

package/lib/index.js

@@ -15,11 +15,13 @@
  *
  * @module dsh-skills-hub
  */
+import * as path from 'node:path';
 import { Config, SKILLS_HUB_DEFAULTS } from "./config.js";
+import { configureMarketCache } from "./market/cache.js";
 import { configureProviderFetch } from "./market/provider-fetch.js";
 import { setInstalledLookup, resetInstalledLookup } from "./market/market-service.js";
 import { installedLookupFrom, scanInstalledSkills } from "./skills/installed.js";
-import { resolveSkillsRoot, resolveSkillsScanRoots } from "./skills/root.js";
+import { resolveDshHome, resolveSkillsRoot, resolveSkillsScanRoots } from "./skills/root.js";
 import { registerSkillsHubRoutes, setSkillsHubPageSize, } from "./web-routes.js";
 export const name = 'skills-hub';
 /**
@@ -52,6 +54,7 @@ function resolveConfig(config) {
         requestRetries: config?.requestRetries ?? SKILLS_HUB_DEFAULTS.requestRetries,
         allowUninstall: config?.allowUninstall ?? SKILLS_HUB_DEFAULTS.allowUninstall,
         pageSize: config?.pageSize ?? SKILLS_HUB_DEFAULTS.pageSize,
+        cacheTtlMinutes: config?.cacheTtlMinutes ?? SKILLS_HUB_DEFAULTS.cacheTtlMinutes,
     };
 }
 /**
@@ -101,6 +104,11 @@ export function apply(ctx, config) {
         retries: resolved.requestRetries,
     });
     setSkillsHubPageSize(resolved.pageSize);
+    configureMarketCache({
+        directory: path.join(resolveDshHome(), 'cache', 'skills-hub', 'v1'),
+        ttlMs: resolved.cacheTtlMinutes * 60_000,
+        onError: (error) => ctx.logger.warn(`skills-hub: persistent cache unavailable: ${String(error)}`),
+    });
     let disposed = false;
     /** Rebuild the installed index and hand it to the market layer. */
     const refreshInstalledIndex = async () => {
@@ -135,11 +143,12 @@ export function apply(ctx, config) {
         // republishing it).
         resetInstalledLookup();
     }, 'skills-hub: activation state');
-    // First scan: `apply()` is synchronous, so this cannot be awaited here. Until
-    // it settles the market layer keeps its empty default lookup (skills show as
-    // installable, and the installer's own conflict check still refuses to clobber
-    // an existing directory), and /installed reads the disk directly.
-    void rescan();
+    // Apply is synchronous, but the first HTTP read must wait for install
+    // annotations even when a persisted snapshot arrives before the scan does.
+    const initialScan = refreshInstalledIndex().catch((error) => {
+        ctx.logger.warn(`skills-hub: installed-skill index refresh failed: ${String(error)}`);
+    });
+    void initialScan.then(() => refreshSkillCatalog(ctx));
     // The Web server may bind before or after this plugin (the Loader activates
     // rows concurrently), and older compositions name the service `httpServer`.
     // Bind lazily on the first service event that makes a server reachable.
@@ -159,6 +168,7 @@ export function apply(ctx, config) {
             skillsRoot: () => resolveSkillsRoot(resolved.skillsRoot),
             allowUninstall: () => resolved.allowUninstall,
             rescan,
+            ready: () => initialScan,
         };
         // `ctx.effect` runs the factory immediately; `dsh-host-webserver` throws on a
         // duplicate route path, so the flag may only be set once registration has

package/lib/market/cache.js

@@ -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,56 +7,128 @@
  * 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.
  */
-/** Hard cap so a long-lived host process cannot grow the map without bound. */
-const MAX_ENTRIES = 500;
-/** Per-payload TTLs: cheap-to-refetch list pages expire sooner than file bodies. */
+import { DiskMarketCache, MAX_CACHE_ENTRIES, MAX_STALE_AGE_MS } from "./disk-cache.js";
+/** Default snapshot lifetime; activation can override it with cacheTtlMinutes. */
 export const MARKET_TTL = {
-    list: 5 * 60_000,
-    search: 2 * 60_000,
-    detail: 10 * 60_000,
-    files: 10 * 60_000,
-    fileContent: 30 * 60_000,
+    list: 60 * 60_000,
+    search: 60 * 60_000,
+    detail: 60 * 60_000,
+    files: 60 * 60_000,
+    fileContent: 60 * 60_000,
 };
-class MarketCache {
+const stats = {
+    hits: 0,
+    misses: 0,
+    staleServed: 0,
+    upstreamRequests: 0,
+    forcedRefreshes: 0,
+};
+/** Record one cache event. Kept tiny so it can sit on the request path. */
+export function noteMarketStat(entry) {
+    stats[entry] += 1;
+}
+/** Snapshot of the counters; the caller cannot mutate the live object. */
+export function getMarketStats() {
+    return { ...stats };
+}
+export class MarketCache {
+    options;
     entries = new Map();
-    get(key) {
-        const entry = this.entries.get(key);
+    disk;
+    warned = false;
+    ttlMs;
+    constructor(options = {}) {
+        this.options = options;
+        this.ttlMs = options.ttlMs ?? MARKET_TTL.list;
+        if (options.directory)
+            this.disk = new DiskMarketCache(options.directory);
+    }
+    warn(error) {
+        if (this.warned)
+            return;
+        this.warned = true;
+        this.options.onError?.(error);
+    }
+    remember(key, entry) {
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        if (this.entries.size > MAX_CACHE_ENTRIES) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest !== undefined)
+                this.entries.delete(oldest);
+        }
+    }
+    async read(key) {
+        const existing = this.entries.get(key);
+        if (existing)
+            return existing;
+        try {
+            const restored = await this.disk?.read(key);
+            // A concurrent upstream response may have replaced the snapshot while
+            // the disk read was pending. Never overwrite that newer memory entry.
+            const current = this.entries.get(key);
+            if (current)
+                return current;
+            if (restored)
+                this.remember(key, restored);
+            return restored;
+        }
+        catch (error) {
+            // A corrupt or unwritable cache must never break the market request.
+            this.warn(error);
+            return undefined;
+        }
+    }
+    /**
+     * 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.
+     */
+    async getRecord(key) {
+        const entry = await this.read(key);
         if (!entry)
             return undefined;
-        if (Date.now() > entry.expiresAt)
+        if (Date.now() >= Math.min(entry.expiresAt, entry.storedAt + this.ttlMs))
             return undefined;
         // LRU touch: re-insert so the oldest key is the least recently used one.
         this.entries.delete(key);
         this.entries.set(key, entry);
-        return entry.value;
+        return { value: entry.value, storedAt: entry.storedAt };
     }
     /** Returns the entry even when expired — used for the stale-while-error fallback. */
-    getStale(key) {
-        const entry = this.entries.get(key);
-        if (!entry)
+    async getStale(key) {
+        const entry = await this.read(key);
+        if (!entry || Date.now() - entry.storedAt > MAX_STALE_AGE_MS)
             return undefined;
         return { value: entry.value, storedAt: entry.storedAt };
     }
-    set(key, value, ttlMs) {
-        if (this.entries.has(key))
-            this.entries.delete(key);
+    async set(key, value, ttlMs = this.ttlMs) {
         const now = Date.now();
-        this.entries.set(key, { value, expiresAt: now + ttlMs, storedAt: now });
-        if (this.entries.size > MAX_ENTRIES) {
-            // Map iteration is insertion-ordered, so the first key is the oldest.
-            const oldest = this.entries.keys().next().value;
-            if (oldest !== undefined)
-                this.entries.delete(oldest);
+        const entry = { value, expiresAt: now + ttlMs, storedAt: now };
+        this.remember(key, entry);
+        try {
+            await this.disk?.write(key, entry);
         }
+        catch (error) {
+            this.warn(error);
+        }
+        return now;
     }
     clear() {
         this.entries.clear();
     }
 }
-export const marketCache = new MarketCache();
+export let marketCache = new MarketCache();
+/** Replace memory state when activating a profile; disk entries are read lazily. */
+export function configureMarketCache(options) {
+    marketCache = new MarketCache(options);
+}
 function freshHealth() {
     return {
         clawhub: { status: 'ok' },
@@ -106,8 +178,10 @@ export function resetSourceHealth() {
         sourceHealth[source] = fresh[source];
     }
 }
-/** Test hook: drop cached payloads and reset source health. */
+/** Test hook: drop memory payloads, reset source health and the counters. */
 export function resetMarketCache() {
     marketCache.clear();
     resetSourceHealth();
+    for (const entry of Object.keys(stats))
+        stats[entry] = 0;
 }

package/lib/market/disk-cache.js

@@ -0,0 +1,113 @@
+/** Atomic, bounded storage for upstream snapshots; never stores install state. */
+import { createHash, randomUUID } from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+export const MAX_CACHE_ENTRIES = 500;
+export const MAX_STALE_AGE_MS = 7 * 24 * 60 * 60_000;
+const MAX_ENTRY_BYTES = 5 * 1024 * 1024;
+const MAX_DISK_BYTES = 64 * 1024 * 1024;
+const CACHE_FILE = /^[a-f0-9]{64}\.json$/;
+const TEMP_FILE = /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}\.tmp$/;
+const MAX_TEMP_AGE_MS = 60 * 60_000;
+function snapshotHash(key, entry) {
+    return createHash('sha256').update(JSON.stringify([2, key, entry.storedAt, entry.expiresAt, entry.value])).digest('hex');
+}
+export class DiskMarketCache {
+    directory;
+    writes = Promise.resolve();
+    constructor(directory) {
+        this.directory = directory;
+    }
+    filename(key) {
+        return path.join(this.directory, `${createHash('sha256').update(key).digest('hex')}.json`);
+    }
+    async read(key) {
+        let handle;
+        try {
+            handle = await fs.open(this.filename(key), 'r');
+            if ((await handle.stat()).size > MAX_ENTRY_BYTES)
+                return undefined;
+            const record = JSON.parse(await handle.readFile('utf8'));
+            if (!record || record.version !== 2 || record.key !== key || !('value' in record))
+                return undefined;
+            const { storedAt, expiresAt, value } = record;
+            if (typeof storedAt !== 'number' || !Number.isFinite(storedAt) || storedAt < 0
+                || typeof expiresAt !== 'number' || !Number.isFinite(expiresAt) || expiresAt < storedAt
+                || storedAt > Date.now() || Date.now() - storedAt > MAX_STALE_AGE_MS)
+                return undefined;
+            const entry = { storedAt, expiresAt, value };
+            if (record.sha256 !== snapshotHash(key, entry))
+                return undefined;
+            return entry;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    async write(key, entry) {
+        const body = JSON.stringify({ version: 2, key, ...entry, sha256: snapshotHash(key, entry) });
+        const oversized = Buffer.byteLength(body) > MAX_ENTRY_BYTES;
+        // Serialize publication and pruning within this host. Each response awaits
+        // its write, so quitting after reading a page does not lose a delayed flush.
+        const pending = this.writes.then(async () => {
+            // An unpersistable refresh must not resurrect the previous version after
+            // restart. Serialize invalidation with ordinary writes of the same key.
+            if (oversized) {
+                await fs.rm(this.filename(key), { force: true });
+                return;
+            }
+            await fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+            const temporary = path.join(this.directory, `${randomUUID()}.tmp`);
+            try {
+                await fs.writeFile(temporary, body, { mode: 0o600, flag: 'wx' });
+                await fs.rename(temporary, this.filename(key));
+                await this.prune();
+            }
+            finally {
+                await fs.rm(temporary, { force: true });
+            }
+        });
+        this.writes = pending.catch(() => { });
+        await pending;
+    }
+    async prune() {
+        const names = (await fs.readdir(this.directory)).filter((name) => CACHE_FILE.test(name) || TEMP_FILE.test(name));
+        const records = await Promise.all(names.map(async (name) => {
+            const filename = path.join(this.directory, name);
+            try {
+                const stat = await fs.stat(filename);
+                if (TEMP_FILE.test(name)) {
+                    // A killed host can leave a partial write. Leave recent files alone:
+                    // another host may still be publishing in this shared home.
+                    if (Date.now() - stat.mtimeMs > MAX_TEMP_AGE_MS)
+                        await fs.rm(filename, { force: true });
+                    return undefined;
+                }
+                return { filename, size: stat.size, modifiedAt: stat.mtimeMs };
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            }
+        }));
+        const newest = records.filter((record) => record !== undefined).sort((a, b) => b.modifiedAt - a.modifiedAt);
+        let count = 0;
+        let bytes = 0;
+        for (const record of newest) {
+            if (Date.now() - record.modifiedAt > MAX_STALE_AGE_MS
+                || record.size > MAX_ENTRY_BYTES || count >= MAX_CACHE_ENTRIES || bytes + record.size > MAX_DISK_BYTES) {
+                await fs.rm(record.filename, { force: true });
+            }
+            else {
+                count += 1;
+                bytes += record.size;
+            }
+        }
+    }
+}

package/lib/market/install-service.js

@@ -22,7 +22,8 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { clawhubProvider } from "./clawhub-provider.js";
 import { skillhubProvider } from "./skillhub-provider.js";
-import { getMarketSkillDetail } from "./market-service.js";
+import { getMarketSkillDetail, resolveMarketSkill } from "./market-service.js";
+import { withProviderConfiguration } from "./provider-fetch.js";
 import { INSTALL_META_FILE, parseInstalledMeta, readSkillHeadline, } from "../skills/installed.js";
 import { MARKET_ERROR_CODES, MARKET_LIMITS, sanitizeDirName, skillId, } from "./types.js";
 const providers = {
@@ -104,8 +105,7 @@ function hasErrorCode(error, code) {
 }
 /** The upstream detail for a skill, or the market's own "not installable" verdict. */
 async function loadDetail(source, slug) {
-    const { skill } = await getMarketSkillDetail(source, slug);
-    return skill;
+    return resolveMarketSkill(source, slug);
 }
 /**
  * Refuse to publish over anything we do not own.
@@ -155,7 +155,10 @@ async function readJsonIfExists(filePath) {
  * @throws {import('./types.ts').MarketUpstreamError} for upstream failures,
  *   unwrapped so the route can classify them (404 vs 502).
  */
-export async function installMarketSkill(source, slug, options) {
+export function installMarketSkill(source, slug, options) {
+    return withProviderConfiguration(() => installMarketSkillWithConfiguration(source, slug, options));
+}
+async function installMarketSkillWithConfiguration(source, slug, options) {
     const dirName = sanitizeDirName(slug);
     if (dirName === null) {
         throw new MarketInstallError(400, MARKET_ERROR_CODES.notInstallable, `Skill slug cannot be used as a directory name: ${slug}`);
@@ -188,8 +191,7 @@ async function performInstall(source, slug, dirName, id, skillsRootInput) {
     if (detail.installState === 'not-installable') {
         throw new MarketInstallError(400, MARKET_ERROR_CODES.notInstallable, `Skill is not installable (${detail.notInstallableReason ?? 'unknown'}): ${slug}`);
     }
-    // The cached detail may be older than the provider's version index, so the
-    // file list is fetched fresh at install time (mirrors the reference).
+    // Re-read the file inventory for the freshly resolved manifest version.
     const files = await providers[source].listFiles(slug, detail.version);
     if (files.length === 0 || !files.some((file) => file.path === 'SKILL.md')) {
         throw new MarketInstallError(400, MARKET_ERROR_CODES.notInstallable, `Skill has no installable SKILL.md: ${slug}`);

package/lib/market/market-service.js

@@ -5,12 +5,13 @@
  * 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.
  */
-import { getSourceHealth, markSourceHealth, MARKET_TTL, marketCache } from "./cache.js";
+import { getSourceHealth, markSourceHealth, marketCache, noteMarketStat } from "./cache.js";
+import { getProviderBase, withProviderConfiguration } from "./provider-fetch.js";
 import { clawhubProvider } from "./clawhub-provider.js";
 import { skillhubProvider } from "./skillhub-provider.js";
 import { MARKET_LIMITS, MARKET_SOURCES, detectMarketLanguage, sanitizeDirName, skillId, } from "./types.js";
@@ -154,23 +155,35 @@ export function dedupeSkills(items) {
  * segment so every key is obviously source-scoped.
  */
 function providerPageCacheKey(source, kind, params) {
-    return `${kind}:${source}:${JSON.stringify([params.q ?? null, params.cursor ?? null, params.limit])}`;
+    return `${kind}:${source}:${JSON.stringify([getProviderBase(source), params.q ?? null, params.cursor ?? null, params.limit])}`;
 }
-async function fetchProviderPage(source, params) {
+async function fetchProviderPage(source, params, cache, options = {}) {
     const isSearch = Boolean(params.q);
     const cacheKey = providerPageCacheKey(source, isSearch ? 'search' : 'list', params);
-    const ttl = isSearch ? MARKET_TTL.search : MARKET_TTL.list;
-    const cached = marketCache.get(cacheKey);
-    if (cached) {
-        return { page: cached, status: { status: 'ok', fetchedAt: Date.now(), fromCache: true } };
+    const forced = options.force === true;
+    if (forced) {
+        // A reader asked for this page on purpose; the entry is still rewritten
+        // below, so the refresh costs one request and then serves everyone again.
+        noteMarketStat('forcedRefreshes');
+    }
+    else {
+        const hit = await cache.getRecord(cacheKey);
+        if (hit) {
+            noteMarketStat('hits');
+            // The real fetch time travels with the payload: a hit is a snapshot, and
+            // the panel has to be able to say how old it is.
+            return { page: hit.value, status: { status: 'ok', fetchedAt: hit.storedAt, fromCache: true } };
+        }
     }
+    noteMarketStat('misses');
     try {
         const q = params.q;
         const page = isSearch && q !== undefined
             ? await providers[source].search({ q, cursor: params.cursor, limit: params.limit })
             : await providers[source].list({ cursor: params.cursor, limit: params.limit });
-        marketCache.set(cacheKey, page, ttl);
-        return { page, status: { status: 'ok', fetchedAt: Date.now(), fromCache: false } };
+        noteMarketStat('upstreamRequests');
+        const storedAt = await cache.set(cacheKey, page);
+        return { page, status: { status: 'ok', fetchedAt: storedAt, fromCache: false } };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -181,8 +194,9 @@ async function fetchProviderPage(source, params) {
         markSourceHealth(source, 'failed', message);
         // Stale-while-error: a degraded source still serves its last good page, so a
         // temporary upstream outage does not empty the panel.
-        const stale = marketCache.getStale(cacheKey);
+        const stale = await cache.getStale(cacheKey);
         if (stale) {
+            noteMarketStat('staleServed');
             return {
                 page: stale.value,
                 status: { status: 'cached', fetchedAt: stale.storedAt, fromCache: true, error: message },
@@ -191,7 +205,11 @@ async function fetchProviderPage(source, params) {
         return { page: null, status: { ...getSourceHealth(source), fromCache: false, error: message } };
     }
 }
-export async function listMarketSkills(params) {
+export function listMarketSkills(params) {
+    const cache = marketCache;
+    return withProviderConfiguration(() => listMarketSkillsWithCache(params, cache));
+}
+async function listMarketSkillsWithCache(params, cache) {
     const cursor = decodeCursor(params.cursor);
     const isFirstPage = !params.cursor;
     const activeSources = params.source === 'all' ? MARKET_SOURCES : [params.source];
@@ -207,7 +225,7 @@ export async function listMarketSkills(params) {
         // ClawHub search has no pagination: ask it for one big page and let the
         // aggregate cap apply, instead of pretending a second page exists.
         const limit = q && source === 'clawhub' ? MARKET_LIMITS.searchResultCap : params.limit;
-        outcomes.set(source, await fetchProviderPage(source, { q, cursor: providerCursor, limit }));
+        outcomes.set(source, await fetchProviderPage(source, { q, cursor: providerCursor, limit }, cache, { force: params.refresh === true }));
     }));
     let merged = [];
     const nextCursor = {};
@@ -239,20 +257,38 @@ export async function listMarketSkills(params) {
     return { items: merged, nextCursor: encodeCursor(nextCursor), sources };
 }
 // ─── Detail / file content ───────────────────────────────────────────────────
-export async function getMarketSkillDetail(source, slug) {
-    const cacheKey = `detail:${source}:${slug}`;
-    let detail = marketCache.get(cacheKey);
-    let sourceStatus = { status: 'ok', fetchedAt: Date.now(), fromCache: true };
-    if (!detail) {
+export function getMarketSkillDetail(source, slug, options = {}) {
+    const cache = marketCache;
+    return withProviderConfiguration(() => getMarketSkillDetailWithCache(source, slug, options, cache));
+}
+async function getMarketSkillDetailWithCache(source, slug, options, cache) {
+    const cacheKey = `detail:${source}:${JSON.stringify([getProviderBase(source), slug])}`;
+    const forced = options.force === true;
+    if (forced)
+        noteMarketStat('forcedRefreshes');
+    const hit = forced ? undefined : await cache.getRecord(cacheKey);
+    let detail;
+    let sourceStatus;
+    if (hit) {
+        noteMarketStat('hits');
+        detail = hit.value;
+        sourceStatus = { status: 'ok', fetchedAt: hit.storedAt, fromCache: true };
+    }
+    else {
+        noteMarketStat('misses');
         try {
             detail = await providers[source].detail(slug);
-            marketCache.set(cacheKey, detail, MARKET_TTL.detail);
-            sourceStatus = { status: 'ok', fetchedAt: Date.now(), fromCache: false };
+            noteMarketStat('upstreamRequests');
+            const storedAt = await cache.set(cacheKey, detail);
+            sourceStatus = { status: 'ok', fetchedAt: storedAt, fromCache: false };
         }
         catch (error) {
-            const stale = marketCache.getStale(cacheKey);
+            if (options.allowStale === false)
+                throw error;
+            const stale = await cache.getStale(cacheKey);
             if (!stale)
                 throw error;
+            noteMarketStat('staleServed');
             detail = stale.value;
             sourceStatus = {
                 status: 'cached',
@@ -274,13 +310,20 @@ export function isValidMarketFilePath(filePath) {
         return false;
     return true;
 }
-export async function getMarketFileContent(source, slug, filePath) {
+export function getMarketFileContent(source, slug, filePath) {
+    const cache = marketCache;
+    return withProviderConfiguration(() => getMarketFileContentWithCache(source, slug, filePath, cache));
+}
+async function getMarketFileContentWithCache(source, slug, filePath, cache) {
     // JSON-encoded for the same reason as the list keys: slug and filePath are
     // both caller-controlled, so a `:`-joined key is ambiguous.
-    const cacheKey = `file:${source}:${JSON.stringify([slug, filePath])}`;
-    const cached = marketCache.get(cacheKey);
-    if (cached)
-        return cached;
+    const cacheKey = `file:${source}:${JSON.stringify([getProviderBase(source), slug, filePath])}`;
+    const cached = await cache.getRecord(cacheKey);
+    if (cached) {
+        noteMarketStat('hits');
+        return cached.value;
+    }
+    noteMarketStat('misses');
     const fetched = await providers[source].fetchFile(slug, filePath);
     let content = fetched.content;
     let truncated = false;
@@ -295,7 +338,7 @@ export async function getMarketFileContent(source, slug, filePath) {
         size: fetched.size,
         truncated,
     };
-    marketCache.set(cacheKey, result, MARKET_TTL.fileContent);
+    await cache.set(cacheKey, result);
     return result;
 }
 // ─── Status ──────────────────────────────────────────────────────────────────
@@ -305,8 +348,15 @@ export function getMarketStatus() {
         skillhub: getSourceHealth('skillhub'),
     };
 }
-/** 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 async function resolveMarketSkill(source, slug) {
-    const { skill } = await getMarketSkillDetail(source, slug);
+    const { skill } = await getMarketSkillDetail(source, slug, { force: true, allowStale: false });
     return skill;
 }

package/lib/market/provider-fetch.js

@@ -10,6 +10,7 @@
  * `process.env` at module scope, so the module (and every provider built on it)
  * is directly unit-testable by pointing the bases at a local stub.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { markSourceHealth } from "./cache.js";
 import { MARKET_ERROR_CODES, MARKET_LIMITS, MarketUpstreamError } from "./types.js";
 const DEFAULT_CONFIG = {
@@ -20,6 +21,11 @@ const DEFAULT_CONFIG = {
     userAgent: 'dsh-skills-hub',
 };
 let currentConfig = { ...DEFAULT_CONFIG };
+const requestConfig = new AsyncLocalStorage();
+/** Keep cache keys and all chained upstream reads on one configuration snapshot. */
+export function withProviderConfiguration(operation) {
+    return requestConfig.run(requestConfig.getStore() ?? currentConfig, operation);
+}
 /** Strip trailing slashes so `new URL('/api/...', base)` never doubles a separator. */
 function normalizeBaseUrl(value) {
     return value.replace(/\/+$/, '');
@@ -51,7 +57,8 @@ export function configureProviderFetch(config) {
 }
 /** Base URL of one upstream, as resolved from the active configuration. */
 export function getProviderBase(source) {
-    return source === 'clawhub' ? currentConfig.clawhubBaseUrl : currentConfig.skillhubBaseUrl;
+    const config = requestConfig.getStore() ?? currentConfig;
+    return source === 'clawhub' ? config.clawhubBaseUrl : config.skillhubBaseUrl;
 }
 /**
  * An upstream answered with a non-2xx status (or a retryable 429/5xx).
@@ -93,7 +100,7 @@ function requestHeaders(init, userAgent) {
  * provider can map it to a meaningful error.
  */
 export async function providerFetch(source, url, init) {
-    const config = currentConfig;
+    const config = requestConfig.getStore() ?? currentConfig;
     const attempts = Math.max(1, config.retries + 1);
     let lastError;
     for (let attempt = 0; attempt < attempts; attempt++) {

package/lib/market/types.js

@@ -70,7 +70,8 @@ export function sanitizeDirName(slug) {
     return name;
 }
 const LANG_MAP = {
-    md: 'markdown', ts: 'typescript', tsx: 'typescript',
+    md: 'markdown', markdown: 'markdown', mdx: 'markdown',
+    ts: 'typescript', tsx: 'typescript',
     js: 'javascript', jsx: 'javascript', mjs: 'javascript', cjs: 'javascript',
     json: 'json', yaml: 'yaml', yml: 'yaml', sh: 'bash', bash: 'bash', zsh: 'bash',
     py: 'python', toml: 'toml', css: 'css', html: 'html',