dsh-plugin-update 0.1.2 → 0.3.0

package/dist/diag.js

@@ -0,0 +1,243 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/diag.ts
+import { DIAG_INLINE_BUDGET_BYTES, diagByteLength, enforceDiagBudget, resolveRegistryHost, sanitizeDetail } from "./redaction.js";
+import { validReleaseVersion, validRequestId } from "./service.js";
+const DIAG_VERSION = 1;
+const DIAG_STAGES = [
+  "read-installed",
+  "fetch-release",
+  "validate-release",
+  "preflight",
+  "exec",
+  "verify"
+];
+const DIAG_ACTIONS = ["retry", "manual", "contact", "restart"];
+const DIAG_KNOWN_TYPES = {
+  v: "number",
+  stage: "string",
+  route: "string",
+  method: "string",
+  httpStatus: "number",
+  exitCode: "number",
+  latencyMs: "number",
+  detail: "string",
+  targetPackageName: "string",
+  runningVersion: "string",
+  latestVersion: "string",
+  environmentKind: "string",
+  requestId: "string",
+  checkId: "string",
+  registryHost: "string",
+  action: "string"
+};
+const DIAG_KEYS = Object.keys(DIAG_KNOWN_TYPES);
+const DIAG_STAGE_EXPECT = {
+  "read-installed": { want: [], forbid: ["httpStatus", "exitCode"] },
+  "fetch-release": { want: ["httpStatus"], forbid: ["exitCode"] },
+  "validate-release": { want: [], forbid: ["httpStatus", "exitCode"] },
+  preflight: { want: [], forbid: ["httpStatus", "exitCode"] },
+  exec: { want: [], forbid: ["httpStatus"] },
+  verify: { want: [], forbid: ["httpStatus", "exitCode"] }
+};
+function isStage(v) {
+  return typeof v === "string" && DIAG_STAGES.includes(v);
+}
+function isAction(v) {
+  return typeof v === "string" && DIAG_ACTIONS.includes(v);
+}
+function deriveStage(errorCode, phoneKind) {
+  const code = String(errorCode || "");
+  if (phoneKind === "update-status") return "read-installed";
+  if (phoneKind === "update-check") {
+    if (code === "check-failed" || code === "internal") return "fetch-release";
+    if (code === "invalid-release") return "validate-release";
+    return "read-installed";
+  }
+  if (code === "install-failed") return "exec";
+  if (code === "check-failed" || code === "internal") return "fetch-release";
+  if (code === "invalid-release") return "validate-release";
+  return "preflight";
+}
+function deriveRouteMethod(stage, environmentKind, errorCode) {
+  if (stage === "fetch-release" || stage === "validate-release") return { route: "registry", method: "https" };
+  if (stage === "read-installed" || stage === "verify") return { route: "disk", method: "fs" };
+  if (stage === "preflight") {
+    if (String(errorCode || "") === "update-busy") return { route: "queue", method: "fs" };
+    return { route: "disk", method: "fs" };
+  }
+  const kind = String(environmentKind || "");
+  if (kind === "desktop-manager") return { route: "desktop-manager", method: "phone" };
+  if (kind === "desktop") return { route: "desktop-service", method: "service" };
+  if (kind === "cli") return { route: "cli-process", method: "spawn" };
+  return {};
+}
+function deriveAction(stage, errorCode) {
+  const code = String(errorCode || "");
+  if (code === "pending-restart" || stage === "verify") return "restart";
+  if (code === "install-failed" || stage === "exec") return "contact";
+  if (code === "invalid-release" || stage === "validate-release") return "manual";
+  if (code === "check-expired") return "manual";
+  if (code === "update-busy") return "retry";
+  if (code === "check-failed" || code === "internal") return "retry";
+  if (stage === "fetch-release") return "retry";
+  return "manual";
+}
+function pickHttpStatus(stage, error) {
+  if (DIAG_STAGE_EXPECT[stage].forbid.includes("httpStatus")) return null;
+  const raw = error?.httpStatus;
+  if (typeof raw === "number" && Number.isInteger(raw) && raw >= 100 && raw <= 599) return raw;
+  return null;
+}
+function pickExitCode(stage, error) {
+  if (DIAG_STAGE_EXPECT[stage].forbid.includes("exitCode")) return null;
+  const raw = error?.exitCode;
+  if (typeof raw === "number" && Number.isInteger(raw)) return raw;
+  return null;
+}
+function pickLatencyMs(raw) {
+  if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) return null;
+  return Math.floor(raw);
+}
+function pickVersion(raw) {
+  if (typeof raw !== "string" || !raw) return null;
+  const t = raw.trim();
+  if (!t) return null;
+  return validReleaseVersion(t) ? t : null;
+}
+function pickPackageName(raw) {
+  if (typeof raw !== "string" || !raw) return null;
+  const t = raw.trim();
+  if (!t || t.length > 256) return null;
+  if (/^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/.test(t)) return t;
+  return null;
+}
+function pickEnvironmentKind(raw) {
+  return raw === "desktop" || raw === "desktop-manager" || raw === "cli" ? String(raw) : null;
+}
+function pickId(raw) {
+  return typeof raw === "string" && validRequestId(raw) ? raw.trim() : null;
+}
+function pickDetail(errorCode, error, httpStatus, phoneKind) {
+  try {
+    const rawDetail = error?.detail;
+    if (typeof rawDetail === "string" && rawDetail.trim()) {
+      const clean2 = sanitizeDetail(rawDetail);
+      return clean2 ? clean2 : null;
+    }
+    const rawMessage = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    const msg = typeof rawMessage === "string" ? rawMessage.trim() : "";
+    const isBareCode = msg && /^[a-z][a-z-]*$/.test(msg) && msg.length <= 32;
+    if (msg && !isBareCode) {
+      const clean2 = sanitizeDetail(msg);
+      if (clean2) return clean2;
+    }
+    const code = String(errorCode || "");
+    const phone = String(phoneKind || "");
+    let fallback = "\u64CD\u4F5C\u5931\u8D25";
+    if (code === "check-failed" && phone === "update-status") fallback = "\u8BFB\u672C\u5730\u72B6\u6001\u6CA1\u6210\u529F";
+    else if ((code === "check-failed" || code === "internal") && phone === "update-install") fallback = "\u88C5\u524D\u91CD\u9A8C\u53D6\u6570\u6CA1\u6210\u529F";
+    else if (code === "check-failed" && httpStatus === 429) fallback = "\u6E90\u8FD4\u56DE 429\uFF0C\u8FD9\u4E00\u5206\u949F\u8BF7\u6C42\u592A\u591A";
+    else if (code === "check-failed" && typeof httpStatus === "number") fallback = `\u6E90\u8FD4\u56DE ${httpStatus}\uFF0C\u91CD\u8BD5\u4ECD\u5931\u8D25`;
+    else if (code === "check-failed" || code === "internal") fallback = "\u67E5\u65B0\u7248\u6CA1\u6210\u529F\uFF08\u8054\u7F51\u3001\u6E90\u3001\u9650\u6D41\u90FD\u53EF\u80FD\uFF09";
+    else if (code === "invalid-release") fallback = "\u6E05\u5355\u91CC\u7684\u7248\u672C\u53F7\u4E0D\u662F\u5408\u6CD5\u7248\u672C";
+    else if (code === "check-expired") fallback = "\u51ED\u8BC1\u8FC7\u671F\u4E86\uFF0C\u5B89\u88C5\u8BF7\u6C42\u88AB\u62D2";
+    else if (code === "update-busy") fallback = "\u540C\u4E00\u4F7F\u7528\u8303\u56F4\u6B63\u5728\u88C5\u53E6\u4E00\u4E2A";
+    else if (code === "install-failed") fallback = "\u5B89\u88C5\u5931\u8D25";
+    else if (code === "unknown-profile") fallback = "\u4F7F\u7528\u8303\u56F4\u6216\u63D2\u4EF6\u4F4D\u7F6E\u8BA4\u4E0D\u51FA";
+    else if (code === "source-install") fallback = "\u5F53\u524D\u662F\u4ECE\u6E90\u7801\u88C5\u7684\uFF0C\u4E0D\u662F\u6309\u7248\u672C\u53F7\u88C5\u7684";
+    else if (code === "invalid-installation") fallback = "\u5DF2\u88C5\u7684\u5305\u4E0D\u5B8C\u6574";
+    else if (code === "installation-changed") fallback = "\u5B89\u88C5\u4F4D\u7F6E\u5728\u4F7F\u7528\u4E2D\u9014\u53D8\u4E86";
+    else if (code === "pending-restart") fallback = "\u65B0\u7248\u5DF2\u88C5\u5230\u78C1\u76D8\uFF0C\u6B63\u5728\u8DD1\u7684\u8FD8\u662F\u65E7\u7248";
+    else if (code === "incompatible-node") fallback = "\u65B0\u7248\u8981\u6C42\u7684 Node \u4E0E\u5F53\u524D\u8FD0\u884C\u7684\u5BF9\u4E0D\u4E0A";
+    else if (code === "registry-conflict") fallback = "\u672C\u5730\u58F0\u660E\u7684\u7248\u672C\u4E0E\u78C1\u76D8\u5B9E\u9645\u7248\u672C\u4E92\u76F8\u77DB\u76FE";
+    else if (code === "recovery-required") fallback = "\u4E0A\u6B21\u5B89\u88C5\u88AB\u6253\u65AD\uFF0C\u7559\u4E0B\u4E00\u4E2A\u534A\u622A\u4EFB\u52A1";
+    const clean = sanitizeDetail(fallback);
+    return clean ? clean : null;
+  } catch {
+    return null;
+  }
+}
+function byteLength(text) {
+  try {
+    return diagByteLength(text);
+  } catch {
+    return text.length;
+  }
+}
+function buildDiag(input) {
+  try {
+    const errorCode = String(input?.errorCode || "");
+    if (!errorCode) return void 0;
+    const phoneKind = String(input?.phoneKind || "");
+    const stage = deriveStage(errorCode, phoneKind);
+    if (!isStage(stage)) return void 0;
+    const { route, method } = deriveRouteMethod(stage, input?.environmentKind, errorCode);
+    const action = deriveAction(stage, errorCode);
+    if (!isAction(action)) return void 0;
+    const httpStatus = pickHttpStatus(stage, input?.error);
+    const exitCode = pickExitCode(stage, input?.error);
+    const latencyMs = pickLatencyMs(input?.latencyMs);
+    const detail = pickDetail(errorCode, input?.error, httpStatus, phoneKind);
+    const targetPackageName = pickPackageName(input?.targetPackageName);
+    const runningVersion = pickVersion(input?.runningVersion);
+    const latestVersion = pickVersion(input?.latestVersion);
+    const environmentKind = pickEnvironmentKind(input?.environmentKind);
+    const args = input?.args && typeof input.args === "object" ? input.args : {};
+    const requestId = pickId(args["requestId"]);
+    const checkId = pickId(args["checkId"]);
+    let registryHost = null;
+    try {
+      registryHost = resolveRegistryHost(String(input?.registryUrl ?? ""));
+    } catch {
+      registryHost = null;
+    }
+    const diag = { v: DIAG_VERSION, stage };
+    if (route) diag.route = route;
+    if (method) diag.method = method;
+    if (httpStatus !== null) diag.httpStatus = httpStatus;
+    if (exitCode !== null) diag.exitCode = exitCode;
+    if (latencyMs !== null) diag.latencyMs = latencyMs;
+    if (detail) diag.detail = detail;
+    if (targetPackageName) diag.targetPackageName = targetPackageName;
+    if (runningVersion) diag.runningVersion = runningVersion;
+    if (latestVersion) diag.latestVersion = latestVersion;
+    if (environmentKind) diag.environmentKind = environmentKind;
+    if (requestId) diag.requestId = requestId;
+    if (checkId) diag.checkId = checkId;
+    if (registryHost) diag.registryHost = registryHost;
+    diag.action = action;
+    return enforceBudget(diag);
+  } catch {
+    return void 0;
+  }
+}
+function enforceBudget(diag) {
+  try {
+    const out = enforceDiagBudget(diag);
+    if (!out || typeof out !== "object") return void 0;
+    if (out.truncated === true) return out;
+    const clean = { ...out };
+    delete clean["truncated"];
+    try {
+      if (diagByteLength(clean) > DIAG_INLINE_BUDGET_BYTES) return void 0;
+    } catch {
+      return void 0;
+    }
+    return clean;
+  } catch {
+    return void 0;
+  }
+}
+void DIAG_INLINE_BUDGET_BYTES;
+export {
+  DIAG_ACTIONS,
+  DIAG_KEYS,
+  DIAG_KNOWN_TYPES,
+  DIAG_STAGES,
+  DIAG_STAGE_EXPECT,
+  DIAG_VERSION,
+  buildDiag,
+  deriveAction,
+  deriveRouteMethod,
+  deriveStage,
+  enforceBudget
+};

