dsh-plugin-manager-companion 0.1.0

package/dist/registry.d.ts

@@ -0,0 +1,295 @@
+/**
+ * registry.ts — 社区索引（topic:dsh-plugin 全量表）的多源兜底链与磁盘缓存。
+ *
+ * 归属：A 类·重写（旧 src/registry.ts 仅作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/registry.ts（理解意图用，未复制代码）——它解决的问题是：
+ *   社区索引（registry.json，CI 每两小时重建）能让市场拿到几千条条目而**完全不碰 GitHub API 配额**；
+ *   CDN 会滞后所以需要新鲜度判断；单一来源不可靠所以需要多源兜底；全部失败时要有磁盘缓存兜底。
+ * 官方复用：无。官方没有市场概念，也没有索引/代理/缓存能力（见 DESIGN.md §1 的分工表）。
+ * 前提检查：旧实现的前提仍然成立（社区索引依旧是唯一零配额的全量来源），但它踩过的四个坑必须避开，
+ *   旧审计 docs/private/audit/correctness.md 有记录：
+ *   1) M14：GitHub api/raw 的响应**没有 generated_at**，旧实现因此只允许 CDN 结果落盘——一旦 CDN 不可达，
+ *      缓存永远不会被写入。本实现改成"**只允许更新，不允许回退**"：候选索引的 generated_at 必须不旧于
+ *      已缓存的那个，才允许落盘（对任何来源都成立，比"按来源白名单"更精确）。
+ *   2) M15：五跳串行 × 单请求 15s 可以挂住 75s。本实现给整条链一个总预算（默认 60s）并**真正中止**
+ *      在途请求（AbortController），而不是只把 Promise.race 掉、让请求继续在后台跑。
+ *   3) 缓存写入用 pretty-print 的 JSON，3115 条时 1.93MB / 5.4ms（旧 perf 审计 §1.8）。这里一律紧凑输出。
+ *   4) 索引内容没有做"条目级"校验——非对象、缺 repo 名的条目会被当成合法条目流入下游。这里逐条严格归一化，
+ *      并如实报告丢掉了多少条（skipped），不静默。
+ *
+ * 数据源与旧仓库一致（**不扩数据源**：不做 catalog 目录抓取、不引入 dsh.so 覆盖层）。
+ */
+import type { Fetcher } from './net.ts';
+import type { MarketInstallable, MarketItemKind, MarketRiskFlag, MarketRiskTier } from './types.ts';
+/** 社区索引仓库。只读消费，永远是硬编码兜底，不是依赖。 */
+export declare const REGISTRY_OWNER = "bradeGithub";
+export declare const REGISTRY_REPO = "DSH-Plugins-Marketplace";
+/** 索引文件名（仓库根目录下由 CI 生成）。 */
+export declare const REGISTRY_FILE = "registry.json";
+/** 索引缓存的默认有效期（分钟级配置见 settings.marketplace.cacheTtlMinutes）。 */
+export declare const REGISTRY_CACHE_TTL_MS: number;
+/** CDN 会滞后：标记为 requireFresh 的来源，其索引超过这个年龄就跳到下一跳。 */
+export declare const CDN_MAX_INDEX_AGE_MS: number;
+/** 整条兜底链的总预算：单请求超时由调用方给，总预算在这里封顶。 */
+export declare const REGISTRY_TOTAL_BUDGET_MS = 60000;
+/**
+ * 生态泛化主题词：它们是"生态标签"而不是功能信号，会挤掉卡片上有信息量的 topic。
+ *
+ * 这是一份**手写的小表**（不是从旧仓库或上游复制的 100+ 词表）：只保留最容易泛滥的
+ * 十几个，宁可少过滤也不误杀有意义的主题。要扩充时按同一标准加（"这个词能否区分两个插件"）。
+ */
+export declare const ECO_GENERIC_TOPICS: Set<string>;
+/** 一个主题列表 → 去掉生态泛化词后的功能主题（最多 8 个，卡片上只显示 2 个）。 */
+export declare function functionalTopics(topics: readonly string[] | undefined): string[];
+/** 索引里的一条仓库条目（已归一化，JSON-safe）。 */
+export interface RegistryRepo {
+    /** owner/repo，原样大小写。 */
+    readonly repo: string;
+    /** 仓库名（repo 的 basename）。 */
+    readonly name: string;
+    readonly description: string;
+    /** 星数；索引没给时为 null（**不伪造 0**——0 与"未知"在排序/展示上是两回事）。 */
+    readonly stars: number | null;
+    /** 最后更新时间的 ISO 串；未知时 null。 */
+    readonly updatedAt: string | null;
+    readonly topics: readonly string[];
+    readonly category?: string;
+    /** 仓库发布的 npm 包名（CI 采集）；装到 profile 里的键就是它。 */
+    readonly packageName?: string;
+    /** 仓库 package.json 里的版本（CI 采集）。 */
+    readonly latestVersion?: string;
+    /** 上游若显式给出条目形态就透传；否则由 marketplace.ts 按来源判定。 */
+    readonly kind?: MarketItemKind;
+    /**
+     * ── 上游元数据（task-45 政策决定"展示哪些"，本层只负责**原样透传事实**）──
+     *
+     * 分层：**服务端只给事实，展示决策在客户端**。典型例子：installable=non-plugin 的条目
+     * 仍然会出现在 REST 结果里（1,018 条），是否隐藏由 UI 的 filterInstallable 决定——
+     * host 替用户做过滤会让"上游到底标了什么"无从查证。
+     */
+    readonly installable?: MarketInstallable;
+    /** 上游风险等级；缺省表示上游没给结论（不是 safe）。 */
+    readonly riskTier?: MarketRiskTier;
+    /** 上游风险明细（超长会截断：卡片不用，详情够用）。 */
+    readonly riskFlags?: readonly MarketRiskFlag[];
+    /** 独立验证报告外链（仅在 verdict=pass 时透传，见 normalize）。 */
+    readonly reportUrl?: string;
+    /** 上游收录标记（community-pick / verified-install / …）。 */
+    readonly marketTags?: readonly string[];
+    /** 仓库已归档。 */
+    readonly archived?: boolean;
+    /** 近 7 天 star 增量（只用于排序）。 */
+    readonly starsDelta7d?: number;
+    /** 仓库许可证（SPDX id）；按政策只进详情。 */
+    readonly license?: string;
+    /** 独立校验方（verdict=pass 时）。 */
+    readonly verifiedBy?: string;
+    /** 独立校验时间（verdict=pass 时，ISO 日期）。 */
+    readonly verifiedAt?: string;
+}
+/**
+ * 归一化一条原始索引条目；不可用时返回 null。
+ *
+ * 严格性是有意的：索引是外部 JSON，字段缺失/类型漂移必须在这里被挡住，
+ * 否则下游的类型假设会变成运行时 TypeError（旧仓库在卡片渲染里就被 topic 非字符串炸过）。
+ *
+ * @param raw - 索引里的一条记录（registry.json 或 search API 的形状都兼容）。
+ * @returns 归一化条目；非对象、无 repo 名、或被排除的仓库返回 null。
+ */
+export declare function normalizeRegistryRepo(raw: unknown): RegistryRepo | null;
+/** 索引载荷的解析结果。 */
+export interface ParsedRegistryPayload {
+    readonly repos: readonly RegistryRepo[];
+    /** 索引自身的生成时间（ISO）；载荷没给时为 null。 */
+    readonly generatedAt: string | null;
+    /** 被丢弃的条目数（形状不合法或被排除）——如实报告，不静默。 */
+    readonly skipped: number;
+}
+/**
+ * 解析一份索引载荷（registry.json 的 `{generated_at, repos}`、search API 的 `{items}`、或裸数组）。
+ *
+ * 按 repo 名去重（保留先出现的那条：索引自己已排好序，先出现的是上游的取舍）。
+ *
+ * @param payload - 已 JSON.parse 的载荷。
+ * @returns 解析结果；没有任何可用条目时返回 null（调用方据此跳到下一跳）。
+ */
+export declare function parseRegistryPayload(payload: unknown): ParsedRegistryPayload | null;
+/** 索引的一跳来源。 */
+export interface RegistryIndexSource {
+    readonly id: string;
+    readonly url: string;
+    /** 响应是 gzip（.gz 文件）时需要解压。 */
+    readonly gzip: boolean;
+    /** 附带 GitHub token（只有 api.github.com 认这个头）。 */
+    readonly token: boolean;
+    /** CDN 一跳：索引必须比 CDN_MAX_INDEX_AGE_MS 新，否则跳到下一跳。 */
+    readonly requireFresh: boolean;
+}
+/**
+ * 兜底链的跳数顺序：api.github → jsDelivr(.gz) → raw(.gz) → jsDelivr → raw。
+ *
+ * 顺序的由来：api.github.com 带 token 时最可靠且能读到刚 push 的文件（CDN 会滞后），
+ * 但无 token 时配额只有 60/h，所以 CDN 的 .gz（体积最小）紧跟其后；raw 是最不依赖 CDN 的一跳。
+ *
+ * settings.marketplace.indexUrl 非空时作为**首选**跳插入队首，但内置链仍然保留：
+ * 用户填错地址不该让整个市场变成空的（配置是"优选"而不是"唯一"，这一点在配置项注释里也写了）。
+ *
+ * @param options - indexUrl（用户自定义源）与 branch（fork/镜像用）。
+ * @returns 按尝试顺序排列的来源列表。
+ */
+export declare function registryIndexSources(options?: {
+    readonly indexUrl?: string;
+    readonly branch?: string;
+}): RegistryIndexSource[];
+/**
+ * 磁盘缓存的落盘格式版本。
+ *
+ * 为什么必须显式带版本：缓存里存的是**我们归一化后的记录形**（stars / updatedAt / riskTier …），
+ * 与上游 registry.json 的 snake_case 完全不同。旧版本（无该字段）的读法把缓存记录又喂给上游解析器，
+ * 于是 11 个字段静默丢失（stars 变 null、riskTier/marketTags/starsDelta7d 等整块消失）——
+ * 表现为"缓存命中的那次加载功能少一半，冷抓取却正常"。
+ *
+ * 版本不符按**无缓存**处理：宁可重新抓一次，也不读出一份被削过的数据。
+ */
+export declare const REGISTRY_CACHE_FORMAT = 2;
+/** 磁盘缓存的落盘形状。 */
+export interface RegistryCacheFile {
+    /** 落盘时刻（epoch ms）——文件年龄。 */
+    readonly savedAt: number;
+    /** 索引自身生成时间（ISO）；未知时 null。 */
+    readonly generatedAt: string | null;
+    readonly repos: readonly RegistryRepo[];
+    /** 形状对不上而被丢弃的记录数（如实记账用；0 表示整份缓存都可用）。 */
+    readonly skipped: number;
+}
+/** 索引磁盘缓存路径（本插件自己的缓存目录，不与旧包共用）。 */
+export declare function registryCachePath(): string;
+/**
+ * 解析一条**已归一化**的缓存记录（我们自己的记录形）。
+ *
+ * 与 {@link normalizeRegistryRepo} 的唯一区别是字段名：那个读上游的 snake_case
+ * （stargazers_count / updated_at / risk_tier …），这个读我们自己写出去的名字
+ * （stars / updatedAt / riskTier …）。**两者不能互相复用**——这正是本轮缺陷的成因。
+ *
+ * 校验仍然严格：缓存是外部文件（用户可能手改、磁盘可能截断），形状对不上的条目
+ * 一律丢弃并计数，绝不产出一条"看着像记录、其实缺了半数字段"的对象。
+ *
+ * @param raw - 缓存文件里的一条记录。
+ * @returns 归一化条目；形状不可用时 null。
+ */
+export declare function normalizeCachedRepo(raw: unknown): RegistryRepo | null;
+/**
+ * 解析缓存文件里的记录列表（我们自己的记录形）：严格校验 + 按 repo 去重。
+ *
+ * @param list - 缓存文件里的 repos 数组。
+ * @returns 记录与丢弃计数；没有任何可用记录时 null。
+ */
+export declare function parseCachedRepos(list: unknown): {
+    repos: RegistryRepo[];
+    skipped: number;
+} | null;
+/**
+ * 读取磁盘缓存；不存在/损坏/格式版本不符/形状不对时返回 null。
+ *
+ * 三条边界：
+ * 1. **不抛错**：缓存是可重建的派生物，抛错会把一次网络抖动升级成市场页整页失败；
+ * 2. **格式版本不符即视为无缓存**（旧文件按新读法读会得到一份被削过的数据，宁可重抓）；
+ * 3. **按我们自己的记录形解析**（{@link parseCachedRepos}），不再复用上游解析器——
+ *    复用会让 11 个字段在往返里静默消失（本轮 task-69 的根因）。
+ */
+export declare function readRegistryCacheFile(): RegistryCacheFile | null;
+/**
+ * 写入磁盘缓存（紧凑 JSON）。
+ *
+ * 写失败**不抛**：缓存是派生物，磁盘满/无权限不该让一次成功的抓取变成失败。
+ *
+ * @returns 是否真的写成功了（调用方据此在 notes 里如实记账）。
+ */
+export declare function writeRegistryCacheFile(entry: {
+    readonly savedAt: number;
+    readonly generatedAt: string | null;
+    readonly repos: readonly RegistryRepo[];
+}): boolean;
+/**
+ * 缓存是否新鲜（纯函数，TTL 语义的唯一实现处）。
+ *
+ * 两条都要满足：**文件年龄**在 TTL 内（savedAt），且**内容年龄**（generatedAt，若可知）也在 TTL 内。
+ * 只看 savedAt 会让"今天才存下来的三天前索引"被当成新鲜；只看 generatedAt 则无法处理
+ * 载荷不带生成时间的来源（那时只能靠文件年龄）。
+ *
+ * @param entry - 缓存的 savedAt 与 generatedAt。
+ * @param now - 当前时刻（epoch ms），由调用方注入以便测试。
+ * @param ttlMs - 有效期。
+ */
+export declare function isRegistryCacheFresh(entry: {
+    readonly savedAt: number;
+    readonly generatedAt: string | null;
+}, now: number, ttlMs: number): boolean;
+/**
+ * 候选索引是否允许覆盖已缓存的那个（M14，纯函数）。
+ *
+ * 规则只有一条：**只许更新，不许回退**。
+ * - 候选没有 generatedAt：无法证明它不旧，拒绝落盘（宁可下次再抓，也不拿一个无法判断年龄的
+ *   快照覆盖掉已知新鲜的缓存）；
+ * - 没有缓存：允许；
+ * - 有缓存：候选的 generatedAt 必须 >= 缓存的那个。
+ */
+export declare function shouldPersistRegistryIndex(candidateGeneratedAt: string | null, cachedGeneratedAt: string | null): boolean;
+/** 一次索引加载的结果。 */
+export interface RegistryIndex {
+    readonly repos: readonly RegistryRepo[];
+    /** 索引自身生成时间（ISO）；未知时 null。 */
+    readonly generatedAt: string | null;
+    /** 本进程读到这份数据的时刻（epoch ms）。 */
+    readonly savedAt: number;
+    /** true = 来自磁盘缓存（本次没有走网络）。 */
+    readonly cached: boolean;
+    /** true = 缓存已过期（TTL 之外）但仍被采用——UI 应如实显示"数据可能过时"。 */
+    readonly stale: boolean;
+    /** 数据来源标识：`network:<id>` / `cache` / `empty`。 */
+    readonly source: string;
+    /** 逐跳的失败原因与如实记账（不静默吞掉）。 */
+    readonly notes: readonly string[];
+    /** 进程内镜像的内容代际（每次写入 +1）；缓存键的内容身份之一。 */
+    readonly generation: number;
+    /** 被丢弃的索引条目数。 */
+    readonly skipped: number;
+}
+/** 加载入参。 */
+export interface LoadRegistryIndexOptions {
+    /** 忽略新鲜缓存，强制走网络（用户点"刷新"）。 */
+    readonly refresh?: boolean;
+    readonly ttlMs?: number;
+    readonly timeoutMs?: number;
+    readonly totalBudgetMs?: number;
+    readonly indexUrl?: string;
+    readonly branch?: string;
+    /** 注入当前时刻（测试用）。 */
+    readonly now?: number;
+    /** 注入抓取器（测试用）；默认走 net.ts 的 fetchWithProxy。 */
+    readonly fetcher?: Fetcher;
+    /** 注入环境变量（token 读取用）。 */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * 内容哈希（FNV-1a，32 位十六进制）。
+ *
+ * 逐段就地计算，不拼接中间大字符串。段间混入一个分隔符，避免 (`ab`,`c`) 与 (`a`,`bc`) 撞。
+ * 放在 registry.ts 而不是 marketplace.ts：内容身份首先是"索引内容"的概念，
+ * 下游（管线缓存键）只是复用同一个哈希。
+ */
+export declare function hashIdentity(parts: readonly string[]): string;
+/** 当前镜像的内容代际；无镜像时为 0。 */
+export declare function registryGeneration(): number;
+/** 清空进程内镜像与在途状态（测试与插件卸载用）。 */
+export declare function resetRegistryMemory(): void;
+/**
+ * 加载索引：新鲜镜像 → 新鲜磁盘缓存 → 网络兜底链 → 过期磁盘缓存 → 空。
+ *
+ * 每一跳的结果都记进 `notes`：调用方（诊断页/市场页）能把"这次数据是怎么来的、
+ * 哪几跳失败了"如实展示给用户，而不是给一个空列表让人以为是"没有插件"。
+ *
+ * @param options - 见 {@link LoadRegistryIndexOptions}。
+ * @returns 索引结果；全部来源都不可用时返回空 items 的 `source: 'empty'`（**不抛错**）。
+ */
+export declare function loadRegistryIndex(options?: LoadRegistryIndexOptions): Promise<RegistryIndex>;