dsh-skill-hub 0.3.7 → 0.3.8

package/lib/types/repo/github-client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * GitHub API 统一请求层：token 管理、鉴权头、ETag 缓存、错误映射、
+ * 带缓存的 JSON GET。从 repo.ts 抽出，原 6 处重复的 try/catch +
+ * headers + json 解析收敛到 fetchJson / fetchJsonCached 两个入口。
+ */
+/** 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>;
+/** JSON API 默认请求头（含鉴权）。 */
+export declare function apiHeaders(): Record<string, string>;
+export declare function clearEtagCache(): void;
+/**
+ * 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;
+/** 是否限流/中断类错误（调用方可直接透出，不再包装）。 */
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * 不带缓存的统一 GET+JSON：网络异常、非 2xx、坏 JSON 全部映射为
+ * RepoFetchError，调用方无需重复写 try/catch。
+ */
+export declare function fetchJson(url: string, fetchImpl: typeof fetch, context: string, headers?: Record<string, string>): Promise<{
+    json: unknown;
+    response: Response;
+}>;
+/**
+ * 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 fetchJsonCached(url: string, fetchImpl: typeof fetch, context: string): Promise<{
+    json: unknown;
+    response: Response;
+}>;

package/lib/types/repo.d.ts

@@ -7,6 +7,7 @@
  * `workflows/**`) is treated as a skill root. No hard-coded allowlist.
  */
 import type { RepoRoot, RepoSkillEntry } from './protocol.ts';
+export { RepoFetchError, clearEtagCache, fetchError, fetchJson, fetchJsonCached, githubAuthHeaders, isAbortError, setGithubToken } from './repo/github-client.ts';
 /** Preferred display order for known roots; unknown roots sort alphabetically after these. */
 export declare const REPO_ROOTS: readonly RepoRoot[];
 /** Parsed GitHub repository reference. */
@@ -27,21 +28,6 @@ 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>;
-export declare function clearEtagCache(): void;
-/**
- * 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;
 /**
@@ -62,8 +48,6 @@ export declare function originForRoot(repo: string, rootsPresent: ReadonlySet<st
 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[]>;
-/** Whether an error is an abort (AbortError / signal). */
-export declare function isAbortError(error: unknown): boolean;
 /**
  * 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
@@ -90,6 +74,11 @@ export declare function cleanupLeftoverImportDirs(targetRoot: string): Promise<n
  * repo has no releases (GitHub's /releases/latest skips prereleases/drafts).
  */
 export declare function getLatestReleaseTag(repo: string, fetchImpl?: typeof fetch): Promise<string | undefined>;
+/** Stars + release-asset downloads of a repo (two GitHub API requests). */
+export declare function getRepoStats(repo: string, fetchImpl?: typeof fetch): Promise<{
+    stars: number;
+    downloads: number;
+}>;
 /** Release tags of a repo, newest first (skips drafts, keeps prereleases). */
 export declare function listRepoReleases(repo: string, fetchImpl?: typeof fetch): Promise<string[]>;
 /** Branch names of a repo, default branch first (one GitHub API request). */

