@nanmicoder/dsh-skills-hub 0.0.1

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

@@ -0,0 +1,119 @@
+/**
+ * Skills Hub panel state machine — framework-free, so it is unit-testable
+ * outside React.
+ *
+ * Ported from the reference desktop store (`desktop/src/stores/marketStore.ts`)
+ * with the same invariants:
+ *
+ *  - **stale-response rejection**: every request family carries a monotonically
+ *    increasing sequence; a response whose sequence is no longer current is
+ *    dropped instead of overwriting newer state.
+ *  - **merge by id**: a page append and an install/uninstall patch both merge on
+ *    `NormalizedSkill.id`, and pagination never duplicates a skill the list
+ *    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.
+ *  - **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.
+ *
+ * Aborts are control flow, never user-visible: the panel aborts superseded
+ * 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';
+/**
+ * Notice values that are dictionary *codes* rather than literal text.
+ *
+ * The controller has no locale (it is framework-free and testable), so it stores
+ * a code for the panel to translate and stores a verbatim message for anything
+ * that has no dictionary entry — which is exactly what a Host error is.
+ */
+export declare const MARKET_NOTICE_CODES: readonly ["installDone", "uninstallDone"];
+/** A notice value the panel translates through its dictionary. */
+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;
+/** Active catalogue filters. */
+export interface MarketFilters {
+    q: string;
+    source: 'all' | MarketSource;
+    security: 'all' | SecurityStatus;
+    installed: 'all' | 'installed' | 'installable';
+}
+/** Everything the panel renders from. Immutable: each commit publishes a new object. */
+export interface MarketState {
+    filters: MarketFilters;
+    items: NormalizedSkill[];
+    nextCursor: string | null;
+    sources: Record<MarketSource, SourceStatusInfo>;
+    loading: boolean;
+    loadingMore: boolean;
+    error: string | null;
+    view: {
+        kind: 'home';
+    } | {
+        kind: 'detail';
+        id: string;
+    };
+    detail: NormalizedSkillDetail | null;
+    detailLoading: boolean;
+    detailError: string | null;
+    activeTab: 'overview' | 'files';
+    file: MarketFileContent | null;
+    fileLoading: boolean;
+    installingIds: ReadonlySet<string>;
+    confirmInstallId: string | null;
+    disclaimerDismissed: boolean;
+    notice: string | null;
+}
+/** Actions and state the panel root drives. */
+export interface MarketController {
+    state: MarketState;
+    readonly injected: MarketPageInjected;
+    refresh(): Promise<void>;
+    loadMore(): Promise<void>;
+    setQuery(q: string): void;
+    setSource(source: MarketFilters['source']): void;
+    setSecurity(security: MarketFilters['security']): void;
+    setInstalledFilter(installed: MarketFilters['installed']): void;
+    openDetail(id: string): Promise<void>;
+    closeDetail(): void;
+    setTab(tab: 'overview' | 'files'): void;
+    selectFile(path: string): Promise<void>;
+    requestInstall(id: string): void;
+    cancelInstall(): void;
+    confirmInstall(): Promise<void>;
+    uninstall(id: string): Promise<void>;
+    dismissDisclaimer(): void;
+    dismissNotice(): void;
+}
+/** The business face one `main` registration injects into the panel component. */
+export interface MarketPageInjected {
+    useMarketController: () => MarketController;
+}
+/**
+ * Create one panel controller.
+ *
+ * `useMarketController` calls this per mounted panel; `createMarketController` is
+ * also the entry point for tests, which is why the factory performs no I/O — the
+ * first request only happens when the panel asks for it.
+ */
+export declare function createMarketController(): MarketController;
+/**
+ * React binding.
+ *
+ * `useSyncExternalStore` is the whole subscription: React owns the subscribe /
+ * unsubscribe pairing, so an unmount cannot leak a listener, and the initializer
+ * runs at most twice under StrictMode's development double-invocation (the extra
+ * controller is discarded and holds no resources — no request, timer or
+ * subscription exists until the panel asks for one).
+ *
+ * There is deliberately no unmount disposer: a StrictMode cleanup would tear down
+ * the controller React is still using, and a late response writing into this
+ * store is inert — nothing but the snapshot identity of an external store
+ * changes, so no React state update happens after unmount.
+ */
+export declare function useMarketController(): MarketController;