package/dist/entry.d.ts

@@ -0,0 +1,60 @@
+import { type UpdatePanelContainer, type UpdatePanelTheme } from './panel.js';
+import type { UpdateSnapshot } from './ports.js';
+/** 入口件的形态。 */
+export type EntryVariant = 'button' | 'badge' | 'inline';
+/** 什么时候主动查一次（只读，联网一次）。 */
+export type EntryAutoCheck = 'mount' | 'never';
+/** 用户点下去之后做什么。 */
+export type EntryOpenOn = 'has-update' | 'always' | 'manual';
+/** 入口件主题（与面板同一套取值，切换即换肤）。 */
+export type EntryTheme = UpdatePanelTheme;
+/** 入口件的状态档：只用来算文案与 data-state，不另立状态机。 */
+export type EntryStateKind = 'idle' | 'update' | 'busy' | 'restart' | 'failed';
+/** 算文案要的全部输入：一份快照 + 最近一次通话的失败稳定码（没查过、没失败为 null）。 */
+export interface UpdateEntryState {
+    snapshot: UpdateSnapshot | null;
+    error: string | null;
+}
+export interface UpdateEntryOptions {
+    pluginId: string;
+    /** 单插件电话前缀（与宿主侧一致）。 */
+    prefix: string;
+    /** 调宿主电话：(phoneName, args) => Promise<reply>。 */
+    call: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    variant?: EntryVariant;
+    theme?: 'default' | 'd5-paper';
+    /** 缺省 'mount'：进页面静默查一次（只读）。'never' 则只在用户点击时查。 */
+    autoCheck?: EntryAutoCheck;
+    /** 缺省 'has-update'：有新版才开面板，没有就只在原地给一句提示。 */
+    openOn?: EntryOpenOn;
+    /** 覆盖默认按钮文案（不传就用状态联动文案）。 */
+    label?: string;
+    profileName?: string;
+    pollMs?: number;
+    /** variant='badge' 或 openOn='manual' 时，点击交给接入方（自己跳自己的页面）。 */
+    onActivate?: (state: {
+        hasUpdate: boolean;
+        latestVersion: string | null;
+    }) => void;
+}
+export interface UpdateEntryController {
+    /** 立刻查一次并把状态刷到界面上（只读）。 */
+    refresh(): Promise<void>;
+    /** 打开更新面板（dialog 形态）。 */
+    open(): void;
+    /** 关掉更新面板。 */
+    close(): void;
+    /** 当前按钮上的状态文案（接入方做自定义排版时读它）。 */
+    label(): string;
+    setTheme(theme: 'default' | 'd5-paper'): void;
+    unmount(): void;
+}
+/**
+ * 状态档：快照六字段 + 失败码推出，顺序固定（活任务 > 待重启 > 失败 > 有新版 > 待查）。
+ * 待重启是正常终态（不是失败），所以排在失败前面；正在装的任务比一条陈旧的失败码更可信。
+ */
+export declare function entryStateKind(state: UpdateEntryState | null | undefined): EntryStateKind;
+/** 入口件文案（唯一出处：测试与接入方都读它，不各写一份）。 */
+export declare function entryLabelFor(state: UpdateEntryState | null | undefined): string;
+export declare const UPDATE_ENTRY_CSS: string;
+export declare function mountUpdateEntry(container: UpdatePanelContainer, options: UpdateEntryOptions): UpdateEntryController;

