dsh-skill-hub 0.3.7 → 0.3.8

package/src/protocol/market.ts

@@ -0,0 +1,100 @@
+/** 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/source/versions?repo= — releases + branches for the version picker. */
+export interface MarketSourceVersionsResponse {
+  ok: true
+  repo: string
+  /** Currently pinned ref, when one is recorded. */
+  current?: string
+  /** Release tags, newest first (drafts excluded). */
+  releases: string[]
+  /** Branch names, default branch first. */
+  branches: string[]
+}
+
+/** Persisted market-stats snapshot (sidecar `marketStats` field): last fetched stars/downloads per repo. */
+export interface MarketStatsSnapshot {
+  /** Epoch ms of the fetch this snapshot was built from (drives the hourly TTL). */
+  fetchedAt: number
+  /** Per-repo numbers, keyed by repo slug. */
+  stats: Record<string, { stars: number; downloads: number }>
+}
+
+/** GET /api/skill-hub/market/stats — stars + release-asset downloads per market source. */
+export interface MarketStatsResponse {
+  ok: true
+  results: Array<{
+    repo: string
+    stars: number
+    downloads: number
+    /** Throttled: served from the hourly cache without a network round. */
+    throttled?: boolean
+    /** Stale: older than the hourly TTL, a background refresh is on its way. */
+    stale?: boolean
+    error?: 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[]
+}

package/src/protocol/repo.ts

@@ -0,0 +1,104 @@
+/** A skill discovered in a GitHub repo under any top-level root (e.g. skills/, 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
+}
+
+/** Skill root in a GitHub repo: the top-level directory that contains skills (e.g. skills, design-templates, templates). Auto-derived from SKILL.md locations, not hard-coded. */
+export type RepoRoot = string
+
+/** 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[]
+  /** GitHub truncated the tree; discovery is partial (mirrors codex walk_truncated). */
+  truncated?: boolean
+}
+
+/** 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 — now creates an async job (B方案) */
+export interface RepoImportResponse {
+  ok: true
+  jobId: string
+  total: number
+  totalBytes: number
+}
+
+/** GET /api/skill-hub/repo/import/progress?jobId=xxx */
+export interface RepoImportProgressResponse {
+  ok: true
+  jobId: string
+  status: 'running' | 'done' | 'cancelled' | 'error'
+  total: number
+  done: number
+  /** 当前正在下载的 skill 名，done < total 时有效 */
+  current?: string
+  /** 当前正在下载的文件路径（相对 skill dir） */
+  currentFile?: string
+  /** 字节级进度 */
+  totalBytes: number
+  downloadedBytes: number
+  /** 下载速度 bytes/sec，running 时有效 */
+  bytesPerSecond?: number
+  imported: Array<{ name: string; origin: string; path: string }>
+  skipped: Array<{ name: string; reason: 'exists' }>
+  failed: Array<{ name: string; error: string }>
+  /** error 状态时的原因 */
+  error?: string
+}
+
+/** POST /api/skill-hub/repo/import/cancel */
+export interface RepoImportCancelRequest {
+  jobId: string
+}
+export interface RepoImportCancelResponse {
+  ok: true
+  jobId: string
+  status: 'cancelled' | 'done'
+}
+
+/** 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
+}

package/src/protocol/sources.ts

@@ -0,0 +1,146 @@
+import type { CollectionGroup } from './groups.ts'
+import type { RepoRoot } from './repo.ts'
+
+/** 来源跟踪记录：一组来自同一上游仓库根目录的技能。 */
+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 }>
+}
+
+/** 项目级技能来源（它们有 workspace 归属，不属于「个人」组）。 */
+export function isProjectSource(source: string): boolean {
+  return source === 'project-dsh' || source === 'project-agents'
+}

package/src/protocol/stats.ts

@@ -0,0 +1,42 @@
+/** 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 {
+  ok: true
+  /** Whether a session-log source was available (false means counts are empty). */
+  available: boolean
+  /** Sorted per-skill invocation counts. */
+  stats: SkillStat[]
+}
+
+/**
+ * Persisted incremental-scan checkpoint for the usage statistics (sidecar
+ * `skillStats` field). Sessions created before `frozenBefore` are treated as
+ * finalized: their per-session counts live in `frozenSessions` (only sessions
+ * with at least one invocation are kept) and they are not re-read on
+ * incremental scans. A daily full reconciliation rebuilds the cache and
+ * advances the watermark, so a resumed old session is eventually re-counted.
+ */
+export interface SkillStatsCheckpoint {
+  /** The rolling-window configuration this checkpoint was built for (0 = all history). */
+  windowDays: number
+  /** Watermark: every session with header.createdAt < this value is frozen. */
+  frozenBefore: number
+  /** Per-session counts of finalized sessions, keyed by session id. */
+  frozenSessions: Record<string, { createdAt: number; counts: Record<string, { count: number; lastUsed: number }> }>
+  /** Epoch ms of the last full reconciliation (drives the daily cadence). */
+  lastFullReconcile: number
+  /**
+   * Totals from the last completed scan (any kind). Served instantly on cold
+   * start so a restart still shows numbers while the background rescan runs.
+   */
+  lastTotals?: SkillStat[]
+}