package/lib/types/config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Skills Hub configuration.
+ *
+ * The schema below is the plugin's whole configuration surface: DSH validates
+ * the profile's plugin row against it and hands `apply()` the resolved value.
+ * Every field carries a default, so a row written as `{}` — or an `apply()`
+ * called directly from a test — still boots the plugin with the shipped
+ * behaviour instead of failing on a missing key.
+ *
+ * `skillsRoot: null` means "the user skills directory DSH itself scans"
+ * (`$DSH_HOME/skills`); a string is an explicit override for tests, for
+ * throwaway profiles, or for a deployment that keeps skills outside the
+ * harness home. The reference implementation hard-coded its own
+ * `~/.claude/skills`, which is exactly the coupling this field removes.
+ */
+import z from '@deepseek-ai/schemastery';
+export interface SkillsHubConfig {
+    /** Absolute skills directory to install into; `null` = the DSH user skills directory. */
+    skillsRoot: string | null;
+    /** ClawHub base URL (default `https://clawhub.ai`). */
+    clawhubBaseUrl: string;
+    /** SkillHub base URL (default `https://api.skillhub.cn`). */
+    skillhubBaseUrl: string;
+    /** Per-request upstream timeout in milliseconds. */
+    timeoutMs: number;
+    /** Extra upstream attempts after the first failure (network error, 429, 5xx). */
+    requestRetries: number;
+    /** Whether `POST /uninstall` may remove installed skills at all. */
+    allowUninstall: boolean;
+    /** Default `limit` for `GET /skills` when the request omits one (clamped to 1…100). */
+    pageSize: number;
+}
+/**
+ * Shipped defaults. Exported so `apply()` can fill in a partially resolved
+ * config when the plugin is mounted without going through the schema (unit
+ * tests, direct composition), without restating the literals in two places.
+ */
+export declare const SKILLS_HUB_DEFAULTS: SkillsHubConfig;
+/**
+ * `null` must stay a legal value for `skillsRoot` (it is the "use the DSH
+ * default" marker), so the field is modelled as a union rather than as a
+ * nullable string: a plain `z.string().default('')` would make "unset" and
+ * "empty string" indistinguishable and would leak an empty path into `path.join`.
+ *
+ * Schemastery quirk worth knowing: its object resolver drops a key whose
+ * resolved value is nullable and which was absent from the input, so
+ * `Config({}).skillsRoot` is `undefined`, not `null`. Both mean "use the DSH
+ * default" and `apply()` normalizes either to `null` before using it, so a
+ * caller that bypasses the schema cannot change the behaviour.
+ */
+export declare const Config: z<SkillsHubConfig>;

package/lib/types/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Skills Hub — DeepSeek Harness host plugin.
+ *
+ * Adds the market half of the Skills Hub panel to a DSH profile:
+ *
+ *  - `/api/skills-hub/*` (browse, search, detail, file preview, installed,
+ *    install, uninstall) served from the composition's Web server;
+ *  - installation into the DSH user skills directory, so an installed skill is
+ *    immediately discoverable by the `skill` tool;
+ *  - the installed-skill index the market layer asks for via
+ *    `setInstalledLookup()`.
+ *
+ * Installation is deliberately not a realm feature: it is plain filesystem work
+ * plus HTTP, no agent session is involved, and the tools registry is untouched.
+ *
+ * @module dsh-skills-hub
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config, type SkillsHubConfig } from './config.ts';
+export declare const name = "skills-hub";
+/**
+ * Required services.
+ *
+ * Empty on purpose, and the honest answer for this plugin: nothing must exist for
+ * it to *load*. The Web server is looked up lazily (`ctx.get`, both known keys)
+ * and bound whenever it appears, so a headless profile keeps the plugin inert
+ * instead of pending forever on a service key that composition never provides;
+ * the skill registry is optional (it only informs a post-install catalog read);
+ * and the market core is pure code with no service dependency at all. Injecting
+ * `'webServer'` here would make the plugin unusable in the very profiles where
+ * the harness would still boot it, and would break on a composition that spells
+ * the service `httpServer`.
+ */
+export declare const inject: string[];
+export { Config };
+/**
+ * Activate the plugin.
+ *
+ * @param ctx - host plugin context.
+ * @param config - resolved {@link SkillsHubConfig} (schema defaults already applied).
+ */
+export declare function apply(ctx: Context, config: SkillsHubConfig): void;

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

