dsh-plugin-manager-companion 0.1.0

package/dist/upgrade.d.ts

@@ -0,0 +1,428 @@
+/**
+ * 升级引擎（档三）：把"升级已装插件"做成真实可执行、且**说清边界**的能力。
+ *
+ * 归属：A 类·重写（新代码；旧仓库没有升级能力，只有 CLI 的 `update` 把 spec 重写到 @latest）。
+ * 官方复用：
+ *   · 写通道只有一条 —— 官方 `runPluginCommand(['add', '<name>@<version>'])`（绝不自己调 pnpm，
+ *     也绝不写 cordis.patch.yml）；官方 CLI 的 plugin 子命令与我们走的是同一条通道。
+ *   · 版本查询走本仓库既有的出网层（net.ts 的 Fetcher），不新造 HTTP 客户端。
+ *   · 金丝雀复用 task-50/75 的试装引擎：它就是"在 <环境>-dpmc 里装候选再跑两次启动"。
+ * 前提检查：旧前提是"官方只有只读清单，升级得自己想办法"。0.1.6 之后官方给了完整写面与
+ *   `installed` / `removable` 事实，所以本模块只做官方不覆盖的三件事：版本事实（dist-tags）、
+ *   三类单元的分类、金丝雀与回滚的盘上核对。
+ *
+ * 三类单元（必须分开对待，这是本模块的核心诚实点）：
+ *   1. `profile-dependency`：在 profile 的 dependencies 里 → 可在 profile 内升级；
+ *   2. `installation-provided`：只出现在 dsh.profile.bundles 里（官方运行时层 dsh-base / dsh-web-app）
+ *      → profile 内**升不了**，只检测 + 给命令，不给按钮；
+ *   3. `self`：本插件自身 → 可升级，但**正在运行的就是旧代码**，必须走独立 job 并写明"下次启动生效"。
+ *
+ * 四态：`update-available` / `up-to-date` / `unknown` / `not-upgradable`。
+ * 铁律：拿不到版本事实一律 `unknown`（文案"查不到"），**绝不**显示"已是最新"——"没查到"与
+ *   "确实没有更新"是两个不同的状态，把前者说成后者就是编一个事实。
+ *
+ * 出网纪律（Lead 定稿）：检查时机 = 进入即查 + TTL + 手动常驻，**不做后台轮询**。
+ *   "每天一次"的语义是"下次进入时若距上次成功检查超过 24h 就查"；失败也记时间戳（1 小时内不自动重试，
+ *   免得每次进入都等超时）；手动按钮永远可用（不受开关、TTL 与负缓存限制）。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { PackageResult } from '@deepseek-ai/dsh-plugin-manager/types';
+import type { BootVerification, PluginCommandRunner, TrialInstallOptions, TrialInstallResult } from './envManager.ts';
+/**
+ * 试装执行器（测试注入金丝雀结论）。
+ *
+ * 与 index.ts 里那个 TrialRunner **结构相同、刻意各自定义**：index.ts 要 import 本模块的 op 编排，
+ * 本模块再去 import 它的类型就成环了。类型层面结构一致，互相传参没有问题。
+ */
+export type UpgradeTrialRunner = (spec: string, realName: string, options: TrialInstallOptions) => Promise<TrialInstallResult>;
+import { type Fetcher } from './net.ts';
+import { type RegistryRepo } from './registry.ts';
+import { type CompanionConfig } from './settings.ts';
+import type { UpgradeActionResult, UpgradeCanaryReport, UpgradeCheckResult, UpgradeRollbackResult, UpgradeState, UpgradeTag, UpgradeUnitKind } from './types.ts';
+/** 配置留空时的 registry（官方 npm）。 */
+export declare const OFFICIAL_REGISTRY_URL = "https://registry.npmjs.org";
+/** 单次 registry 查询的超时（一个包文档很小，15s 是宽松上限）。 */
+export declare const REGISTRY_TIMEOUT_MS = 15000;
+/** 一次检查里所有出网查询的总预算；超了就停手并如实记账，不拖住页面。 */
+export declare const CHECK_BUDGET_MS = 20000;
+/**
+ * 检查失败后的静默期：1 小时内不再自动重试。
+ *
+ * 存在的理由：registry 挂掉时，每次进入关于页都等一次 15s 超时是折磨；手动按钮不受它限制。
+ */
+export declare const NEGATIVE_TTL_MS: number;
+/** tags 磁盘缓存的格式版本（与 registry 缓存同一纪律：格式不符即视为无缓存）。 */
+export declare const TAGS_CACHE_FORMAT = 1;
+/** tags 磁盘缓存文件名（放在我们自己的缓存目录里，与市场索引缓存同级）。 */
+export declare const TAGS_CACHE_FILE = "upgrade-tags.json";
+/** 一次 dist-tags 查询的入参。 */
+export interface DistTagsQuery {
+    /** registry 地址；留空 = 官方 registry。 */
+    readonly registryUrl?: string;
+    readonly timeoutMs?: number;
+    /** 抓取器注入（测试）；省略时用 net.ts 的带代理实现。 */
+    readonly fetch?: Fetcher;
+}
+/** 一次 dist-tags 查询的结果。 */
+export interface DistTagsAnswer {
+    readonly ok: boolean;
+    /** tag 名 → 版本；失败时为 null。 */
+    readonly tags: Readonly<Record<string, string>> | null;
+    /** 失败原因（面向用户；成功时为 undefined）。 */
+    readonly reason?: string;
+}
+/**
+ * 包文档 URL。
+ *
+ * scoped 名必须整体转义（`@scope/name` → `%40scope%2Fname`），否则 `/` 会被当成路径分隔符。
+ *
+ * @param registryUrl - registry 基地址（可带尾斜杠）。
+ * @param name - 包名。
+ * @returns 文档 URL。
+ */
+export declare function registryDocumentUrl(registryUrl: string, name: string): string;
+/**
+ * 从 registry 文档里取 dist-tags（纯函数，便于用固定载荷测试）。
+ *
+ * 只认 `dist-tags`；缺字段或值不是字符串时返回 null（**不猜**：把 `versions` 里最大的那个
+ * 当成 latest 会与 tag 的真实语义脱钩）。
+ *
+ * @param payload - 解析后的 JSON。
+ * @returns tag 表；拿不到时 null。
+ */
+export declare function parseDistTags(payload: unknown): Record<string, string> | null;
+/**
+ * 查一个包的 dist-tags。
+ *
+ * 失败一律以 `ok: false` + reason 返回（调用方据此显示"查不到"），不抛异常：
+ * 一次网络抖动不该让整页检查失败。
+ *
+ * @param name - 包名。
+ * @param query - registry 地址 / 超时 / 抓取器。
+ * @returns 结果。
+ */
+export declare function fetchDistTags(name: string, query?: DistTagsQuery): Promise<DistTagsAnswer>;
+/**
+ * 一条版本线（major.minor.patch）；非法/缺失时 null。
+ *
+ * "与当前版本同线"= 同 major.minor.patch（例如 0.1.6-alpha.2 与 0.1.6-alpha.9 同线，
+ * 与 0.1.7 不同线）。判定只做字符串切分，不假装懂 semver：比较大小交给 match.ts 的 compareVersions。
+ *
+ * @param version - 版本串。
+ * @returns 线，或 null。
+ */
+export declare function versionLine(version: string | null): string | null;
+/**
+ * 一个包是不是本地来源（`link:` / `file:` / 相对或绝对路径）。
+ *
+ * 本地来源也能"升级"到 registry 版本，但那会**改变来源**（不再是本地那份）——必须显式说出来。
+ *
+ * @param spec - dependencies 里的 spec。
+ * @returns 是本地来源时 true。
+ */
+export declare function isLocalSpec(spec: string | undefined): boolean;
+/** 把 dist-tags 折成界面要的列表（含"同线/另一条线"与默认高亮）。 */
+export declare function tagReports(tags: Readonly<Record<string, string>>, currentVersion: string | null): readonly UpgradeTag[];
+/**
+ * 默认目标版本：与当前同线的**最新**；没有同线候选（或当前版本未知）时取 `latest`，
+ * 再退一步取所有 tag 里版本最大的那个（顺序即优先级，界面据此说"会切到哪条线"）。
+ *
+ * @param tags - tag 表。
+ * @param currentVersion - 当前版本。
+ * @returns 目标版本与提供它的 tag；没有可用 tag 时 null。
+ */
+export declare function pickTarget(tags: Readonly<Record<string, string>>, currentVersion: string | null): {
+    readonly version: string;
+    readonly tag: string;
+} | null;
+/** 一个包的缓存条目。 */
+export interface TagsCacheEntry {
+    readonly ok: boolean;
+    readonly tags: Readonly<Record<string, string>> | null;
+    /** 这次查询发生的时刻（epoch ms）。 */
+    readonly at: number;
+    readonly reason?: string;
+    /**
+     * 这条事实是在**哪个环境**的检查里取到的。
+     *
+     * 为什么必须带上它（不是可有可无的记账）：dist-tags 本身与环境无关，但"查不到"是
+     * **逐环境**的用户体验。实测反例（就是这条红测）：A 环境刚查成功，B 环境里同一个包
+     * 就再也不出网了——因为全局时间戳把 B 的检查判成"还没到期"，于是 B 永远看不到
+     * 自己的失败，也就永远拿不到属于它的"查不到 + 重试"。条目只在自己取到的那个环境里
+     * 生效，换环境一律重新取。
+     */
+    readonly environment: string;
+}
+/**
+ * 一个环境的检查记账。
+ *
+ * 为什么记账是**逐环境**的（而不是全局一份）：TTL 的语义是"这个环境下次进入时要不要出网"，
+ * 而"查不到"是**逐环境**的用户体验。实测反例（就是这条红测）：A 环境刚查成功，
+ * 紧接着 B 环境进入时被全局时间戳判成"还没到期"→ B 一次网都不出，于是 B 永远看不到
+ * 自己的失败，也永远拿不到属于它的"查不到 + 重试"。全局时间戳把两个环境的账记成了一本。
+ */
+export interface TagsCacheEnvState {
+    /** 这个环境上次**成功**拿到版本事实的时刻；从未成功过时 null。 */
+    readonly lastCheckAt: number | null;
+    /** 这个环境上次**尝试**（含失败）的时刻；用于负缓存。 */
+    readonly lastAttemptAt: number | null;
+}
+/** 磁盘缓存文件。 */
+export interface TagsCacheFile {
+    /** 逐环境的检查记账（环境名 → 记账）。 */
+    readonly environments: Readonly<Record<string, TagsCacheEnvState>>;
+    /**
+     * 逐包的版本事实。
+     *
+     * 键是包名，但每条都带 {@link TagsCacheEntry.environment}：条目只在自己取到的那个
+     * 环境里生效，换环境一律重新取（见那个字段的注释）。
+     */
+    readonly packages: Readonly<Record<string, TagsCacheEntry>>;
+}
+/** 缓存文件路径（我们自己的缓存目录，与市场索引缓存同级）。 */
+export declare function tagsCachePath(): string;
+/**
+ * 读缓存；不存在/损坏/格式不符时返回空壳（**不抛**：缓存是可重建的派生物）。
+ *
+ * @returns 缓存内容。
+ */
+export declare function readTagsCache(): TagsCacheFile;
+/**
+ * 写缓存（失败不抛，返回是否写成功）。
+ *
+ * @param file - 要写的内容。
+ * @returns 是否写成功。
+ */
+export declare function writeTagsCache(file: TagsCacheFile): boolean;
+/**
+ * 一条缓存是否仍然可用（纯函数，**逐包判定**）。
+ *
+ * 成功的条目按配置的检查间隔计时；失败的条目按 {@link NEGATIVE_TTL_MS} 计时
+ * （失败也要记时间戳，否则每次进入都会重试一次超时）。
+ *
+ * 为什么判据是**条目自己的** at 而不是全局时间戳：全局时间戳会让一个包的成功
+ * 顺带放行另一个包的负缓存。实测反例（就是这条红测）：环境 A 的包查成功之后，
+ * 同一个环境 B 里刚失败过的包在"1 小时内不自动重试"的窗口里又被查了一次。
+ *
+ * @param entry - 缓存条目。
+ * @param now - 当前时刻。
+ * @param ttlMs - 成功条目的有效期；null = 仅手动（此时对成功条目返回 true，
+ *   语义是"不因过期而自动查"——真正的自动检查开关由调用方管）。
+ * @returns 可直接使用该条目时 true。
+ */
+export declare function tagsCacheUsable(entry: TagsCacheEntry, now: number, ttlMs: number | null): boolean;
+/** 一个升级单元的事实（读盘得来，不含网络）。 */
+export interface UpgradeUnitFact {
+    readonly name: string;
+    readonly kind: UpgradeUnitKind;
+    /** dependencies 里的 spec；安装方提供的层没有这一项。 */
+    readonly spec?: string;
+    /** spec 是本地来源（升级会改变来源）。 */
+    readonly specIsLocal: boolean;
+    /** 当前版本（node_modules 里那个包的 version）；读不到时 null。 */
+    readonly currentVersion: string | null;
+}
+/**
+ * 一个包在当前环境里装着的版本（读 node_modules/<name>/package.json）。
+ *
+ * 读不到就返回 null（link: 断链、没装、目录不可读都算）——**不猜**，调用方按"当前版本未知"处理。
+ *
+ * @param environment - 环境名。
+ * @param name - 包名。
+ * @returns 版本，或 null。
+ */
+export declare function readInstalledVersion(environment: string, name: string): string | null;
+/**
+ * 列出这个环境的全部升级单元（三类）。
+ *
+ * 分类只认**盘上的结构事实**：出现在 dependencies 里 = profile 依赖（可升）；只出现在
+ * dsh.profile.bundles 里 = 安装方提供的层（profile 内升不了）。这一条与官方 listBundles 的
+ * `installed` 字段同源（已核实：dsh-base / dsh-web-app 只在 bundles 里、不在 dependencies 里）。
+ *
+ * @param environment - 环境名。
+ * @param options - 本插件自身包名（默认取常量；测试可覆盖）。
+ * @returns 单元清单（按名字排序，顺序稳定便于断言）。
+ * @throws {EnvironmentError} 环境名不合法或环境不存在时。
+ */
+export declare function unitFacts(environment: string, options?: {
+    readonly ourPackage?: string;
+}): readonly UpgradeUnitFact[];
+/**
+ * 安装方提供的层该给什么命令。
+ *
+ * 刻意**不**给 `dsh plugin add` / `dshpmc update`：那会把这一层变成 profile 的依赖（装出第二份），
+ * 是"看起来能修、其实更坏"的建议。真正要做的是升级 dsh 安装本身，而具体命令取决于当初怎么装的，
+ * 所以这里只给一种常见形态 + 明确的口径说明。
+ *
+ * @param name - 包名。
+ * @returns 面向用户的命令说明。
+ */
+export declare function installationUpgradeCommand(name: string): string;
+/** 市场索引给出的版本事实。 */
+export interface MarketVersionFact {
+    readonly version: string;
+    /** 索引的生成时间（ISO）；拿不到时为 null。 */
+    readonly at: string | null;
+}
+/**
+ * 从**已有的**市场索引缓存里找这个包的最新版本（零网络）。
+ *
+ * 只用缓存，不触发索引下载：关于页的一次检查不该顺手拉一份几 MB 的索引。
+ *
+ * @param name - 包名。
+ * @param options - 注入索引仓库（测试）；省略时读磁盘缓存。
+ * @returns 事实，或 null。
+ */
+export declare function marketVersionFact(name: string, options?: {
+    readonly repos?: readonly RegistryRepo[];
+}): MarketVersionFact | null;
+/** 检查的选项。 */
+export interface UpgradeCheckOptions {
+    readonly environment: string;
+    readonly config: CompanionConfig;
+    /** 手动检查：无视开关、TTL 与负缓存，强制出网。 */
+    readonly refresh?: boolean;
+    readonly fetch?: Fetcher;
+    readonly now?: () => number;
+    readonly ourPackage?: string;
+    readonly repos?: readonly RegistryRepo[];
+}
+/**
+ * 一个单元的四态（纯函数，便于逐态断言）。
+ *
+ * @param input - 事实与版本来源。
+ * @returns 状态。
+ */
+export declare function upgradeStateFor(input: {
+    readonly kind: UpgradeUnitKind;
+    readonly currentVersion: string | null;
+    readonly targetVersion: string | null;
+}): UpgradeState;
+/**
+ * 检查一个环境的升级情况（三类单元 × 四态）。
+ *
+ * 事实来源优先级（Lead 定稿）：① 市场索引缓存（零网络）② npm registry dist-tags（受 TTL 与开关约束）。
+ * 两条都拿不到 = `unknown`（"查不到"），**绝不**显示"已是最新"。
+ *
+ * @param options - 环境、配置与注入缝。
+ * @returns 检查结果。
+ */
+export declare function checkUpgrades(options: UpgradeCheckOptions): Promise<UpgradeCheckResult>;
+/** 升级引擎的共享依赖（全部可注入，测试不碰真 pnpm / 真 registry）。 */
+export interface UpgradeEngineDeps {
+    readonly ctx?: Context;
+    readonly installAnchor?: string;
+    /** 官方运行器覆盖（测试注入）。 */
+    readonly runCommand?: PluginCommandRunner;
+    /** 试装执行器覆盖（测试注入金丝雀结论）。 */
+    readonly trial?: UpgradeTrialRunner;
+    /**
+     * 无头验证覆盖（测试注入"永远挂载成功/失败"）。
+     *
+     * 为什么这条缝必须存在：金丝雀走**真试装引擎**时，它默认会真起一个 dsh 子进程
+     * （15s 超时、约 161 MiB）。单测要验的是"层栈激活"这条逻辑，不是启动器本身，
+     * 所以这里透传引擎既有的注入缝（envManager 的 TrialInstallOptions.verify）。
+     */
+    readonly verify?: (name: string) => Promise<BootVerification>;
+    readonly fetch?: Fetcher;
+    readonly now?: () => number;
+    /** 清理日志回调（测试注入；生产写 <DSH_HOME>/dpmc-trial-cleanup.log）。 */
+    readonly log?: (line: string) => void;
+}
+/**
+ * 走官方通道 `add <spec>`（升级与回滚都是它）。
+ *
+ * @param environment - 目标环境名。
+ * @param spec - 官方 spec（`name@version`、`link:...`、绝对路径…）。
+ * @param deps - 共享依赖。
+ * @returns 官方结果。
+ */
+export declare function runOfficialAdd(environment: string, spec: string, deps?: UpgradeEngineDeps): Promise<PackageResult>;
+/**
+ * 一个包在这个环境里的盘上事实（升级前后各取一次，用来核对"真的变了吗"）。
+ *
+ * @param environment - 环境名。
+ * @param name - 包名。
+ * @returns 面向用户的多行事实。
+ */
+export declare function installFacts(environment: string, name: string): readonly string[];
+/** 金丝雀清理日志路径（与引擎的测试环境清理共用同一份日志与同一行格式）。 */
+export declare function canaryLogPath(): string;
+/**
+ * 金丝雀的"激活"证据：候选装完之后，测试环境的 `dsh.profile.bundles` 里到底有没有它。
+ *
+ * 为什么这条证据是金丝雀成立的前提（真机缺陷，task-80）：官方 reconcile **跳过
+ * `beforeDeps` 里已有的依赖**，所以一个**已装插件的新版本**（正是升级场景）装进测试环境后
+ * 进不了层栈 → 挂载期从不加载它 → 坏候选也会被判 `passed`（假通过）。
+ * 因此"装上了"不等于"验证到了"：只有层栈里真的出现它，这次启动验证才算数。
+ */
+export interface CanaryActivation {
+    /** 候选包名。 */
+    readonly name: string;
+    /** 装完候选后测试环境的层栈（读盘事实）。 */
+    readonly bundles: readonly string[];
+    /** 候选是否真的进了层栈（false = 挂载期不会加载它，这次验证不作数）。 */
+    readonly activated: boolean;
+    /** 是否为了让候选成为"新装"而先执行了官方 remove。 */
+    readonly removedFirst: boolean;
+    /** 那一步的结果说明（成功或失败都如实写）。 */
+    readonly removeNote: string;
+}
+/**
+ * 跑一次金丝雀：在 `<环境>-dpmc` 里把**新版本**装进快照并跑基线/候选两次启动，然后立刻删掉测试环境。
+ *
+ * 四条纪律：
+ *   1. 复用 task-50/75 的试装引擎（含含 web 层环境读官方就绪行的那套形态），不另造验证器；
+ *   2. 候选要先成为"新装"（见 activationFor 的说明），否则升级场景下它永远进不了层栈，
+ *      金丝雀就退化成"什么都没验证"；
+ *   3. `cannot-trial`（没验证）**不是** `passed`：调用方据此拒绝升级；
+ *   4. 测试环境是**一次性资产**：用完即删（不留 14 天），删不掉也如实说，并写清理日志。
+ *
+ * @param environment - 真实环境名。
+ * @param spec - 候选 spec（`name@version`）。
+ * @param config - 本插件配置（试装段决定深度/基线/联网）。
+ * @param deps - 共享依赖（试装执行器可注入）。
+ * @returns 金丝雀报告。
+ */
+export declare function runUpgradeCanary(environment: string, spec: string, config: CompanionConfig, deps?: UpgradeEngineDeps): Promise<UpgradeCanaryReport>;
+/** 一次升级的入参。 */
+export interface UpgradeActionInput extends UpgradeEngineDeps {
+    readonly environment: string;
+    readonly name: string;
+    /** 目标版本（来自检查结果的 targetVersion 或用户挑的 tag）。 */
+    readonly version: string;
+    readonly config: CompanionConfig;
+    /** 当前来源（用于判断"升级会改变来源"）。 */
+    readonly spec?: string;
+    /** 显式跳过金丝雀（默认由试装总开关决定）。 */
+    readonly canary?: boolean;
+}
+/**
+ * 升级一个已装包：金丝雀通过（或未做金丝雀）→ 官方 add → 盘上核对。
+ *
+ * 顺序不可颠倒：先验证再动真环境。金丝雀没通过（含 `cannot-trial`）就**不升级**，
+ * 并把试装结论原文作为原因返回——"没验证"绝不当成"通过"。
+ *
+ * @param input - 目标与依赖。
+ * @returns 结果（含 before/after 的盘上事实）。
+ */
+export declare function upgradePackage(input: UpgradeActionInput): Promise<UpgradeActionResult>;
+/**
+ * 回滚一个包到指定版本（或回滚到原来的本地来源）。
+ *
+ * 核对按**盘上事实**：依赖行与 node_modules 里的版本都要对上才算干净；对不上就说对不上
+ * （沿用 task-23 的教训：不许声称"环境未被改动"而留下残留）。
+ *
+ * @param input - 目标与依赖。
+ * @returns 结果。
+ */
+export declare function rollbackUpgrade(input: UpgradeActionInput): Promise<UpgradeRollbackResult>;
+/**
+ * 让某个包的版本事实失效（升级/回滚后必须重新取，不许拿旧事实当新状态）。
+ *
+ * 只删这一个包的条目，**不动**环境记账：记账说的是"这个环境什么时候查过"，
+ * 那件事并没有因为一次升级而改变（升级成功只让**这个包**的版本事实过期）。
+ *
+ * @param name - 包名。
+ */
+export declare function invalidateTagsCache(name: string): void;