@nanmicoder/dsh-skills-hub 0.0.1 → 0.0.3

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

@@ -0,0 +1,32 @@
+/**
+ * Files tab body, shared by the two detail pages.
+ *
+ * The market page lists provider file metadata and the local page lists the
+ * bytes on disk, but both are the same control: a picker on the left, one
+ * document on the right, and a copy button that confirms itself. The only
+ * difference the caller keeps is how a selection is fetched.
+ *
+ * A markdown document opens *rendered*: SKILL.md is prose meant to be read, and
+ * showing its source first answers a question nobody asked. Installing still has
+ * to be a trust decision, though, so the raw bytes are one toggle away — with
+ * line numbers and the copy button pointed at exactly what is on disk. Other
+ * files have no rendered form and stay source-only.
+ */
+import type { MarketFileContent } from '../../market/types.ts';
+/** The subset of a file row this control renders; both pages' metadata fits it. */
+export interface SkillFileListItem {
+    path: string;
+    size: number;
+    language: string;
+    /** Provider flagged the file as beyond the preview/install limit. */
+    tooBig?: boolean;
+}
+export declare function SkillFiles(props: {
+    files: SkillFileListItem[];
+    /** Already-fetched document for the selected path, or `null` while none is loaded. */
+    selected: MarketFileContent | null;
+    loading: boolean;
+    /** Reader-facing failure of the last selection, if any. */
+    error?: string | null;
+    onSelect: (path: string) => void;
+}): JSX.Element;

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

@@ -5,6 +5,10 @@ import type { MarketSource, SourceStatusInfo } from '../../market/types.ts';
  * The upstream error string rides the pill's `title` instead of being printed:
  * a 720px panel has no room for a stack trace next to two source names, and an
  * operator who needs it can hover.