@@ -0,0 +1,49 @@
+/**
+ * Skills Market — in-memory TTL cache with stale-while-error support, plus
+ * per-source health tracking.
+ *
+ * Only *upstream* data is cached here (list pages, details, file bodies).
+ * Install state is derived per request from the injected installed-skill index
+ * 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`.
+ */
+import type { MarketSource, SourceHealthStatus, SourceStatusInfo } from './types.ts';
+/** Per-payload TTLs: cheap-to-refetch list pages expire sooner than file bodies. */
+export declare const MARKET_TTL: {
+    readonly list: number;
+    readonly search: number;
+    readonly detail: number;
+    readonly files: number;
+    readonly fileContent: number;
+};
+declare class MarketCache {
+    private entries;
+    get<T>(key: string): 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;
+    clear(): void;
+}
+export declare const marketCache: MarketCache;
+/**
+ * Record the outcome of one upstream interaction.
+ *
+ * A `failed` report is downgraded to `degraded` when the source succeeded
+ * recently (it answered a moment ago, this request just went wrong) — repeated
+ * failures after the last success report `failed`. This mirrors the reference
+ * server's `recordSourceFailure`, which is what the UI's source bar was built
+ * around; callers that genuinely know better can pass `degraded` explicitly.
+ */
+export declare function markSourceHealth(source: MarketSource, status: SourceHealthStatus, error?: string): void;
+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. */
+export declare function resetMarketCache(): void;
+export {};

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

@@ -0,0 +1,28 @@
+/**
+ * ClawHub provider (https://clawhub.ai)
+ *
+ * Endpoints (verified against the live API):
+ *  - GET /api/v1/skills?limit=&cursor=&sort=downloads → {items, nextCursor}
+ *  - GET /api/v1/search?q=                            → {results} (no pagination)
+ *  - 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
+ */
+import { type MarketProvider } from './types.ts';
+export type ParsedFrontmatter = {
+    frontmatter: Record<string, unknown>;
+    content: string;
+};
+/**
+ * Split `---` frontmatter from a markdown body.
+ *
+ * The reference server delegated YAML to Bun.YAML / the `yaml` package; this
+ * plugin must not add a runtime dependency, so `parseYamlSubset` below covers
+ * the subset SKILL.md frontmatter actually uses (scalars, quoted strings, flow
+ * collections, nested mappings, block sequences and block scalars) and any
+ * value it cannot understand is dropped rather than throwing.
+ */
+export declare function parseFrontmatter(markdown: string): ParsedFrontmatter;
+/** Test hook: forget which owner disambiguated an ambiguous slug. */
+export declare function resetClawhubOwnerCache(): void;
+export declare const clawhubProvider: MarketProvider;

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

