dsh-plugin-update 0.2.0 → 0.3.0

package/dist/changelog-io.js

@@ -0,0 +1,258 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/changelog-io.ts
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import { CHANGELOG_FILENAME, CHANGELOG_MAX_CHARS } from "./changelog.js";
+import { INTEGRITY_PATTERN } from "./service.js";
+const CHANGELOG_TARBALL_MAX_BYTES = 8 * 1024 * 1024;
+const CHANGELOG_TAR_MAX_BYTES = 32 * 1024 * 1024;
+const CHANGELOG_FETCH_MAX_BYTES = 64 * 1024;
+const CHANGELOG_DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+function byteLengthOf(text) {
+  try {
+    return Buffer.byteLength(text, "utf8");
+  } catch {
+    return text.length;
+  }
+}
+function truncateToBytes(text, maxBytes) {
+  try {
+    if (byteLengthOf(text) <= maxBytes) return text;
+    const buf = Buffer.from(text, "utf8");
+    return buf.slice(0, maxBytes).toString();
+  } catch {
+    return text.slice(0, Math.min(text.length, maxBytes));
+  }
+}
+function timeoutSignal(ms) {
+  try {
+    const ctor = globalThis.AbortSignal;
+    if (ctor && typeof ctor.timeout === "function") return ctor.timeout(ms);
+  } catch {
+  }
+  return void 0;
+}
+async function readInstalledChangelogText(targetPackageDir, opts) {
+  try {
+    const dir = typeof targetPackageDir === "string" ? targetPackageDir.trim() : "";
+    if (!dir) return null;
+    const maxBytes = opts && typeof opts.maxBytes === "number" && Number.isFinite(opts.maxBytes) && opts.maxBytes > 0 ? Math.floor(opts.maxBytes) : CHANGELOG_FETCH_MAX_BYTES;
+    let text;
+    try {
+      text = await readFile(join(dir, CHANGELOG_FILENAME), "utf8");
+    } catch {
+      return null;
+    }
+    if (typeof text !== "string" || !text.trim()) return null;
+    if (text.length > CHANGELOG_MAX_CHARS) text = text.slice(0, CHANGELOG_MAX_CHARS);
+    if (byteLengthOf(text) > maxBytes) text = truncateToBytes(text, maxBytes);
+    return text.trim() ? text : null;
+  } catch {
+    return null;
+  }
+}
+async function readResponseBytes(response) {
+  try {
+    const r = response;
+    if (r && typeof r.arrayBuffer === "function") {
+      const ab = await r.arrayBuffer();
+      if (ab instanceof ArrayBuffer) return new Uint8Array(ab);
+      if (ab && typeof ab.byteLength === "number") {
+        return new Uint8Array(ab);
+      }
+      return null;
+    }
+    if (r && typeof r.bytes === "function") {
+      const b = await r.bytes();
+      if (b instanceof Uint8Array) return b;
+      return null;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function parseOctal(bytes, offset, length) {
+  try {
+    let s = "";
+    for (let i = 0; i < length; i++) {
+      const c = bytes[offset + i];
+      if (c === 0 || c === 32) {
+        if (s) break;
+        continue;
+      }
+      s += String.fromCharCode(c);
+      if (s.length > 12) break;
+    }
+    s = s.trim();
+    if (!/^[0-7]+$/.test(s)) return NaN;
+    return parseInt(s, 8);
+  } catch {
+    return NaN;
+  }
+}
+function readTarName(bytes, offset) {
+  try {
+    let end = offset;
+    while (end < offset + 100 && end < bytes.length && bytes[end] !== 0) end++;
+    const slice = bytes.slice(offset, end);
+    try {
+      return Buffer.from(slice).toString().trim();
+    } catch {
+      let s = "";
+      for (let i = 0; i < slice.length; i++) s += String.fromCharCode(slice[i]);
+      return s.trim();
+    }
+  } catch {
+    return "";
+  }
+}
+function normalizeTarEntryName(raw) {
+  try {
+    let n = String(raw || "").trim().replace(/\\/g, "/");
+    n = n.replace(/^\.\//, "");
+    n = n.replace(/^\/+/, "");
+    return n;
+  } catch {
+    return "";
+  }
+}
+function isChangelogEntryName(normalized) {
+  try {
+    if (!normalized) return false;
+    if (normalized === CHANGELOG_FILENAME) return true;
+    if (normalized.endsWith(`/${CHANGELOG_FILENAME}`)) return true;
+    return false;
+  } catch {
+    return false;
+  }
+}
+function extractChangelogFromTar(tarBytes, maxBytes = CHANGELOG_FETCH_MAX_BYTES) {
+  try {
+    if (!tarBytes || tarBytes.length < 512 || tarBytes.length % 512 !== 0) {
+      if (!tarBytes || tarBytes.length < 512) return null;
+    }
+    let offset = 0;
+    while (offset + 512 <= tarBytes.length) {
+      let allZero = true;
+      for (let i = 0; i < 512; i++) {
+        if (tarBytes[offset + i] !== 0) {
+          allZero = false;
+          break;
+        }
+      }
+      if (allZero) break;
+      const rawName = readTarName(tarBytes, offset);
+      const name = normalizeTarEntryName(rawName);
+      const size = parseOctal(tarBytes, offset + 124, 12);
+      if (!Number.isFinite(size) || size < 0) return null;
+      const typeflag = String.fromCharCode(tarBytes[offset + 156] ?? 0);
+      const dataStart = offset + 512;
+      const dataEnd = dataStart + size;
+      if (dataEnd > tarBytes.length) return null;
+      const isFile = typeflag === "0" || typeflag === "\0" || typeflag === "";
+      if (isFile && isChangelogEntryName(name)) {
+        const slice = tarBytes.slice(dataStart, dataEnd);
+        let text = "";
+        try {
+          text = Buffer.from(slice).toString();
+        } catch {
+          return null;
+        }
+        if (!text.trim()) return null;
+        if (text.length > CHANGELOG_MAX_CHARS) text = text.slice(0, CHANGELOG_MAX_CHARS);
+        if (byteLengthOf(text) > maxBytes) text = truncateToBytes(text, maxBytes);
+        return text.trim() ? text : null;
+      }
+      const blocks = Math.ceil(size / 512);
+      offset = dataStart + blocks * 512;
+      if (blocks < 0) return null;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function verifyIntegrity(bytes, integrity) {
+  try {
+    const m = String(integrity).match(/^sha512-([A-Za-z0-9+/]{86}==)$/);
+    if (!m) return false;
+    const actual = createHash("sha512").update(Buffer.from(bytes)).digest("base64");
+    return actual === m[1];
+  } catch {
+    return false;
+  }
+}
+async function fetchReleaseChangelogText(fetchImpl, release, opts) {
+  try {
+    if (typeof fetchImpl !== "function") return null;
+    const tarballText = release?.tarball;
+    const integrityText = release?.integrity;
+    if (typeof tarballText !== "string" || !tarballText) return null;
+    if (typeof integrityText !== "string" || !new RegExp(INTEGRITY_PATTERN).test(integrityText)) return null;
+    const registryUrl = opts && typeof opts.registryUrl === "string" && opts.registryUrl ? String(opts.registryUrl) : CHANGELOG_DEFAULT_REGISTRY;
+    let tarballUrl;
+    let registryOrigin = "";
+    try {
+      tarballUrl = new URL(tarballText);
+      registryOrigin = new URL(registryUrl).origin;
+    } catch {
+      return null;
+    }
+    if (tarballUrl.protocol !== "https:") return null;
+    if (tarballUrl.origin !== registryOrigin) return null;
+    if (tarballUrl.username || tarballUrl.password || tarballUrl.search || tarballUrl.hash) return null;
+    if (!tarballUrl.pathname.endsWith(".tgz")) return null;
+    const targetName = opts && typeof opts.targetPackageName === "string" ? String(opts.targetPackageName) : "";
+    const versionText = release && typeof release.version === "string" ? String(release.version) : "";
+    if (targetName && versionText) {
+      const expectPath = `/${targetName}/-/${targetName}-${versionText}.tgz`;
+      if (tarballUrl.pathname !== expectPath) return null;
+    }
+    const timeoutMs = opts && typeof opts.timeoutMs === "number" && Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? Math.floor(opts.timeoutMs) : 1e4;
+    const maxTarballBytes = opts && typeof opts.maxTarballBytes === "number" && Number.isFinite(opts.maxTarballBytes) && opts.maxTarballBytes > 0 ? Math.floor(opts.maxTarballBytes) : CHANGELOG_TARBALL_MAX_BYTES;
+    const maxChangelogBytes = opts && typeof opts.maxChangelogBytes === "number" && Number.isFinite(opts.maxChangelogBytes) && opts.maxChangelogBytes > 0 ? Math.floor(opts.maxChangelogBytes) : CHANGELOG_FETCH_MAX_BYTES;
+    let response = null;
+    try {
+      response = await fetchImpl(tarballUrl.href, {
+        headers: { accept: "application/octet-stream" },
+        redirect: "error",
+        signal: timeoutSignal(timeoutMs)
+      });
+    } catch {
+      return null;
+    }
+    const ok = response?.ok;
+    if (ok !== true) return null;
+    try {
+      const headers = response.headers;
+      const declared = headers && typeof headers.get === "function" ? Number(headers.get("content-length")) : NaN;
+      if (Number.isFinite(declared) && declared > maxTarballBytes) return null;
+    } catch {
+    }
+    const bytes = await readResponseBytes(response);
+    if (!bytes || bytes.length === 0 || bytes.length > maxTarballBytes) return null;
+    if (!verifyIntegrity(bytes, integrityText)) return null;
+    let tar;
+    try {
+      const out = gunzipSync(Buffer.from(bytes));
+      tar = new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
+    } catch {
+      return null;
+    }
+    if (tar.length === 0 || tar.length > CHANGELOG_TAR_MAX_BYTES) return null;
+    return extractChangelogFromTar(tar, maxChangelogBytes);
+  } catch {
+    return null;
+  }
+}
+export {
+  CHANGELOG_DEFAULT_REGISTRY,
+  CHANGELOG_FETCH_MAX_BYTES,
+  CHANGELOG_TARBALL_MAX_BYTES,
+  CHANGELOG_TAR_MAX_BYTES,
+  extractChangelogFromTar,
+  fetchReleaseChangelogText,
+  readInstalledChangelogText
+};

package/dist/changelog.d.ts

@@ -0,0 +1,96 @@
+/**
+ * src/changelog.ts —— 包内 CHANGELOG.md 的纯解析与面板渲染（#23，承接 #11 取证）。
+ *
+ * 取证结论（research/changelog-optimal-form.md）：
+ * 包内 `CHANGELOG.md`（包根 + files 白名单已落地）是唯一推荐数据源；
+ * Keep-a-Changelog 子集；缺日志中性提示、不挡安装。
+ *
+ * 本模块零依赖、纯函数、无 Node/浏览器专属能力，两边都跑得动：
+ * 解析只做字符串切分，不读盘、不联网；版本语义与核心同口径
+ * （validReleaseVersion / compareReleaseVersions，stable 纯三段、prerelease 显式）。
+ *
+ * 面板约定（Question 原文逐字落实）：
+ * - `Added/Fixed/Changed` 必显；`Deprecated/Removed/Security` 透传折叠；
+ * - `Unreleased` 与空节忽略；
+ * - 缺日志中性提示，不挡安装、不写 blockedReason、不动快照六字段
+ *   （本模块不碰快照，面板只增一节 HTML，安装门控只跟快照）；
+ * - 已装版离线读、新版按需取 tarball 同名文件复用官方源 integrity
+ *   （I/O 在 `src/changelog-io.ts` Node 侧，取不到回落中性提示）；
+ * - 零依赖纯函数解析器（本文件零导入）。
+ */
+/** 包内日志文件名（包根，与 tarball 内同名文件同一名字）。 */
+export declare const CHANGELOG_FILENAME = "CHANGELOG.md";
+/** 缺日志时的中性提示（不挡安装，安装按钮状态不变）。 */
+export declare const CHANGELOG_NEUTRAL_HINT = "\u4F5C\u8005\u672A\u63D0\u4F9B\u66F4\u65B0\u8BF4\u660E";
+/** 中性提示完整行（含“安装不受影响”，把“不挡安装”说成人话）。 */
+export declare const CHANGELOG_NEUTRAL_LINE = "\u4F5C\u8005\u672A\u63D0\u4F9B\u66F4\u65B0\u8BF4\u660E\uFF0C\u5B89\u88C5\u4E0D\u53D7\u5F71\u54CD\u3002";
+/** 输入上限（字符）：超限截断后解析，永不抛错、不OOM。 */
+export declare const CHANGELOG_MAX_CHARS: number;
+/** 版本节上限：超限只取文件顺序前 N 节（Keep-a-Changelog 最新在前）。 */
+export declare const CHANGELOG_MAX_ENTRIES = 100;
+/** 每类条目上限：超限只取前 N 条。 */
+export declare const CHANGELOG_MAX_BULLETS_PER_SECTION = 200;
+/** 单条上限（字符）：超限在尾部截断并加省略号。 */
+export declare const CHANGELOG_MAX_BULLET_CHARS = 500;
+/** 六类全集（Keep-a-Changelog #types 节）。 */
+export declare const CHANGELOG_ALL_CATEGORIES: readonly ["Added", "Fixed", "Changed", "Deprecated", "Removed", "Security"];
+export type ChangelogCategory = (typeof CHANGELOG_ALL_CATEGORIES)[number];
+/** 必显三类（面板展开渲染）。 */
+export declare const CHANGELOG_MUST_SHOW: readonly ChangelogCategory[];
+/** 透传折叠三类（原样展示、不解析、不参与“有无新版”判断）。 */
+export declare const CHANGELOG_FOLDED: readonly ChangelogCategory[];
+/** 六类中文名（面板双语标题用，顺序与英文一一对应）。 */
+export declare const CHANGELOG_CATEGORY_ZH: Record<ChangelogCategory, string>;
+/** 一节版本（Unreleased 也保留在解析结果里，渲染与区间筛选时忽略）。 */
+export interface ChangelogEntry {
+    /** 归一化版本号：`Unreleased` 或发行版本号（如 `1.2.3`、`1.2.3-rc.1`）。 */
+    version: string;
+    /** 标题里的 ISO 日期（`YYYY-MM-DD`），没有为 null。 */
+    date: string | null;
+    /**
+     * 标题带 `[YANKED]` 标记（仅文本提示，不做机器信号：区间照算，渲染补“已撤回”）。
+     * 对抗复查补记：Keep-a-Changelog 要求 yanked 可见，本模块此前直接丢掉标记。
+     */
+    yanked: boolean;
+    /** 六类各自的条目（空类为空数组，空节忽略由渲染层执行）。 */
+    sections: Record<ChangelogCategory, string[]>;
+}
+/** 是否 Unreleased（大小写不敏感，前后空白忽略）。 */
+export declare function isUnreleasedVersion(v: unknown): boolean;
+/**
+ * 解析 CHANGELOG Markdown（纯函数，永不抛错）：
+ * 非字符串/空串回 []；超长截断后解析；未知版本标题与其下条目一律丢弃；
+ * 全空节版本直接丢弃（空节忽略）；Unreleased 保留（渲染与区间时忽略）。
+ */
+export declare function parseChangelog(markdown: unknown): ChangelogEntry[];
+/** 该节是否有可见内容（六类任一非空）。 */
+export declare function hasVisibleSections(entry: ChangelogEntry | null | undefined): boolean;
+/**
+ * 按区间筛选（文件顺序不变，最新在前）：
+ * 只收发行版本号（Unreleased 与非法版本一律忽略）；
+ * 只收 `(fromExclusive, toInclusive]`；
+ * from 非法/缺省视为 -inf（全收 `<= to`）；to 非法/缺省回 []。
+ *
+ * 预发布节取舍（#23 对抗复查定稿）：区间内的预发布节一并收录（如 `(1.0.0, 1.1.0]` 含 `1.1.0-rc.1`）。
+ * 通道门禁不在此做——`to` 本身由核心按通道滤过（stable 通道下远端永不为预发布），
+ * 此处只管“两版之间有何内容”的人读完整性；面板永不拿它做安装分支。
+ */
+export declare function selectChangelogEntries(entries: unknown, fromExclusive: unknown, toInclusive: unknown): ChangelogEntry[];
+/**
+ * 更新区间便捷口：from 取运行版（ fallback 已装版），to 取远端版；
+ * 任一缺失/非法即回 []（调用方渲染中性提示，不挡安装）。
+ */
+export declare function changelogForUpdate(entries: unknown, runningVersion: unknown, latestVersion: unknown, installedVersion?: unknown): ChangelogEntry[];
+/** 单节 HTML（调用方保证已过滤 Unreleased 与空节，本函数再兜底一次）。 */
+export declare function renderChangelogSection(entry: ChangelogEntry): string;
+/** 中性提示 HTML（缺日志、取不到、无区间内容时统一用它，不挡安装）。 */
+export declare function renderChangelogNeutral(): string;
+/**
+ * 区间渲染 HTML（纯函数）：
+ * entries 非数组/空、无可见区间内容一律回中性提示；
+ * Unreleased 与空节永不渲染；输出已转义，可直接拼进面板。
+ */
+export declare function renderChangelogHTML(entries: unknown, opts?: {
+    from?: string | null;
+    to?: string | null;
+}): string;

package/dist/changelog.js

@@ -0,0 +1,287 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/changelog.ts
+import { compareReleaseVersions, validReleaseVersion } from "./service.js";
+const CHANGELOG_FILENAME = "CHANGELOG.md";
+const CHANGELOG_NEUTRAL_HINT = "\u4F5C\u8005\u672A\u63D0\u4F9B\u66F4\u65B0\u8BF4\u660E";
+const CHANGELOG_NEUTRAL_LINE = "\u4F5C\u8005\u672A\u63D0\u4F9B\u66F4\u65B0\u8BF4\u660E\uFF0C\u5B89\u88C5\u4E0D\u53D7\u5F71\u54CD\u3002";
+const CHANGELOG_MAX_CHARS = 64 * 1024;
+const CHANGELOG_MAX_ENTRIES = 100;
+const CHANGELOG_MAX_BULLETS_PER_SECTION = 200;
+const CHANGELOG_MAX_BULLET_CHARS = 500;
+const CHANGELOG_ALL_CATEGORIES = [
+  "Added",
+  "Fixed",
+  "Changed",
+  "Deprecated",
+  "Removed",
+  "Security"
+];
+const CHANGELOG_MUST_SHOW = ["Added", "Fixed", "Changed"];
+const CHANGELOG_FOLDED = ["Deprecated", "Removed", "Security"];
+const CHANGELOG_CATEGORY_ZH = {
+  Added: "\u65B0\u589E",
+  Fixed: "\u4FEE\u590D",
+  Changed: "\u53D8\u66F4",
+  Deprecated: "\u5F03\u7528\u9884\u544A",
+  Removed: "\u79FB\u9664",
+  Security: "\u5B89\u5168"
+};
+function emptySections() {
+  return { Added: [], Fixed: [], Changed: [], Deprecated: [], Removed: [], Security: [] };
+}
+function isCategoryName(v) {
+  return CHANGELOG_ALL_CATEGORIES.includes(v);
+}
+function normalizeCategory(raw) {
+  const t = String(raw || "").trim().toLowerCase();
+  if (t === "added") return "Added";
+  if (t === "fixed") return "Fixed";
+  if (t === "changed") return "Changed";
+  if (t === "deprecated") return "Deprecated";
+  if (t === "removed") return "Removed";
+  if (t === "security") return "Security";
+  return null;
+}
+function isUnreleasedVersion(v) {
+  return typeof v === "string" && v.trim().toLowerCase() === "unreleased";
+}
+function extractVersionDateAndYanked(title) {
+  const t = String(title || "").trim();
+  if (!t) return { version: null, date: null, yanked: false };
+  const yanked = /\[YANKED\]/i.test(t);
+  if (/unreleased/i.test(t)) return { version: "Unreleased", date: null, yanked };
+  const vm = t.match(/(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
+  if (!vm) return { version: null, date: null, yanked: false };
+  const dm = t.match(/(\d{4}-\d{2}-\d{2})/);
+  return { version: vm[1], date: dm ? dm[1] : null, yanked };
+}
+function truncateBullet(text) {
+  const t = String(text || "").replace(/\s+/g, " ").trim();
+  if (!t) return "";
+  if (t.length <= CHANGELOG_MAX_BULLET_CHARS) return t;
+  return `${t.slice(0, CHANGELOG_MAX_BULLET_CHARS - 1)}\u2026`;
+}
+function parseChangelog(markdown) {
+  try {
+    if (typeof markdown !== "string" || !markdown.trim()) return [];
+    let text = markdown.replace(/\r\n/g, "\n");
+    if (text.length > CHANGELOG_MAX_CHARS) text = text.slice(0, CHANGELOG_MAX_CHARS);
+    const lines = text.split("\n");
+    const entries = [];
+    let cur = null;
+    let curCat = null;
+    let inFence = false;
+    const pushCurrent = () => {
+      if (!cur) return;
+      const hasAny = CHANGELOG_ALL_CATEGORIES.some(
+        (c) => cur.sections[c].length > 0
+      );
+      if (!hasAny) return;
+      for (const c of CHANGELOG_ALL_CATEGORIES) {
+        const list = cur.sections[c];
+        if (list.length > CHANGELOG_MAX_BULLETS_PER_SECTION) {
+          cur.sections[c] = list.slice(0, CHANGELOG_MAX_BULLETS_PER_SECTION);
+        }
+      }
+      entries.push(cur);
+    };
+    for (const rawLine of lines) {
+      const line = String(rawLine ?? "");
+      if (/^\s*(```|~~~)/.test(line)) {
+        inFence = !inFence;
+        continue;
+      }
+      if (inFence) continue;
+      const versionHeading = line.match(/^##(?!#)\s*(.+?)\s*$/);
+      if (versionHeading) {
+        pushCurrent();
+        cur = null;
+        curCat = null;
+        const title = (versionHeading[1] ?? "").trim();
+        const { version, date, yanked } = extractVersionDateAndYanked(title);
+        if (!version) continue;
+        cur = { version, date, yanked, sections: emptySections() };
+        continue;
+      }
+      const catMatch = line.match(/^###\s*(.+?)\s*$/);
+      if (catMatch) {
+        const cat = normalizeCategory(catMatch[1] ?? "");
+        curCat = cur && cat && isCategoryName(cat) ? cat : null;
+        continue;
+      }
+      const bullet = line.match(/^\s*[-*+]\s+(.+?)\s*$/);
+      if (bullet && cur && curCat) {
+        const item = truncateBullet(bullet[1] ?? "");
+        if (item) cur.sections[curCat].push(item);
+        continue;
+      }
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith("#") && /^\s/.test(line) && cur && curCat) {
+        const list = cur.sections[curCat];
+        if (list.length > 0) {
+          const merged = truncateBullet(`${list[list.length - 1]} ${trimmed}`);
+          if (merged) list[list.length - 1] = merged;
+        }
+        continue;
+      }
+    }
+    pushCurrent();
+    return entries.slice(0, CHANGELOG_MAX_ENTRIES);
+  } catch {
+    return [];
+  }
+}
+function hasVisibleSections(entry) {
+  if (!entry || typeof entry !== "object") return false;
+  try {
+    return CHANGELOG_ALL_CATEGORIES.some((c) => Array.isArray(entry.sections?.[c]) && entry.sections[c].length > 0);
+  } catch {
+    return false;
+  }
+}
+function compareReleaseSafe(a, b) {
+  try {
+    return compareReleaseVersions(a, b);
+  } catch {
+    return null;
+  }
+}
+function selectChangelogEntries(entries, fromExclusive, toInclusive) {
+  try {
+    if (!Array.isArray(entries) || entries.length === 0) return [];
+    const to = typeof toInclusive === "string" ? toInclusive.trim() : "";
+    if (!to || !validReleaseVersion(to)) return [];
+    const from = typeof fromExclusive === "string" ? fromExclusive.trim() : "";
+    const fromValid = from && validReleaseVersion(from) ? from : null;
+    const out = [];
+    for (const e of entries) {
+      if (!e || typeof e !== "object") continue;
+      const v = typeof e.version === "string" ? String(e.version) : "";
+      if (!v || isUnreleasedVersion(v) || !validReleaseVersion(v)) continue;
+      if (!hasVisibleSections(e)) continue;
+      const leTo = compareReleaseSafe(v, to);
+      if (leTo === null || leTo > 0) continue;
+      if (fromValid) {
+        const gtFrom = compareReleaseSafe(v, fromValid);
+        if (gtFrom === null || gtFrom <= 0) continue;
+      }
+      out.push(e);
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+function changelogForUpdate(entries, runningVersion, latestVersion, installedVersion) {
+  try {
+    const to = typeof latestVersion === "string" ? latestVersion.trim() : "";
+    if (!to || !validReleaseVersion(to)) return [];
+    const run = typeof runningVersion === "string" ? runningVersion.trim() : "";
+    const inst = typeof installedVersion === "string" ? installedVersion.trim() : "";
+    const from = run && validReleaseVersion(run) ? run : inst && validReleaseVersion(inst) ? inst : "";
+    if (!from) return [];
+    const order = compareReleaseSafe(to, from);
+    if (order === null || order <= 0) return [];
+    return selectChangelogEntries(entries, from, to);
+  } catch {
+    return [];
+  }
+}
+function escapeChangelogHtml(text) {
+  return String(text ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function renderChangelogSection(entry) {
+  try {
+    if (!entry || typeof entry !== "object") return "";
+    const version = String(entry.version ?? "").trim();
+    if (!version || isUnreleasedVersion(version)) return "";
+    if (!hasVisibleSections(entry)) return "";
+    const date = typeof entry.date === "string" ? String(entry.date) : "";
+    const yankedSuffix = entry.yanked === true ? " \xB7 \u5DF2\u64A4\u56DE" : "";
+    const title = (date ? `${version} \xB7 ${date}` : version) + yankedSuffix;
+    const parts = [];
+    parts.push(`<div class="dsh-upd-changelog-version" data-version="${escapeChangelogHtml(version)}">`);
+    parts.push(`<div class="dsh-upd-changelog-title">${escapeChangelogHtml(title)}</div>`);
+    for (const cat of CHANGELOG_MUST_SHOW) {
+      const items = Array.isArray(entry.sections?.[cat]) ? entry.sections[cat] : [];
+      if (items.length === 0) continue;
+      const label = `${cat} \xB7 ${CHANGELOG_CATEGORY_ZH[cat]}`;
+      parts.push(`<div class="dsh-upd-changelog-cat" data-cat="${cat}">`);
+      parts.push(`<div class="dsh-upd-changelog-catname">${escapeChangelogHtml(label)}</div>`);
+      parts.push("<ul>");
+      for (const item of items) {
+        if (!item) continue;
+        parts.push(`<li>${escapeChangelogHtml(item)}</li>`);
+      }
+      parts.push("</ul></div>");
+    }
+    for (const cat of CHANGELOG_FOLDED) {
+      const items = Array.isArray(entry.sections?.[cat]) ? entry.sections[cat] : [];
+      if (items.length === 0) continue;
+      const label = `${cat} \xB7 ${CHANGELOG_CATEGORY_ZH[cat]}\uFF08${items.length}\uFF09`;
+      parts.push(`<details class="dsh-upd-changelog-fold" data-cat="${cat}">`);
+      parts.push(`<summary>${escapeChangelogHtml(label)}</summary>`);
+      parts.push("<ul>");
+      for (const item of items) {
+        if (!item) continue;
+        parts.push(`<li>${escapeChangelogHtml(item)}</li>`);
+      }
+      parts.push("</ul></details>");
+    }
+    parts.push("</div>");
+    return parts.join("\n");
+  } catch {
+    return "";
+  }
+}
+function renderChangelogNeutral() {
+  return `<div class="dsh-upd-changelog-neutral">${escapeChangelogHtml(CHANGELOG_NEUTRAL_LINE)}</div>`;
+}
+function renderChangelogHTML(entries, opts) {
+  try {
+    if (!Array.isArray(entries) || entries.length === 0) return renderChangelogNeutral();
+    const from = opts && typeof opts.from === "string" ? opts.from : null;
+    const to = opts && typeof opts.to === "string" ? opts.to : null;
+    let ranged;
+    if (from !== null || to !== null) {
+      ranged = selectChangelogEntries(entries, from, to);
+    } else {
+      ranged = entries.filter((e) => {
+        try {
+          const v = String(e.version ?? "");
+          return !!v && !isUnreleasedVersion(v) && hasVisibleSections(e);
+        } catch {
+          return false;
+        }
+      });
+    }
+    if (ranged.length === 0) return renderChangelogNeutral();
+    const blocks = ranged.map((e) => renderChangelogSection(e)).filter((s) => !!s);
+    if (blocks.length === 0) return renderChangelogNeutral();
+    return `<div class="dsh-upd-changelog">
+${blocks.join("\n")}
+</div>`;
+  } catch {
+    return renderChangelogNeutral();
+  }
+}
+export {
+  CHANGELOG_ALL_CATEGORIES,
+  CHANGELOG_CATEGORY_ZH,
+  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
+};

package/dist/client.d.ts

@@ -0,0 +1,16 @@
+import { type PhoneAction } from './config.js';
+export { buildPhoneName, buildPhoneNames } from './config.js';
+export type { PhoneAction } from './config.js';
+export { manualCommand } from './commands.js';
+export { QUEUE_INTENT_TTL_MS, cancelEnqueuedInQueue, emptyQueueState, enqueueInQueue, isHeadOfQueue, isQueueBusy, normalizeQueueState, pruneExpiredIntents, queuePositionOf, releaseOwnerInQueue, setOwnerIfFree, visibleQueueFor, } from './queue.js';
+export type { QueuedEntry, QueueOwner, UpdateQueueState, VisibleQueue, VisibleQueueOwner } from './queue.js';
+export { BATCH_SESSION_VERSION, batchEntryOf, batchProgress, batchRequestId, createBatchSession, emptyBatchSession, failedKeys, isBatchFinished, isTerminalPhase, markBatchEntry, needsRestartKeys, nextBatchKey, normalizeBatchSession, orderTargets, resumeBatchSession, } from './batch.js';
+export type { BatchEntry, BatchPhase, BatchProgress, BatchSession } from './batch.js';
+export { CHANGELOG_FILENAME, CHANGELOG_NEUTRAL_HINT, CHANGELOG_NEUTRAL_LINE, changelogForUpdate, parseChangelog, renderChangelogHTML, selectChangelogEntries, } from './changelog.js';
+export type { ChangelogCategory, ChangelogEntry } from './changelog.js';
+export declare const CLIENT_POLL: {
+    readonly defaultMs: 1000;
+    readonly minMs: 250;
+};
+export declare function buildClientPhoneNames(prefix: string): Record<PhoneAction, string>;
+export declare function assertPollInterval(ms: unknown): number;