+ *
+ * The snapshot age *is* printed: a healthy source can still be answering from a
+ * cache, and a reader deciding whether to install third-party code is entitled
+ * to see that the page in front of them was read minutes ago rather than now.
  */
 export declare function SourceStatusBar(props: {
     sources: Record<MarketSource, SourceStatusInfo>;

package/lib/types/client/icons.d.ts

@@ -69,3 +69,7 @@ export declare function ChevronRightIcon({ size, className }: SkillsHubIconProps
 export declare function CloseIcon({ size, className }: SkillsHubIconProps): JSX.Element;
 /** Price tag: leading glyph of a card's tag row. */
 export declare function TagIcon({ size, className }: SkillsHubIconProps): JSX.Element;
+/** Folder: leading glyph of the installed skill's location line. */
+export declare function FolderIcon({ size, className }: SkillsHubIconProps): JSX.Element;
+/** Arrow leaving a frame: open the same skill in the marketplace. */
+export declare function ExternalLinkIcon({ size, className }: SkillsHubIconProps): JSX.Element;

package/lib/types/client/locales.d.ts

@@ -29,6 +29,34 @@ declare const zhDictionary: {
     localUninstallDescription: string;
     unlinkDescription: string;
     uninstalling: string;
+    uninstallDisabled: string;
+    copyPath: string;
+    copiedPath: string;
+    sourceLabel: string;
+    managedByHub: string;
+    unmanagedSkill: string;
+    symlinkSkill: string;
+    installedAtLabel: string;
+    skillKind: string;
+    bundleSkill: string;
+    flatSkill: string;
+    filesCount: string;
+    emptyDocument: string;
+    installedReadFailed: string;
+    openInMarket: string;
+    fileView: string;
+    filePreview: string;
+    fileSource: string;
+    snapshotAge: string;
+    ageJustNow: string;
+    ageMinutes: string;
+    ageHours: string;
+    ageDays: string;
+    refreshNow: string;
+    refreshSnapshot: string;
+    detailSnapshot: string;
+    installSnapshot: string;
+    marketProvenance: string;
     panel: string;
     title: string;
     subtitle: string;
@@ -37,6 +65,7 @@ declare const zhDictionary: {
     'source.all': string;
     'source.clawhub': string;
     'source.skillhub': string;
+    'source.local': string;
     'security.all': string;
     'security.verified': string;
     'security.benign': string;
@@ -45,6 +74,70 @@ declare const zhDictionary: {
     'installed.all': string;
     'installed.installed': string;
     'installed.installable': string;
+    'category.lang': string;
+    'category.label': string;
+    'category.all': string;
+    categoryTag: string;
+    breadcrumb: string;
+    updatedOn: string;
+    needsApiKey: string;
+    sourcePage: string;
+    securityReport: string;
+    changelog: string;
+    whenToUse: string;
+    info: string;
+    latestUpdate: string;
+    fullChangelog: string;
+    olderVersions: string;
+    openChangelogFile: string;
+    noChangelog: string;
+    scanReports: string;
+    noReports: string;
+    scanDisclaimer: string;
+    readingTime: string;
+    expand: string;
+    collapse: string;
+    capTitle: string;
+    viewFullReport: string;
+    capNote: string;
+    'cap.shell': string;
+    'cap.shell.detail': string;
+    'cap.hooks': string;
+    'cap.hooks.detail': string;
+    'cap.secrets': string;
+    'cap.secrets.detail': string;
+    'cap.network': string;
+    'cap.network.detail': string;
+    'cap.writes': string;
+    'cap.writes.detail': string;
+    'cap.binaries': string;
+    'cap.binaries.detail': string;
+    'scan.verified': string;
+    'scan.benign': string;
+    'scan.unknown': string;
+    'scan.flagged': string;
+    installTitle: string;
+    confirmInstall: string;
+    willGet: string;
+    'level.high': string;
+    'level.medium': string;
+    'level.low': string;
+    installWarnFlagged: string;
+    installWarnUnknown: string;
+    ack: string;
+    installedOn: string;
+    'scanShort.verified': string;
+    'scanShort.benign': string;
+    'scanShort.unknown': string;
+    'scanShort.flagged': string;
+    catalogSummary: string;
+    catalogUpdated: string;
+    liveResults: string;
+    featured: string;
+    'scope.catalogHint': string;
+    'scope.marketHint': string;
+    'scope.searchMarket': string;
+    'scope.backToCatalog': string;
     'filter.source': string;
     'filter.security': string;
     'filter.installed': string;
@@ -96,6 +189,7 @@ declare const zhDictionary: {
     uninstallDone: string;
     noFiles: string;
     fileTooLarge: string;
+    fileTruncated: string;
     copy: string;
     copied: string;
     unoaudited: string;

package/lib/types/client/relative-time.d.ts

@@ -0,0 +1,13 @@
+/**
+ * How old a snapshot is, in the panel's own vocabulary.
+ *
+ * The panel shows cached catalogue data, so "when was this actually fetched" is
+ * part of the answer rather than a debug detail: a reader who is about to
+ * install third-party code is entitled to know whether the security report in
+ * front of them was read a minute ago or yesterday.
+ */
+import type { Translate } from './locale-context.tsx';
+/** Coarse buckets: the first match wins, and precision beyond them is noise. */
+export declare function formatAge(t: Translate, from: number, now?: number): string;
+/** Absolute timestamp for the hover text, so the bucket never hides the fact. */
+export declare function formatStamp(from: number): string;

package/lib/types/client/skill-insights.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What a skill will do, read off its own files — before anyone installs it.
+ *
+ * Everything here is rule-based and explainable: each finding points at the
+ * file, command, variable or host it came from, and nothing is inferred that
+ * the SKILL.md and file list do not show. When no rule fires, the panel is not
+ * rendered at all; an empty "this skill does nothing risky" claim would be a
+ * verdict this module cannot make.
+ */
+import type { MarketFileMeta } from '../market/types.ts';
+export type CapabilityKind = 'shell' | 'hooks' | 'network' | 'secrets' | 'binaries' | 'writes';
+export type CapabilityLevel = 'high' | 'medium' | 'low';
+export interface Capability {
+    kind: CapabilityKind;
+    level: CapabilityLevel;
+    /** The evidence, verbatim: paths, commands, variable names or hosts. */
+    evidence: string[];
+}
+export declare function detectCapabilities(input: {
+    markdown: string;
+    frontmatter?: Record<string, unknown>;
+    files: readonly Pick<MarketFileMeta, 'path'>[];
+}): Capability[];
+/**
+ * The "when to use" list a SKILL.md description usually carries:
+ * `Use when (1) …, (2) …` / `Use when: …; …` / `当……时使用`.
+ */
+export declare function extractTriggers(description: string | undefined): string[];
+/** Rough reading time: ~400 CJK characters or ~220 Latin words per minute. */
+export declare function readingMinutes(markdown: string): number;

package/lib/types/client/skill-markdown.d.ts

@@ -1,2 +1,41 @@
+/**
+ * Frontmatter handling for skill documents.
+ *
+ * A `SKILL.md` opens with a YAML block, and feeding that block to a markdown
+ * renderer is not merely ugly — it is wrong: a lone `---` is a setext underline,
+ * so the closing fence promotes the whole metadata block into one giant heading.
+ * The block is split off here instead, so the UI can render it as structured
+ * metadata (`FrontmatterPanel`) while the rest of the document goes to the
+ * renderer. The approach mirrors the desktop project's `skillFrontmatter.ts`.
+ *
+ * The parser is a deliberately small YAML subset — scalars, inline and block
+ * sequences, `|`/`>` block scalars, and one level of nested mapping that is kept
+ * as the raw YAML it is — because skill frontmatter is flat by convention and a
+ * full YAML engine is a dependency this browser bundle does not need. It never
+ * throws: a document without a fence, or with an unterminated one, comes back as
+ * body only.
+ */
+/** One document separated into its metadata and everything else. */
+export interface SkillFrontmatterSplit {
+    /** Parsed metadata, or `null` when the document carries none worth showing. */
+    frontmatter: Record<string, unknown> | null;
+    /** The document with its metadata block removed. */
+    body: string;
+}
+/**
+ * Parse a metadata block that has already been extracted — the Host bounds its
+ * size before it reaches the browser, so this entry point works on that text.
+ *
+ * @param yaml - the block's text, without its fences.
+ * @returns the parsed keys, or `null` when the block carries nothing to show.
+ */
+export declare function parseSkillFrontmatter(yaml: string): Record<string, unknown> | null;
+/**
+ * Separate a document's frontmatter from its body.
+ *
+ * @param markdown - the whole document.
+ * @returns the parsed metadata (or `null`) plus the body to render.
+ */
+export declare function splitSkillFrontmatter(markdown: string): SkillFrontmatterSplit;
 /** Frontmatter is metadata, not part of the skill's rendered instructions. */
 export declare function stripSkillFrontmatter(markdown: string): string;

package/lib/types/client/state.d.ts

@@ -13,8 +13,8 @@
  *    already holds.
  *  - **in-flight guards**: one install/uninstall per id, one page per cursor, one
  *    detail/file request per target.
- *  - **detail/file caching**: reopening a skill is instant and cannot blank the
- *    pane with a spinner.
+ *  - **detail snapshots**: reopening can show the previous copy immediately,
+ *    while the Host rechecks its TTL and current install annotations.
  *  - **local management**: the InstalledSkills component independently lists what is already
  *    on disk (`fetchInstalled`) instead of asking the market, matching the
  *    contract's §5.3 behaviour.
@@ -23,7 +23,7 @@
  * requests on purpose, and `isAbortError` keeps those rejections out of
  * `state.error` / `state.notice`.
  */
-import type { MarketFileContent, MarketSource, NormalizedSkill, NormalizedSkillDetail, SecurityStatus, SourceStatusInfo } from '../market/types.ts';
+import type { MarketCategory, MarketFileContent, MarketSource, NormalizedSkill, NormalizedSkillDetail, SecurityStatus, SourceStatusInfo } from '../market/types.ts';
 /**
  * Notice values that are dictionary *codes* rather than literal text.
  *
@@ -36,9 +36,19 @@ export declare const MARKET_NOTICE_CODES: readonly ["installDone", "uninstallDon
 export type MarketNoticeCode = (typeof MARKET_NOTICE_CODES)[number];
 /** Whether a `state.notice` value is a dictionary code (as opposed to verbatim text). */
 export declare function isMarketNoticeCode(notice: string): notice is MarketNoticeCode;
+/** Tabs of the market detail page. */
+export type MarketDetailTab = 'overview' | 'files' | 'security' | 'changelog';
 /** Active catalogue filters. */
 export interface MarketFilters {
     q: string;
+    /**
+     * `catalog`: the curated list shipped with the plugin (default).
+     * `market`: live search across both registries, entered explicitly from a
+     * catalogue search; clearing the query returns to the catalogue.
+     */
+    scope: 'catalog' | 'market';
+    /** Catalogue category key, or `'all'`. */
+    category: string;
     source: 'all' | MarketSource;
     security: 'all' | SecurityStatus;
     installed: 'all' | 'installed' | 'installable';
@@ -46,9 +56,15 @@ export interface MarketFilters {
 /** Everything the panel renders from. Immutable: each commit publishes a new object. */
 export interface MarketState {
     filters: MarketFilters;
+    /** Category bar entries; empty until loaded. */
+    categories: MarketCategory[];
     items: NormalizedSkill[];
     nextCursor: string | null;
+    /** Matching skills in total, when the list knows it (the curated catalogue does). */
+    total: number | null;
     sources: Record<MarketSource, SourceStatusInfo>;
+    /** Each card retains the provenance of its own page when more pages append. */
+    itemStatuses: Record<string, SourceStatusInfo>;
     loading: boolean;
     loadingMore: boolean;
     error: string | null;
@@ -59,9 +75,11 @@ export interface MarketState {
         id: string;
     };
     detail: NormalizedSkillDetail | null;
+    /** Provenance of `detail`: when it was fetched upstream, and whether it is a snapshot. */
+    detailStatus: SourceStatusInfo | null;
     detailLoading: boolean;
     detailError: string | null;
-    activeTab: 'overview' | 'files';
+    activeTab: MarketDetailTab;
     file: MarketFileContent | null;
     fileLoading: boolean;
     installingIds: ReadonlySet<string>;
@@ -73,15 +91,26 @@ export interface MarketState {
 export interface MarketController {
     state: MarketState;
     readonly injected: MarketPageInjected;
-    refresh(): Promise<void>;
+    /** `force` is the reader's refresh: it must not be answered from the cache. */
+    refresh(options?: {
+        force?: boolean;
+    }): Promise<void>;
     loadMore(): Promise<void>;
     setQuery(q: string): void;
+    setCategory(category: MarketFilters['category']): void;
+    setScope(scope: MarketFilters['scope']): void;
+    /** Load the category bar once per controller (repeat calls share it). */
+    loadCategories(): Promise<void>;
     setSource(source: MarketFilters['source']): void;
     setSecurity(security: MarketFilters['security']): void;
     setInstalledFilter(installed: MarketFilters['installed']): void;
-    openDetail(id: string): Promise<void>;
+    /** `owner` names the registry author when the id alone is ambiguous (ClawHub). */
+    openDetail(id: string, options?: {
+        refresh?: boolean;
+        owner?: string;
+    }): Promise<void>;
     closeDetail(): void;
-    setTab(tab: 'overview' | 'files'): void;
+    setTab(tab: MarketDetailTab): void;
     selectFile(path: string): Promise<void>;
     requestInstall(id: string): void;
     cancelInstall(): void;

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/clawhub-provider.d.ts

@@ -7,6 +7,9 @@
  *  - GET /api/v1/skills/{slug}                        → {skill, latestVersion, owner, metadata, moderation}
  *  - GET /api/v1/skills/{slug}/versions/{v}           → {version:{license, files[], security}}
  *  - GET /api/v1/skills/{slug}/file?path=             → raw file text
+ *
+ * Slugs are not unique: every endpoint accepts `?owner=`, and without it a
+ * shared slug answers 409 AMBIGUOUS_SKILL_SLUG. See `clawhubOwnerFor`.
  */
 import { type MarketProvider } from './types.ts';
 export type ParsedFrontmatter = {
@@ -23,6 +26,18 @@ export type ParsedFrontmatter = {
  * value it cannot understand is dropped rather than throwing.
  */
 export declare function parseFrontmatter(markdown: string): ParsedFrontmatter;
+/** Shape of a ClawHub owner handle (also the route's validation rule). */
+export declare const CLAWHUB_OWNER_PATTERN: RegExp;
+export declare function setClawhubOwnerHints(hints: Iterable<readonly [string, string]>): void;
+/**
+ * Run one operation pinned to `owner` for `slug`. Without an owner the
+ * operation runs unpinned and falls back to the hint/cache/probe order.
+ */
+export declare function withClawhubOwner<T>(slug: string, owner: string | undefined, operation: () => Promise<T>): Promise<T>;
+/** The owner a read of `slug` will use right now, if one is known before asking upstream. */
+export declare function clawhubOwnerFor(slug: string): string | undefined;
+/** A release note worth showing: registries stamp placeholders on synced versions. */
+export declare function meaningfulChangelog(text: unknown): string | undefined;
 /** Test hook: forget which owner disambiguated an ambiguous slug. */
 export declare function resetClawhubOwnerCache(): void;
 export declare const clawhubProvider: MarketProvider;

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/install-service.d.ts

@@ -56,6 +56,7 @@ export declare class MarketInstallError extends Error {
 export declare function installMarketSkill(source: MarketSource, slug: string, options: {
     skillsRoot: string;
     allowUninstall: boolean;
+    owner?: string;
 }): Promise<InstallResult>;
 /**
  * Remove one skill this plugin installed.

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

@@ -5,12 +5,12 @@
  * 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 { type MarketFileContent, type MarketListResult, type MarketSource, type NormalizedSkill, type NormalizedSkillDetail, type SecurityStatus, type SourceStatusInfo } from './types.ts';
+import { type MarketCategoriesResult, type MarketFileContent, type MarketListResult, type MarketSource, type NormalizedSkill, type NormalizedSkillDetail, type SecurityStatus, type SourceStatusInfo } from './types.ts';
 /**
  * Local install state, injected by the plugin host (which owns the skills
  * directory). Both methods are synchronous: the host keeps an in-memory index
@@ -55,20 +55,54 @@ export declare function applyFileLimits(detail: NormalizedSkillDetail): Normaliz
 export declare function dedupeSkills(items: NormalizedSkill[]): NormalizedSkill[];
 export interface ListMarketSkillsParams {
     q?: string;
+    /**
+     * `catalog` (default): the curated snapshot shipped with the plugin.
+     * `market`: live upstream list/search across both registries.
+     */
+    scope?: 'catalog' | 'market';
+    /** Catalogue category key; ignored by the live market scope. */
+    category?: string;
     source: 'all' | MarketSource;
     security: 'all' | SecurityStatus;
     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<{
+/**
+ * One page of the curated catalogue.
+ *
+ * Everything is local, so every filter — security and installed included — runs
+ * before pagination: a page is always full until the list is exhausted, which
+ * is what keeps infinite scroll from stalling on a filtered-out page.
+ */
+export declare function listCatalogSkills(params: ListMarketSkillsParams): MarketListResult;
+export declare function listMarketCategories(): MarketCategoriesResult;
+export declare function getMarketSkillDetail(source: MarketSource, slug: string, options?: {
+    force?: boolean;
+    allowStale?: boolean;
+    owner?: string;
+}): 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 getMarketFileContent(source: MarketSource, slug: string, filePath: string, owner?: string): Promise<MarketFileContent>;
+/**
+ * Pin a ClawHub read to the owner the reader asked for. ClawHub slugs are
+ * shared across authors, so `clawhub:<slug>` alone does not name one skill.
+ */
+export declare function withMarketOwner<T>(source: MarketSource, slug: string, owner: string | undefined, operation: () => Promise<T>): Promise<T>;
 export declare function getMarketStatus(): Record<MarketSource, SourceStatusInfo>;
-/** Look up a single skill (used by install) — the detail path, bypassing list. */
-export declare function resolveMarketSkill(source: MarketSource, slug: string): Promise<NormalizedSkillDetail>;
+/**
+ * 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, owner?: 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.