@@ -0,0 +1,75 @@
+/**
+ * Skills Market — install / uninstall service.
+ *
+ * Install: fetch the whole file list, enforce `MARKET_LIMITS`, verify every
+ * provider-reported SHA-256, sanitize the slug into a directory name, stage the
+ * complete skill in a hidden sibling directory and publish it with a single
+ * `rename` — the skills root never contains a partially written skill, and a
+ * failure leaves nothing behind but the (removed) staging directory.
+ *
+ * Uninstall: only ever removes a directory that carries our provenance sidecar
+ * with an id matching the requested skill, and only inside the configured
+ * skills root. Every path is resolved and containment-checked before a delete,
+ * because "the plugin deleted something outside its own tree" is the one bug a
+ * skills market must not have.
+ *
+ * Ported from the reference `installService.ts` (Claude Code desktop), with the
+ * filesystem layout, the sidecar name and the concurrency key all frozen by the
+ * interface contract.
+ */
+import { type MarketSource, type NormalizedSkill } from './types.ts';
+export interface InstallResult {
+    installedPath: string;
+    skill: NormalizedSkill;
+}
+export interface UninstallResult {
+    removedPath: string;
+    skill: NormalizedSkill;
+}
+/**
+ * One rejected install/uninstall carrying both the market error code and the
+ * HTTP status the route layer must answer with.
+ *
+ * The reference used its server-wide `ApiError`; this plugin owns no server
+ * middleware, so the code/status pair travels with the error instead of being
+ * re-derived from a message string at the edge. Upstream failures are *not*
+ * wrapped: W1's `MarketUpstreamError` already carries the code the route maps
+ * (`upstreamBadResponse` → 404, everything else → 502).
+ */
+export declare class MarketInstallError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(status: number, code: string, message: string);
+}
+/**
+ * Install one market skill into `options.skillsRoot`.
+ *
+ * @param source - market the skill comes from.
+ * @param slug - provider slug; also the directory name after sanitization.
+ * @param options - resolved skills root and the (unused here) uninstall switch,
+ *   kept in the signature so both verbs take one shape.
+ * @returns the absolute installed path and the skill re-annotated as `installed`.
+ * @throws {MarketInstallError} for anything this plugin refuses itself.
+ * @throws {import('./types.ts').MarketUpstreamError} for upstream failures,
+ *   unwrapped so the route can classify them (404 vs 502).
+ */
+export declare function installMarketSkill(source: MarketSource, slug: string, options: {
+    skillsRoot: string;
+    allowUninstall: boolean;
+}): Promise<InstallResult>;
+/**
+ * Remove one skill this plugin installed.
+ *
+ * @param source - market the skill was installed from.
+ * @param slug - provider slug; the directory name after sanitization.
+ * @param options - resolved skills root and the `allowUninstall` switch.
+ * @returns the removed path and a best-effort refreshed skill record.
+ * @throws {MarketInstallError} when the switch is off, the skill is missing, or
+ *   the directory is not provably ours.
+ */
+export declare function uninstallMarketSkill(source: MarketSource, slug: string, options: {
+    skillsRoot: string;
+    allowUninstall: boolean;
+}): Promise<UninstallResult>;
+/** Drop every install lock. Test hook, mirroring the reference implementation. */
+export declare function resetInstallLocksForTests(): void;

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

