dsh-skill-hub 0.1.0 → 0.2.0

package/lib/types/protocol.d.ts

@@ -8,10 +8,31 @@
 export declare const SKILL_HUB_API: {
     readonly catalog: "/api/skill-hub/catalog";
     readonly skill: "/api/skill-hub/skill";
+    readonly skillDelete: "/api/skill-hub/skill/delete";
     readonly toggle: "/api/skill-hub/toggle";
+    readonly toggleBatch: "/api/skill-hub/toggle-batch";
     readonly create: "/api/skill-hub/create";
     readonly stats: "/api/skill-hub/stats";
     readonly config: "/api/skill-hub/config";
+    readonly market: "/api/skill-hub/market";
+    readonly marketSource: "/api/skill-hub/market/source";
+    readonly marketSourceDelete: "/api/skill-hub/market/source/delete";
+    readonly marketSourceRef: "/api/skill-hub/market/source/ref";
+    readonly marketCheck: "/api/skill-hub/market/check";
+    readonly marketSync: "/api/skill-hub/market/source/sync";
+    readonly repo: "/api/skill-hub/repo";
+    readonly repoImport: "/api/skill-hub/repo/import";
+    readonly update: "/api/skill-hub/update";
+    readonly groups: "/api/skill-hub/groups";
+    readonly tag: "/api/skill-hub/tag";
+    readonly tagDelete: "/api/skill-hub/tag/delete";
+    readonly tagMembers: "/api/skill-hub/tag/members";
+    readonly sources: "/api/skill-hub/sources";
+    readonly sourceCheck: "/api/skill-hub/sources/check";
+    readonly sourceSync: "/api/skill-hub/sources/sync";
+    readonly sourceDelete: "/api/skill-hub/sources/delete";
+    readonly sourceRestore: "/api/skill-hub/sources/restore";
+    readonly sourceTrashClear: "/api/skill-hub/sources/trash/clear";
 };
 /** User-level roots the hub may write to (matches dsh-skill-filesystem ranks 400/500). */
 export type WritableRoot = 'user-dsh' | 'user-agents';
