dsh-plugin-update 0.2.0 → 0.3.0

package/dist/panel.d.ts

@@ -0,0 +1,256 @@
+import { type VisibleQueue } from './queue.js';
+import type { BlockedReason, UpdateSnapshot } from './ports.js';
+/** 摆放形态：默认内嵌，切弹窗走同一参数。 */
+export type UpdatePanelMode = 'embedded' | 'dialog';
+/** 面板主题：默认最小可用样式；`d5-paper` 为可选 D5 档案卷专业主题（只换肤，不换 DOM 顺序）。 */
+export type UpdatePanelTheme = 'default' | 'd5-paper';
+/** 与宿主通话的传输函数：面板只认这个签名，不认任何宿主对象的具体形状。 */
+export type UpdatePanelCall = (phoneName: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/** 复制文本的出口：不传即尝试浏览器剪贴板，都没有则只留“已生成、请手动复制”提示。 */
+export type UpdatePanelCopyText = (text: string) => void | Promise<void>;
+/** 面板可点的动作（与 HTML 里 data-action 一一对应，测试走同一条路）。 */
+export type UpdatePanelActionKind = 'check' | 'install' | 'skip' | 'reset-skip' | 'copy-manual' | 'copy-diag' | 'toggle-queue' | 'restart-hint' | 'close-view';
+export interface UpdatePanelOptions {
+    /** 插件标识：必填，与宿主侧 createHostUpdate 传的 pluginId 一致。 */
+    pluginId: string;
+    /** 电话名前缀：默认 wf，必须与宿主侧一致（取值只从这里算，不写字面量）。 */
+    prefix?: string;
+    /** 摆放形态：默认内嵌。 */
+    mode?: UpdatePanelMode;
+    /** 面板主题：默认 `default`（最小可用样式，一字不动）；传 `d5-paper` 切 D5 档案卷可选主题。 */
+    theme?: UpdatePanelTheme;
+    /** 是否看他人排队明细：默认只看自己的（他人仅露正忙占位，位置照给）。 */
+    showOthers?: boolean;
+    /** 轮询间隔毫秒：默认 1000，不得小于 250。 */
+    pollMs?: number;
+    /** 与宿主通话的函数（面板侧唯一的宿主接触面）。 */
+    call: UpdatePanelCall;
+    copyText?: UpdatePanelCopyText;
+    skipStore?: PanelSkipStore;
+    /** 宿主种类（调用方知道就传进诊断文本；不传就用宿主 includeEnv 回的宿主种类，再没有显示“未知”）。 */
+    hostKind?: string | null;
+    /**
+     * 使用范围名（profile）：**装到哪个范围**的展示面。不传就用宿主 includeEnv 回的真值；
+     * 两者都没有时显示“未知”，绝不猜（猜错会让人以为更新装到了别的范围）。
+     */
+    profileName?: string | null;
+    /**
+     * 「重启宿主」按钮的落地（可选）：宿主没有重启自己的电话，默认点击只提示手动重启；
+     * 调用方能把重启流程接进来（拉起自己的重启脚本/提示用户），按钮就交给它。
+     */
+    onRestartRequested?: () => void | Promise<void>;
+    diagCopyFormat?: DiagCopyFormat;
+    /**
+     * 更新日志 Markdown（#23 包内 CHANGELOG 展示）：
+     * 调用方按“已装版离线读、新版按需取 tarball”备好后传入（取不到传 null/空串即中性提示）；
+     * 面板只渲染不取数，缺日志永不挡安装、不写 blockedReason。
+     */
+    changelogMarkdown?: string | null;
+}
+/** 挂载点：只要有 innerHTML 的容器即可（浏览器元素或测试替身都行）。 */
+export interface UpdatePanelContainer {
+    innerHTML: string;
+    addEventListener?: (type: string, listener: (ev: unknown) => void) => void;
+    removeEventListener?: (type: string, listener: (ev: unknown) => void) => void;
+}
+export interface UpdatePanelController {
+    /** 立刻重查一次并重绘（挂载时自动调一次，重开面板即恢复进度）。 */
+    refresh(): Promise<void>;
+    /** 点一次按钮（DOM 监听只是它的薄适配，测试直接调它）。 */
+    act(kind: UpdatePanelActionKind, arg?: string): Promise<void>;
+    /** 切换摆放（同一状态重绘同一内核，只换外层包裹）。 */
+    setMode(mode: UpdatePanelMode): Promise<void>;
+    /** 切换主题（同一内核重绘，只换肤；默认主题输出与旧版一字不差）。 */
+    setTheme(theme: UpdatePanelTheme): Promise<void>;
+    /** 切换排队可见性（重查一次，位置口径不变）。 */
+    setShowOthers(show: boolean): Promise<void>;
+    /**
+     * 换一版更新日志后重绘（#23：宿主侧备好新文本后调用；传 null/空串即回中性提示）。
+     * 只换日志节，安装门控只跟快照，一字不动。
+     */
+    setChangelogMarkdown(markdown: string | null): void;
+    /** 卸载：只停轮询、只拆监听，绝不中断安装。 */
+    unmount(): void;
+}
+/** 面板本地的跳过读写承诺：按版本记、可重置（宿主侧 skipped.json 是另一套落盘，互不干扰）。 */
+export interface PanelSkipStore {
+    list(): string[];
+    has(version: string): boolean;
+    skip(version: string): void;
+    reset(version?: string): void;
+}
+export interface BlockedCopy {
+    title: string;
+    action: string;
+}
+/** 装不了的原因 → 中文一句话（能装传 null 即回 null，不猜）。 */
+export declare function blockedCopy(reason: BlockedReason | null): BlockedCopy | null;
+export interface FailureCopy {
+    zh: string;
+    act: string;
+}
+/** 14 码全表是否包含该码（8 阻塞 + 5 电话 + internal；未来码不在此列，走兜底）。 */
+export declare function isKnownFailureCode(code: unknown): boolean;
+/**
+ * 稳定码 → 中文一句话（14 码全覆盖；未知码回未来兜底，空码回 null）。
+ * 8 阻塞行复用 BLOCKED_COPY 原文，不另起措辞；面板分支只认返回值，不碰 diag。
+ */
+export declare function failureCopy(code: unknown): FailureCopy | null;
+/**
+ * 失败回包取稳定码：只认 errorKind，error 仅作回退（#22 验收：errorKind=internal 时
+ * 不许误判为查新版失败；包内已把未知码收敛为 error=check-failed/errorKind=internal，
+ * 此时 error 那格不可信）。缺省回 internal，不抛错。
+ */
+export declare function failureCodeOf(reply: {
+    error?: unknown;
+    errorKind?: unknown;
+} | null | undefined, fallback?: unknown): string;
+/** 诊断复制预算（单源：值取 redaction.COPY_BUDGET_CHARS，此处只转出口，老名保留兼容）。 */
+export declare const PANEL_DIAG_MAX_CHARS = 1500;
+/** 复制前把一行文本收干净（确定性：同一输入两次运行逐字节相同；实现见 redaction.sanitizeForCopy）。 */
+export declare function redactForCopy(text: unknown): string;
+export interface PanelDiagnosticInput {
+    pluginId: string;
+    /** 稳定码（失败回包的 errorKind 优先，error 仅回退；任务 message 取前缀码）。 */
+    code: string;
+    /** 脱敏前的详情（任务 message 去掉前缀码剩下的部分，可空）。 */
+    detail?: string | null;
+    runningVersion?: string | null;
+    installedVersion?: string | null;
+    latestVersion?: string | null;
+    hostKind?: string | null;
+    /** 使用范围名：装到哪个 profile 是排错第一信息；不传则那一段不出现（输出与旧版一字不差）。 */
+    profileName?: string | null;
+    queuePosition?: number | null;
+    requestId?: string | null;
+    manual?: string | null;
+    /** 电话侧 diag（#21 落定前多半没有；有则宽容读，无则走显式字段，缺省说人话）。 */
+    diag?: unknown;
+    /** 显式来源（diag 没有时用；有 diag 时显式优先，缺省仍说人话，不留白）。 */
+    route?: string | null;
+    checkId?: string | null;
+}
+/** 组出一段自包含诊断（调用方直接拿去粘工单/issue；粘之前已脱敏，不必手检）。 */
+export declare function buildDiagnosticText(input: PanelDiagnosticInput): string;
+export type DiagCopyFormat = 'block' | 'line';
+export interface TolerantDiag {
+    stage: string | null;
+    route: string | null;
+    method: string | null;
+    httpStatus: number | null;
+    exitCode: number | null;
+    latencyMs: number | null;
+    detail: string | null;
+    targetPackageName: string | null;
+    runningVersion: string | null;
+    latestVersion: string | null;
+    environmentKind: string | null;
+    requestId: string | null;
+    checkId: string | null;
+    registryHost: string | null;
+    action: string | null;
+    /** 目录外的键（如 queuePos 转正前）一律忽略，记在这里仅供排错，不进渲染。 */
+    unknownKeys: string[];
+}
+/** 宽容读 diag：未知键忽略、错类型忽略、缺省当正常（永不抛；面板分支永不用它）。 */
+export declare function readDiagTolerant(diag: unknown): TolerantDiag;
+export interface UpdateDiagCopyInput extends PanelDiagnosticInput {
+    /** 复制形态：默认三行块；单行用于单行输入框，内容顺序与块完全一致。 */
+    format?: DiagCopyFormat;
+}
+/**
+ * 组出 [update-diag] 复制块（双形态同序；调用方直接拿去粘工单/issue，已脱敏）。
+ * 第一性：顺序码→摘要→来源（#18 定），怎么办是面板页脚放最后，不插断三元组；
+ * 缺省即省略（#18）：路由/请求/检查/阶段等缺失即不出现，不占位“未知”；
+ * 插件/版本/宿主/队列恒显（面板侧显式值兜底），摘要缺省给人话，源缺省给人话（省略本身即信息，人读不懂所以必须说）。
+ */
+export declare function buildUpdateDiagCopy(input: UpdateDiagCopyInput): string;
+export declare function createMemorySkipStore(now?: () => number): PanelSkipStore;
+/** 浏览器跳过存储（localStorage 形状即可；没有或写坏退内存，绝不因跳过挡住更新）。 */
+export declare function createBrowserSkipStore(pluginId: string, storage?: unknown, now?: () => number): PanelSkipStore;
+export interface PanelBanner {
+    kind: 'loading' | 'restart' | 'blocked' | 'update' | 'busy' | 'failed' | 'done' | 'idle';
+    title: string;
+    action: string;
+}
+export interface PanelView {
+    banner: PanelBanner;
+    installEnabled: boolean;
+    installLabel: string;
+    skippedLatest: boolean;
+    showManual: boolean;
+    showReset: boolean;
+    queueNote: string | null;
+    /** 大印章（状态词）与小印章（一字）：取值与原型 `d5-paper.html:431-432` 的状态映射一一对应。 */
+    seal: PanelSeal;
+}
+/** 印章色调：与原型 `seal-ink / seal-green / seal-yellow / seal-red` 四个类同名同义。 */
+export type PanelSealTone = 'ink' | 'green' | 'yellow' | 'red';
+export interface PanelSeal {
+    /** 大印章文字：待查 / 可装 / 安装中 / 待重启 / 受阻 / 已最新。 */
+    text: string;
+    /** 小印章文字：查 / 装 / 启 / 阻 / 定（一字，与原型 sealmini 同口径）。 */
+    mini: string;
+    tone: PanelSealTone;
+}
+export interface PanelViewInput {
+    snapshot: UpdateSnapshot | null;
+    manual: string | null;
+    queue: VisibleQueue | null;
+    skippedLatest: boolean;
+    lastError: string | null;
+    /** 失败回包的 errorKind（有则优先于 lastError；internal 时不许误判为查新版失败）。 */
+    errorKind?: string | null;
+    /**
+     * 更新日志 Markdown（#23）：只影响日志节的渲染，不参与安装门控。
+     * 缺省/空串即中性提示；快照六字段与 blockedReason 一字不动。
+     */
+    changelogMarkdown?: string | null;
+}
+export declare function panelViewModel(input: PanelViewInput): PanelView;
+export declare const UPDATE_PANEL_CSS: string;
+export declare const UPDATE_PANEL_D5_CSS: string;
+export interface PanelRenderInput extends PanelViewInput {
+    mode: UpdatePanelMode;
+    showOthers: boolean;
+    pluginId: string;
+    copyNotice: string | null;
+    /** 可选主题：不传即默认（输出与旧版一字不差）；`d5-paper` 切 D5 档案卷。 */
+    theme?: UpdatePanelTheme;
+    /** 使用范围名（profile）：面板「使用范围」一栏的唯一来源，缺省显示“未知”，不猜。 */
+    profileName?: string | null;
+    /** 宿主种类：进诊断文本；缺省显示“未知”。 */
+    hostKind?: string | null;
+    /**
+     * 动作面归谁：`default`（缺省）由内核画动作按钮；`none` 只画内容、不画按钮。
+     * 给「调用方自己提供动作面」的场景（如批量面板的详情：动作由批量面板经自己的通道提供）。
+     * 只读渲染下五章内容、进度条、「已跳过」提示一字不减，只是没有动作按钮。
+     */
+    actions?: 'default' | 'none';
+}
+/** 内核 HTML（双形态行为等价的根：同一视图产出同一内核，只换外层）。 */
+export declare function renderUpdatePanelKernel(input: PanelRenderInput, view: PanelView): string;
+/** 整面板 HTML（含样式；重绘即整体替换 innerHTML，故每次都带 style 也只留一份）。 */
+export declare function renderUpdatePanelHTML(input: PanelRenderInput): string;
+/**
+ * 挂载整组件（面板侧一行即跑）：
+ * ```js
+ * const panel = mountUpdatePanel(document.getElementById('upd'), { pluginId: 'my-plugin', prefix: 'notes', call: host.call })
+ * // …离开时 panel.unmount()（只停轮询，安装在宿主侧继续跑）
+ * ```
+ */
+export declare function mountUpdatePanel(container: UpdatePanelContainer, options: UpdatePanelOptions): UpdatePanelController;
+export { buildPhoneNames as buildPanelPhoneNames } from './config.js';
+export type { PhoneAction as PanelPhoneAction } from './config.js';
+/** 面板轮询口径（默认 1 秒、下限 250 毫秒，与宿主侧同一套）。 */
+export declare const PANEL_POLL: {
+    readonly defaultMs: 1000;
+    readonly minMs: 250;
+};
+export { QUEUE_INTENT_TTL_MS, emptyQueueState, normalizeQueueState, queuePositionOf, isHeadOfQueue, isQueueBusy, visibleQueueFor, } from './queue.js';
+export type { QueuedEntry, QueueOwner, UpdateQueueState, VisibleQueue as PanelVisibleQueue, VisibleQueueOwner } from './queue.js';
+export type { EnvironmentKind as PanelEnvironmentKind } from './ports.js';
+export type { UpdateSnapshot as PanelSnapshot } from './ports.js';
+export type { BlockedReason as PanelBlockedReason } from './ports.js';
+export { CHANGELOG_ALL_CATEGORIES, CHANGELOG_FILENAME, CHANGELOG_FOLDED, CHANGELOG_MAX_BULLETS_PER_SECTION, CHANGELOG_MAX_BULLET_CHARS, CHANGELOG_MAX_CHARS, CHANGELOG_MAX_ENTRIES, CHANGELOG_MUST_SHOW, CHANGELOG_NEUTRAL_HINT, CHANGELOG_NEUTRAL_LINE, changelogForUpdate, hasVisibleSections, isUnreleasedVersion, parseChangelog, renderChangelogHTML, renderChangelogNeutral, renderChangelogSection, selectChangelogEntries, } from './changelog.js';
+export type { ChangelogCategory, ChangelogEntry } from './changelog.js';