package/lib/types/routes/catalog.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 目录域路由：catalog / skill 详情 / skill 删除 / toggle / toggle-batch /
+ * create / stats。从 routes.ts 原样搬出，handler 逻辑不变。
+ */
+import { type RouteSpec, type SkillHubRouteDeps } from './helpers.ts';
+/** 目录域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
+export declare function catalogRoutes(deps: SkillHubRouteDeps): RouteSpec[];

package/lib/types/routes/config.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 配置域路由：config（总开关开着也可用，设置卡自救入口）/ update 自身更新
+ * 检查 / diagnosticFix。从 routes.ts 原样搬出，handler 逻辑不变。
+ */
+import { type RouteSpec, type SkillHubRouteDeps } from './helpers.ts';
+/** 配置域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
+export declare function configRoutes(deps: SkillHubRouteDeps): RouteSpec[];

package/lib/types/routes/groups.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 分组域路由：groups / tag 新建重命名 / tag 删除 / tag 成员 / tag 重排 /
+ * collection 重排 / source-group 重排。从 routes.ts 原样搬出，handler 逻辑不变。
+ */
+import { type RouteSpec, type SkillHubRouteDeps } from './helpers.ts';
+/** 分组域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
+export declare function groupRoutes(deps: SkillHubRouteDeps): RouteSpec[];

package/lib/types/routes/helpers.d.ts

@@ -0,0 +1,145 @@
+/**
+ * routes 共享层：请求围栏（回环信任/方法/总开关/JSON 体）、统一错误映射、
+ * 可写技能解析、目录/分组数据装配。handler 只写业务，从这里 import。
+ * 从 routes.ts 原样搬出，行为不变。
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
+import type { SkillDefinition, SkillSummary } from '@deepseek-ai/dsh-skill';
+import { type CatalogResponse, type GroupsResponse, type HubConfig, type SkillDetail, type WritableRoot } from '../protocol.ts';
+import { type SkillHubStore } from '../store.ts';
+/** Cap on JSON request bodies (toggle/create payloads are tiny). */
+export declare const MAX_JSON_BODY_BYTES: number;
+/** Loopback literal check plus browser same-origin markers. */
+export declare function isLoopbackRequest(request: IncomingMessage): boolean;
+/** One JSON response. */
+export declare function writeJson(res: ServerResponse, status: number, body: unknown): void;
+/** One JSON error response. */
+export declare function writeError(res: ServerResponse, status: number, error: unknown): void;
+/** HTTP status per store business-rule kind (user error, not server fault). */
+export declare const STORE_ERROR_STATUS: {
+    readonly validation: 400;
+    readonly 'not-found': 404;
+    readonly conflict: 409;
+};
+/** Map known error types onto HTTP statuses: repo fetch + store business rules. */
+export declare function writeRouteError(res: ServerResponse, error: unknown): void;
+/** Read a JSON request body (undefined when too large or unparseable). */
+export declare function readJsonBody(req: IncomingMessage): Promise<Record<string, unknown> | undefined>;
+/** URL query helper (first value, decoded). */
+export declare function queryParam(url: URL, name: string): string | undefined;
+/** Async existence check (import/sync use it on the user root). */
+export declare function pathExists(path: string): Promise<boolean>;
+/** Sources the hub may toggle (the user-level filesystem roots). */
+export declare function isWritableSource(source: string): source is WritableRoot;
+/** Lookup options the hub forwards to the registry (cwd selects project roots). */
+export interface SkillLookupLike {
+    cwd?: string;
+}
+/** Route family dependencies (narrow structural view of ctx.skills for tests). */
+export interface SkillHubRouteDeps {
+    skills: {
+        snapshot(options?: SkillLookupLike): Promise<{
+            skills: SkillSummary[];
+            complete: boolean;
+        }>;
+        get(name: string, options?: SkillLookupLike): Promise<SkillDefinition | undefined>;
+    };
+    store: SkillHubStore;
+    /** DSH home override (tests isolate the writable roots; defaults to ~/.dsh). */
+    home?: string;
+    /** Invalidate the registry catalog cache after hub-driven mutations. */
+    invalidate?: () => void;
+    /** Optional invocation-count reader; absent means the stats route reports unavailable. */
+    stats?: import('../stats.ts').SkillStatsReader;
+    /** Resolves the current plugin config; business routes honour the master switch. */
+    config?: () => HubConfig;
+    /** Resolves the raw saved config layer (fields the user explicitly overrode). */
+    saved?: () => Partial<HubConfig>;
+    /** Persist a config patch and re-sync plugin surfaces; resolves with the fresh config. */
+    updateConfig?: (patch: Partial<HubConfig>) => Promise<HubConfig>;
+}
+/** The resolved hub config a route sees (the shared resolver fills defaults). */
+export declare function configOf(deps: SkillHubRouteDeps): HubConfig;
+/** The raw saved config layer a route reports (empty when the owner omits it). */
+export declare function savedOf(deps: SkillHubRouteDeps): Partial<HubConfig>;
+/** Refuse business routes while the master switch is off (the config route stays up). */
+export declare function disabledGate(deps: SkillHubRouteDeps, res: ServerResponse): boolean;
+/** Resolve the home used for writable-root operations. */
+export declare function homeOf(deps: SkillHubRouteDeps): string;
+/** A skill resolved as a hub-writable user-level file. */
+export interface WritableSkill {
+    skill: SkillDefinition;
+    /** Absolute discovery-file path (guaranteed present by the resolver). */
+    path: string;
+    /** The writable root containing the file. */
+    root: WritableRoot;
+}
+/** A refusal with the exact HTTP error the caller should answer with. */
+export interface WritableSkillRefusal {
+    status: number;
+    error: string;
+}
+export type WritableSkillResult = {
+    ok: true;
+} & WritableSkill | {
+    ok: false;
+} & WritableSkillRefusal;
+/**
+ * Resolve a skill by name as something the hub may write, or the exact
+ * refusal the caller should answer with. Owns the guard sequence shared by
+ * toggle, toggle-batch, and skill/delete: registry lookup, writable source,
+ * writable file, and path containment inside a user root.
+ */
+export declare function resolveWritableSkill(deps: SkillHubRouteDeps, name: string, cwd?: string): Promise<WritableSkillResult>;
+/** 系统集合组 + 用户 tag + origin 映射（groups 路由的数据源）。 */
+export declare function buildGroups(deps: SkillHubRouteDeps): Promise<GroupsResponse>;
+/** 目录中存在的技能名集合（tag 成员校验用）：启用目录 ∪ 已禁用名单，避免成员因禁用而丢失。 */
+export declare function knownSkillNames(deps: SkillHubRouteDeps): Promise<Set<string>>;
+/** 已知工作区条目（dsh 的 workspace.json 表）。 */
+export interface WorkspaceEntry {
+    path: string;
+    title: string;
+}
+/**
+ * 读取 dsh 的已知工作区清单（~/.dsh/storages/workspace.json 的
+ * tables.workspaces 表）。面板默认视图据此合并所有工作区的项目技能；
+ * 文件缺失/损坏时返回空清单（回退为仅用户级视图）。
+ */
+export declare function workspaceEntries(home: string): Promise<WorkspaceEntry[]>;
+/**
+ * Build the full catalog response (shared by catalog/toggle/create handlers).
+ * 显式 cwd 只看该工作区；否则合并所有已知工作区（workspace.json）的项目技能
+ * + 用户级技能，同名技能先到先得；没有任何工作区时回退为仅用户级视图。
+ */
+export declare function buildCatalog(deps: SkillHubRouteDeps, cwd?: string): Promise<CatalogResponse>;
+/** Map a loaded definition onto the wire shape. */
+export declare function toDetail(skill: SkillDefinition): SkillDetail;
+/** What a route handler receives: fences already passed, URL/body prepared. */
+export interface RouteContext {
+    req: IncomingMessage;
+    res: ServerResponse;
+    /** Request URL parsed against a localhost base (query reading for GET). */
+    url: URL;
+    /** Parsed JSON body; empty object for requests without one. */
+    body: Record<string, unknown>;
+}
+export type RouteHandler = (context: RouteContext) => Promise<void>;
+/** One declarative route: path + accepted methods + the business handler. */
+export interface RouteSpec {
+    path: string;
+    /** Accepted HTTP methods; anything else answers 405. */
+    methods: readonly ('GET' | 'POST')[];
+    /** POST requests must carry a JSON body (400 when missing/unparseable). */
+    jsonBody?: boolean;
+    /** Skip the master-switch gate (the config route stays up while disabled). */
+    skipGate?: boolean;
+    handler: RouteHandler;
+}
+/**
+ * Wrap one handler in the shared request fences. Order matches the
+ * original per-handler prologue: loopback trust → HTTP method → master
+ * switch → JSON body. The outer catch maps errors onto the JSON error
+ * body (preserving RepoFetchError status codes).
+ */
+export declare function createRoute(deps: SkillHubRouteDeps, spec: RouteSpec): WebRoute;

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

