@nanmicoder/dsh-skills-hub 0.0.1

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

@@ -0,0 +1,163 @@
+/**
+ * Skills Market — shared types for the market aggregation layer.
+ *
+ * Upstream sources:
+ *  - ClawHub  (https://clawhub.ai)      — cursor pagination, no security audits
+ *  - SkillHub (https://api.skillhub.cn) — page/pageSize pagination, security reports
+ */
+export type MarketSource = 'clawhub' | 'skillhub';
+export declare const MARKET_SOURCES: MarketSource[];
+export type SecurityStatus = 'verified' | 'benign' | 'unknown' | 'flagged';
+export type InstallState = 'installed' | 'installable' | 'not-installable';
+export type SourceHealthStatus = 'ok' | 'degraded' | 'failed' | 'cached';
+export type NotInstallableReason = 'empty-file-list' | 'file-too-large' | 'too-many-files' | 'invalid-name' | 'name-conflict' | 'source-unavailable';
+export type SecurityReport = {
+    vendor: string;
+    status: string;
+    statusText: string;
+    reportUrl?: string;
+};
+export type NormalizedSkill = {
+    /** `${source}:${slug}` — globally unique */
+    id: string;
+    source: MarketSource;
+    slug: string;
+    name: string;
+    summary: string;
+    author: {
+        handle: string;
+        displayName?: string;
+        avatarUrl?: string;
+    };
+    stats: {
+        downloads: number;
+        installs?: number;
+        stars?: number;
+    };
+    tags: string[];
+    category?: string;
+    version?: string;
+    updatedAt?: number;
+    iconUrl?: string;
+    securityStatus: SecurityStatus;
+    securityReports?: SecurityReport[];
+    requiresApiKey?: boolean;
+    verified?: boolean;
+    /** Set on SkillHub entries that mirror a ClawHub skill */
+    upstream?: {
+        source: MarketSource;
+        slug: string;
+    };
+    /** After dedupe: ids of merged duplicate entries from other sources */
+    mirrors?: string[];
+    installState: InstallState;
+    notInstallableReason?: NotInstallableReason;
+    installedInfo?: {
+        version?: string;
+        installedAt?: string;
+        dirName: string;
+    };
+};
+export type MarketFileMeta = {
+    path: string;
+    size: number;
+    sha256?: string;
+    contentType?: string;
+    language: string;
+    /** File exceeds the preview/install size limit */
+    tooBig: boolean;
+};
+export type NormalizedSkillDetail = NormalizedSkill & {
+    /** Full SKILL.md body (markdown, frontmatter stripped) */
+    description: string;
+    /** Raw frontmatter parsed from SKILL.md description, when present */
+    descriptionFrontmatter?: Record<string, unknown>;
+    license?: string;
+    files: MarketFileMeta[];
+    totalSize: number;
+};
+export type MarketFileContent = {
+    path: string;
+    content: string;
+    language: string;
+    size: number;
+    truncated: boolean;
+};
+export type SourceStatusInfo = {
+    status: SourceHealthStatus;
+    fetchedAt?: number;
+    fromCache?: boolean;
+    error?: string;
+};
+export type MarketListResult = {
+    items: NormalizedSkill[];
+    nextCursor: string | null;
+    sources: Record<MarketSource, SourceStatusInfo>;
+};
+export type ProviderListPage = {
+    items: NormalizedSkill[];
+    /** Provider-native cursor for the next page; undefined = exhausted */
+    nextCursor?: string;
+    total?: number;
+};
+export type ProviderFileEntry = {
+    path: string;
+    size: number;
+    sha256?: string;
+    contentType?: string;
+};
+export interface MarketProvider {
+    readonly source: MarketSource;
+    list(params: {
+        cursor?: string;
+        limit: number;
+    }): Promise<ProviderListPage>;
+    search(params: {
+        q: string;
+        cursor?: string;
+        limit: number;
+    }): Promise<ProviderListPage>;
+    detail(slug: string): Promise<NormalizedSkillDetail>;
+    listFiles(slug: string, version?: string): Promise<ProviderFileEntry[]>;
+    fetchFile(slug: string, filePath: string): Promise<{
+        content: string;
+        size: number;
+    }>;
+}
+export declare const MARKET_ERROR_CODES: {
+    readonly upstreamError: "MARKET_UPSTREAM_ERROR";
+    readonly upstreamTimeout: "MARKET_UPSTREAM_TIMEOUT";
+    readonly upstreamBadResponse: "MARKET_UPSTREAM_BAD_RESPONSE";
+    readonly installInProgress: "MARKET_INSTALL_IN_PROGRESS";
+    readonly alreadyInstalled: "MARKET_ALREADY_INSTALLED";
+    readonly notInstallable: "MARKET_NOT_INSTALLABLE";
+    readonly checksumMismatch: "MARKET_CHECKSUM_MISMATCH";
+    readonly diskError: "MARKET_DISK_ERROR";
+    readonly notInstalled: "MARKET_NOT_INSTALLED";
+    readonly notManaged: "MARKET_NOT_MANAGED";
+};
+export declare class MarketUpstreamError extends Error {
+    source: MarketSource;
+    code: string;
+    constructor(source: MarketSource, code: string, message: string);
+}
+export declare const MARKET_LIMITS: {
+    /** Max bytes for a single skill file (install + preview) */
+    readonly maxFileSize: number;
+    /** Max total bytes for an installable skill */
+    readonly maxTotalSize: number;
+    /** Max file count for an installable skill */
+    readonly maxFileCount: 200;
+    /** File preview content is truncated beyond this many bytes */
+    readonly previewTruncateBytes: number;
+    /** ClawHub search has no pagination — cap merged search results */
+    readonly searchResultCap: 50;
+};
+export declare function skillId(source: MarketSource, slug: string): string;
+export declare function parseSkillId(id: string): {
+    source: MarketSource;
+    slug: string;
+} | null;
+/** Directory-name whitelist: lowercase alnum, dash, underscore, dot (no leading dot). */
+export declare function sanitizeDirName(slug: string): string | null;
+export declare function detectMarketLanguage(filename: string): string;

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