package/dist/entry.js

@@ -0,0 +1,305 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/entry.ts
+import { DEFAULT_PREFIX, MIN_PANEL_POLL_MS, buildPhoneNames } from "./config.js";
+import {
+  failureCodeOf,
+  mountUpdatePanel
+} from "./panel.js";
+const LABEL_IDLE = "\u68C0\u67E5\u66F4\u65B0";
+const LABEL_FAILED = "\u66F4\u65B0\u5931\u8D25\uFF0C\u70B9\u6B64\u67E5\u770B";
+const LABEL_BUSY = "\u6B63\u5728\u5B89\u88C5\u2026";
+const LABEL_RESTART = "\u5F85\u91CD\u542F";
+function hasUpdateOf(snapshot) {
+  if (!snapshot) return false;
+  const latest = snapshot.latestVersion;
+  if (typeof latest !== "string" || !latest.trim()) return false;
+  return latest.trim() !== snapshot.runningVersion;
+}
+function entryStateKind(state) {
+  const snapshot = state?.snapshot ?? null;
+  const job = snapshot?.job ?? null;
+  if (job && (job.state === "installing" || job.state === "verifying")) return "busy";
+  if (snapshot && (snapshot.blockedReason === "pending-restart" || job?.state === "restart-required")) {
+    return "restart";
+  }
+  if (state && state.error || job && (job.state === "failed" || job.state === "interrupted")) {
+    return "failed";
+  }
+  if (hasUpdateOf(snapshot)) return "update";
+  return "idle";
+}
+function entryLabelFor(state) {
+  switch (entryStateKind(state)) {
+    case "busy":
+      return LABEL_BUSY;
+    case "restart":
+      return LABEL_RESTART;
+    case "failed":
+      return LABEL_FAILED;
+    case "update": {
+      const latest = state?.snapshot?.latestVersion;
+      return typeof latest === "string" && latest.trim() ? `\u6709\u65B0\u7248 ${latest.trim()}` : LABEL_IDLE;
+    }
+    default:
+      return LABEL_IDLE;
+  }
+}
+const UPDATE_ENTRY_CSS = [
+  '.dsh-upd-entry{display:inline-flex;align-items:center;gap:8px;font:13px/1.6 system-ui,"Microsoft YaHei",sans-serif;color:var(--dsh-upd-fg,#1f2937)}',
+  ".dsh-upd-entry-btn{font:inherit;border:1px solid var(--dsh-upd-line,#d1d5db);border-radius:6px;",
+  "background:var(--dsh-upd-btn,#f9fafb);color:inherit;padding:4px 12px;cursor:pointer}",
+  ".dsh-upd-entry-btn:hover{border-color:var(--dsh-upd-primary,#2563eb)}",
+  ".dsh-upd-entry-btn:focus-visible,.dsh-upd-entry-dot:focus-visible{outline:2px solid var(--dsh-upd-focus,#2563eb);outline-offset:1px}",
+  '.dsh-upd-entry[data-state="update"] .dsh-upd-entry-btn{border-color:var(--dsh-upd-ok-line,#059669);color:var(--dsh-upd-ok-line,#059669)}',
+  '.dsh-upd-entry[data-state="restart"] .dsh-upd-entry-btn{border-color:var(--dsh-upd-warn-line,#d97706);color:var(--dsh-upd-warn-line,#d97706)}',
+  '.dsh-upd-entry[data-state="failed"] .dsh-upd-entry-btn{border-color:var(--dsh-upd-bad-line,#dc2626);color:var(--dsh-upd-bad-line,#dc2626)}',
+  ".dsh-upd-entry-dot{width:10px;height:10px;padding:0;border:0;border-radius:50%;background:var(--dsh-upd-line,#9ca3af);cursor:pointer}",
+  '.dsh-upd-entry[data-state="update"] .dsh-upd-entry-dot{background:var(--dsh-upd-ok-line,#059669)}',
+  '.dsh-upd-entry[data-state="busy"] .dsh-upd-entry-dot,.dsh-upd-entry[data-state="restart"] .dsh-upd-entry-dot{background:var(--dsh-upd-warn-line,#d97706)}',
+  '.dsh-upd-entry[data-state="failed"] .dsh-upd-entry-dot{background:var(--dsh-upd-bad-line,#dc2626)}',
+  ".dsh-upd-entry-note{font-size:12.5px;opacity:.75}",
+  '.dsh-upd-entry[data-theme="d5-paper"]{font-family:Georgia,"Songti SC","STSong","SimSun",serif;color:#1a1a1a}',
+  '.dsh-upd-entry[data-theme="d5-paper"] .dsh-upd-entry-btn{border-color:#c4b896;background:transparent;border-radius:3px}',
+  '.dsh-upd-entry[data-theme="d5-paper"] .dsh-upd-entry-btn:hover{border-color:#c8402a;color:#c8402a}',
+  "@media (prefers-color-scheme: dark){.dsh-upd-entry{color:#e5e7eb}",
+  ".dsh-upd-entry-btn{--dsh-upd-btn:#1f2937;--dsh-upd-line:#374151}}"
+].join("\n");
+const ENTRY_ATTR = "data-dsh-upd-entry";
+const ENTRY_SELECTOR = "[data-dsh-upd-entry]";
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function asSnapshot(value) {
+  if (!isObject(value)) return null;
+  if (typeof value["runningVersion"] !== "string") return null;
+  if (typeof value["canInstall"] !== "boolean") return null;
+  return value;
+}
+function escapeHtml(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function mountUpdateEntry(container, options) {
+  if (!container || typeof container.innerHTML !== "string") {
+    throw new Error("[dsh-plugin-update] \u6302\u66F4\u65B0\u5165\u53E3\u4EF6\u9700\u8981\u4E00\u4E2A\u6709 innerHTML \u7684\u5BB9\u5668");
+  }
+  if (!options || typeof options !== "object") {
+    throw new Error("[dsh-plugin-update] \u6302\u66F4\u65B0\u5165\u53E3\u4EF6\u7F3A\u5C11\u914D\u7F6E\uFF1A\u63D2\u4EF6\u6807\u8BC6 pluginId \u5FC5\u586B");
+  }
+  const pluginId = options.pluginId;
+  if (typeof pluginId !== "string" || !pluginId) {
+    throw new Error(`[dsh-plugin-update] \u63D2\u4EF6\u6807\u8BC6 pluginId \u5FC5\u586B\uFF1A\u987B\u4E3A\u975E\u7A7A\u5B57\u7B26\u4E32\uFF08\u6536\u5230 ${JSON.stringify(pluginId)}\uFF09`);
+  }
+  if (typeof options.call !== "function") {
+    throw new Error("[dsh-plugin-update] \u6302\u66F4\u65B0\u5165\u53E3\u4EF6\u9700\u8981\u4F20\u8F93\u51FD\u6570 call\uFF08\u5165\u53E3\u4EF6\u8C03\u5BBF\u4E3B\u7535\u8BDD\u7684\u552F\u4E00\u63A5\u89E6\u9762\uFF09");
+  }
+  const rawPrefix = options.prefix;
+  const prefix = rawPrefix === void 0 ? DEFAULT_PREFIX : rawPrefix;
+  const phoneNames = buildPhoneNames(prefix);
+  const variant = options.variant ?? "button";
+  if (variant !== "button" && variant !== "badge" && variant !== "inline") {
+    throw new Error(`[dsh-plugin-update] \u5165\u53E3\u4EF6\u5F62\u6001\u975E\u6CD5\uFF1A\u53EA\u6536 button / badge / inline\uFF08\u6536\u5230 ${JSON.stringify(options.variant)}\uFF09`);
+  }
+  const autoCheck = options.autoCheck ?? "mount";
+  if (autoCheck !== "mount" && autoCheck !== "never") {
+    throw new Error(`[dsh-plugin-update] \u81EA\u52A8\u68C0\u67E5\u65F6\u673A\u975E\u6CD5\uFF1A\u53EA\u6536 mount \u6216 never\uFF08\u6536\u5230 ${JSON.stringify(options.autoCheck)}\uFF09`);
+  }
+  const openOn = options.openOn ?? "has-update";
+  if (openOn !== "has-update" && openOn !== "always" && openOn !== "manual") {
+    throw new Error(`[dsh-plugin-update] \u70B9\u51FB\u53BB\u5411\u975E\u6CD5\uFF1A\u53EA\u6536 has-update / always / manual\uFF08\u6536\u5230 ${JSON.stringify(options.openOn)}\uFF09`);
+  }
+  let theme = options.theme ?? "default";
+  if (theme !== "default" && theme !== "d5-paper") {
+    throw new Error(`[dsh-plugin-update] \u4E3B\u9898\u975E\u6CD5\uFF1A\u53EA\u6536 default \u6216 d5-paper\uFF08\u6536\u5230 ${JSON.stringify(options.theme)}\uFF09`);
+  }
+  const pollMs = options.pollMs;
+  if (pollMs !== void 0 && (typeof pollMs !== "number" || !Number.isFinite(pollMs) || pollMs < MIN_PANEL_POLL_MS)) {
+    throw new Error(`[dsh-plugin-update] \u9762\u677F\u8F6E\u8BE2\u95F4\u9694\u975E\u6CD5\uFF1A\u4E0D\u5F97\u5C0F\u4E8E 250 \u6BEB\u79D2\uFF08\u6536\u5230 ${JSON.stringify(options.pollMs)}\uFF09`);
+  }
+  const labelOverride = typeof options.label === "string" && options.label ? options.label : null;
+  const profileName = typeof options.profileName === "string" && options.profileName ? options.profileName : null;
+  const onActivate = typeof options.onActivate === "function" ? options.onActivate : null;
+  const call = options.call;
+  let snapshot = null;
+  let error = null;
+  let note = null;
+  let mounted = true;
+  let panel = null;
+  let panelMode = null;
+  const panelHost = {
+    get innerHTML() {
+      return container.innerHTML;
+    },
+    set innerHTML(value) {
+      container.innerHTML = value;
+    },
+    addEventListener(type, listener) {
+      container.addEventListener?.(type, listener);
+    },
+    removeEventListener(type, listener) {
+      container.removeEventListener?.(type, listener);
+    }
+  };
+  async function panelCall(name, args) {
+    const reply = await call(name, args);
+    return isObject(reply) ? reply : {};
+  }
+  function stateOf() {
+    return { snapshot, error };
+  }
+  function currentLabel() {
+    return labelOverride ?? entryLabelFor(stateOf());
+  }
+  function hasUpdate() {
+    return hasUpdateOf(snapshot);
+  }
+  function phoneArgs() {
+    return {};
+  }
+  function entryHTML() {
+    const kind = entryStateKind(stateOf());
+    const text = currentLabel();
+    const themeAttr = theme === "d5-paper" ? ' data-theme="d5-paper"' : "";
+    const control = variant === "badge" ? `<button type="button" class="dsh-upd-entry-dot" ${ENTRY_ATTR}="activate" title="${escapeHtml(text)}" aria-label="${escapeHtml(text)}"></button>` : `<button type="button" class="dsh-upd-entry-btn" ${ENTRY_ATTR}="activate">${escapeHtml(text)}</button>`;
+    const noteHTML = note ? `<span class="dsh-upd-entry-note" data-dsh-upd-note="1">${escapeHtml(note)}</span>` : "";
+    return `<style>${UPDATE_ENTRY_CSS}</style>
+<span class="dsh-upd-entry" data-variant="${variant}" data-state="${kind}"${themeAttr}>${control}${noteHTML}</span>`;
+  }
+  function render() {
+    if (!mounted) return;
+    if (panelMode !== null) return;
+    container.innerHTML = entryHTML();
+  }
+  function applyReply(reply) {
+    if (!isObject(reply) || reply["ok"] !== true) {
+      error = failureCodeOf(isObject(reply) ? reply : null, "check-failed");
+      return;
+    }
+    const next = asSnapshot(reply["snapshot"]);
+    if (next) snapshot = next;
+    error = null;
+  }
+  async function refresh() {
+    if (!mounted) return;
+    try {
+      const reply = await call(phoneNames.updateStatus, phoneArgs());
+      if (!mounted) return;
+      applyReply(reply);
+    } catch {
+      if (!mounted) return;
+      error = "check-failed";
+    }
+    render();
+  }
+  async function checkNow() {
+    try {
+      const reply = await call(phoneNames.updateCheck, phoneArgs());
+      if (!mounted) return;
+      applyReply(reply);
+    } catch {
+      if (!mounted) return;
+      error = "check-failed";
+    }
+  }
+  function mountPanel(mode) {
+    if (!mounted || panelMode !== null) return;
+    panel = mountUpdatePanel(panelHost, {
+      pluginId,
+      prefix,
+      mode,
+      theme,
+      pollMs,
+      profileName,
+      call: panelCall
+    });
+    panelMode = mode;
+  }
+  function openDialog() {
+    mountPanel("dialog");
+  }
+  function open() {
+    if (!mounted || panelMode !== null) return;
+    if (variant === "inline") return;
+    openDialog();
+  }
+  function close() {
+    if (!mounted || panelMode !== "dialog" || !panel) return;
+    const opened = panel;
+    panel = null;
+    panelMode = null;
+    try {
+      opened.unmount();
+    } catch {
+    }
+    render();
+    void refresh();
+  }
+  async function activate() {
+    if (!mounted || panelMode !== null) return;
+    note = null;
+    render();
+    await checkNow();
+    if (!mounted) return;
+    if (variant === "badge" || openOn === "manual") {
+      if (onActivate) onActivate({ hasUpdate: hasUpdate(), latestVersion: snapshot?.latestVersion ?? null });
+      else openDialog();
+      render();
+      return;
+    }
+    if (openOn === "always" || hasUpdate() || !snapshot || error) {
+      openDialog();
+      return;
+    }
+    note = `\u5DF2\u662F\u6700\u65B0 ${snapshot.runningVersion}`;
+    render();
+  }
+  function setTheme(next) {
+    if (next !== "default" && next !== "d5-paper") {
+      throw new Error(`[dsh-plugin-update] \u4E3B\u9898\u975E\u6CD5\uFF1A\u53EA\u6536 default \u6216 d5-paper\uFF08\u6536\u5230 ${JSON.stringify(next)}\uFF09`);
+    }
+    theme = next;
+    if (panel) void panel.setTheme(next);
+    else render();
+  }
+  function onClick(ev) {
+    if (!mounted) return;
+    try {
+      const target = ev?.target;
+      const closest = target && typeof target.closest === "function" ? target.closest.bind(target) : null;
+      if (!closest) return;
+      if (closest(ENTRY_SELECTOR)) {
+        void activate();
+        return;
+      }
+      if (panelMode === "dialog" && closest('[data-action="close-view"]')) close();
+    } catch {
+    }
+  }
+  function unmount() {
+    if (!mounted) return;
+    mounted = false;
+    const opened = panel;
+    panel = null;
+    panelMode = null;
+    try {
+      opened?.unmount();
+    } catch {
+    }
+    try {
+      container.removeEventListener?.("click", onClick);
+    } catch {
+    }
+  }
+  try {
+    container.addEventListener?.("click", onClick);
+  } catch {
+  }
+  if (variant === "inline") mountPanel("embedded");
+  else render();
+  if (autoCheck === "mount") void refresh();
+  return { refresh, open, close, label: currentLabel, setTheme, unmount };
+}
+export {
+  UPDATE_ENTRY_CSS,
+  entryLabelFor,
+  entryStateKind,
+  mountUpdateEntry
+};

package/dist/gate.d.ts

@@ -0,0 +1,35 @@
+export declare const EVENT_LEVELS: readonly ["error", "warn", "info", "debug"];
+export type GateEventLevel = (typeof EVENT_LEVELS)[number];
+export declare const EVENT_KINDS: readonly ["resident", "ondemand", "selfmon"];
+export type GateEventKind = (typeof EVENT_KINDS)[number];
+export interface GateEventEntry {
+    level: GateEventLevel;
+    kind: GateEventKind;
+    fields: string[];
+    codes?: string[];
+    rules?: string[];
+    guard?: string;
+}
+export interface GateEventCounts {
+    resident: number;
+    ondemand: number;
+    selfmon: number;
+}
+export interface GateEventList {
+    version: 1;
+    pluginId: string;
+    counts: GateEventCounts;
+    events: Record<string, GateEventEntry>;
+}
+export declare function parseEventListManifest(value: unknown): GateEventList;
+export interface GateFieldCheck {
+    ok: boolean;
+    unknownEvent: boolean;
+    unknownFields: string[];
+}
+export declare function checkEventFields(manifest: GateEventList, eventName: string, fieldNames: string[]): GateFieldCheck;
+export interface GateCountCheck {
+    ok: boolean;
+    problems: string[];
+}
+export declare function checkEventCounts(manifest: GateEventList): GateCountCheck;