@@ -0,0 +1,8 @@
+/**
+ * 市场域路由：market 列表 / source 增删 / ref 锁定 / versions 选择器 /
+ * check 更新检查 / stats 星标统计 / sync 对齐版本。从 routes.ts 原样搬出，
+ * handler 逻辑不变。
+ */
+import { type RouteSpec, type SkillHubRouteDeps } from './helpers.ts';
+/** 市场域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
+export declare function marketRoutes(deps: SkillHubRouteDeps): RouteSpec[];

package/lib/types/routes/repo-import.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 仓库导入域路由：repo 发现 / repoImport 异步导入任务 / progress 轮询 /
+ * cancel 取消。从 routes.ts 原样搬出，handler 逻辑不变。
+ */
+import { type RouteSpec, type SkillHubRouteDeps } from './helpers.ts';
+/** 仓库导入域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
+export declare function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[];

package/lib/types/routes/route-state.d.ts

@@ -0,0 +1,55 @@
+/**
+ * routes 共享状态：各类节流表、市场统计内存缓存、异步导入任务表。
+ * 从 routes.ts 原样搬出，行为不变；各域 handler 从这里 import。
+ */
+import type { SkillHubRouteDeps } from './helpers.ts';
+/** Minimum interval between network update checks per source (GitHub rate limits). */
+export declare const MIN_CHECK_INTERVAL_MS: number;
+/** Last successful check time per repo (in-memory throttle for GitHub rate limits). */
+export declare const lastSourceCheck: Map<string, number>;
+/** Last successful market update check per repo (same throttle). */
+export declare const lastMarketCheck: Map<string, number>;
+/** Market stats (stars/downloads) throttle: hourly, plus a fallback cache. */
+export declare const lastMarketStats: Map<string, number>;
+export declare const marketStatsCache: Map<string, {
+    stars: number;
+    downloads: number;
+}>;
+export declare const MARKET_STATS_TTL_MS: number;
+export declare function seedMarketStats(deps: SkillHubRouteDeps): Promise<void>;
+/** Async import job (B方案：jobId + 轮询，选项2后台继续) */
+export interface ImportJob {
+    jobId: string;
+    repo: string;
+    ref: string;
+    total: number;
+    done: number;
+    current?: string;
+    currentFile?: string;
+    totalBytes: number;
+    downloadedBytes: number;
+    startTime: number;
+    imported: Array<{
+        name: string;
+        origin: string;
+        path: string;
+    }>;
+    skipped: Array<{
+        name: string;
+        reason: 'exists';
+    }>;
+    failed: Array<{
+        name: string;
+        error: string;
+    }>;
+    status: 'running' | 'done' | 'cancelled' | 'error';
+    error?: string;
+    controller: AbortController;
+    createdAt: number;
+}
+export declare const importJobs: Map<string, ImportJob>;
+export declare const IMPORT_JOB_TTL_MS: number;
+export declare const IMPORT_JOB_MAX = 100;
+export declare function gcImportJobs(): void;
+/** Replace one skill directory with a fresh download; restores the old dir on failure. */
+export declare function replaceSkillDir(targetDir: string, download: () => Promise<void>): Promise<void>;

