@xrxs-ai/dsh-xrxs-skillhub 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xrxs-ai contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,44 @@
+# @xrxs-ai/dsh-xrxs-skillhub
+
+> 中文文档:[README.md](README.md)
+
+A DeepSeek Harness (Cordis) plugin for the private SkillHub registry: search, view, install, and manage your organization's agent skills inside DSH.
+
+- **Registry**: defaults to `https://skillhub.xinrenxinshi.com` (editable on the settings page).
+- **Auth**: the console-issued **API Token** (`sk_...`) — the same credential the official CLI uses. Anonymous callers only see PUBLIC skills.
+- **Install target**: the DSH user-level skill scan root `~/.dsh/skills` by default, which hot-loads without a restart.
+
+## Features
+
+- **Model tools**: `skillhub_search` / `skillhub_view` / `skillhub_install` / `skillhub_installed` / `skillhub_remove`, with stable names across restarts.
+- **Settings page + marketplace**: the built-in same-origin `/skillhub` page offers marketplace search (keyword / namespace / sort / pagination), skill detail (versions + file manifest + SKILL.md preview), one-click install, and an installed-list with uninstall.
+- **Sidebar entry**: the browser half injects a "SkillHub" footer button (with a status dot) into the left sidebar; hosts without the slot system fall back to a better-sidebar tab.
+- **Token precedence**: page-pasted token > loader patch config > anonymous. The plugin persists the token itself (`~/.xrxs/dsh-xrxs-skillhub/settings.json`, 0600, atomic); the page only ever sees a `hasToken` boolean.
+- **Safe install flow**: resolve version → size-capped zip download → pure-JS fflate extraction (traversal/absolute-path/size guards, wrapper-dir stripping) → SKILL.md validation → backup + rename swap with rollback. Only plugin-owned directories are ever touched; the `.skillhub/metadata.json` marker matches the official CLI.
+- **Zero startup side effects**: nothing dials the network during load; mounting failures degrade to log lines and can never take the profile down.
+
+## Usage
+
+Loaded as an npm bundle row (the shipped patch pre-configures the default registry):
+
+```yaml
+- id: skillhub
+  name: '@xrxs-ai/dsh-xrxs-skillhub'
+  config:
+    registry: 'https://skillhub.xinrenxinshi.com'
+    # token: !!js process.env.SKILLHUB_API_TOKEN
+    # installDir: /absolute/path
+```
+
+**Recommended: configure from the page.** Open `<local-web-url>/skillhub` (or the sidebar button), paste your API token, and hit "Test connection". Page settings override the patch config and hot-apply immediately.
+
+## Development
+
+```sh
+pnpm install
+pnpm run typecheck
+pnpm run test
+pnpm run build        # host half → lib/
+pnpm run build:client # browser half → lib/client.js
+pnpm pack             # builds both halves into the installable .tgz
+```

package/README.md