@@ -0,0 +1,117 @@
+/**
+ * Installed-skill index.
+ *
+ * This module is the filesystem truth behind two things the market layer cannot
+ * know by itself:
+ *
+ *  - `InstalledLookup` — which market ids (`source:slug`) are already present
+ *    locally, so the list/detail responses can report `installState` and the
+ *    installer can refuse to clobber a directory it does not own.
+ *  - `GET /api/skills-hub/installed` — the panel's "installed" filter, including
+ *    skills the user dropped into the skills directory by hand.
+ *
+ * A directory is *managed* when it carries the provenance sidecar
+ * ({@link INSTALL_META_FILE}) written by the installer. Nothing else in the tree
+ * is overwritten by the market installer; local entries can be explicitly
+ * removed through the installed-management endpoint after user confirmation.
+ */
+import type { InstalledLookup } from '../market/market-service.ts';
+import { type MarketSource } from '../market/types.ts';
+/** Provenance sidecar written next to `SKILL.md` by the installer. */
+export declare const INSTALL_META_FILE = ".skills-hub.json";
+/**
+ * Parsed {@link INSTALL_META_FILE} content.
+ *
+ * `files` is the ledger of the installed bytes (path + SHA-256) used for
+ * integrity reporting; removal decisions are made from the identity fields
+ * only, so a sidecar with a damaged ledger still proves ownership.
+ */
+export interface InstalledMetaFile {
+    id: string;
+    source: MarketSource;
+    slug: string;
+    version?: string;
+    installedAt: string;
+    files: Array<{
+        path: string;
+        sha256: string;
+    }>;
+}
+export interface InstalledSkillRecord {
+    /** Opaque identity of this exact filesystem entry (duplicates remain addressable). */
+    key: string;
+    /** Symlink removal only unlinks this entry, never its target. */
+    linked: boolean;
+    removable: boolean;
+    /** `source:slug` when the sidecar provenance file exists, else `local:<dir>` */
+    id: string;
+    source: MarketSource | 'local';
+    slug: string;
+    name: string;
+    dirName: string;
+    /**
+     * Absolute path of the skill entry: its directory for a directory bundle,
+     * the Markdown file itself for a flat `<name>.md` skill (both layouts are
+     * discovered by the DSH filesystem skill provider).
+     */
+    dirPath: string;
+    version?: string;
+    summary?: string;
+    installedAt?: string;
+    /** installed by this plugin (sidecar `.skills-hub.json` present) */
+    managed: boolean;
+    bytes: number;
+    fileCount: number;
+}
+/**
+ * Validate and normalize a sidecar payload.
+ *
+ * The identity fields are checked against each other (`id` must be
+ * `skillId(source, slug)`) because a sidecar that disagrees with itself cannot
+ * authorize a delete: the reference implementation's "not managed" branch
+ * exists for exactly this class of tampering, and the same check is reused on
+ * the uninstall path.
+ *
+ * @param value - parsed JSON of unknown shape.
+ * @returns the normalized sidecar, or `null` when it does not prove ownership.
+ */
+export declare function parseInstalledMeta(value: unknown): InstalledMetaFile | null;
+/**
+ * Scan every root for installed skills, most specific root first.
+ *
+ * Each filesystem entry remains individually addressable for management; the
+ * market lookup separately gives earlier roots precedence. Dot-prefixed entries are skipped — DSH's own
+ * filesystem provider skips `.system` in the user-dsh root, and the installer's
+ * staging/trash directories are dot-prefixed so no scanner ever sees a
+ * half-published skill.
+ *
+ * @param roots - absolute skill roots, most specific first (see `resolveSkillsScanRoots`).
+ * @returns one record per filesystem entry, in scan order.
+ */
+export declare function scanInstalledSkills(roots: string[]): Promise<InstalledSkillRecord[]>;
+/**
+ * Read just the display identity of a skill file.
+ *
+ * Used by the uninstall path, which must describe a skill after its directory is
+ * gone: the frontmatter has to be captured while the file still exists, and it
+ * must not fail the removal when it cannot be read.
+ *
+ * @param skillFile - absolute path of a `SKILL.md`.
+ * @returns `name`/`summary` as far as they could be read, or `undefined`.
+ */
+export declare function readSkillHeadline(skillFile: string): Promise<{
+    name?: string;
+    summary?: string;
+} | undefined>;
+/**
+ * Project scanned records into the market layer's installed-id seam.
+ *
+ * The lookup is a pure function of the records so the caller can rebuild it
+ * after an install/uninstall without any shared mutable state.
+ *
+ * @param records - output of {@link scanInstalledSkills}.
+ * @returns the lookup W1's `setInstalledLookup()` expects.
+ */
+export declare function installedLookupFrom(records: InstalledSkillRecord[]): InstalledLookup;
+/** Path-derived identifiers never expose a caller-controlled filesystem path. */
+export declare function installedEntryKey(entryPath: string): string;

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