package/lib/types/routes/sources.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 来源跟踪域路由：sources 列表 / check 上游更新 / sync 同步 / delete 跟进
+ * 删除 / restore 恢复 / trash/clear 清空回收站。从 routes.ts 原样搬出，
+ * handler 逻辑不变。
+ */
+import { type RouteSpec, type SkillHubRouteDeps } from './helpers.ts';
+/** 来源跟踪域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
+export declare function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[];

package/lib/types/routes.d.ts

@@ -7,42 +7,13 @@
  * 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.
+ * 按域拆分后的聚合入口：各域 handler 在 ./routes/<domain>.ts，共享围栏在
+ * ./routes/helpers.ts，节流/任务状态在 ./routes/route-state.ts。
+ * 老 `from './routes.ts'`（makeRoutes + SkillHubRouteDeps）保持可用。
  */
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
-import type { SkillDefinition, SkillSummary } from '@deepseek-ai/dsh-skill';
-import { type HubConfig } from './protocol.ts';
-import { type SkillHubStore } from './store.ts';
-import type { SkillStatsReader } from './stats.ts';
-/** Lookup options the hub forwards to the registry (cwd selects project roots). */
-export interface SkillLookupLike {
-    cwd?: string;
-}
-/** Route family dependencies (narrow structural view of ctx.skills for tests). */
-export interface SkillHubRouteDeps {
-    skills: {
-        snapshot(options?: SkillLookupLike): Promise<{
-            skills: SkillSummary[];
-            complete: boolean;
-        }>;
-        get(name: string, options?: SkillLookupLike): Promise<SkillDefinition | undefined>;
-    };
-    store: SkillHubStore;
-    /** DSH home override (tests isolate the writable roots; defaults to ~/.dsh). */
-    home?: string;
-    /** Invalidate the registry catalog cache after hub-driven mutations. */
-    invalidate?: () => void;
-    /** Optional invocation-count reader; absent means the stats route reports unavailable. */
-    stats?: SkillStatsReader;
-    /** Resolves the current plugin config; business routes honour the master switch. */
-    config?: () => HubConfig;
-    /** Resolves the raw saved config layer (fields the user explicitly overrode). */
-    saved?: () => Partial<HubConfig>;
-    /** Persist a config patch and re-sync plugin surfaces; resolves with the fresh config. */
-    updateConfig?: (patch: Partial<HubConfig>) => Promise<HubConfig>;
-}
+import { type SkillHubRouteDeps } from './routes/helpers.ts';
+export type { SkillHubRouteDeps, SkillLookupLike } from './routes/helpers.ts';
 /**
  * Build every /api/skill-hub route.
  * @param deps - skill registry view + sidecar store.

package/lib/types/stats.d.ts

@@ -77,8 +77,9 @@ export interface SkillStatsReaderOptions {
     ttlMs?: number | (() => number);
     /** Rolling window in days; a getter reads the live config each scan. 0 = all history. */
     windowDays?: () => number;