@@ -0,0 +1,73 @@
+# @xrxs-ai/dsh-xrxs-skillhub
+
+> English documentation: [README.en.md](README.en.md)
+
+连接**私有 SkillHub 技能仓库**的 DeepSeek Harness(Cordis)插件:在 DSH 内搜索、查看、下载、管理组织的 Agent 技能。
+
+- **仓库地址**:默认指向 `https://skillhub.xinrenxinshi.com`(可在设置页修改)
+- **鉴权**:控制台签发的 **API Token**(`sk_...`),与官方 CLI `skillhub login --token` 同一把;匿名只能看公开技能
+- **安装目标**:默认装到 DSH 用户级 skill 扫描根 `~/.dsh/skills`,**免重启热生效**
+
+## 特性
+
+- **模型工具**:注册 `skillhub_search` / `skillhub_view` / `skillhub_install` / `skillhub_installed` / `skillhub_remove` 五个稳定命名的工具,agent 可直接对话式搜索/查看/安装技能。
+- **设置页 + 技能市场**:内置 `/skillhub` 同源页面——市场搜索(关键词/命名空间/排序/分页)、技能详情(版本列表 + 文件清单 + SKILL.md 在线预览)、一键安装、已安装列表与卸载。
+- **侧栏入口**:浏览器半在左下侧栏 footer 注入「SkillHub」按钮(带状态点),点开浮动面板内嵌同源页面;不支持插槽系统的旧宿主回退到 better-sidebar 页签。
+- **Token 三级来源**:设置页粘贴 > 加载器 patch 配置 > 匿名。Token 由插件自己持久化(`~/.xrxs/dsh-xrxs-skillhub/settings.json`,0600,原子写),页面只回显「是否已配置」,永不回显明文。
+- **安全安装流程**:resolve 版本 → 64MB 上限下载 zip → fflate 纯 JS 解压(拒绝路径穿越/绝对路径/超限,自动剥包装目录)→ 校验 SKILL.md → 备份 + rename 原子替换(失败回滚)。只动自己名下的目录,与官方 CLI 同名安装记录(`.skillhub/metadata.json`)。
+- **启动零副作用**:加载阶段不访问网络、不弹窗;工具或页面挂载失败只降级记日志,绝不拖垮 profile。
+
+## 使用
+
+npm 包形式随 profile 组合加载(bundle patch 已预置默认行,装上即生效):
+
+```yaml
+- id: skillhub
+  name: '@xrxs-ai/dsh-xrxs-skillhub'
+  config:
+    registry: 'https://skillhub.xinrenxinshi.com'   # 默认私有仓库
+    # token: !!js process.env.SKILLHUB_API_TOKEN    # 可选:patch 注入(页面配置优先)
+    # installDir: /absolute/path                    # 可选:默认 ~/.dsh/skills
+    # requestTimeoutMs: 30000
+```
+
+**推荐:从设置页配置。** 打开 `<local-web-url>/skillhub`(或点侧栏「SkillHub」按钮),粘贴 API Token,点「测试连接」即可;页面保存的配置覆盖 patch 配置,保存即时生效。
+
+> 页面保存的设置存于 `~/.xrxs/dsh-xrxs-skillhub/settings.json`;「恢复默认」删除该文件回到 patch 配置。要覆盖 patch 行本身,请在 profile 自己的 `cordis.patch.yml` 中 override 行 id `skillhub`(override 会整体替换 `config`,需重述全部字段)。
+
+## API Token 从哪来
+
+SkillHub 控制台 → **API Tokens** → 生成 `sk_...`。这把 token 同时用于:
+
+- 官方 CLI:`skillhub login --token sk_...`
+- 本插件:设置页粘贴(推荐)
+
+插件不会读取或改写 CLI 的凭证文件(`~/.skillhub/credentials.json`)——两者独立,用同一把 token 即可。
+
+## 开发
+
+```sh
+pnpm install
+pnpm run typecheck        # tsc --noEmit(strict)
+pnpm run test             # node --test tests/*.test.ts(Node 直接跑 .ts)
+pnpm run build            # host 半:lib/(ESM + d.ts)
+pnpm run build:client     # browser 半:tsconfig.client.json + scripts/build-client.mjs
+pnpm pack                 # prepack 构建双半,产出可安装 .tgz
+```
+
+### 架构
+
+- **Host 半(`src/`)**:`index.ts` 组装 controller(设置/测试/搜索/详情/安装/卸载)+ 模型工具 + web 页;`api-client.ts` 封装 REST(`/api/web/skills` 搜索、`/api/v1/skills/...` 详情/版本/文件/下载、`/api/v1/whoami` 校验);`installer.ts` 负责安装状态与原子替换;`zip.ts` 安全解压;`settings.ts` 页面设置(0600 原子写)。
+- **Browser 半(`src/client/`)**:`sidebar.footer.action` 插槽按钮 + 主题跟随的 iframe 浮动面板。单独编译为 CommonJS 后由 `scripts/build-client.mjs` 包成 DSH client module-loader bundle(`lib/client.js`);**client bundle 纯净性**——运行时只允许 `require('react')`。
+- **打包**:`dsh.bundle.patch` → `cordis.patch.yml`,`dsh.client` 声明 browser face。
+
+### TypeScript 约定
+
+`tsconfig.json` 全 strict(`exactOptionalPropertyTypes`、`noUncheckedIndexedAccess`、`erasableSyntaxOnly`、`verbatimModuleSyntax`);相对导入带 `.ts` 扩展名(emit 时改写为 `.js`),测试直接 import `../src/*.ts` 依赖 Node 类型剥离(需要 `engines` 声明的 Node 版本)。
+
+### 不变量
+
+- Token 不进日志;设置文件 0600 + 原子写;页面只见 `hasToken` 布尔值。
+- 启动绝不访问网络;任何挂载失败只降级,绝不拖垮桌面。
+- 安装只触碰状态文件(`~/.xrxs/dsh-xrxs-skillhub/installed.json`)登记过的目录;手工放置的同名目录是冲突报错,绝不覆盖;替换走 temp → validate → rename 带回滚,绝不在原位解压。
+- 工具命名 `skillhub_*` 跨重启稳定。

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# dsh-xrxs-skillhub bundle patch: insert the SkillHub connector into the profile.
+#
+# The row ships ENABLED and pre-configured with the private SkillHub registry.
+# The plugin loads, registers its model tools and the `/skillhub` settings
+# page, and works anonymously against PUBLIC skills until the user pastes an
+# API token on the page (page-saved settings override this config and are
+# hot-applied without a restart).
+#
+# Prefer editing files instead? Override row id `skillhub` from the profile's
+# own `cordis.patch.yml` (applied after every bundle layer) — a config
+# override replaces this row's whole `config`, so restate everything.
+- insert:
+    - id: skillhub
+      name: '@xrxs-ai/dsh-xrxs-skillhub'
+      disabled: false
+      config:
+        registry: 'https://skillhub.xinrenxinshi.com'

