dsh-plugin-manager-companion 0.1.0

package/dist/client/upgradeView.d.ts

@@ -0,0 +1,278 @@
+/**
+ * upgradeView.ts — 升级的**纯决策**：四态怎么显示、注册面收哪些包、结果怎么读。
+ *
+ * 归属：A 类·重写（新模块，无旧实现可参考：旧仓库的"升级"只是一句提示文案）。
+ * 旧实现参考：无（旧 dsh-web-plugin-manager 没有升级功能；其市场页只有"可更新 x.y.z"徽标）。
+ * 官方复用：无。本模块**不认识 React、不认识 ctx、不联网、不读盘**——它是可独立测试的
+ *   决策层（与 marketView.ts / tags.ts 同一方法论：把判定抽出来，组件只负责画）。
+ * 前提检查：四态（update-available / up-to-date / unknown / not-upgradable）由 host 的
+ *   upgradeCheck op 直接给出（docs/REST-CONTRACT.md「UpgradeCheckResult.units[].state 四态」），
+ *   界面**直接渲染，不自己推断**。本模块只回答三个界面问题：
+ *   ① 这一行该不该画、画什么；② 官方插件页的 keyed 注册面该注册哪些包名；③ 一次升级结果
+ *   该被读成成功/失败/回滚/没验证。
+ *
+ * 为什么必须有这一层（而不是把判断写进组件）：
+ *   · "靠缺席传达状态"是本仓库反复踩过的坑（DESIGN §5.5 / §12.3.3）。四态里 up-to-date
+ *     与 unknown 都不画升级入口，但它们的**事实完全不同**：前者是"查过，没有更新"，
+ *     后者是"查不到"。把两者的可见性判定收进一个纯函数，测试才能逐个钉住
+ *     "unknown 绝不显示成已是最新"。
+ *   · 注册对账（§5.5：不留孤儿 key）需要一个可断言的集合运算，而不是散在 apply 里的副作用。
+ */
+import type { UpgradeState } from '../types.ts';
+/**
+ * 本模块读的单元形状（host 的 UpgradeUnitReport 是它的超集，wire 的 UpgradeUnitView 也是）。
+ *
+ * 刻意用结构类型而不是 import 契约类型：判定只看这几个字段，
+ * 于是同一份函数既能吃 host 的原始报告（host 侧测试）也能吃归一后的视图（客户端）。
+ */
+export interface UpgradeUnitLike {
+    readonly name: string;
+    readonly state: string;
+    readonly currentVersion: string | null;
+    readonly targetVersion: string | null;
+    readonly targetTag: string | null;
+    readonly tags: readonly UpgradeTagLike[] | null;
+    readonly source?: string;
+    readonly at?: string;
+}
+/**
+ * 升级入口的显示形态。
+ *
+ * 刻意做成**四态一一对应**的枚举（而不是布尔的 canUpgrade）：布尔会把
+ * up-to-date 与 unknown 压成同一个 false，而那正是要防的"靠缺席传达"。
+ */
+export type UpgradeRowKind = 
+/** 有版本事实且比当前新 → 画升级入口（tags 非空时列出让用户挑）。 */
+'upgrade'
+/** 有版本事实、没有更新的 → 插件页**不画**（"已是最新"的口径在市场页/关于页）。 */
+ | 'hidden'
+/** 查不到版本事实 → **必须画**「查不到：<原因>」+ 重试。 */
+ | 'unknown'
+/** 结构上就升不了（安装方提供的层）→ 画说明 + 命令，**不给按钮**。 */
+ | 'command';
+/** 状态值 → 形态（逐态显式表：新增状态时编译期就会在这里暴露，不会静默落进 default）。 */
+export declare const ROW_KIND_OF_STATE: Readonly<Record<UpgradeState, UpgradeRowKind>>;
+/** 四态的稳定顺序（用于断言与文档对照，不用于渲染顺序）。 */
+export declare const ROW_KIND_ORDER: readonly UpgradeRowKind[];
+/**
+ * 一个单元在界面上的形态。
+ *
+ * @param unit - host 给出的单元报告。
+ * @returns 形态；状态值未知时按 unknown 处理（读不懂的状态不能染成"已是最新"，
+ *   也不能给出一个可能无效的升级按钮）。
+ */
+export declare function rowKindOf(unit: {
+    readonly state: string;
+}): UpgradeRowKind;
+/**
+ * 这一行是否要出现在界面上。
+ *
+ * 判据直接来自 DESIGN §5.5 的表格：只有 up-to-date 缺席，其余三态各自有形态。
+ * 这是本模块**唯一**的可见性出口——组件不许再写一份。
+ *
+ * @param unit - host 给出的单元报告。
+ * @returns 要画时 true。
+ */
+export declare function rowVisible(unit: {
+    readonly state: string;
+}): boolean;
+/**
+ * 把一次检查结果折成"包名 → 单元"的查找表。
+ *
+ * 同名条目后到者不覆盖先到者：host 的 unitFacts 按名字去重过，出现重复说明契约被破坏，
+ * 此时保留第一条（并让界面的计数与列表一致）比"悄悄用最后一条"更可解释。
+ *
+ * @param units - 检查结果的单元列表。
+ * @returns 查找表。
+ */
+export declare function unitIndex<T extends {
+    readonly name: string;
+}>(units: readonly T[]): ReadonlyMap<string, T>;
+/**
+ * 注册面的**目标集合**：该为哪些包名持有 plugins.bundle.config 的 key。
+ *
+ * 判据 = **已装** ∧ （还没查过 ∨ 这一态要显示）。两种情况都在集合里：
+ *
+ *   ① **还没查过**（units 为 undefined，或这一轮检查里没有这个包）→ 注册。
+ *      这是必须的，而且有两个理由：
+ *        · 诚实：此时界面画的是"尚未检查 + 检查按钮"，而不是一片安静——
+ *          "查不到"与"没查"都必须说出来（§12.3.3：不许用缺席表达状态）；
+ *        · 因果：检查正是由**行自己挂载时的 effect** 触发的（§5.5 的"进入即查"）。
+ *          若先要求"查过才注册"，就永远没有东西去触发那次检查（先有鸡还是先有蛋）。
+ *   ② **查过且要显示**（update-available / unknown / not-upgradable）→ 注册；
+ *      **查过且 up-to-date** → 不注册，于是那个 key 的 disposer 被释放，
+ *      官方 config-ledger 重算，那一节**当场消失**（§5.5 的回收纪律）。
+ *
+ * 与 {@link rowVisible} 分开的理由：它们回答不同的问题——"这一行要不要画"（渲染期）与
+ * "这个 key 要不要注册"（装配期）。合并会让"不画"变成"不注册"，而 keyed slot 的 key
+ * 一旦撤掉那一节会**当场消失**（§5.5 要的正是这个），所以两者必须能被分别断言。
+ *
+ * @param installed - 当前已装的包名（官方台账）。
+ * @param units - 最新一次检查的单元列表；还没检查时为 undefined。
+ * @returns 要注册的包名（去重、稳定顺序：按名字排序）。
+ */
+export declare function registeredNames(installed: Iterable<string>, units: readonly {
+    readonly name: string;
+    readonly state: string;
+}[] | undefined): string[];
+/**
+ * 默认选中的 tag。
+ *
+ * 口径与 host 的 pickTarget 一致（同线最新优先），但**不重算**：host 已经在
+ * unit.targetTag 里给了答案，这里只是"把那个 tag 在列表里找出来"。找不到时退到
+ * preferred 标记，再退到第一个——绝不返回一个不在列表里的 tag。
+ *
+ * @param unit - 单元报告。
+ * @returns 选中的 tag 名；没有可选 tag 时 undefined（此时不给"挑版本"）。
+ */
+export declare function defaultTag(unit: {
+    readonly tags: readonly UpgradeTagLike[] | null;
+    readonly targetTag: string | null;
+}): string | undefined;
+/**
+ * 本模块只读 dist-tag 的这四个字段（host 的 UpgradeTag 是它的超集）。
+ *
+ * line 是宽松的 string：host 新增一档版本线时，界面要能如实显示，而不是被一个窄联合
+ * 挡在编译期之外。判定只对 'other-line' 取真（其余一律按"同线/未知"处理，宁可少提醒一次
+ * 也不谎报"会切到另一条线"）。
+ */
+export interface UpgradeTagLike {
+    readonly tag: string;
+    readonly version: string;
+    readonly line: string;
+    readonly preferred: boolean;
+}
+/**
+ * 用户挑的 tag 对应的版本。
+ *
+ * @param unit - 单元报告。
+ * @param tag - 选中的 tag 名；undefined 时用 {@link defaultTag}。
+ * @returns 版本；没有可选 tag 时退回 host 给的 targetVersion。
+ */
+export declare function versionForTag(unit: {
+    readonly tags: readonly UpgradeTagLike[] | null;
+    readonly targetTag: string | null;
+    readonly targetVersion: string | null;
+}, tag?: string): string | null;
+/**
+ * 所选版本是不是**切到另一条线**。
+ *
+ * 判据用 host 给的 UpgradeTag.line，不在这里重算版本线（那是 host 的 versionLine）。
+ *
+ * @param unit - 单元报告。
+ * @param tag - 选中的 tag 名。
+ * @returns 会切到另一条线时 true。
+ */
+export declare function changesLine(unit: {
+    readonly tags: readonly UpgradeTagLike[] | null;
+    readonly targetTag: string | null;
+}, tag?: string): boolean;
+/**
+ * 所选版本与当前版本是否相同（相同时不给可点按钮，DESIGN §5.5）。
+ *
+ * @param unit - 单元报告。
+ * @param tag - 选中的 tag 名。
+ * @returns 相同时 true。
+ */
+export declare function sameAsCurrent(unit: {
+    readonly tags: readonly UpgradeTagLike[] | null;
+    readonly targetTag: string | null;
+    readonly currentVersion: string | null;
+    readonly targetVersion: string | null;
+}, tag?: string): boolean;
+/**
+ * 「当前 x → y ｜ 升级」里的版本对，缺失时给 null 让界面显示"未知"而不是编一个。
+ *
+ * @param unit - 单元报告。
+ * @param tag - 选中的 tag 名。
+ * @returns 当前版本与目标版本。
+ */
+export declare function versionPair(unit: {
+    readonly currentVersion: string | null;
+    readonly tags: readonly UpgradeTagLike[] | null;
+    readonly targetTag: string | null;
+    readonly targetVersion: string | null;
+}, tag?: string): {
+    readonly from: string | null;
+    readonly to: string | null;
+};
+/**
+ * 「来源与时间」这一行要显示什么。
+ *
+ * 契约要求界面**必须**把事实来源与时间标出来（否则"最新"这个断言没有依据）。
+ * 来源未知时返回 undefined（不编一个来源出来）。
+ *
+ * @param unit - 单元报告。
+ * @returns 来源标识与时间；来源未知时 undefined。
+ */
+export declare function sourceFacts(unit: {
+    readonly source?: string;
+    readonly at?: string;
+}): {
+    readonly source: 'market-index' | 'registry';
+    readonly at: string | undefined;
+} | undefined;
+/**
+ * 升级结果的**诚实分类**。
+ *
+ * 这是本模块最要紧的一条：失败态绝不能被渲染成完成（task-14/18/85 那一类问题的第四次机会）。
+ * 分类刻意按"用户该知道什么"切，而不是按 host 的错误码切：
+ *   · done：真升级成功；
+ *   · rolled-back：试装没通过 → **没有在真实环境执行升级**（host 返回 canary-not-passed）；
+ *   · failed：官方通道失败或盘上核对没到位；
+ *   · unverified：金丝雀**没跑**就升级了 —— "没验证"既不是通过也不是失败，
+ *     它必须能被看出来（否则用户以为验证过了）。
+ */
+export type UpgradeOutcomeKind = 'done' | 'rolled-back' | 'failed' | 'unverified';
+/**
+ * 读一次升级结果。
+ *
+ * @param result - host 的 upgrade op 结果（已归一）。
+ * @returns 分类。
+ */
+export declare function upgradeOutcome(result: {
+    readonly ok: boolean;
+    readonly code?: string;
+    readonly canary?: {
+        readonly ran: boolean;
+        readonly conclusion?: string;
+    };
+}): UpgradeOutcomeKind;
+/**
+ * 金丝雀的读法：**"没验证"与"验证失败"必须分开**。
+ *
+ * @param canary - 升级结果里的金丝雀报告；没有时为 undefined。
+ * @returns 四态；没有金丝雀字段时 absent（宿主没给，界面据此不宣称任何结论）。
+ */
+export declare function canaryVerdict(canary: {
+    readonly ran: boolean;
+    readonly conclusion?: string;
+} | undefined): 'passed' | 'failed' | 'not-run' | 'absent';
+/**
+ * 一次升级/回滚结果里"盘上事实"是否真的对上了。
+ *
+ * 回滚用的是 host 的 clean（它按盘上事实核对过）；升级用的是 ok。
+ * 两者都不是"我们没看到报错"——**没看到不等于核对过**。
+ *
+ * @param result - 升级或回滚结果。
+ * @returns 核对通过时 true；载荷缺字段时 false（读不出来不算核对过）。
+ */
+export declare function diskVerified(result: {
+    readonly ok: boolean;
+    readonly clean?: boolean;
+}): boolean;
+/**
+ * 市场卡片上要不要画「升级到 x.y.z」。
+ *
+ * 零新机制：用既有的 updateAvailable 判据（marketView.ts）与 latestVersion。
+ * 未安装、无更新、或版本读不到时都不出现。
+ *
+ * @param item - 市场条目（只读它关心的字段）。
+ * @param updateAvailable - marketView 的判据（注入以便复用同一份实现，不抄第二份）。
+ * @returns 目标版本；不画时 undefined。
+ */
+export declare function marketUpgradeTarget<T extends {
+    readonly installed?: boolean;
+    readonly installedVersion?: string;
+    readonly latestVersion?: string;
+}>(item: T, updateAvailable: (item: T) => boolean): string | undefined;

