dsh-plugin-update 0.2.0 → 0.3.1

package/dist/http.d.ts

@@ -0,0 +1,127 @@
+import { assertPollInterval } from './client.js';
+import { type UpdatePanelContainer, type UpdatePanelController, type UpdatePanelOptions } from './panel.js';
+import { type UpdateEntryController, type UpdateEntryOptions } from './entry.js';
+import { type BatchPanelContainer, type BatchPanelController, type BatchPanelOptions } from './panel-batch.js';
+/** 传输失败码：永不进面板 14 稳定码分支，只走抛异常通道。 */
+export declare const HTTP_TRANSPORT_FAILED = "http-transport-failed";
+/** 抓取超时默认：查 15s / 装 16min（#30 冻结，调用方可覆写 + AbortSignal 透入）。 */
+export declare const DEFAULT_HTTP_CHECK_TIMEOUT_MS = 15000;
+export declare const DEFAULT_HTTP_INSTALL_TIMEOUT_MS: number;
+export declare const DEFAULT_HTTP_STATUS_TIMEOUT_MS = 15000;
+/** 单插件三电话动作名（与 src/config.ts PHONE_ACTIONS 同字面，不另起字面）。 */
+export declare const HTTP_PHONE_ACTIONS: readonly ["updateStatus", "updateCheck", "updateInstall"];
+export type HttpPhoneAction = (typeof HTTP_PHONE_ACTIONS)[number];
+/** 批量五电话动作名（与 src/panel-batch.ts buildBatchPhoneNames 同字面，不另起字面；同一内核）。 */
+export declare const HTTP_BATCH_ACTIONS: readonly ["batchStatus", "batchCheck", "batchInstall", "batchResume", "batchCancel"];
+export type HttpBatchAction = (typeof HTTP_BATCH_ACTIONS)[number];
+/** 逐电话覆写表：键为全电话名（prefix.动作）或短动作名；未知键拒绝。 */
+export type HttpRoutes = Record<string, string>;
+/** 抓取函数形状：与 globalThis.fetch 同形（测试给内存假件）。 */
+export type HttpFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: unknown;
+}) => Promise<unknown>;
+export interface HttpTimeouts {
+    /** 查/状态超时毫秒（默认 15s）。 */
+    checkMs?: number;
+    /** 装超时毫秒（默认 16min）。 */
+    installMs?: number;
+    /** 状态超时毫秒（默认 15s，与查同值）。 */
+    statusMs?: number;
+}
+export interface CreateHttpCallOptions {
+    /** 单插件电话前缀（与宿主侧一致；电话名从它算出，不写字面量）。 */
+    prefix: string;
+    /** 批量电话前缀（独立于单插件前缀；给了即同时校验批量五电话键，同一内核）。 */
+    batchPrefix?: string;
+    /** 网关根：默认路径 = 网关根 + 全电话名（首尾斜杠归一）。 */
+    baseUrl: string;
+    /** 电话级覆写表（routes[全电话名] ?? routes[短动作] ?? 默认拼接）。 */
+    routes?: HttpRoutes;
+    /** 抓取注入点（不传即 globalThis.fetch；测试给假件）。 */
+    fetch?: HttpFetch;
+    /** 同上别名（与 fetch 二选一，fetch 优先）。 */
+    fetchImpl?: HttpFetch;
+    /** 超时覆写：数字即全电话统一；对象即按电话分设。 */
+    timeout?: number | HttpTimeouts;
+    /** 同上别名（与 timeout 二选一，timeout 优先）。 */
+    timeoutMs?: number | HttpTimeouts;
+}
+/** 覆写表未知键拒绝（创建即抛， fail-fast）。 */
+export declare function assertHttpRoutes(routes: HttpRoutes | undefined, prefix: string, batchPrefix?: string): void;
+/** 电话名 → POST 路径（默认拼接 + 电话级覆写 + 缺键回落 + 斜杠归一）。 */
+export declare function resolveHttpPath(options: {
+    prefix: string;
+    batchPrefix?: string;
+    baseUrl: string;
+    routes?: HttpRoutes;
+}, phoneName: string): string;
+/** 传输失败：断网/非 2xx/JSON 非法/超时，永不进稳定码分支。 */
+export declare function httpTransportFailed(reason: string, detail?: unknown): Error & {
+    code: string;
+    detail: string;
+};
+/** diag 宽容读：只留 16 键（DIAG_KEYS），detail 脱敏；diagnostic 原话丢弃。 */
+export declare function pickHttpDiag(raw: unknown): Record<string, unknown> | undefined;
+/** 回包整形：diagnostic 丢弃，diag 过滤，其余（queue/env/session/rows/progress/未知键）原样透传。
+ *
+ * 批量行内同理：rows[i].diagnostic 丢弃，rows[i].diag 只留 16 键且 detail 脱敏；
+ * 行内 queue/manual/snapshot/phoneNames 等原样透传（排队/续跑语义不裁剪）。 */
+export declare function shapeHttpReply(parsed: unknown): Record<string, unknown>;
+/** 建 HTTP 通话函数：(phoneName, args) => Promise<reply>，回包全透传，失败抛异常。 */
+export declare function createHttpCall(options: CreateHttpCallOptions): (phoneName: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+export interface UpdatePanelHttpOptions extends Omit<UpdatePanelOptions, "call" | "prefix"> {
+    /** 单插件电话前缀（与宿主侧一致）。 */
+    prefix?: string;
+    /** 网关根（必填）。 */
+    baseUrl: string;
+    /** 电话级覆写表（可选）。 */
+    routes?: HttpRoutes;
+    /** 抓取注入点（可选）。 */
+    fetch?: HttpFetch;
+    fetchImpl?: HttpFetch;
+    /** 超时覆写（可选）。 */
+    timeout?: number | HttpTimeouts;
+    timeoutMs?: number | HttpTimeouts;
+}
+/** 面板整组件 HTTP 直挂：只传三样即跑，内核复用 mountUpdatePanel。 */
+export declare function mountUpdatePanelHttp(container: UpdatePanelContainer, options: UpdatePanelHttpOptions): UpdatePanelController;
+export interface UpdateEntryHttpOptions extends Omit<UpdateEntryOptions, "call" | "prefix"> {
+    /** 单插件电话前缀（与宿主侧一致）。 */
+    prefix?: string;
+    /** 网关根（必填）。 */
+    baseUrl: string;
+    /** 电话级覆写表（可选）。 */
+    routes?: HttpRoutes;
+    /** 抓取注入点（可选）。 */
+    fetch?: HttpFetch;
+    fetchImpl?: HttpFetch;
+    /** 超时覆写（可选）。 */
+    timeout?: number | HttpTimeouts;
+    timeoutMs?: number | HttpTimeouts;
+}
+/** 入口件 HTTP 直挂：内部源码级禁安装电话，内核复用 mountUpdateEntry。 */
+export declare function mountUpdateEntryHttp(container: UpdatePanelContainer, options: UpdateEntryHttpOptions): UpdateEntryController;
+export interface UpdateBatchPanelHttpOptions extends Omit<BatchPanelOptions, "call" | "prefix"> {
+    /** 批量电话前缀（与宿主侧一致；五电话名从它算出，不写字面量）。 */
+    batchPrefix: string;
+    /** 单插件电话前缀（可选；给了即同一内核同时认单三电话，便于同网关共用一张 routes 表）。 */
+    prefix?: string;
+    /** 网关根（必填）。 */
+    baseUrl: string;
+    /** 电话级覆写表（可选；键为全电话名或短动作名，未知键拒绝）。 */
+    routes?: HttpRoutes;
+    /** 抓取注入点（可选）。 */
+    fetch?: HttpFetch;
+    fetchImpl?: HttpFetch;
+    /** 超时覆写（可选；batchInstall 走装时限 16min，其余走查/状态 15s）。 */
+    timeout?: number | HttpTimeouts;
+    timeoutMs?: number | HttpTimeouts;
+}
+/** 批量面板 HTTP 直挂：只传批量前缀加网关根即跑，内核复用 mountUpdateBatchPanel。
+ *
+ * 取消整批走 batchCancel 电话而不走中止等待（语义不混淆）；卸载只停轮询，宿主侧照跑。 */
+export declare function mountUpdateBatchPanelHttp(container: BatchPanelContainer, options: UpdateBatchPanelHttpOptions): BatchPanelController;
+export { assertPollInterval };

package/dist/http.js

@@ -0,0 +1,300 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/http.ts
+import { DEFAULT_PREFIX, assertPrefix } from "./config.js";
+import { assertPollInterval } from "./client.js";
+import { DIAG_KEYS } from "./diag.js";
+import { sanitizeDetail } from "./redaction.js";
+import { mountUpdatePanel } from "./panel.js";
+import { mountUpdateEntry } from "./entry.js";
+import { mountUpdateBatchPanel } from "./panel-batch.js";
+const HTTP_TRANSPORT_FAILED = "http-transport-failed";
+const DEFAULT_HTTP_CHECK_TIMEOUT_MS = 15e3;
+const DEFAULT_HTTP_INSTALL_TIMEOUT_MS = 16 * 6e4;
+const DEFAULT_HTTP_STATUS_TIMEOUT_MS = 15e3;
+const HTTP_PHONE_ACTIONS = ["updateStatus", "updateCheck", "updateInstall"];
+const HTTP_BATCH_ACTIONS = ["batchStatus", "batchCheck", "batchInstall", "batchResume", "batchCancel"];
+function isAbsoluteUrl(value) {
+  return /^https?:\/\//i.test(value);
+}
+function stripRightSlash(value) {
+  return String(value ?? "").replace(/\/+$/, "");
+}
+function joinBase(baseUrl, rel) {
+  const b = stripRightSlash(baseUrl);
+  let r = String(rel ?? "");
+  if (!r) return b;
+  if (!r.startsWith("/")) r = "/" + r;
+  return b + r;
+}
+function shortActionOf(phoneName) {
+  const name = String(phoneName ?? "");
+  const at = name.lastIndexOf(".");
+  return at >= 0 ? name.slice(at + 1) : name;
+}
+function allowedRouteKeys(prefix, batchPrefix) {
+  const out = /* @__PURE__ */ new Set();
+  for (const a of HTTP_PHONE_ACTIONS) {
+    out.add(a);
+    out.add(prefix + "." + a);
+  }
+  if (batchPrefix) {
+    for (const a of HTTP_BATCH_ACTIONS) {
+      out.add(a);
+      out.add(batchPrefix + "." + a);
+    }
+  }
+  return out;
+}
+function assertHttpRoutes(routes, prefix, batchPrefix) {
+  if (!routes) return;
+  const allowed = allowedRouteKeys(prefix, batchPrefix);
+  for (const key of Object.keys(routes)) {
+    if (!allowed.has(key)) {
+      throw new Error("[dsh-plugin-update] routes \u672A\u77E5\u952E\u62D2\u7EDD\uFF1A" + JSON.stringify(key));
+    }
+    const value = routes[key];
+    if (typeof value !== "string" || !value) {
+      throw new Error("[dsh-plugin-update] routes \u503C\u975E\u6CD5\uFF1A" + JSON.stringify(key));
+    }
+  }
+}
+function resolveHttpPath(options, phoneName) {
+  if (typeof phoneName !== "string" || !phoneName) {
+    throw new Error("[dsh-plugin-update] \u7535\u8BDD\u540D\u975E\u6CD5\uFF1A\u987B\u4E3A\u975E\u7A7A\u5B57\u7B26\u4E32");
+  }
+  const routes = options.routes ?? {};
+  assertHttpRoutes(routes, options.prefix, options.batchPrefix);
+  const short = shortActionOf(phoneName);
+  const hit = routes[phoneName] ?? routes[short];
+  if (hit !== void 0) {
+    if (isAbsoluteUrl(hit)) return hit;
+    return joinBase(options.baseUrl, hit);
+  }
+  return joinBase(options.baseUrl, phoneName);
+}
+function httpTransportFailed(reason, detail) {
+  const clean = sanitizeDetail(String(detail ?? reason ?? ""));
+  const err = new Error("[dsh-plugin-update] http-transport-failed: " + reason);
+  err.code = HTTP_TRANSPORT_FAILED;
+  err.detail = clean;
+  return err;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function pickHttpDiag(raw) {
+  if (!isRecord(raw)) return void 0;
+  const out = {};
+  let kept = 0;
+  for (const key of DIAG_KEYS) {
+    const value = raw[key];
+    if (typeof value === "string" || typeof value === "number") {
+      out[key] = key === "detail" ? sanitizeDetail(String(value)) : value;
+      kept++;
+    }
+  }
+  return kept > 0 ? out : void 0;
+}
+function shapeHttpReply(parsed) {
+  if (!isRecord(parsed)) {
+    throw httpTransportFailed("\u56DE\u5305\u5F62\u72B6\u975E\u6CD5", String(parsed).slice(0, 120));
+  }
+  const out = { ...parsed };
+  if ("diagnostic" in out) delete out["diagnostic"];
+  if ("diag" in out) {
+    const kept = pickHttpDiag(out["diag"]);
+    if (kept) out["diag"] = kept;
+    else delete out["diag"];
+  }
+  if (Array.isArray(out["rows"])) {
+    out["rows"] = out["rows"].map((row) => {
+      if (!isRecord(row)) return row;
+      const copy = { ...row };
+      if ("diagnostic" in copy) delete copy["diagnostic"];
+      if ("diag" in copy) {
+        const kept = pickHttpDiag(copy["diag"]);
+        if (kept) copy["diag"] = kept;
+        else delete copy["diag"];
+      }
+      return copy;
+    });
+  }
+  return out;
+}
+function timeoutForPhone(phoneName, timeout) {
+  if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) return timeout;
+  const t = timeout ?? {};
+  if (phoneName.endsWith(".updateInstall") || phoneName.endsWith(".batchInstall")) {
+    if (typeof t.installMs === "number" && Number.isFinite(t.installMs) && t.installMs > 0) return t.installMs;
+    return DEFAULT_HTTP_INSTALL_TIMEOUT_MS;
+  }
+  if (phoneName.endsWith(".updateCheck") || phoneName.endsWith(".batchCheck")) {
+    if (typeof t.checkMs === "number" && Number.isFinite(t.checkMs) && t.checkMs > 0) return t.checkMs;
+    return DEFAULT_HTTP_CHECK_TIMEOUT_MS;
+  }
+  if (typeof t.statusMs === "number" && Number.isFinite(t.statusMs) && t.statusMs > 0) return t.statusMs;
+  if (typeof t.checkMs === "number" && Number.isFinite(t.checkMs) && t.checkMs > 0) return t.checkMs;
+  return DEFAULT_HTTP_STATUS_TIMEOUT_MS;
+}
+function resolveFetchImpl(options) {
+  const impl = options.fetch ?? options.fetchImpl ?? globalThis.fetch;
+  if (typeof impl !== "function") {
+    throw new Error("[dsh-plugin-update] HTTP \u4F20\u8F93\u7F3A\u5C11\u6293\u53D6\u51FD\u6570\uFF1A\u8BF7\u4F20 fetch \u6216\u5728\u6709 globalThis.fetch \u7684\u73AF\u5883\u8FD0\u884C");
+  }
+  return impl;
+}
+function createHttpCall(options) {
+  if (!options || typeof options !== "object") {
+    throw new Error("[dsh-plugin-update] \u5EFA HTTP \u4F20\u8F93\u7F3A\u5C11\u914D\u7F6E\uFF1A\u524D\u7F00 prefix \u4E0E\u7F51\u5173\u6839 baseUrl \u5FC5\u586B");
+  }
+  const prefix = options.prefix;
+  if (typeof prefix !== "string" || !prefix) {
+    throw new Error("[dsh-plugin-update] \u7535\u8BDD\u540D\u524D\u7F00 prefix \u975E\u6CD5\uFF1A\u987B\u4E3A\u975E\u7A7A\u5B57\u7B26\u4E32");
+  }
+  if (prefix.includes(".") || prefix.includes("/") || prefix.includes("\\") || /\s/.test(prefix)) {
+    throw new Error("[dsh-plugin-update] \u7535\u8BDD\u540D\u524D\u7F00 prefix \u975E\u6CD5\uFF1A\u4E0D\u5F97\u542B\u6709\u70B9\u3001\u8DEF\u5F84\u5206\u9694\u7B26\u6216\u7A7A\u767D");
+  }
+  const baseUrl = options.baseUrl;
+  if (typeof baseUrl !== "string" || !baseUrl.trim()) {
+    throw new Error("[dsh-plugin-update] \u7F51\u5173\u6839 baseUrl \u5FC5\u586B\uFF1A\u987B\u4E3A\u975E\u7A7A\u5B57\u7B26\u4E32");
+  }
+  const routes = options.routes ?? {};
+  assertHttpRoutes(routes, prefix, options.batchPrefix);
+  const fetchImpl = resolveFetchImpl(options);
+  const timeout = options.timeout ?? options.timeoutMs;
+  return async function httpCall(phoneName, args) {
+    if (typeof phoneName !== "string" || !phoneName) {
+      throw new Error("[dsh-plugin-update] \u7535\u8BDD\u540D\u975E\u6CD5\uFF1A\u987B\u4E3A\u975E\u7A7A\u5B57\u7B26\u4E32");
+    }
+    const url = resolveHttpPath({ prefix, batchPrefix: options.batchPrefix, baseUrl, routes }, phoneName);
+    const safeArgs = args && typeof args === "object" ? args : {};
+    const timeoutMs = timeoutForPhone(phoneName, timeout);
+    const body = JSON.stringify(stripSignal(safeArgs));
+    const AbortCtor = globalThis.AbortController;
+    const controller = typeof AbortCtor === "function" ? new AbortCtor() : null;
+    const callerSignal = safeArgs["signal"];
+    const onCallerAbort = () => {
+      try {
+        controller?.abort();
+      } catch {
+      }
+    };
+    if (callerSignal && typeof callerSignal.addEventListener === "function") {
+      try {
+        callerSignal.addEventListener.call(callerSignal, "abort", onCallerAbort, { once: true });
+      } catch {
+      }
+    }
+    let res;
+    const fetchPromise = fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body,
+      ...controller ? { signal: controller.signal } : {}
+    });
+    let timeoutTimer = null;
+    void fetchPromise.catch(() => {
+    });
+    try {
+      res = await Promise.race([
+        fetchPromise,
+        new Promise((_, reject) => {
+          timeoutTimer = setTimeout(() => {
+            try {
+              controller?.abort();
+            } catch {
+            }
+            reject(httpTransportFailed("\u8D85\u65F6", "\u6293\u53D6\u8D85\u65F6\uFF08" + String(timeoutMs) + "ms\uFF09\uFF1A" + phoneName));
+          }, timeoutMs);
+        })
+      ]);
+    } catch (e) {
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (e && typeof e === "object" && e.code === HTTP_TRANSPORT_FAILED) throw e;
+      throw httpTransportFailed(isAbortError(e) ? "\u8D85\u65F6\u6216\u53D6\u6D88" : "\u65AD\u7F51\u6216\u6293\u53D6\u5931\u8D25", e instanceof Error ? e.message : String(e));
+    }
+    if (timeoutTimer) clearTimeout(timeoutTimer);
+    const ok = res.ok === true;
+    if (!ok) {
+      const status = res.status;
+      const text2 = await readReplyText(res).catch(() => "");
+      throw httpTransportFailed("\u975E 2xx\uFF08" + String(status ?? "unknown") + "\uFF09", "HTTP " + String(status ?? "?") + ": " + String(text2).slice(0, 120));
+    }
+    const text = await readReplyText(res);
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      throw httpTransportFailed("JSON \u975E\u6CD5", String(text).slice(0, 120));
+    }
+    return shapeHttpReply(parsed);
+  };
+}
+function stripSignal(args) {
+  if (!("signal" in args)) return args;
+  const out = { ...args };
+  delete out["signal"];
+  return out;
+}
+function isAbortError(e) {
+  const name = e.name;
+  return name === "AbortError" || name === "TimeoutError";
+}
+async function readReplyText(res) {
+  const textFn = res.text;
+  if (typeof textFn === "function") return String(await textFn.call(res));
+  const jsonFn = res.json;
+  if (typeof jsonFn === "function") return JSON.stringify(await jsonFn.call(res));
+  throw httpTransportFailed("\u56DE\u5305\u5F62\u72B6\u975E\u6CD5", "\u6293\u53D6\u56DE\u5305\u65E2\u65E0 text() \u4E5F\u65E0 json()");
+}
+function mountUpdatePanelHttp(container, options) {
+  if (!options || typeof options !== "object") {
+    throw new Error("[dsh-plugin-update] \u6302 HTTP \u9762\u677F\u7F3A\u5C11\u914D\u7F6E\uFF1A\u63D2\u4EF6\u6807\u8BC6 pluginId \u4E0E\u7F51\u5173\u6839 baseUrl \u5FC5\u586B");
+  }
+  const prefix = options.prefix ?? DEFAULT_PREFIX;
+  const call = createHttpCall({ prefix, baseUrl: options.baseUrl, routes: options.routes, fetch: options.fetch, fetchImpl: options.fetchImpl, timeout: options.timeout, timeoutMs: options.timeoutMs });
+  const { baseUrl: _b, routes: _r, fetch: _f, fetchImpl: _fi, timeout: _t, timeoutMs: _tm, prefix: _p, ...panelRest } = options;
+  return mountUpdatePanel(container, { ...panelRest, pluginId: options.pluginId, prefix, call });
+}
+function mountUpdateEntryHttp(container, options) {
+  if (!options || typeof options !== "object") {
+    throw new Error("[dsh-plugin-update] \u6302 HTTP \u5165\u53E3\u4EF6\u7F3A\u5C11\u914D\u7F6E\uFF1A\u63D2\u4EF6\u6807\u8BC6 pluginId \u4E0E\u7F51\u5173\u6839 baseUrl \u5FC5\u586B");
+  }
+  const prefix = options.prefix ?? DEFAULT_PREFIX;
+  const rawCall = createHttpCall({ prefix, baseUrl: options.baseUrl, routes: options.routes, fetch: options.fetch, fetchImpl: options.fetchImpl, timeout: options.timeout, timeoutMs: options.timeoutMs });
+  const guarded = async (name, args) => {
+    if (shortActionOf(name) === "updateInstall") {
+      throw new Error("[dsh-plugin-update] \u5165\u53E3\u4EF6\u53EA\u5141\u8BB8\u53EA\u8BFB\u7535\u8BDD\uFF0CupdateInstall \u7981\u6B62\uFF08\u6E90\u7801\u7EA7\uFF09");
+    }
+    return rawCall(name, args);
+  };
+  const { baseUrl: _b, routes: _r, fetch: _f, fetchImpl: _fi, timeout: _t, timeoutMs: _tm, prefix: _p, ...entryRest } = options;
+  return mountUpdateEntry(container, { ...entryRest, pluginId: options.pluginId, prefix, call: guarded });
+}
+function mountUpdateBatchPanelHttp(container, options) {
+  if (!options || typeof options !== "object") {
+    throw new Error("[dsh-plugin-update] \u6302 HTTP \u6279\u91CF\u9762\u677F\u7F3A\u5C11\u914D\u7F6E\uFF1A\u6279\u91CF\u524D\u7F00 batchPrefix \u4E0E\u7F51\u5173\u6839 baseUrl \u5FC5\u586B");
+  }
+  const batchPrefix = assertPrefix(options.batchPrefix, "\u6279\u91CF\u7535\u8BDD\u524D\u7F00 batchPrefix");
+  const kernelPrefix = typeof options.prefix === "string" && options.prefix ? assertPrefix(options.prefix, "\u7535\u8BDD\u540D\u524D\u7F00 prefix") : batchPrefix;
+  const call = createHttpCall({ prefix: kernelPrefix, batchPrefix, baseUrl: options.baseUrl, routes: options.routes, fetch: options.fetch, fetchImpl: options.fetchImpl, timeout: options.timeout, timeoutMs: options.timeoutMs });
+  const { baseUrl: _b, routes: _r, fetch: _f, fetchImpl: _fi, timeout: _t, timeoutMs: _tm, prefix: _p, batchPrefix: _bp, ...batchRest } = options;
+  return mountUpdateBatchPanel(container, { ...batchRest, prefix: batchPrefix, call });
+}
+export {
+  DEFAULT_HTTP_CHECK_TIMEOUT_MS,
+  DEFAULT_HTTP_INSTALL_TIMEOUT_MS,
+  DEFAULT_HTTP_STATUS_TIMEOUT_MS,
+  HTTP_BATCH_ACTIONS,
+  HTTP_PHONE_ACTIONS,
+  HTTP_TRANSPORT_FAILED,
+  assertHttpRoutes,
+  assertPollInterval,
+  createHttpCall,
+  httpTransportFailed,
+  mountUpdateBatchPanelHttp,
+  mountUpdateEntryHttp,
+  mountUpdatePanelHttp,
+  pickHttpDiag,
+  resolveHttpPath,
+  shapeHttpReply
+};