package/lib/api-client.d.ts

@@ -0,0 +1,217 @@
+/**
+ * SkillHub REST API client for the private registry.
+ *
+ * Endpoints (all relative to the registry base URL):
+ *   GET /api/v1/whoami                                  — token check (401 when anonymous)
+ *   GET /api/web/skills?q=&namespace=&sort=&page=&size= — search (enveloped, paged)
+ *   GET /api/v1/skills/{ns}/{slug}                      — skill detail
+ *   GET /api/v1/skills/{ns}/{slug}/versions             — version list
+ *   GET /api/v1/skills/{ns}/{slug}/versions/{v}/files   — file manifest
+ *   GET /api/v1/skills/{ns}/{slug}/versions/{v}/file?path= — raw file content
+ *   GET /api/v1/skills/{ns}/{slug}/resolve?version=     — version resolution
+ *   GET /api/v1/skills/{ns}/{slug}/versions/{v}/download — zip package (binary)
+ *
+ * The token is the console-issued API token (`sk_...`); the CLI uses the
+ * same credential. Anonymous callers only see PUBLIC skills.
+ *
+ * @module
+ */
+/** One skill as returned by the search endpoint. */
+export interface SearchItem {
+    /** Web shape: the namespace slug as its own field. */
+    namespace?: string;
+    slug: string;
+    displayName?: string;
+    summary?: string;
+    /** Web shape (`/api/web/skills`): flat counters. */
+    downloadCount?: number;
+    starCount?: number;
+    /** Web shape: lifecycle projections carry the versions. */
+    publishedVersion?: {
+        version?: string;
+    } | null;
+    headlineVersion?: {
+        version?: string;
+    } | null;
+    /** ClawHub compat shape (`/api/v1/skills`): nested stats + latestVersion. */
+    stats?: {
+        downloads?: number;
+        stars?: number;
+    };
+    updatedAt?: number;
+    latestVersion?: {
+        version?: string;
+        createdAt?: number;
+        changelog?: string | null;
+    };
+}
+/** Download count across both search response shapes. */
+export declare function downloadsOf(item: SearchItem): number;
+/** Latest published version string across both search response shapes. */
+export declare function versionOf(item: SearchItem): string;
+/** The namespace slug across both shapes (compat items carry a composite slug). */
+export declare function namespaceOf(item: SearchItem): string;
+/** One namespace entry (list + me/namespaces endpoints). */
+export interface NamespaceInfo {
+    slug?: string;
+    displayName?: string;
+    description?: string;
+    type?: string;
+    currentUserRole?: string;
+    [key: string]: unknown;
+}
+/** Search result page. */
+export interface SearchPage {
+    items: SearchItem[];
+    total: number;
+    page: number;
+    size: number;
+}
+/** Skill detail (envelope `data`). */
+export interface SkillDetail {
+    id?: number;
+    namespace?: string;
+    slug?: string;
+    displayName?: string;
+    ownerDisplayName?: string;
+    summary?: string;
+    visibility?: string;
+    latestVersion?: {
+        version?: string;
+    } | null;
+    [key: string]: unknown;
+}
+/** One version entry from the version list. */
+export interface SkillVersion {
+    version: string;
+    status?: string;
+    changelog?: string | null;
+    fileCount?: number;
+    totalSize?: number;
+    publishedAt?: string;
+    downloadAvailable?: boolean;
+}
+/** One file entry from the manifest. */
+export interface SkillFileInfo {
+    filePath: string;
+    fileSize?: number;
+    contentType?: string;
+    sha256?: string;
+}
+/** Resolve response (`data`). */
+export interface ResolveData {
+    namespace?: string;
+    slug?: string;
+    version?: string;
+    versionId?: number;
+    fingerprint?: string;
+    downloadUrl?: string;
+}
+/** Whoami response, flattened from the compat `{user: {handle, ...}}` shape. */
+export interface WhoAmI {
+    handle?: string;
+    displayName?: string;
+    image?: string;
+    email?: string;
+    [key: string]: unknown;
+}
+/** Registry unreachable, or the API returned a structured error envelope. */
+export declare class SkillHubApiError extends Error {
+    /** HTTP status, when the failure was an HTTP-level one. */
+    readonly status: number;
+    /** Structured envelope `code`, when present (equals the HTTP status). */
+    readonly code: number;
+    constructor(message: string, status?: number, code?: number, options?: {
+        cause?: unknown;
+    });
+}
+/** Download cap: a bigger package is rejected before it fills the disk. */
+export declare const MAX_DOWNLOAD_BYTES: number;
+/** Read-back cap for file contents (page preview + model tools). */
+export declare const MAX_FILE_BYTES: number;
+/** Search parameters shared by the client, controller, and tool bridge. */
+export interface SearchOptions {
+    q?: string | undefined;
+    namespace?: string | undefined;
+    sort?: string | undefined;
+    page?: number | undefined;
+    size?: number | undefined;
+}
+/** View parameters shared by the controller and the tool bridge. */
+export interface ViewOptions {
+    namespace: string;
+    slug: string;
+    version?: string | undefined;
+    path?: string | undefined;
+}
+/** Install parameters shared by the controller and the tool bridge. */
+export interface InstallOptions {
+    namespace: string;
+    slug: string;
+    version?: string | undefined;
+}
+export interface ApiClientOptions {
+    registry: string;
+    token?: string;
+    requestTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+/** Normalized API client for one registry. */
+export declare class SkillHubApiClient {
+    readonly registry: string;
+    private readonly token;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: ApiClientOptions);
+    /**
+     * Verify the configured token (or probe anonymous access). A 401 means
+     * "not authenticated" — mapped to `undefined`, not an error, so callers
+     * can distinguish "no token" from "broken registry". The compat endpoint
+     * nests the user object; the result is flattened.
+     */
+    whoami(): Promise<WhoAmI | undefined>;
+    /** Visible namespaces (market filter); anonymous callers see public ones. */
+    namespaces(limit?: number): Promise<NamespaceInfo[]>;
+    /** The authenticated user's namespaces (publish target picker); requires a token. */
+    myNamespaces(): Promise<NamespaceInfo[]>;
+    /**
+     * Publish a packaged skill (zip with `SKILL.md` at its root) into a
+     * namespace. `confirmWarnings: true` acknowledges pre-check warnings —
+     * a 400 without it usually means the server wants explicit confirmation.
+     */
+    publish(options: {
+        namespace: string;
+        zip: Uint8Array;
+        visibility: 'PUBLIC' | 'NAMESPACE_ONLY' | 'PRIVATE';
+        confirmWarnings?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /** Full-text search with optional namespace filter, sort, and pagination. */
+    search(options?: SearchOptions): Promise<SearchPage>;
+    /** Skill detail. */
+    skill(namespace: string, slug: string): Promise<SkillDetail>;
+    /** Version list (newest first). */
+    versions(namespace: string, slug: string): Promise<SkillVersion[]>;
+    /** File manifest for one version. */
+    files(namespace: string, slug: string, version: string): Promise<SkillFileInfo[]>;
+    /** Raw file content for one version, capped at {@link MAX_FILE_BYTES}. */
+    file(namespace: string, slug: string, version: string, path: string): Promise<string>;
+    /** Resolve the effective version for a skill (latest published by default). */
+    resolve(namespace: string, slug: string, version?: string): Promise<ResolveData>;
+    /**
+     * Download the zip package for one version (latest published when
+     * `version` is omitted), size-capped at {@link MAX_DOWNLOAD_BYTES}.
+     */
+    download(namespace: string, slug: string, version?: string): Promise<Buffer>;
+    /** GET a JSON endpoint and unwrap the `{code, msg, data}` envelope. */
+    private getJson;
+    /** GET with auth header, timeout, and HTTP error mapping. */
+    private request;
+    /**
+     * Map a non-OK response to SkillHubApiError. Failure envelopes use the
+     * same `{code, msg}` structure with code = HTTP status; the server's
+     * message is surfaced when one is present (publish pre-check warnings
+     * arrive exactly this way).
+     */
+    private fail;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/lib/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/lib/api-client.js

@@ -0,0 +1,265 @@
+/**
+ * SkillHub REST API client for the private registry.
+ *
+ * Endpoints (all relative to the registry base URL):
+ *   GET /api/v1/whoami                                  — token check (401 when anonymous)
+ *   GET /api/web/skills?q=&namespace=&sort=&page=&size= — search (enveloped, paged)
+ *   GET /api/v1/skills/{ns}/{slug}                      — skill detail
+ *   GET /api/v1/skills/{ns}/{slug}/versions             — version list
+ *   GET /api/v1/skills/{ns}/{slug}/versions/{v}/files   — file manifest
+ *   GET /api/v1/skills/{ns}/{slug}/versions/{v}/file?path= — raw file content
+ *   GET /api/v1/skills/{ns}/{slug}/resolve?version=     — version resolution
+ *   GET /api/v1/skills/{ns}/{slug}/versions/{v}/download — zip package (binary)
+ *
+ * The token is the console-issued API token (`sk_...`); the CLI uses the
+ * same credential. Anonymous callers only see PUBLIC skills.
+ *
+ * @module
+ */
+/** Download count across both search response shapes. */
+export function downloadsOf(item) {
+    return item.downloadCount ?? item.stats?.downloads ?? 0;
+}
+/** Latest published version string across both search response shapes. */
+export function versionOf(item) {
+    return item.publishedVersion?.version ?? item.latestVersion?.version ?? item.headlineVersion?.version ?? '';
+}
+/** The namespace slug across both shapes (compat items carry a composite slug). */
+export function namespaceOf(item) {
+    if (item.namespace !== undefined && item.namespace !== '')
+        return item.namespace;
+    const index = item.slug.indexOf('--');
+    return index > 0 ? item.slug.slice(0, index) : '';
+}
+/** Registry unreachable, or the API returned a structured error envelope. */
+export class SkillHubApiError extends Error {
+    /** HTTP status, when the failure was an HTTP-level one. */
+    status;
+    /** Structured envelope `code`, when present (equals the HTTP status). */
+    code;
+    constructor(message, status = 0, code = 0, options) {
+        super(message, options);
+        this.name = 'SkillHubApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+/** Download cap: a bigger package is rejected before it fills the disk. */
+export const MAX_DOWNLOAD_BYTES = 64 * 1024 * 1024;
+/** Read-back cap for file contents (page preview + model tools). */
+export const MAX_FILE_BYTES = 512 * 1024;
+/** Normalized API client for one registry. */
+export class SkillHubApiClient {
+    registry;
+    token;
+    timeoutMs;
+    fetchImpl;
+    constructor(options) {
+        this.registry = options.registry.replace(/\/+$/, '');
+        let parsed;
+        try {
+            parsed = new URL(this.registry);
+        }
+        catch {
+            throw new SkillHubApiError(`invalid registry URL: ${options.registry}`);
+        }
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            throw new SkillHubApiError(`registry must use http or https: ${options.registry}`);
+        }
+        this.token = options.token ?? '';
+        this.timeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    /**
+     * Verify the configured token (or probe anonymous access). A 401 means
+     * "not authenticated" — mapped to `undefined`, not an error, so callers
+     * can distinguish "no token" from "broken registry". The compat endpoint
+     * nests the user object; the result is flattened.
+     */
+    async whoami() {
+        try {
+            const data = await this.getJson('/api/v1/whoami');
+            const record = typeof data === 'object' && data !== null ? data : {};
+            const user = typeof record.user === 'object' && record.user !== null ? record.user : record;
+            return user;
+        }
+        catch (error) {
+            if (error instanceof SkillHubApiError && (error.status === 401 || error.status === 403))
+                return undefined;
+            throw error;
+        }
+    }
+    /** Visible namespaces (market filter); anonymous callers see public ones. */
+    async namespaces(limit = 100) {
+        const data = await this.getJson(`/api/v1/namespaces?page=0&size=${Math.min(200, Math.max(1, limit))}`);
+        return Array.isArray(data?.items) ? data.items : [];
+    }
+    /** The authenticated user's namespaces (publish target picker); requires a token. */
+    async myNamespaces() {
+        const data = await this.getJson('/api/v1/me/namespaces');
+        return Array.isArray(data) ? data : [];
+    }
+    /**
+     * Publish a packaged skill (zip with `SKILL.md` at its root) into a
+     * namespace. `confirmWarnings: true` acknowledges pre-check warnings —
+     * a 400 without it usually means the server wants explicit confirmation.
+     */
+    async publish(options) {
+        const form = new FormData();
+        form.append('file', new Blob([options.zip], { type: 'application/zip' }), 'skill.zip');
+        form.append('visibility', options.visibility);
+        if (options.confirmWarnings === true)
+            form.append('confirmWarnings', 'true');
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.registry}/api/v1/skills/${encodeURIComponent(options.namespace)}/publish`, {
+                method: 'POST',
+                headers: this.token !== '' ? { authorization: `Bearer ${this.token}` } : {},
+                body: form,
+                redirect: 'follow',
+                signal: AbortSignal.timeout(Math.max(this.timeoutMs, 120_000)),
+            });
+        }
+        catch (error) {
+            throw new SkillHubApiError(`registry unreachable: ${this.registry}`, 0, 0, { cause: error });
+        }
+        if (!response.ok)
+            await this.fail(response);
+        const body = await response.json();
+        if (typeof body === 'object' && body !== null && 'code' in body) {
+            const envelope = body;
+            if (envelope.code !== 0) {
+                throw new SkillHubApiError(typeof envelope.msg === 'string' && envelope.msg !== '' ? envelope.msg : `API error ${String(envelope.code)}`, response.status, typeof envelope.code === 'number' ? envelope.code : 0);
+            }
+            return (envelope.data ?? {});
+        }
+        return (body ?? {});
+    }
+    /** Full-text search with optional namespace filter, sort, and pagination. */
+    async search(options = {}) {
+        const params = new URLSearchParams();
+        if (options.q !== undefined && options.q !== '')
+            params.set('q', options.q);
+        if (options.namespace !== undefined && options.namespace !== '')
+            params.set('namespace', options.namespace);
+        if (options.sort !== undefined && options.sort !== '')
+            params.set('sort', options.sort);
+        params.set('page', String(Math.max(0, options.page ?? 0)));
+        params.set('size', String(Math.min(50, Math.max(1, options.size ?? 20))));
+        const data = await this.getJson(`/api/web/skills?${params.toString()}`);
+        return {
+            items: Array.isArray(data?.items) ? data.items : [],
+            total: typeof data?.total === 'number' ? data.total : 0,
+            page: typeof data?.page === 'number' ? data.page : 0,
+            size: typeof data?.size === 'number' ? data.size : 0,
+        };
+    }
+    /** Skill detail. */
+    async skill(namespace, slug) {
+        return await this.getJson(`/api/v1/skills/${encodeURIComponent(namespace)}/${encodeURIComponent(slug)}`);
+    }
+    /** Version list (newest first). */
+    async versions(namespace, slug) {
+        const data = await this.getJson(`/api/v1/skills/${encodeURIComponent(namespace)}/${encodeURIComponent(slug)}/versions`);
+        return Array.isArray(data?.items) ? data.items : [];
+    }
+    /** File manifest for one version. */
+    async files(namespace, slug, version) {
+        const data = await this.getJson(`/api/v1/skills/${encodeURIComponent(namespace)}/${encodeURIComponent(slug)}/versions/${encodeURIComponent(version)}/files`);
+        return Array.isArray(data) ? data : [];
+    }
+    /** Raw file content for one version, capped at {@link MAX_FILE_BYTES}. */
+    async file(namespace, slug, version, path) {
+        const params = new URLSearchParams({ path });
+        const response = await this.request(`/api/v1/skills/${encodeURIComponent(namespace)}/${encodeURIComponent(slug)}/versions/${encodeURIComponent(version)}/file?${params.toString()}`);
+        const buffer = Buffer.from(await response.arrayBuffer());
+        if (buffer.length > MAX_FILE_BYTES) {
+            throw new SkillHubApiError(`file larger than ${MAX_FILE_BYTES} bytes`, 0, 0);
+        }
+        return buffer.toString('utf8');
+    }
+    /** Resolve the effective version for a skill (latest published by default). */
+    async resolve(namespace, slug, version) {
+        const suffix = version !== undefined && version !== '' ? `?version=${encodeURIComponent(version)}` : '';
+        return await this.getJson(`/api/v1/skills/${encodeURIComponent(namespace)}/${encodeURIComponent(slug)}/resolve${suffix}`);
+    }
+    /**
+     * Download the zip package for one version (latest published when
+     * `version` is omitted), size-capped at {@link MAX_DOWNLOAD_BYTES}.
+     */
+    async download(namespace, slug, version) {
+        const suffix = version !== undefined && version !== '' ? `versions/${encodeURIComponent(version)}/download` : 'download';
+        const response = await this.request(`/api/v1/skills/${encodeURIComponent(namespace)}/${encodeURIComponent(slug)}/${suffix}`);
+        const declared = Number(response.headers.get('content-length') ?? '');
+        if (Number.isFinite(declared) && declared > MAX_DOWNLOAD_BYTES) {
+            throw new SkillHubApiError(`package larger than ${MAX_DOWNLOAD_BYTES} bytes`);
+        }
+        const chunks = [];
+        let total = 0;
+        for await (const chunk of response.body ?? []) {
+            const bytes = chunk;
+            total += bytes.length;
+            if (total > MAX_DOWNLOAD_BYTES)
+                throw new SkillHubApiError(`package larger than ${MAX_DOWNLOAD_BYTES} bytes`);
+            chunks.push(bytes);
+        }
+        return Buffer.concat(chunks);
+    }
+    /** GET a JSON endpoint and unwrap the `{code, msg, data}` envelope. */
+    async getJson(path) {
+        const response = await this.request(path);
+        const body = await response.json();
+        // Enveloped endpoints use {code:0, data}; tolerate bare payloads too.
+        if (typeof body === 'object' && body !== null && 'code' in body) {
+            const envelope = body;
+            if (envelope.code !== 0) {
+                throw new SkillHubApiError(typeof envelope.msg === 'string' && envelope.msg !== '' ? envelope.msg : `API error ${String(envelope.code)}`, response.status, typeof envelope.code === 'number' ? envelope.code : 0);
+            }
+            return envelope.data;
+        }
+        return body;
+    }
+    /** GET with auth header, timeout, and HTTP error mapping. */
+    async request(path) {
+        const url = `${this.registry}${path}`;
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                headers: this.token !== '' ? { authorization: `Bearer ${this.token}` } : {},
+                redirect: 'follow',
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (error) {
+            throw new SkillHubApiError(`registry unreachable: ${url}`, 0, 0, { cause: error });
+        }
+        if (!response.ok)
+            await this.fail(response);
+        return response;
+    }
+    /**
+     * Map a non-OK response to SkillHubApiError. Failure envelopes use the
+     * same `{code, msg}` structure with code = HTTP status; the server's
+     * message is surfaced when one is present (publish pre-check warnings
+     * arrive exactly this way).
+     */
+    async fail(response) {
+        let message = '';
+        try {
+            const body = await response.json();
+            if (typeof body?.msg === 'string' && body.msg !== '')
+                message = body.msg;
+        }
+        catch {
+            // Not JSON — fall through to the generic messages.
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new SkillHubApiError(message !== '' ? message : 'authentication failed — token missing, invalid, or out of scope', response.status, response.status);
+        }
+        if (response.status === 404) {
+            throw new SkillHubApiError(message !== '' ? message : 'skill or version not found', response.status, response.status);
+        }
+        throw new SkillHubApiError(message !== '' ? message : `registry request failed with HTTP ${response.status}`, response.status, response.status);
+    }
+}
+//# sourceMappingURL=api-client.js.map