-    /** Called after a full reconciliation mutated the checkpoint (never after an
-     *  incremental scan) so the host can persist it to the sidecar. */
+    /** Called after every completed scan (full or incremental) so the host can
+     *  persist the checkpoint including the fresh totals. Cadence follows the
+     *  scan TTL (minutes, not days) — the payload is tiny and writes are atomic. */
     onCheckpoint?: (checkpoint: SkillStatsCheckpoint) => void;
 }
 /**

package/lib/types/store/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Business-rule failure the routes layer can map onto a 4xx status instead
+ * of a blanket 500: user input is invalid (validation → 400), the target
+ * does not exist (not-found → 404), or the operation conflicts with an
+ * invariant (conflict → 409).
+ */
+export declare class StoreError extends Error {
+    readonly kind: 'validation' | 'not-found' | 'conflict';
+    constructor(kind: StoreError['kind'], message: string);
+}

package/lib/types/store/migrate.d.ts

@@ -0,0 +1,44 @@
+import type { DisabledSkill, HubConfig, MarketSourceRecord, MarketStatsSnapshot, SkillStatsCheckpoint, SkillTag, SourceRecord, TrashEntry } from '../protocol.ts';
+/** Normalized raw sidecar document after schema migration (fields still unvalidated). */
+export interface MigratedStore {
+    version: number;
+    disabled: unknown;
+    config?: unknown;
+    tags?: unknown;
+    sources?: unknown;
+    marketSources?: unknown;
+    trash?: unknown;
+    skillStats?: unknown;
+    marketStats?: unknown;
+    collectionOrder?: unknown;
+    sourceGroupOrder?: unknown;
+}
+/**
+ * Normalize an arbitrary parsed sidecar document to the current schema.
+ * v1 to v2: scenes are dropped (the one-click role merged into group
+ * switches), and origins are migrated into source records (repo = origin
+ * value, commit snapshot empty — the first update check backfills it).
+ * v2 to v3: market sources become records ({ repo, ref?, commitSha? })
+ * instead of bare repo slugs, so a source can pin a release/branch version.
+ * Returns null when the file claims a newer schema than this plugin
+ * understands, so the caller starts empty instead of risking data loss.
+ */
+export declare function migrateStore(parsed: unknown): MigratedStore | null;
+/** Validated in-memory state hydrated from a migrated document. */
+export interface HydratedState {
+    entries: Map<string, DisabledSkill>;
+    config: Partial<HubConfig>;
+    tagsById: Map<string, SkillTag>;
+    sourcesByRepo: Map<string, SourceRecord>;
+    marketSources: MarketSourceRecord[];
+    trashByName: Map<string, TrashEntry>;
+    skillStats: SkillStatsCheckpoint | undefined;
+    marketStats: MarketStatsSnapshot | undefined;
+    collectionOrder: string[];
+    sourceGroupOrder: string[];
+}
+/**
+ * 把迁移后的原始文档校验为内存状态：坏条目丢弃、坏桶降级为空，
+ * 绝不因一条脏数据丢掉整个 sidecar（与原 ensureLoaded 内联逻辑一致）。
+ */
+export declare function hydrateMigratedState(migrated: MigratedStore): HydratedState;