package/dist/panel-batch.d.ts

@@ -0,0 +1,151 @@
+import { type UpdatePanelTheme } from './panel.js';
+/** 一行要画的东西（宿主回包里的形状）。 */
+export interface BatchRowView {
+    key: string;
+    title: string;
+    /** 会话相位：pending/checking/ready/installing/current/done/failed/skipped（认不出按 pending）。 */
+    phase: string;
+    targetVersion: string | null;
+    restartRequired: boolean;
+    error: string | null;
+    /** 该行的单插件快照（展开详情与「安装这家」按钮的门控都用它）。 */
+    snapshot: unknown;
+    manual?: string | null;
+    queue?: unknown;
+    profileName?: string | null;
+    /** 该行的插件标识（跳过存储与诊断文本用；缺省用 key）。宿主侧后补字段，缺了照样跑。 */
+    pluginId?: string | null;
+    /** 该行的诊断详情（宿主给就带上；没有就不带）。 */
+    diag?: unknown;
+    /** 宿主种类（进诊断文本；缺省说人话）。 */
+    hostKind?: string | null;
+    /** 该家单插件三电话的名字（取消排队要用它自己的安装电话；老宿主不给就不给取消入口）。 */
+    phoneNames?: unknown;
+}
+/** 摆放形态：默认内嵌，切弹窗走同一参数（与单插件面板同一套写法）。 */
+export type BatchPanelMode = 'embedded' | 'dialog';
+/** 批量面板的挂载参数。 */
+export interface BatchPanelOptions {
+    /** 批量电话前缀（与宿主一致）。 */
+    prefix: string;
+    /** 调宿主电话：(phoneName, args) => Promise<reply>。 */
+    call: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    /** 主题：与单插件面板同一套（缺省 default）。 */
+    theme?: UpdatePanelTheme;
+    /** 摆放形态：内嵌或弹窗（缺省 embedded）。 */
+    mode?: BatchPanelMode;
+    /** 轮询间隔（毫秒，缺省 1500，下限 250）。 */
+    pollMs?: number;
+    /** 可选：键 -> 中文名覆盖。 */
+    titles?: Record<string, string>;
+    /**
+     * 「重启宿主」的落地（与单插件面板同一口径）：不传就只提示手动重启，不假装能重启。
+     */
+    onRestartRequested?: () => void | Promise<void>;
+    /** 复制文本的出口（与单插件面板同一口径）：不传即试浏览器剪贴板，都没有也不抛错。 */
+    copyText?: (text: string) => void | Promise<void>;
+}
+/** 面板可点的动作（HTML 上 data-act 一一对应；测试走同一条路）。 */
+export type BatchPanelActionKind = 'check' | 'install' | 'resume' | 'cancel' | 'row-install' | 'row-skip' | 'row-resume-skip' | 'row-cancel-queue' | 'row-copy-manual' | 'row-copy-diag' | 'toggle-details' | 'restart' | 'close';
+/** 挂载点：只要有 innerHTML 的容器即可（浏览器元素或测试替身都行）。 */
+export interface BatchPanelContainer {
+    innerHTML: string;
+    addEventListener?: (type: string, listener: (ev: unknown) => void) => void;
+    removeEventListener?: (type: string, listener: (ev: unknown) => void) => void;
+}
+/** 批量面板控制器（与契约桩同名同义；act 多收一个可选 key，供行内动作指认某一家）。 */
+export interface BatchPanelController {
+    refresh(): Promise<void>;
+    act(action: BatchPanelActionKind, key?: string): Promise<void>;
+    setTheme(theme: UpdatePanelTheme): void;
+    setMode(mode: BatchPanelMode): void;
+    unmount(): void;
+}
+/** 批量五个电话名（与宿主侧 MultiHostUpdate.phoneNames 同一形状）。 */
+export interface BatchPhoneNames {
+    status: string;
+    check: string;
+    install: string;
+    resume: string;
+    cancel: string;
+}
+/** 批量面板轮询口径（默认 1.5 秒、下限 250 毫秒，与单插件面板同一套下限）。 */
+export declare const BATCH_PANEL_POLL: {
+    readonly defaultMs: 1500;
+    readonly minMs: 250;
+};
+/** 批量电话名拼法：前缀 + 五个固定动作名（前缀形状校验与单插件面板同一套）。 */
+export declare function buildBatchPhoneNames(prefix: string): BatchPhoneNames;
+export interface BatchLedgerCounts {
+    /** phase=ready：有新版、还没安装。 */
+    updatable: number;
+    /** phase=installing：正在安装。 */
+    installing: number;
+    /** phase=pending/checking：还没轮到/正在查。 */
+    pending: number;
+    /** 安装好了但要重启宿主才生效（终态之外的一档，单独数）。 */
+    restart: number;
+    /** phase=failed。 */
+    failed: number;
+    /** phase=skipped。 */
+    skipped: number;
+    /** phase=current/done 且不用重启：真的没事了。 */
+    settled: number;
+}
+/**
+ * 从行上数分类账（每行恰好进一档，七档之和 === 行数）：
+ * 失败优先（失败行永远算失败，不算待重启）；其余按相位落档；不用重启的终态才算「已最新」。
+ * 例外一处：「忙失败占位」（phase=failed 但 error=update-busy）其实是**排队**不是失败——
+ * 宿主忙时先写占位再回 update-busy，面板把它翻回「可更新」，免得总账把它报成失败。
+ */
+export declare function batchLedgerCounts(rows: readonly BatchRowView[]): BatchLedgerCounts;
+/** 分类计数 → 一句话总账（只出现非零档，顺序固定：可更新 · 安装中 · 待查 · 待重启 · 失败 · 已跳过 · 已最新）。 */
+export declare function batchLedgerText(counts: BatchLedgerCounts): string;
+/**
+ * 排队中的状态词：只回答「还要等多久」。位置从该行的队列视图来。
+ * queue.ts 的 position 是 waiting 顺位（队首为 1、0 = 自己正在装），而正在装的那一家也压在这一家前面，
+ * 所以「前方 N 个」= position N（队首那家前方正好 1 个：正在装的拥有者）。
+ * 位置取不到（宿主只记了忙、没给占位读数）就说「等前面安装完」，不猜数字。
+ */
+export declare function batchQueuedStatus(position: number | null): string;
+/**
+ * 一行的状态词：只回答一个问题——这家的**下一步**是什么。
+ * 中文可执行，不写相位英文（相位只留在 data-phase 属性上，给人看的这句永远是动作）。
+ */
+export declare function batchRowStatus(row: BatchRowView, skippedVersion?: string | null): string;
+export interface BatchPanelRenderInput {
+    rows?: readonly BatchRowView[];
+    theme?: UpdatePanelTheme;
+    mode?: BatchPanelMode;
+    /** 当前展开的那一家（键）；null 即全部收起。 */
+    expandedKey?: string | null;
+    /** 批量电话本身失败的稳定码（ok:false 或抛错）。 */
+    lastError?: string | null;
+    /** 本地提示（重启入口、取消结果之类）。 */
+    notice?: string | null;
+    /** 面板正有一次电话在飞（本地忙守卫的一半）。 */
+    inFlight?: boolean;
+    /** 是否已经拿到过第一次回包（决定总账那句是不是「正在读取…」）。 */
+    loaded?: boolean;
+    titles?: Record<string, string>;
+    /** 键 -> 该家被跳过的版本（挂载侧从跳过存储读出；纯渲染函数不读存储）。 */
+    skippedVersions?: Record<string, string | null>;
+    /** notice 归哪一家：等于某行键时那条回执画在该家详情里（否则画在面板底部）。 */
+    noticeKey?: string | null;
+}
+/** 整面板 HTML（含样式；重绘即整体替换 innerHTML，故每次都带 style 也只留一份）。 */
+export declare function renderBatchPanelHTML(input: BatchPanelRenderInput): string;
+export declare const UPDATE_BATCH_PANEL_CSS: string;
+/**
+ * 批量面板的 D5 皮肤（#20 同一套口径：只换颜色/字体/间距，不改顺序、不藏东西）。
+ * 卷宗抬头右侧给大印章留 120px（与单插件面板档案头同一处理）。
+ */
+export declare const UPDATE_BATCH_PANEL_D5_CSS: string;
+/**
+ * 挂批量面板（调用方一行即跑）：
+ * ```js
+ * const panel = mountUpdateBatchPanel(document.getElementById('upd'), { prefix: 'life', call: host.call })
+ * // …离开时 panel.unmount()（只停轮询，批量更新在宿主侧继续跑）
+ * ```
+ */
+export declare function mountUpdateBatchPanel(container: BatchPanelContainer, options: BatchPanelOptions): BatchPanelController;