@@ -27,13 +48,14 @@ export interface CatalogSkill {
     name: string;
     description: string;
     whenToUse?: string;
-    /** Optional group names declared in the skill's frontmatter (`sets`). */
-    sets?: string[];
     invocation: HubInvocation;
-    source: string;
     provider: string;
     /** Whether the hub may toggle this skill (user-level filesystem skills only). */
     writable: boolean;
+    /** SKILL.md creation time (epoch ms); used for "added" sorting. Absent when unknown. */
+    addedAt?: number;
+    /** SKILL.md last-modified time (epoch ms); used for "updated" display. Absent when unknown. */
+    updatedAt?: number;
 }
 /** One disabled skill tracked by the hub sidecar (SKILL.md renamed away). */
 export interface DisabledSkill {
@@ -67,13 +89,14 @@ export interface SkillDetail {
     name: string;
     description: string;
     whenToUse?: string;
-    /** Optional group names declared in the skill's frontmatter (`sets`). */
-    sets?: string[];
     invocation: HubInvocation;
-    source: string;
     provider: string;
     /** Absolute file path when the skill came from disk. */
     path?: string;
+    /** SKILL.md creation time (epoch ms); absent when the file is unreadable. */
+    addedAt?: number;
+    /** SKILL.md last-modified time (epoch ms); absent when the file is unreadable. */
+    updatedAt?: number;
     /** Markdown instruction body. */
     content: string;
 }
@@ -81,6 +104,17 @@ export interface SkillDetailResponse {
     ok: true;
     skill: SkillDetail;
 }
+/** POST /api/skill-hub/skill/delete — 把单个技能移入回收站（可恢复）。 */
+export interface SkillDeleteRequest {
+    name: string;
+}
+/** POST /api/skill-hub/skill/delete */
+export interface SkillDeleteResponse {
+    ok: true;
+    name: string;
+    /** 移入回收站后的路径（目录或文件）。 */
+    path: string;
+}
 /** POST /api/skill-hub/toggle */
 export interface ToggleRequest {
     /** Kebab-case skill name. */
@@ -93,6 +127,21 @@ export interface ToggleResponse {
     /** Fresh catalog after the mutation (the filesystem provider may lag a beat). */
     catalog: CatalogResponse;
 }
+/** POST /api/skill-hub/toggle-batch — one group of skills, one write. */
+export interface ToggleBatchRequest {
+    names: string[];
+    enabled: boolean;
+}
+/** POST /api/skill-hub/toggle-batch */
+export interface ToggleBatchResponse {
+    ok: true;
+    catalog: CatalogResponse;
+    /** Per-name failures (unknown/read-only skills); empty means all landed. */
+    failures: Array<{
+        name: string;
+        error: string;
+    }>;
+}
 /** POST /api/skill-hub/create */
 export interface CreateRequest {
     /** Kebab-case skill name (validated with the official isSkillName grammar). */
@@ -107,12 +156,14 @@ export interface CreateResponse {
     path: string;
     root: WritableRoot;
 }
-/** One skill's invocation count across the local session logs. */
+/** One skill's invocation stats across the local session logs. */
 export interface SkillStat {
     /** Kebab-case skill name. */
     name: string;
     /** How many sessions recorded a user-explicit invocation of this skill. */
     count: number;
+    /** Unix epoch ms of the most recent invocation (absent when never called). */
+    lastUsed?: number;
 }
 /** GET /api/skill-hub/stats */
 export interface StatsResponse {
@@ -132,7 +183,38 @@ export interface HubConfig {
     enabled: boolean;
     /** When true, a system-prompt section announces the hub to every agent. */
     announceToAgent: boolean;
+    /** Model-invocable dot color (#rrggbb); absent means the panel default. */
+    dotModelColor?: string;
+    /** User-invocable dot color (#rrggbb); absent means the panel default. */
+    dotUserColor?: string;
+    /** Show per-skill invocation count chip. Default true. */
+    showUseCount?: boolean;
+    /** Show per-skill last-used relative time. Default true. */
+    showUseTime?: boolean;
+    /** Show group-header usage summaries (count + last used). Default true. */
+    showGroupSummary?: boolean;
 }
+/**
+ * Hub config defaults — the single source every layer reads: the cordis
+ * schema (index.ts), the host's saved-override merge, and the routes'
+ * fallback view. Changing a default here changes all three.
+ */
+export declare const HUB_CONFIG_DEFAULTS: {
+    readonly enabled: true;
+    readonly announceToAgent: true;
+    readonly showUseCount: true;
+    readonly showUseTime: true;
+    readonly showGroupSummary: true;
+};
+/**
+ * Resolve the effective hub config: saved sidecar overrides win over the
+ * cordis composition entry (the web card owns runtime config), missing
+ * booleans fall back to HUB_CONFIG_DEFAULTS, and dot colors pass through
+ * (saved first, then base) only when set.
+ */
+export declare function resolveHubConfig(saved: Partial<HubConfig>, base?: Partial<HubConfig>): HubConfig;
+/** HEX color validation shared by host routes and the settings card. */
+export declare const HEX_COLOR_RE: RegExp;
 /** GET /api/skill-hub/config */
 export interface ConfigResponse {
     ok: true;
@@ -147,4 +229,343 @@ export interface ConfigRequest {
     enabled?: boolean | null;
     /** Set the field; null clears the saved override so it re-inherits the default. */
     announceToAgent?: boolean | null;
+    /** Set the field; null clears the saved override so it re-inherits the default. */
+    showUseCount?: boolean | null;
+    /** Set the field; null clears the saved override so it re-inherits the default. */
+    showUseTime?: boolean | null;
+    /** Set the field; null clears the saved override so it re-inherits the default. */
+    showGroupSummary?: boolean | null;
+    /** Set the dot color; null clears the saved override so it re-inherits the default. */
+    dotModelColor?: string | null;
+    /** Set the dot color; null clears the saved override so it re-inherits the default. */
+    dotUserColor?: string | null;
+}
+/** One market source: a tracked upstream repo plus its pinned version. */
+export interface MarketSourceRecord {
+    /** Repo slug (owner/repo). */
+    repo: string;
+    /** Pinned version: release tag, branch name, or custom ref. Absent = not yet pinned. */
+    ref?: string;
+    /** Commit the pinned ref last resolved to (update-check baseline). */
+    commitSha?: string;
+}
+/** GET /api/skill-hub/market — the user's added market sources. */
+export interface MarketSourcesResponse {
+    ok: true;
+    /** Added market sources, in addition order. */
+    repos: MarketSourceRecord[];
+}
+/** POST /api/skill-hub/market/source — add one repo as a market source. */
+export interface MarketSourceRequest {
+    /** owner/repo, owner/repo@ref, or a github.com URL. */
+    repo: string;
+}
+/** POST /api/skill-hub/market/source|delete */
+export interface MarketSourceResponse {
+    ok: true;
+    repos: MarketSourceRecord[];
+}
+/** POST /api/skill-hub/market/source/ref — pin a market source to an explicit ref. */
+export interface MarketSourceRefRequest {
+    repo: string;
+    /** Release tag or branch name chosen for the repo. */
+    ref: string;
+}
+/** GET /api/skill-hub/market/check — update check over market sources. */
+export interface MarketCheckResponse {
+    ok: true;
+    results: Array<{
+        repo: string;
+        /** Pinned ref, when one is recorded. */
+        ref?: string;
+        /** Latest release tag on the repo, when it has one. */
+        latestTag?: string;
+        /** Whether the pinned ref (or the repo) has moved ahead. */
+        updateAvailable: boolean;
+        /** Latest commit of the checked ref. */
+        commitSha: string;
+        /** Throttled: the check was skipped within the interval. */
+        throttled?: boolean;
+        error?: string;
+    }>;
+}
+/** POST /api/skill-hub/market/source/sync — align a market source to its pinned ref. */
+export interface MarketSyncResponse {
+    ok: true;
+    repo: string;
+    /** The ref the source is now pinned to. */
+    ref: string;
+    commitSha: string;
+    /** Local skills tracked from this repo (candidates for a batch update). */
+    skills: string[];
+}
+/** A skill discovered in a GitHub repo under skills/ or design-templates/. */
+export interface RepoSkillEntry {
+    /** Kebab-case skill name (directory basename). */
+    name: string;
+    /** Root-relative skill directory, e.g. skills/code-review. */
+    dir: string;
+    /** Root-relative SKILL.md path, e.g. skills/code-review/SKILL.md. */
+    path: string;
+    /** Repo root the skill lives in. */
+    root: RepoRoot;
+    /** Collection name recorded as origin after import. */
+    origin: string;
+    /** Number of files in the skill directory. */
+    fileCount: number;
+    /** Total bytes across all files in the skill directory. */
+    totalBytes: number;
+    /** Whether a same-named skill already exists locally. */
+    existing: boolean;
+}
+/** Supported skill roots in a GitHub repo. */
+export type RepoRoot = 'skills' | 'design-templates';
+/** GET /api/skill-hub/repo — discover importable skills in a GitHub repo. */
+export interface RepoDiscoverResponse {
+    ok: true;
+    repo: string;
+    /**
+     * Ref the discovery ran against (release tag / branch / default branch).
+     * Null means the repo has no release and no pinned ref — the client must
+     * ask the user to pick a branch (see `branches`) and pin it first.
+     */
+    ref: string | null;
+    /** Branch names to choose from when ref is null (default branch first). */
+    branches?: string[];
+    entries: RepoSkillEntry[];
+}
+/** POST /api/skill-hub/repo/import — install selected repo skills. */
+export interface RepoImportRequest {
+    repo: string;
+    /** Selected SKILL.md paths from the discover response. */
+    paths: string[];
+    /** The ref the discovery ran against; the import must use the same one. */
+    ref?: string;
+}
+/** POST /api/skill-hub/repo/import */
+export interface RepoImportResponse {
+    ok: true;
+    imported: Array<{
+        name: string;
+        origin: string;
+        path: string;
+    }>;
+    skipped: Array<{
+        name: string;
+        reason: 'exists';
+    }>;
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/** GET /api/skill-hub/update — check the plugin's own latest GitHub release. */
+export interface UpdateCheckResponse {
+    ok: true;
+    /** Installed plugin version (from the bundled host build). */
+    currentVersion: string;
+    /** Latest release tag, normalized without the leading v; null when unknown. */
+    latestVersion: string | null;
+    /** True when latestVersion is strictly newer than currentVersion. */
+    updateAvailable: boolean;
+    /** Release page URL; null when unavailable. */
+    url: string | null;
+    /** Best-effort message when the check failed or no release exists. */
+    error?: string;
+}
+/** 用户自定义 tag 分组：纯组织视图，不改技能文件。 */
+export interface SkillTag {
+    /** 稳定 ID（新建时由宿主生成）。 */
+    id: string;
+    /** 显示名。 */
+    name: string;
+    /** 成员技能名（集合技能与独立技能都可加入）。 */
+    skillNames: string[];
+    /** 默认场景（「通用」）：系统预置、不可删除、新技能自动归入。 */
+    default?: boolean;
+}
+/** 系统集合组：按 origin（来源集合标识）自动聚合。 */
+export interface CollectionGroup {
+    /** 集合名（origin 值，如 "superpowers" / "anthropics/skills"）。 */
+    name: string;
+    /** 该集合下的技能名，按名称排序。 */
+    skillNames: string[];
+}
+/** GET /api/skill-hub/groups */
+export interface GroupsResponse {
+    ok: true;
+    /** 用户自定义 tag 分组（按创建顺序）。 */
+    tags: SkillTag[];
+    /** 系统集合组（按 origin 聚合，名称排序）。 */
+    collections: CollectionGroup[];
+    /** skillName → 集合名 的完整映射。 */
+    origins: Record<string, string>;
+}
+/** POST /api/skill-hub/tag — 新建（缺省 id）或重命名（带 id）。 */
+export interface TagSaveRequest {
+    /** 已有 tag 的 id；缺省表示新建。 */
+    id?: string;
+    /** 显示名（去空格后非空）。 */
+    name: string;
+}
+/** POST /api/skill-hub/tag */
+export interface TagSaveResponse {
+    ok: true;
+    /** 变更后的全部 tag。 */
+    tags: SkillTag[];
+}
+/** POST /api/skill-hub/tag/delete */
+export interface TagDeleteRequest {
+    id: string;
+}
+/** POST /api/skill-hub/tag/delete */
+export interface TagDeleteResponse {
+    ok: true;
+    tags: SkillTag[];
+}
+/** POST /api/skill-hub/tag/members — 直接设置某 tag 的完整成员列表（幂等）。 */
+export interface TagMembersRequest {
+    id: string;
+    /** 目标成员技能名；后端只保留目录中存在的名字。 */
+    skillNames: string[];
+}
+/** POST /api/skill-hub/tag/members */
+export interface TagMembersResponse {
+    ok: true;
+    tags: SkillTag[];
+}
+/** 来源跟踪记录：一组来自同一上游仓库根目录的技能。 */
+export interface SourceRecord {
+    /** GitHub owner/repo。 */
+    repo: string;
+    /** 显式分支/tag；缺省表示默认分支。 */
+    ref?: string;
+    /** 技能在仓库中的根目录。 */
+    root: RepoRoot;
+    /** 上次导入/同步时的上游 commit SHA；空 = 尚未核对过。 */
+    commitSha: string;
+    /** 该来源下的技能名（来源组 = 这些技能）。 */
+    skills: string[];
+    /** 仓库内路径 → 文件大小 的基线清单（差异检测用；缺失 = 无基线）。 */
+    manifest?: Record<string, number>;
+}
+/** 回收站条目：上游删除后跟进删除（移入 .trash）的技能。 */
+export interface TrashEntry {
+    name: string;
+    /** .trash 下的绝对路径。 */
+    path: string;
+    /** 移入回收站的时间（epoch ms）。 */
+    movedAt: number;
+    /** 移入回收站前的原始路径（目录或文件）；旧版本条目没有该字段。 */
+    sourcePath?: string;
+    /**
+     * 移入回收站前的来源跟踪快照（恢复时用它把技能重新挂回来源记录，
+     * 否则恢复后的技能会丢失来源归属、变成「个人技能」）。
+     */
+    origin?: {
+        repo: string;
+        root: RepoRoot;
+        ref?: string;
+        commitSha: string;
+    };
+    /** 移入回收站前所属的场景（tag）ID；恢复时重新加回这些场景。 */
+    tagIds?: string[];
+}
+/** GET /api/skill-hub/sources */
+export interface SourcesResponse {
+    ok: true;
+    /** 全部来源记录（按 repo 排序）。 */
+    sources: SourceRecord[];
+    /** skillName → 集合名（由 sources 派生）。 */
+    origins: Record<string, string>;
+    /** 来源集合组（按 origin 聚合）。 */
+    collections: CollectionGroup[];
+    /** 回收站内容。 */
+    trash: TrashEntry[];
+}
+/** POST /api/skill-hub/sources/check — 检查指定（或全部）来源的上游更新。 */
+export interface SourceCheckRequest {
+    /** 仅检查该 repo；缺省检查全部。 */
+    repo?: string;
+}
+/** 单个来源的检查结果。 */
+export interface SourceCheckResult {
+    repo: string;
+    ref?: string;
+    /** 检查失败时的原因（如仓库不可达/限流）。 */
+    error?: string;
+    /** 上游 commit 是否变化。 */
+    changed: boolean;
+    /** 上游最新 commit SHA（检查成功时）。 */
+    commitSha?: string;
+    /** 上游有更新的技能名（changed 时经 tree 差异得出）。 */
+    updated: string[];
+    /** 上游已删除的技能名（changed 时经 tree 差异得出）。 */
+    deleted: string[];
+    /** 节流跳过（距上次检查不足 5 分钟，未访问网络）。 */
+    throttled?: boolean;
+    /** 该来源此前没有快照（迁移/旧记录），本次已回填 commit，尚未有差异基线。 */
+    unverified?: boolean;
+}
+/** POST /api/skill-hub/sources/check */
+export interface SourceCheckResponse {
+    ok: true;
+    results: SourceCheckResult[];
+}
+/** POST /api/skill-hub/sources/sync — 按上游重新下载所选技能并更新快照。 */
+export interface SourceSyncRequest {
+    repo: string;
+    /** 要同步的技能名；缺省同步该来源全部技能。 */
+    skills?: string[];
+}
+/** POST /api/skill-hub/sources/sync */
+export interface SourceSyncResponse {
+    ok: true;
+    repo: string;
+    /** 同步后的上游 commit SHA。 */
+    commitSha: string;
+    /** 成功同步的技能。 */
+    synced: string[];
+    /** 失败的技能。 */
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/** POST /api/skill-hub/sources/delete — 跟进上游删除，本地移入回收站。 */
+export interface SourceDeleteRequest {
+    repo: string;
+    /** 要删除的技能名（移入 .trash）。 */
+    skills: string[];
+}
+/** POST /api/skill-hub/sources/delete */
+export interface SourceDeleteResponse {
+    ok: true;
+    /** 已移入回收站的技能。 */
+    trashed: string[];
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/** POST /api/skill-hub/sources/restore — 从回收站恢复一个技能。 */
+export interface SourceRestoreRequest {
+    name: string;
+}
+/** POST /api/skill-hub/sources/restore */
+export interface SourceRestoreResponse {
+    ok: true;
+    name: string;
+    path: string;
+}
+/** POST /api/skill-hub/sources/trash/clear — 永久删除回收站里的全部技能。 */
+export interface SourceTrashClearResponse {
+    ok: true;
+    /** 已永久删除的技能名。 */
+    deleted: string[];
+    /** 未能删除的技能（保留在回收站中）。 */
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
 }

package/lib/types/provider.d.ts

@@ -28,7 +28,12 @@ export declare class SkillHubProvider implements SkillProvider {
     private readonly watchTimer;
     private rootStamp;
     constructor(control: SkillProviderControl, home?: string);
-    /** Invalidate the registry cache when the top-level root shape changed. */
+    /**
+     * Invalidate the registry cache when the discovered skill files changed.
+     * The stamp covers the per-skill discovery file's mtime + size (plus the
+     * entry set itself), so editing a SKILL.md body — not just adding or
+     * renaming directories — refreshes the GUI catalog.
+     */
     private checkRoots;
     list(options: {
         cwd?: string;

package/lib/types/repo.d.ts

@@ -0,0 +1,133 @@
+/**
+ * GitHub repository skill discovery/import helpers.
+ *
+ * Kept dependency-free and mostly pure so the root/origin rules are easy to
+ * test. The two supported roots mirror the repositories we care about:
+ * `skills/**` (standard skill bundles) and `design-templates/**` (template
+ * skill bundles in nexu-io/open-design).
+ */
+import type { RepoRoot, RepoSkillEntry } from './protocol.ts';
+/** Supported skill roots in a GitHub repo. */
+export declare const REPO_ROOTS: readonly RepoRoot[];
+/** Parsed GitHub repository reference. */
+export interface RepoRef {
+    owner: string;
+    repo: string;
+    /** Explicit branch/tag when supplied; undefined means use the default branch. */
+    ref?: string;
+}
+/** One file inside a GitHub repo tree. */
+export interface RepoTreeItem {
+    path: string;
+    type: 'blob' | 'tree';
+    size?: number;
+}
+/** One file belonging to a skill directory. */
+export interface RepoFile {
+    path: string;
+    size: number;
+}
+/** Fetch failure carrying a useful HTTP status for the route layer. */
+export declare class RepoFetchError extends Error {
+    readonly status: number;
+    constructor(message: string, status?: number);
+}
+/** Override the GitHub token at runtime ('' falls back to the env var). */
+export declare function setGithubToken(token: string | undefined): void;
+/** Authorization header for api.github.com / raw.githubusercontent.com calls. */
+export declare function githubAuthHeaders(): Record<string, string>;
+/**
+ * Build a RepoFetchError; when the response shows an exhausted rate limit,
+ * report the reset time instead of a bare HTTP status.
+ */
+export declare function fetchError(context: string, response: Response, fallbackStatus?: number): RepoFetchError;
+/** `owner/repo` slug for a parsed reference. */
+export declare function repoSlug(ref: RepoRef): string;
+/**
+ * Normalize a GitHub URL or `owner/repo`/`owner/repo@ref` input.
+ * Only github.com URLs are accepted in v1.
+ */
+export declare function normalizeRepoInput(input: string): RepoRef | null;
+/**
+ * Load repo metadata and the recursive git tree at the given ref. The meta
+ * request always resolves the default branch (used when ref is absent); the
+ * tree is fetched at `ref ?? default_branch` so an explicit branch/tag scans
+ * the exact same content a later download would fetch.
+ */
+export declare function loadRepoTree(repo: string, ref?: string, fetchImpl?: typeof fetch): Promise<{
+    ref: string;
+    tree: RepoTreeItem[];
+}>;
+/** Collect every file inside a skill directory, including SKILL.md itself. */
+export declare function collectRepoSkillFiles(tree: readonly RepoTreeItem[], dir: string): RepoFile[];
+/** Compute an origin collection name. Multiple roots split by root, one root keeps the repo slug. */
+export declare function originForRoot(repo: string, rootsPresent: ReadonlySet<RepoRoot>, root: RepoRoot): string;
+/** Discover importable skills from a repo tree. Invalid names are ignored. */
+export declare function discoverRepoEntries(tree: readonly RepoTreeItem[], repo: string, existingNames?: ReadonlySet<string>): RepoSkillEntry[];
+/** Run an async worker over items with a bounded concurrency. */
+export declare function mapConcurrent<T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/**
+ * Download one GitHub file as a buffer. Tries raw.githubusercontent.com
+ * first (no API quota); on any failure falls back to the api.github.com
+ * contents endpoint with the raw media type (rate-limited, but reachable
+ * from networks that block the raw host).
+ */
+export declare function downloadGitHubFile(repo: string, ref: string, path: string, fetchImpl?: typeof fetch): Promise<Buffer>;
+/**
+ * Download a full skill directory into a temporary dir, validate SKILL.md,
+ * then atomically rename it into place. The target root is created when missing.
+ * Callers pass a target root and a skill entry plus its collected files.
+ */
+export declare function downloadRepoSkill(repo: string, ref: string, entry: RepoSkillEntry, files: readonly RepoFile[], targetRoot: string, fetchImpl?: typeof fetch): Promise<{
+    targetDir: string;
+    skillPath: string;
+}>;
+/**
+ * The latest non-prerelease release tag of a repo, or undefined when the
+ * repo has no releases (GitHub's /releases/latest skips prereleases/drafts).
+ */
+export declare function getLatestReleaseTag(repo: string, fetchImpl?: typeof fetch): Promise<string | undefined>;
+/** Branch names of a repo, default branch first (one GitHub API request). */
+export declare function listRepoBranches(repo: string, fetchImpl?: typeof fetch): Promise<string[]>;
+/**
+ * Fetch the latest commit of a repo (explicit ref or default branch) with
+ * its tree SHA. One GitHub API request; the tree SHA is used to diff the
+ * upstream tree on change (one extra request).
+ */
+export declare function getLatestCommit(repo: string, ref?: string, fetchImpl?: typeof fetch): Promise<{
+    commitSha: string;
+    treeSha: string;
+}>;
+/** Load the recursive git tree at an explicit tree SHA (one API request). */
+export declare function loadRepoTreeAt(repo: string, treeSha: string, fetchImpl?: typeof fetch): Promise<RepoTreeItem[]>;
+/** Build a path→size manifest for one skill directory from a repo tree. */
+export declare function skillManifest(tree: readonly RepoTreeItem[], dir: string): Record<string, number>;
+/**
+ * The real upstream directory of one tracked skill. Source records keep only
+ * the short name and top-level root (e.g. root "skills", name "ask-matt"),
+ * but upstream repos may nest skills under category directories
+ * (skills/engineering/ask-matt/) or move them between categories. Resolution
+ * order: exact match under the top-level root in the upstream tree, then the
+ * manifest's recorded blob path, then any same-name skill in the tree, then
+ * the flat root/name fallback. Passing the tree paths makes the lookup
+ * resilient to incomplete manifests and upstream moves.
+ */
+export declare function skillDirOf(source: {
+    root: RepoRoot;
+    manifest?: Record<string, number>;
+}, name: string, treePaths?: readonly string[]): string;
+/**
+ * Diff one source record against an upstream tree at treeSha: which tracked
+ * skills disappeared (no SKILL.md blob) and which changed (manifest baseline
+ * differs, or no baseline exists — treated as changed). Pure over the tree.
+ */
+export declare function diffRemoteSkills(tree: readonly RepoTreeItem[], source: {
+    root: RepoRoot;
+    skills: readonly string[];
+    manifest?: Record<string, number>;
+}): {
+    updated: string[];
+    deleted: string[];
+};
+/** Minimal RepoSkillEntry for a tracked skill name (sync re-downloads by name). */
+export declare function repoSkillEntry(name: string, root: RepoRoot, repo: string): RepoSkillEntry;

package/lib/types/routes.d.ts

@@ -1,10 +1,15 @@
 /**
  * The /api/skill-hub route family: full catalog (enabled skills from the
  * official registry + hub-disabled skills + discovery diagnostics), skill
- * detail, enable/disable toggle, and new-skill scaffold. Every route
- * carries a loopback-only trust fence — these endpoints rename files under
- * the user's skill roots, so LAN-exposed dsh web deployments must not
- * serve them.
+ * detail, enable/disable toggle, new-skill scaffold, user groups (tags +
+ * origin collections), and upstream source tracking (check/sync/follow
+ * upstream deletion into a restorable trash). Every route carries a
+ * loopback-only trust fence — these endpoints rename files under the user's
+ * skill roots, so LAN-exposed dsh web deployments must not serve them.
+ *
+ * Every handler is declared through the local `route()` wrapper, which owns
+ * the shared request fences (loopback trust, HTTP method, master switch,
+ * JSON body) exactly once, so a new route cannot forget them.
  */
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import type { SkillDefinition, SkillSummary } from '@deepseek-ai/dsh-skill';