@@ -0,0 +1,7 @@
+import { type InstalledSkillRecord } from './installed.ts';
+export declare function readInstalledSkill(roots: string[], key: string): Promise<{
+    item: InstalledSkillRecord;
+    markdown: string;
+}>;
+/** 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/read-text.d.ts

@@ -0,0 +1,5 @@
+/** Read at most limit + 1 bytes; reject special files and detect growth without an unbounded allocation. */
+export declare function readBoundedText(filePath: string, limit: number): Promise<{
+    text: string;
+    truncated: boolean;
+}>;

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

@@ -0,0 +1,48 @@
+/**
+ * Skills-directory resolution.
+ *
+ * Two different questions are answered here, and they must not be conflated:
+ *
+ *  - {@link resolveSkillsRoot} — *where do we install?* Exactly one directory:
+ *    the configured override, or the user skills directory of the harness home.
+ *  - {@link resolveSkillsScanRoots} — *what does "already installed" mean?*
+ *    Every directory the local filesystem skill provider scans for user-level
+ *    skills, most specific first, so a skill that is already present anywhere in
+ *    the DSH user skill roots is reported as installed instead of being
+ *    downloaded and clobbered.
+ *
+ * `$DSH_HOME` is resolved here instead of through `@deepseek-ai/dsh-home-paths`
+ * on purpose: that package is a dev-only dependency of this plugin (it is not in
+ * `peerDependencies`), so a runtime value import would make the published plugin
+ * fail to load in a profile where it is not hoisted. The resolution rules below
+ * are the documented ones from
+ * `@deepseek-ai/dsh-home-paths/lib/types/index.d.ts` (0.1.7-rc.2):
+ * explicit path → `DSH_HOME` (blank treated as unset) → `~/.dsh`, plus the
+ * `~`, `~/`, `~\` tilde expansion of `expandHomePath`.
+ */
+/**
+ * Absolute skills directory skills are installed into, created on demand.
+ *
+ * A relative configured path is resolved against the host process's working
+ * directory: a skills root must be absolute before any containment check can
+ * mean anything, and refusing relative input outright would break the common
+ * `./tmp-skills` test setup.
+ *
+ * @param configured - `Config.skillsRoot`; `null`/blank selects the DSH user skills directory.
+ * @returns the absolute, existing skills directory.
+ */
+export declare function resolveSkillsRoot(configured: string | null): Promise<string>;
+/**
+ * Every directory DSH will scan for skills, most specific first (installed lookup).
+ *
+ * Order is the install root, then the two user roots the local filesystem skill
+ * provider mounts by default (`$DSH_HOME/skills` with `user-dsh` rank, then
+ * `$DSH_AGENTS_HOME/skills` with `user-agents` rank — see
+ * `@deepseek-ai/dsh-skill-filesystem/lib/index.js#roots`). Project roots
+ * (`.dsh/skills`, `.agents/skills` under a session's cwd) are deliberately
+ * absent: this plugin runs at host scope, has no session, and must not claim
+ * that a skill in whichever directory the server happened to start in is
+ * "installed" for every session. Duplicates (a configured root that *is* the
+ * harness home) collapse to their first, most specific occurrence.
+ */
+export declare function resolveSkillsScanRoots(configured: string | null): Promise<string[]>;

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