package/lib/types/store/paths.d.ts

@@ -0,0 +1,32 @@
+import type { DisabledSkill, HubConfig, MarketSourceRecord, MarketStatsSnapshot, SkillStatsCheckpoint, SkillTag, SourceRecord, TrashEntry } from '../protocol.ts';
+/** 默认场景名（系统预置的兜底场景，新技能自动归入）。 */
+export declare const DEFAULT_SCENE_NAME = "\u901A\u7528";
+/** Wire shape persisted on disk. */
+export interface StoreFile {
+    version: number;
+    disabled: DisabledSkill[];
+    /** Runtime configuration edited from the web settings card (hub-owned, not settings-service). */
+    config?: Partial<HubConfig>;
+    /** User-defined tag groups (pure organization; skill files untouched). */
+    tags?: SkillTag[];
+    /** Upstream source tracking records (repo + commit snapshot). */
+    sources?: SourceRecord[];
+    /** User-added market sources (owner/repo slugs + optional pinned ref). */
+    marketSources?: MarketSourceRecord[];
+    /** Trashed skills (removed after upstream deletion, restorable). */
+    trash?: TrashEntry[];
+    /** Usage-statistics incremental-scan checkpoint (frozen watermark + totals). */
+    skillStats?: SkillStatsCheckpoint;
+    /** Market-stats snapshot (stars/downloads per repo, hourly TTL). */
+    marketStats?: MarketStatsSnapshot;
+    /** Drag-reorder: collection name order for 来源分组 */
+    collectionOrder?: string[];
+    /** Drag-reorder: 来源顶层分组整体顺序（project / col:xxx / uncategorized-source） */
+    sourceGroupOrder?: string[];
+}
+/** Resolve the DSH home directory (the filesystem provider's user-dsh root base). */
+export declare function dshHome(): string;
+/** Resolve the sidecar state path (injectable in tests). */
+export declare function statePath(home?: string): string;
+/** Current sidecar schema version. Bump on breaking shape changes and add a migration below. */
+export declare const STORE_VERSION = 4;