@@ -0,0 +1,74 @@
+/**
+ * Skills Market — aggregation service (host half).
+ *
+ * Merges the two upstream providers into a single paginated feed with
+ * 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
+ * "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';
+/**
+ * Local install state, injected by the plugin host (which owns the skills
+ * directory). Both methods are synchronous: the host keeps an in-memory index
+ * and rescans it after install/uninstall.
+ */
+export interface InstalledLookup {
+    /** ids (`source:slug`) of skills already present in the local skills directory */
+    has(id: string): boolean;
+    info(id: string): {
+        dirName: string;
+        version?: string;
+        installedAt?: string;
+    } | undefined;
+}
+export declare function setInstalledLookup(lookup: InstalledLookup): void;
+/** Test hook: fall back to "nothing installed" (also used when a plugin unloads). */
+export declare function resetInstalledLookup(): void;
+type MergedCursor = Partial<Record<MarketSource, string>>;
+export declare function encodeCursor(cursor: MergedCursor): string | null;
+export declare function decodeCursor(raw: string | null | undefined): MergedCursor | undefined;
+/**
+ * Stamp a market item with its local install state.
+ *
+ * Computed on every request (never cached): a skill installed a second ago must
+ * show up as installed on the next list call. The reference version also probed
+ * the skills directory for a name conflict; that check needs a filesystem, so it
+ * now belongs to the install path, which refuses to overwrite a directory it did
+ * not create.
+ */
+export declare function annotateInstallState<T extends NormalizedSkill>(skill: T): T;
+/** File-level installability checks — only possible once the file list is known. */
+export declare function applyFileLimits(detail: NormalizedSkillDetail): NormalizedSkillDetail;
+/**
+ * SkillHub mirrors ClawHub skills (source='clawhub' + upstream_url). When a
+ * page contains both the mirror and the ClawHub original, merge them: the
+ * ClawHub entry wins (fresher data), enriched with SkillHub-only fields.
+ *
+ * Unlike the reference this does not mutate its input: those items come from
+ * the shared response cache, and mutating them made `mirrors` grow on every
+ * repeat request.
+ */
+export declare function dedupeSkills(items: NormalizedSkill[]): NormalizedSkill[];
+export interface ListMarketSkillsParams {
+    q?: string;
+    source: 'all' | MarketSource;
+    security: 'all' | SecurityStatus;
+    installed: 'all' | 'installed' | 'installable';
+    cursor?: string;
+    limit: number;
+}
+export declare function listMarketSkills(params: ListMarketSkillsParams): Promise<MarketListResult>;
+export declare function getMarketSkillDetail(source: MarketSource, slug: 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 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>;
+export {};

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

@@ -0,0 +1,61 @@
+/**
+ * Skills Market — shared upstream fetch helper.
+ *
+ * Every upstream request goes through `providerFetch` so timeouts, retries,
+ * redirect following (SkillHub file downloads 302 to COS) and per-source health
+ * bookkeeping stay in one place.
+ *
+ * Base URLs, timeout and retry budget are injected with `configureProviderFetch`
+ * — the plugin passes its resolved Config in `apply()`. Nothing is read from
+ * `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 { MarketUpstreamError, type MarketSource } from './types.ts';
+export interface ProviderEndpointConfig {
+    clawhubBaseUrl: string;
+    skillhubBaseUrl: string;
+    timeoutMs: number;
+    retries: number;
+    userAgent: string;
+}
+/**
+ * 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.
+ * Unspecified fields keep their current value, so a partial override can never
+ * silently blank the other source.
+ */
+export declare function configureProviderFetch(config: Partial<ProviderEndpointConfig>): void;
+/** Base URL of one upstream, as resolved from the active configuration. */
+export declare function getProviderBase(source: MarketSource): string;
+/**
+ * An upstream answered with a non-2xx status (or a retryable 429/5xx).
+ *
+ * Extends `MarketUpstreamError` so the existing `instanceof MarketUpstreamError`
+ * handling (and its `code`) keeps working, and adds the HTTP `status` so the
+ * route layer can tell "skill not found" apart from "upstream is broken".
+ */
+export declare class MarketHttpError extends MarketUpstreamError {
+    readonly status: number;
+    constructor(source: MarketSource, status: number, code: string, message: string);
+}
+/**
+ * Fetch an upstream URL with timeout and retries.
+ *
+ * `retries` is the number of *extra* attempts (the contract's default of 1 means
+ * two attempts), matching the reference server. A 429 or 5xx counts as a failed
+ * attempt; every other status — including 404 — is returned to the caller so the
+ * provider can map it to a meaningful error.
+ */
+export declare function providerFetch(source: MarketSource, url: string, init?: RequestInit): Promise<Response>;
+/** `providerFetch` plus JSON decoding and non-2xx/parse-failure classification. */
+export declare function providerFetchJson<T>(source: MarketSource, url: string, init?: RequestInit): Promise<T>;
+/**
+ * Read a response body as text, aborting as soon as it exceeds `maxBytes`.
+ *
+ * `content-length` is only a hint (redirects and chunked responses omit it), so
+ * the body is streamed and counted rather than trusted.
+ */
+export declare function readResponseTextWithLimit(source: MarketSource, response: Response, maxBytes: number, label: string): Promise<{
+    content: string;
+    size: number;
+}>;

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

@@ -0,0 +1,13 @@
+/**
+ * SkillHub provider (https://api.skillhub.cn)
+ *
+ * Endpoints (verified against the live API):
+ *  - GET /api/skills?page=&pageSize=&keyword=      → {code, data:{skills[], total}, message}
+ *      NOTE: pagination param MUST be `pageSize` (a `limit` param is silently ignored)
+ *      NOTE: search param MUST be `keyword` (a `q` param is silently ignored)
+ *  - GET /api/v1/skills/{slug}                     → {skill, owner, latestVersion, securityReports}
+ *  - GET /api/v1/skills/{slug}/files               → {count, files:[{path, sha256, size}]}
+ *  - GET /api/v1/skills/{slug}/file?path=          → 302 redirect to Tencent COS (follow)
+ */
+import { type MarketProvider } from './types.ts';
+export declare const skillhubProvider: MarketProvider;