@@ -0,0 +1,74 @@
+/**
+ * Skills Hub HTTP surface.
+ *
+ * One `prefix` route (`/api/skills-hub`) owns the seven endpoints the panel
+ * needs; every response is JSON with `Cache-Control: no-store`, because the
+ * panel polls and every payload is either live upstream data or live disk state.
+ *
+ * Two properties matter more than the routing itself:
+ *
+ *  - **Nothing escapes as a non-JSON error.** The handler catches its own
+ *    rejections, the web server's own catch-all would answer a thrown handler
+ *    with a bare `400` and no body, and the browser client parses the
+ *    `{ error: { code, message } }` envelope.
+ *  - **The browser-trust gate runs first.** Raw `webServer` routes do not inherit
+ *    the Connection service's Host/Origin fence, so a route registered here would
+ *    otherwise be reachable by a cross-site request or a DNS-rebound page.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+/** Path prefix of the whole Skills Hub API. */
+export declare const ROUTE_PREFIX = "/api/skills-hub";
+/** Structural Web server contract (mirrors `WebServer.register`). */
+export interface WebServerLike {
+    register(route: {
+        kind: 'exact' | 'prefix';
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+    }): () => void;
+}
+export interface SkillsHubRoutesDeps {
+    skillsRoot: () => Promise<string>;
+    allowUninstall: () => boolean;
+    rescan: () => Promise<void>;
+}
+/**
+ * Browser-trust gate, structurally equal to the frozen contract's predicate.
+ *
+ * The real `HostConnectionService.requestRejection` returns `401 | 403 |
+ * undefined` rather than a boolean (see
+ * `@deepseek-ai/dsh-client-connection/lib/types/rpc.d.ts`), so this plugin
+ * accepts both shapes: see {@link evaluateGate} for why the numeric form is
+ * worth preserving.
+ */
+export interface SkillsHubRequestGate {
+    requestRejection(req: IncomingMessage, res: ServerResponse): boolean;
+}
+/**
+ * Resolves the gate for one request.
+ *
+ * A getter, not the service itself: Loader rows activate concurrently, so the
+ * Connection service frequently appears *after* this plugin registered its
+ * route. Snapshotting it at registration time silently produced an unfenced
+ * marketplace (verified against a real host: official `/api/*` routes answered
+ * `403` to an untrusted `Origin` while `/api/skills-hub/*` answered `200`).
+ */
+export type SkillsHubGateSource = () => SkillsHubRequestGate | undefined;
+/**
+ * Set the default `/skills` page size from `Config.pageSize`.
+ *
+ * The frozen `SkillsHubRoutesDeps` has no config seat, and widening it would
+ * change a frozen interface; this setter is the additive seam instead.
+ */
+export declare function setSkillsHubPageSize(pageSize: number): void;
+/**
+ * Register the Skills Hub prefix route.
+ *
+ * @param webServer - the `webServer`/`httpServer` service (`ctx.get` guarded by the caller).
+ * @param gate - resolves the browser-trust gate (`ctx.get('connection')`) *per
+ *   request*; `undefined` means the composition has no Connection fence to
+ *   consult. It is a function rather than a snapshot because the Connection row
+ *   may activate after this route is registered.
+ * @param deps - resolved skills root, the uninstall switch, and the index refresh.
+ * @returns the route disposer (yield it from `ctx.effect`).
+ */
+export declare function registerSkillsHubRoutes(webServer: WebServerLike, gate: SkillsHubGateSource, deps: SkillsHubRoutesDeps): () => void;