package/lib/types/store/store.d.ts

@@ -0,0 +1,133 @@
+import type { DisabledSkill, HubConfig, MarketSourceRecord, MarketStatsSnapshot, SkillStatsCheckpoint, SkillTag, SourceRecord, TrashEntry } from '../protocol.ts';
+/** Sidecar state owner. */
+export declare class SkillHubStore {
+    private readonly file;
+    private entries;
+    private config;
+    private tagsById;
+    private sourcesByRepo;
+    private marketSources;
+    private trashByName;
+    private skillStats;
+    private marketStats;
+    private collectionOrder;
+    private sourceGroupOrder;
+    private loaded;
+    /** Serializes persist runs: concurrent mutators must not let an earlier
+     *  snapshot overwrite a later one (rename is atomic, ordering is not). */
+    private writeChain;
+    constructor(file?: string);
+    private ensureLoaded;
+    /**
+     * 保证存在默认场景：没有任何 default 标记的 tag 时创建「通用」。
+     * 新技能创建后自动归入它；用户可改名，但默认场景不可删除。
+     */
+    private ensureDefaultTag;
+    listDisabled(): Promise<DisabledSkill[]>;
+    getDisabled(name: string): Promise<DisabledSkill | undefined>;
+    addDisabled(entry: DisabledSkill): Promise<void>;
+    removeDisabled(name: string): Promise<void>;
+    /** The hub's saved runtime configuration (fields absent here mean "not overridden"). */
+    getConfig(): Promise<Partial<HubConfig>>;
+    /**
+     * Persist a runtime-config patch, merged over the saved values. A field
+     * whose patch value is undefined is removed from the saved layer, so the
+     * setting re-inherits its default (the web card's "reset" path).
+     */
+    setConfig(config: Partial<HubConfig>): Promise<void>;
+    /** All user-defined tag groups, in creation order. */
+    listTags(): Promise<SkillTag[]>;
+    /** One tag by id (undefined when absent). */
+    getTag(id: string): Promise<SkillTag | undefined>;
+    /**
+     * Create (no id) or rename (with id) a tag. Returns the saved tag.
+     * Creating assigns a fresh UUID; renaming keeps members.
+     */
+    saveTag(input: {
+        id?: string;
+        name: string;
+    }): Promise<SkillTag>;
+    /** Delete a tag by id (no-op when absent). The default scene cannot be deleted. */
+    deleteTag(id: string): Promise<void>;
+    /** The default scene (「通用」), guaranteed to exist after ensureLoaded. */
+    getDefaultTag(): Promise<SkillTag | undefined>;
+    /** Append one skill name to a tag (deduplicated; no-op when already a member). */
+    addSkillToTag(id: string, name: string): Promise<SkillTag | undefined>;
+    /**
+     * Replace a tag's member list wholesale (idempotent). Deduplicates and
+     * drops blank names; unknown skill names are kept (they may arrive later),
+     * the routes layer filters against the live catalog before persisting.
+     */
+    setTagMembers(id: string, skillNames: readonly string[]): Promise<SkillTag | undefined>;
+    /** Remove one skill from every tag group (used when the skill is deleted). */
+    removeSkillFromTags(name: string): Promise<void>;
+    /** Reorder tag groups by orderedIds (drag-and-drop). */
+    reorderTags(orderedIds: string[]): Promise<SkillTag[]>;
+    /** Collection order for 来源分组拖拽 */
+    getCollectionOrder(): Promise<string[]>;
+    /** Reorder collections by orderedNames (drag-and-drop). */
+    reorderCollections(orderedNames: string[]): Promise<string[]>;
+    /** Source top-level group order for 来源分组（project / col:xxx / personal） */
+    getSourceGroupOrder(): Promise<string[]>;
+    /** Reorder source top-level groups by orderedKeys */
+    reorderSourceGroups(orderedKeys: string[]): Promise<string[]>;
+    /** All source records, sorted by repo. */
+    listSources(): Promise<SourceRecord[]>;
+    /** One source record by repo (undefined when absent). */
+    getSource(repo: string): Promise<SourceRecord | undefined>;
+    /** The source record that tracks a skill name (undefined when untracked). */
+    getSourceForSkill(name: string): Promise<SourceRecord | undefined>;
+    /** Remove a source record entirely (no-op when absent). */
+    deleteSource(repo: string): Promise<void>;
+    /**
+     * Upsert one skill into a source record. When the repo has no record yet a
+     * new one is created (root + commit snapshot from the caller).
+     */
+    addSourceSkill(repo: string, root: string, commitSha: string, ref: string | undefined, skillName: string): Promise<void>;
+    /** Replace a source's skill list (used after sync/confirm-delete). */
+    setSourceSkills(repo: string, skills: readonly string[]): Promise<SourceRecord | undefined>;
+    /** Remove one skill from every source record (used when the skill is deleted). */
+    removeSkillFromSources(name: string): Promise<void>;
+    /** Update a source's commit snapshot. */
+    setSourceCommit(repo: string, commitSha: string): Promise<void>;
+    /** Update a source's pinned ref (release tag / branch) when the market syncs. */
+    setSourceRef(repo: string, ref: string): Promise<void>;
+    /**
+     * Merge per-path manifest entries into a source (incremental imports).
+     * When `dir` is given, every baseline path under that skill directory is
+     * dropped first, so files the upstream removed never linger in the
+     * baseline and skew later update diffs.
+     */
+    mergeSourceManifest(repo: string, manifest: Record<string, number>, dir?: string): Promise<void>;
+    /** skillName → collection name for every recorded origin (derived from sources). */
+    listOrigins(): Promise<Record<string, string>>;
+    /** The user's market sources, in addition order. */
+    listMarketSources(): Promise<MarketSourceRecord[]>;
+    /** One market source by repo (undefined when absent). */
+    getMarketSource(repo: string): Promise<MarketSourceRecord | undefined>;
+    /** Add a repo (deduplicated), optionally with a pinned ref. Returns the fresh list. */
+    addMarketSource(repo: string, ref?: string): Promise<MarketSourceRecord[]>;
+    /** Remove a repo (no-op when absent). Returns the fresh list. */
+    removeMarketSource(repo: string): Promise<MarketSourceRecord[]>;
+    /** Pin a market source to an explicit ref (branch/tag). Returns the record. */
+    setMarketSourceRef(repo: string, ref: string): Promise<MarketSourceRecord | undefined>;
+    /** Record the commit a market source's pinned ref resolved to (update baseline). */
+    setMarketSourceCommit(repo: string, commitSha: string): Promise<void>;
+    /** All trashed skills, newest first. */
+    listTrash(): Promise<TrashEntry[]>;
+    /** One trash entry by skill name (undefined when absent). */
+    getTrash(name: string): Promise<TrashEntry | undefined>;
+    /** Record a trashed skill. */
+    addTrash(entry: TrashEntry): Promise<void>;
+    /** Remove a trash record (after restore). */
+    removeTrash(name: string): Promise<void>;
+    /** The persisted usage-statistics checkpoint (undefined until first saved). */
+    getSkillStatsState(): Promise<SkillStatsCheckpoint | undefined>;
+    /** Persist a usage-statistics checkpoint (after every completed scan; cadence follows the scan TTL). */
+    saveSkillStatsState(state: SkillStatsCheckpoint): Promise<void>;
+    /** The persisted market-stats snapshot (undefined until first saved). */
+    getMarketStatsState(): Promise<MarketStatsSnapshot | undefined>;
+    /** Persist a market-stats snapshot (written when a refresh fetched anything new). */
+    saveMarketStatsState(state: MarketStatsSnapshot): Promise<void>;
+    private persist;
+}