package/dist/client/wire.d.ts

@@ -0,0 +1,401 @@
+/**
+ * wire.ts — 把外来的 JSON（自有 REST / 官方 settings）归一成组件可以安全读取的对象。
+ *
+ * 归属：A 类·重写（旧仓库客户端对线缆数据一律 `as` 断言后直接渲染；本模块是新契约的
+ *   失败模式驱动的，没有可参考的旧实现）。
+ * 旧实现参考：dsh-web-plugin-manager/src/client/*（旧实现同样信任 host 返回的形状；
+ *   未复制代码——差异是刻意的：旧实现把"数据一定齐全"当作前提，而实测证明它不成立）。
+ * 官方复用：无。官方 primitives 只渲染、不校验；官方 settings 的 SettingsScopeController
+ *   自带 schema 校验（packages/client/ui-settings/src/client/settings-scope.ts:202），
+ *   但那只覆盖**官方 settings 通道**，本插件的自有 REST 通道没有这层保护。
+ * 前提检查："外部数据一定符合 src/types.ts 声明的形状"这个前提**已被实测证伪**：
+ *   host 的 JobRegistry.start() 返回裸 job id 字符串（docs/REST-CONTRACT.md 写的是
+ *   `{ jobId }`），客户端把字符串当成报告，HealthPanel 在 `report.counts[layer]` 上抛
+ *   TypeError，官方 SlotErrorBoundary 渲染一个空 div —— 用户看到的就是整页空白。
+ *
+ * 纪律（本模块存在的全部理由）：
+ *   1. 归一**只发生在数据入口**（shared.ts 的控制器），组件里不再散落 `?? []`；
+ *      这样"能通过类型检查的字段"与"运行期真的存在的字段"重新合一。
+ *   2. 归一**不编造事实**：缺字段补的是"空/未知"（[] / 0 / undefined），不是看似合理的值；
+ *      整份载荷不可用（不是对象、缺关键标识）时返回 undefined，由控制器如实报"失败"。
+ *   3. 归一**不吞发现**：诊断报告里的每条 issue 都保留（枚举值未知时保留原值，
+ *      由组件回退成原始 id 显示），不因为一个字段不认识就丢掉这条发现。
+ *
+ * 类型纪律：`src/types.ts` 是 wire 契约的唯一权威；本模块只做"运行期兑现契约"，
+ * 不新增字段、不改语义。归一后的对象带完整类型，组件按类型读即可。
+ */
+import type { DiagnosticLayer, DiagnosticReport, EnvironmentBackup, EnvironmentBackupDiff, EnvironmentInfo, EnvironmentResult, GatedInstallResult, KindListResult, MarketplaceResult } from '../types.ts';
+import type { OfficialCapabilities } from '../official.ts';
+import type { CompanionConfig, TrialConfig } from '../settings.ts';
+/**
+ * 归一官方能力探针。
+ *
+ * 界面只读 `missing`（哪里能力缺失要如实告诉用户）。探针读不到时返回 undefined，
+ * 调用方保持"未探到"，绝不伪造"能力齐全"。
+ *
+ * @param raw - capabilities op 的原始值。
+ * @returns 探针结果；不可用时 undefined。
+ */
+export declare function normalizeCapabilities(raw: unknown): OfficialCapabilities | undefined;
+/**
+ * 一条可能读不到的事实（与 host 的 `AboutFact<T>` 同构）。
+ *
+ * 客户端**不做**二次归一（例如把 unknown 折成空串）：那会抹掉"读不到"与"读到了空值"的区别，
+ * 而界面正是靠这个区别决定显示"未知"还是显示值（§12.3.3）。
+ */
+export type AboutFactView<T> = {
+    readonly value: T;
+    readonly source: string;
+} | {
+    readonly unknown: string;
+};
+/** 「关于」页的全部事实（客户端视图）。 */
+export interface AboutFactsView {
+    readonly runtime: {
+        readonly version: AboutFactView<string>;
+        readonly installAnchor: AboutFactView<string>;
+    };
+    readonly process: {
+        readonly node: AboutFactView<string>;
+        readonly platform: AboutFactView<string>;
+        readonly arch: AboutFactView<string>;
+    };
+    readonly companion: {
+        readonly version: AboutFactView<string>;
+    };
+    readonly profile: {
+        readonly name: AboutFactView<string>;
+        readonly dir: AboutFactView<string>;
+    };
+    readonly files: {
+        readonly settingsPath: AboutFactView<string>;
+        readonly registryCachePath: AboutFactView<string>;
+        readonly registryCacheAgeMs: AboutFactView<number>;
+    };
+}
+/**
+ * 归一 `about` op 的结果。
+ *
+ * @param raw - op 的原始值。
+ * @returns 视图；载荷整体不可用时 undefined（界面显示"读不到"并给重试，而不是画一张空表）。
+ */
+export declare function normalizeAbout(raw: unknown): AboutFactsView | undefined;
+/**
+ * 归一一次诊断的报告。
+ *
+ * 各层计数由**归一后的发现**重新统计（而不是信线缆上的 counts）：界面上的"各层计数"
+ * 必须与用户能数出来的列表一致，两者矛盾时以列表为准。传入的 `layers` 决定总览网格
+ * 里哪些层有确定的 0 值（缺层不能渲染成 undefined）。
+ *
+ * @param raw - diagnose job 的结果。
+ * @param layers - 已知的层（本插件来自 shared.ts 的 LAYER_ORDER）。
+ * @returns 报告；整份载荷不可用时 undefined（调用方如实报失败，不渲染半个报告）。
+ */
+export declare function normalizeReport(raw: unknown, layers: readonly DiagnosticLayer[]): DiagnosticReport | undefined;
+/**
+ * 归一环境列表。
+ *
+ * 环境名是这张表的唯一标识（也是后续所有跨环境操作的参数），缺名字的项无法渲染也
+ * 无法操作，直接丢弃。
+ *
+ * @param raw - listEnvironments op 的结果。
+ * @returns 环境列表；载荷不可用（不是数组）时 undefined。
+ */
+export declare function normalizeEnvironments(raw: unknown): EnvironmentInfo[] | undefined;
+/**
+ * 归一一次变更类操作的结果。
+ *
+ * `output` 是给用户看的原始诊断，缺失时不能把 undefined 塞进 Toast（那会渲染成空提示）。
+ *
+ * @param raw - 操作结果。
+ * @returns 结果；不是对象时按失败处理（ok=false），绝不当作成功。
+ */
+export declare function normalizeEnvironmentResult(raw: unknown): EnvironmentResult;
+/**
+ * 归一一份环境备份（导出结果与用户导入的文件走同一个入口）。
+ *
+ * 归一失败意味着"这不是本插件的备份"：`backupRestore` 会据此改写目标环境的 manifest，
+ * 宁可拒绝也不能猜。
+ *
+ * @param raw - 备份文档。
+ * @returns 备份；形状不符时 undefined。
+ */
+export declare function normalizeBackup(raw: unknown): EnvironmentBackup | undefined;
+/**
+ * 归一备份差异。
+ *
+ * 五个分类都会渲染，缺一个就是渲染期崩溃——所以每一类都归一成数组。
+ *
+ * @param raw - backupDiff op 的结果。
+ * @returns 差异；载荷不可用时 undefined。
+ */
+export declare function normalizeBackupDiff(raw: unknown): EnvironmentBackupDiff | undefined;
+/**
+ * 归一市场查询结果。
+ *
+ * @param raw - marketplace op 的结果。
+ * @returns 结果；载荷不可用时 undefined。
+ */
+export declare function normalizeMarketplace(raw: unknown): MarketplaceResult | undefined;
+/**
+ * 归一受质量门保护的安装结果。
+ *
+ * @param raw - install op 的结果。
+ * @returns 结果；载荷不可用时按失败处理。
+ */
+export declare function normalizeGatedInstall(raw: unknown): GatedInstallView;
+/**
+ * 一次安装里的试装结论（客户端视图）。
+ *
+ * 枚举值（conclusion / policy / depth / baseline / candidate）**原样保留字符串**，
+ * 不在这里映射成已知集合：宿主新增一档结论时，界面要能如实显示原始值，而不是把它吞掉
+ * 或猜成最接近的一档（本模块纪律 3：归一不吞发现）。文案映射在组件层，未知值回退显示原值。
+ */
+export interface TrialOutcomeView {
+    readonly conclusion: string;
+    readonly policy: string;
+    readonly policyNote: string;
+    readonly output: string;
+    readonly elapsedMs: number;
+    readonly escalated: boolean;
+    readonly depth?: string;
+    readonly escalationReason?: string;
+    readonly baseline?: string;
+    readonly candidate?: string;
+}
+/** 受质量门保护的安装结果的客户端视图：`trial` 换成上面那个视图。 */
+export type GatedInstallView = Omit<GatedInstallResult, 'trial'> & {
+    readonly trial?: TrialOutcomeView;
+};
+/**
+ * 试装开启前必须让用户看到的事实。
+ *
+ * 数字与口径**必须一起**给出：只有数字没有 measurement 时返回 undefined（宁可不显示，
+ * 也不给一个没有口径的数字——那正是"把不知道说成知道"）。
+ */
+export interface TrialDisclosureView {
+    readonly executesCandidateCode: boolean;
+    readonly peakMemoryMiB: number;
+    readonly measurement: string;
+}
+/**
+ * 归一试装告知事实（来自 capabilities op 的 `trialDisclosure`）。
+ *
+ * @param raw - `capabilities.trialDisclosure`。
+ * @returns 告知事实；数字或口径缺失/不可读时 undefined（界面显示"未知"，不硬编码）。
+ */
+export declare function normalizeTrialDisclosure(raw: unknown): TrialDisclosureView | undefined;
+/**
+ * 一个测试环境（`<真实环境名>-dpmc`）的只读事实。
+ *
+ * 布尔事实用 `undefined` 表示"宿主没给"，而不是 `false`：`false` 是一个结论
+ * （"不在运行"、"归属环境没了"），不能拿它顶替"读不到"（DESIGN §12.3.3）。
+ */
+export interface TrialEnvironmentView {
+    readonly name: string;
+    readonly owner: string;
+    readonly ownerExists: boolean | undefined;
+    readonly dir: string;
+    readonly running: boolean | undefined;
+    readonly modifiedAt: string;
+    readonly ageDays: number | undefined;
+    readonly bytes: number | null;
+    readonly bytesReason?: string;
+    readonly files: number;
+    readonly sharedFiles: number;
+    readonly snapshotMatchesOwner: boolean | null;
+}
+/** 试装环境查询结果的客户端视图（`trialEnvironments` op）。 */
+export interface TrialEnvironmentsView {
+    readonly environments: readonly TrialEnvironmentView[];
+    readonly factsReadable: boolean | undefined;
+    readonly factsReason?: string;
+    readonly totals: {
+        readonly count: number;
+        readonly running: number | undefined;
+        readonly bytes: number;
+        readonly unknownBytes: number;
+    };
+    readonly retention: {
+        readonly days: number;
+        readonly autoCleanup: boolean;
+        readonly maxKept: number;
+    } | undefined;
+    readonly plan: {
+        readonly remove: readonly {
+            readonly name: string;
+            readonly reason: string;
+        }[];
+        readonly keep: readonly {
+            readonly name: string;
+            readonly reason: string;
+        }[];
+    } | undefined;
+    readonly overCap: boolean | undefined;
+    readonly notes: readonly string[];
+}
+/**
+ * 归一试装环境查询结果。
+ *
+ * @param raw - `trialEnvironments` op 的结果。
+ * @returns 视图；载荷不是对象时 undefined（控制器如实报"失败"，不渲染空列表当"没有测试环境"）。
+ */
+export declare function normalizeTrialEnvironments(raw: unknown): TrialEnvironmentsView | undefined;
+/** 一次清理的结果（`trialCleanup` op）：环境操作结果 + 实际删掉的名字。 */
+export interface TrialCleanupView extends EnvironmentResult {
+    readonly removed: readonly string[];
+}
+/**
+ * 归一一次试装环境清理的结果。
+ *
+ * @param raw - `trialCleanup` op 的结果。
+ * @returns 结果；载荷不可用时按失败处理（沿用环境操作结果的归一口径）。
+ */
+export declare function normalizeTrialCleanup(raw: unknown): TrialCleanupView;
+/**
+ * 归一技能与预设列表。
+ *
+ * @param raw - listKinds op 的结果。
+ * @returns 结果；载荷不可用时 undefined。
+ */
+export declare function normalizeKindList(raw: unknown): KindListResult | undefined;
+/**
+ * 归一后的插件配置。
+ *
+ * 与 host 侧 {@link CompanionConfig} 的唯一差别：`trial` 在 host 类型里是**可选**字段
+ * （见 src/settings.ts 的说明），而归一后它一定存在——客户端不假设宿主给了它。
+ */
+export type ClientConfig = CompanionConfig & {
+    readonly trial: TrialConfig;
+};
+/** 归一后的配置与"哪些字段是补出来的"。 */
+export interface NormalizedConfig {
+    readonly config: ClientConfig;
+    /** 由默认值补上的字段路径（用于如实告诉用户：这不是宿主给的完整配置）。 */
+    readonly filled: readonly string[];
+}
+/**
+ * 归一插件配置：逐字段校验，缺失/类型不符的用客户端默认值补齐。
+ *
+ * 为什么是"补齐后渲染"而不是"提示尚未就绪"：这个表单写的是**字段级** op（官方 settings
+ * 的 mutate 按路径写），补出来的字段不会被回写；而用户点开设置页的目的正是看到并改一个
+ * 具体字段——空白或只有一句提示等于什么都做不了。补的是默认值这一事实会通过
+ * `filled` 如实显示出来，不伪装成"宿主就是这么配的"。
+ *
+ * @param raw - settings 快照里的命名空间值（允许残缺）。
+ * @returns 归一后的配置与补出来的字段；`raw` 不是对象时 undefined（连一个字段都没有）。
+ */
+export declare function normalizeConfig(raw: unknown): NormalizedConfig | undefined;
+/**
+ * 一条 dist-tag 的客户端视图。
+ *
+ * line 与 preferred **原样保留字符串/布尔**，不在这里映射成已知集合：host 新增一档线时，
+ * 界面要能如实显示（未知线一律按"另一条线"提示，宁可多提醒一次也不谎报"同线"）。
+ */
+export interface UpgradeTagView {
+    readonly tag: string;
+    readonly version: string;
+    readonly line: string;
+    readonly preferred: boolean;
+}
+/**
+ * 一个升级单元的客户端视图。
+ *
+ * state 原样保留：四态由 host 判定（docs/REST-CONTRACT.md），客户端**不自己推断**
+ * （wire.ts 纪律 3：归一不吞发现）。未知状态值由 upgradeView.rowKindOf 归到 unknown，
+ * 界面据此显示"查不到"而不是"已是最新"。
+ */
+export interface UpgradeUnitView {
+    readonly name: string;
+    readonly kind: string;
+    readonly state: string;
+    readonly currentVersion: string | null;
+    readonly currentLine: string | null;
+    readonly spec?: string;
+    readonly targetVersion: string | null;
+    readonly targetTag: string | null;
+    readonly targetLine: string | null;
+    readonly tags: readonly UpgradeTagView[] | null;
+    readonly source?: string;
+    readonly at?: string;
+    readonly reason?: string;
+    readonly changesSource?: boolean;
+    readonly command?: string;
+}
+/** 升级检查结果的客户端视图（op: upgradeCheck）。 */
+export interface UpgradeCheckView {
+    readonly environment: string;
+    readonly units: readonly UpgradeUnitView[];
+    readonly checked: boolean;
+    readonly lastCheckAt: string | null;
+    readonly notes: readonly string[];
+}
+/**
+ * 归一一次升级检查结果。
+ *
+ * 载荷不是对象时返回 undefined：控制器据此如实报"失败"，**绝不**把它画成"没有可升级的包"
+ * （那是把故障说成结论）。units 缺失时给空数组——"宿主说了一个单元都没有"与"读不出来"
+ * 在契约里是两回事，前者合法。
+ *
+ * @param raw - upgradeCheck op 的结果。
+ * @returns 视图；载荷不可用时 undefined。
+ */
+export declare function normalizeUpgradeCheck(raw: unknown): UpgradeCheckView | undefined;
+/**
+ * 一次升级的金丝雀（试装）结论的客户端视图。
+ *
+ * ran 与 conclusion **都保留**：ran===false 时 conclusion 缺省，界面必须能从 ran 看出
+ * "这次没验证"（DESIGN §5.5：没验证不等于通过）。
+ */
+export interface UpgradeCanaryView {
+    readonly ran: boolean;
+    readonly conclusion?: string;
+    readonly depth?: string;
+    readonly escalated: boolean;
+    readonly elapsedMs?: number;
+    readonly output?: string;
+    readonly skippedReason?: string;
+    readonly cleanup: string;
+    readonly activated?: boolean;
+    readonly bundles?: readonly string[];
+}
+/** 一次升级结果的客户端视图（op: upgrade）。 */
+export interface UpgradeActionView extends EnvironmentResult {
+    readonly name: string;
+    readonly fromVersion: string | null;
+    readonly toVersion: string;
+    readonly spec: string;
+    readonly canary?: UpgradeCanaryView;
+    readonly diskFacts: readonly string[];
+    readonly restartRequired: boolean;
+}
+/**
+ * 归一一次升级结果。
+ *
+ * 沿用环境操作结果的归一口径：载荷不可用时按失败处理（ok=false），绝不当作成功。
+ * canary 缺失时**不补**一个"没跑"——"宿主没给这个字段"与"金丝雀没跑"是两件事，
+ * 前者界面不许宣称任何验证结论。
+ *
+ * @param raw - upgrade op 的结果。
+ * @returns 视图。
+ */
+export declare function normalizeUpgradeAction(raw: unknown): UpgradeActionView;
+/** 一次回滚结果的客户端视图（op: upgradeRollback）。 */
+export interface UpgradeRollbackView extends EnvironmentResult {
+    readonly name: string;
+    readonly fromVersion: string | null;
+    readonly toVersion: string;
+    readonly diskFacts: readonly string[];
+    /** 盘上核对是否一致；读不出来时 undefined（**不是** false——"读不出来"不是"不干净"）。 */
+    readonly clean: boolean | undefined;
+}
+/**
+ * 归一一次回滚结果。
+ *
+ * clean 读不出来时给 undefined 而不是 false：false 是一个结论（"有残留"），
+ * 不能拿它顶替"读不到"（DESIGN §12.3.3）。
+ *
+ * @param raw - upgradeRollback op 的结果。
+ * @returns 视图。
+ */
+export declare function normalizeUpgradeRollback(raw: unknown): UpgradeRollbackView;