dsh-plugin-update 0.2.0 → 0.3.0

package/dist/batch-run.d.ts

@@ -0,0 +1,80 @@
+import { type BatchSession } from './batch.js';
+/** 查一家的结果。 */
+export type BatchCheckOutcome = 
+/** 有新版可装。 */
+{
+    kind: 'update';
+    version: string;
+}
+/** 已是最新，不需要动。 */
+ | {
+    kind: 'current';
+}
+/** 这一版被用户跳过（不装，但也不算失败）。 */
+ | {
+    kind: 'skipped';
+    version: string | null;
+}
+/** 查失败（稳定码）。 */
+ | {
+    kind: 'failed';
+    error: string;
+};
+/** 装一家的结果。 */
+export type BatchInstallOutcome = 
+/** 装完；restartRequired 表示要重启宿主才生效。 */
+{
+    kind: 'done';
+    restartRequired: boolean;
+}
+/** 装失败（稳定码）。 */
+ | {
+    kind: 'failed';
+    error: string;
+}
+/**
+ * 已入队：全局锁被别家占着（宿主的 update-busy），本家排上了但还没轮到。
+ * **不是失败**——这一行的相位回到 ready（远端版本留着），本轮推动到此为止，
+ * 下次推动（或宿主 drain）会从它接着走。这是「一个一个加入队列」那条路的正解：
+ * 用户点「加入队列」= 递一个意图进队列，而不是报一次错。
+ */
+ | {
+    kind: 'queued';
+    position?: number | null;
+};
+/** 驱动器要用到的传输与落盘（调用方注入）。 */
+export interface BatchRunDeps {
+    /** 查这一家的远端版本。 */
+    check: (key: string) => Promise<BatchCheckOutcome>;
+    /** 装这一家：**必须**带上会话给的幂等 requestId（重复提交由队列按它去重）。 */
+    install: (key: string, requestId: string, version: string) => Promise<BatchInstallOutcome>;
+    /** 会话落盘（每一步之后都调一次：这就是「断点续跑」的全部秘密）。 */
+    save: (session: BatchSession) => Promise<void> | void;
+    now: () => number;
+}
+/** 驱动器读数：给日志、面板与门禁用。 */
+export interface BatchRunStep {
+    key: string;
+    action: 'check' | 'install';
+    /** 这一步把该行推到了哪个相位。 */
+    phase: string;
+    /** 失败稳定码（成功为 null）。 */
+    error: string | null;
+}
+export interface BatchRunResult {
+    session: BatchSession;
+    steps: BatchRunStep[];
+    /** 停下来的原因：做完了／按策略遇错停／步数用完／没活可干／**排上队但还没轮到**。 */
+    stoppedBecause: 'finished' | 'stopped-after-failure' | 'max-steps' | 'empty' | 'queued';
+}
+/** 驱动器选项：`maxSteps` 给 1 就是「只推进一步」，便于宿主按自己的节奏推进（drain）。 */
+export interface BatchRunOptions {
+    maxSteps?: number;
+}
+/**
+ * 把会话往前推，直到：收尾／按 stopOnFailure 遇错停下／步数用完／没活可干。
+ * 每一步都先落盘再继续——中途被打断也不会丢进度。
+ */
+export declare function runBatch(session: BatchSession, deps: BatchRunDeps, options?: BatchRunOptions): Promise<BatchRunResult>;
+/** 会话是否已收尾（面板与日志用同一口径）。 */
+export declare function batchRunFinished(session: BatchSession): boolean;

package/dist/batch-run.js

@@ -0,0 +1,86 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/batch-run.ts
+import {
+  batchProgress,
+  isTerminalPhase,
+  markBatchEntry,
+  nextBatchKey
+} from "./batch.js";
+async function runBatch(session, deps, options = {}) {
+  const maxSteps = typeof options.maxSteps === "number" && Number.isFinite(options.maxSteps) && options.maxSteps > 0 ? Math.floor(options.maxSteps) : Number.POSITIVE_INFINITY;
+  const steps = [];
+  let current = session;
+  let used = 0;
+  const persist = async (next) => {
+    current = next;
+    await deps.save(next);
+    return next;
+  };
+  const budgetLeft = () => used < maxSteps;
+  while (true) {
+    const key = nextBatchKey(current);
+    if (key === null) {
+      return { session: current, steps, stoppedBecause: stoppedBecause(current) };
+    }
+    const entry = current.entries.find((e) => e.key === key);
+    if (!entry) return { session: current, steps, stoppedBecause: "empty" };
+    if (!budgetLeft()) return { session: current, steps, stoppedBecause: "max-steps" };
+    let version = entry.phase === "ready" && entry.targetVersion ? entry.targetVersion : null;
+    if (version === null) {
+      await persist(markBatchEntry(current, key, { phase: "checking", error: null }, deps.now()).session);
+      const checked = await deps.check(key);
+      used += 1;
+      if (checked.kind === "failed") {
+        await persist(markBatchEntry(current, key, { phase: "failed", error: checked.error }, deps.now()).session);
+        steps.push({ key, action: "check", phase: "failed", error: checked.error });
+        if (current.stopOnFailure) return { session: current, steps, stoppedBecause: "stopped-after-failure" };
+        continue;
+      }
+      if (checked.kind === "current") {
+        await persist(markBatchEntry(current, key, { phase: "current", targetVersion: null }, deps.now()).session);
+        steps.push({ key, action: "check", phase: "current", error: null });
+        continue;
+      }
+      if (checked.kind === "skipped") {
+        await persist(markBatchEntry(current, key, { phase: "skipped", targetVersion: checked.version }, deps.now()).session);
+        steps.push({ key, action: "check", phase: "skipped", error: null });
+        continue;
+      }
+      await persist(markBatchEntry(current, key, { phase: "ready", targetVersion: checked.version, error: null }, deps.now()).session);
+      steps.push({ key, action: "check", phase: "ready", error: null });
+      version = checked.version;
+      if (!budgetLeft()) return { session: current, steps, stoppedBecause: "max-steps" };
+    }
+    if (version === null) continue;
+    await persist(markBatchEntry(current, key, { phase: "installing" }, deps.now()).session);
+    const installed = await deps.install(key, entry.requestId, version);
+    used += 1;
+    if (installed.kind === "queued") {
+      await persist(markBatchEntry(current, key, { phase: "ready", error: null }, deps.now()).session);
+      steps.push({ key, action: "install", phase: "queued", error: null });
+      return { session: current, steps, stoppedBecause: "queued" };
+    }
+    if (installed.kind === "failed") {
+      await persist(markBatchEntry(current, key, { phase: "failed", error: installed.error }, deps.now()).session);
+      steps.push({ key, action: "install", phase: "failed", error: installed.error });
+      if (current.stopOnFailure) return { session: current, steps, stoppedBecause: "stopped-after-failure" };
+      continue;
+    }
+    await persist(
+      markBatchEntry(current, key, { phase: "done", restartRequired: installed.restartRequired, error: null }, deps.now()).session
+    );
+    steps.push({ key, action: "install", phase: "done", error: null });
+  }
+  return { session: current, steps, stoppedBecause: "max-steps" };
+}
+function stoppedBecause(session) {
+  if (session.entries.length === 0) return "empty";
+  if (session.entries.every((e) => isTerminalPhase(e.phase))) return "finished";
+  return "stopped-after-failure";
+}
+function batchRunFinished(session) {
+  return batchProgress(session).finished;
+}
+export {
+  batchRunFinished,
+  runBatch
+};

package/dist/batch.d.ts

@@ -0,0 +1,111 @@
+/** 会话账本版本号：收到别的数字按空会话处理，不抛错（与队列同一纪律）。 */
+export declare const BATCH_SESSION_VERSION = 1;
+/** 一个目标在一轮批量里的相位。 */
+export type BatchPhase = 
+/** 还没轮到你 */
+'pending'
+/** 正在查远端版本 */
+ | 'checking'
+/** 查到了、有新版可装，等排队 */
+ | 'ready'
+/** 已提交安装，正在进行 */
+ | 'installing'
+/** 本家已是最新，不需要动 */
+ | 'current'
+/** 装完了（可能还要重启宿主才生效，见 restartRequired） */
+ | 'done'
+/** 这一家失败了（error 给稳定码），按策略决定要不要继续下一家 */
+ | 'failed'
+/** 这一家被跳过（用户跳过该版本） */
+ | 'skipped';
+/** 终态：不会再变化的相位。 */
+export declare function isTerminalPhase(phase: BatchPhase): boolean;
+/** 会话里的一行。 */
+export interface BatchEntry {
+    /** 目标稳定键（会话内唯一）。 */
+    key: string;
+    phase: BatchPhase;
+    /** 幂等编号：同一会话同一目标恒定，重复提交不重复装（队列按它占位）。 */
+    requestId: string;
+    /** 远端最新版（查过才有）。 */
+    targetVersion: string | null;
+    /** 装完之后是否要重启宿主才生效（pending-restart）。 */
+    restartRequired: boolean;
+    /** 失败稳定码（认不出给 internal）；成功恒为 null。 */
+    error: string | null;
+    /** 这一行最后一次变化的时刻。 */
+    updatedAt: number;
+}
+/** 一轮批量更新的会话账本（落盘形状）。 */
+export interface BatchSession {
+    version: 1;
+    /** 会话编号（调用方给：时间戳 + 随机串之类，只作标识用）。 */
+    id: string;
+    /** 「自己」的键：排序时排最后；没有就传 null。 */
+    selfKey: string | null;
+    /** 一家失败后是否停下（默认 false：继续下一家）。 */
+    stopOnFailure: boolean;
+    /** 目标处理顺序（自更新安全：selfKey 在最后）。 */
+    order: string[];
+    entries: BatchEntry[];
+    createdAt: number;
+    updatedAt: number;
+}
+/** 会话里进度的读数。 */
+export interface BatchProgress {
+    total: number;
+    done: number;
+    failed: number;
+    skipped: number;
+    current: number;
+    pending: number;
+    /** 终态齐了就 true（失败也算收尾——不阻塞整轮的结束）。 */
+    finished: boolean;
+}
+/**
+ * 目标顺序：selfKey 排最后，其余保持传入顺序（稳定排序，不许键乱序导致顺序漂移）。
+ * 传进来的键去重后仍为空即返回空数组，调用方按「没有可做的」处理。
+ */
+export declare function orderTargets(keys: readonly string[], selfKey?: string | null): string[];
+/** 会话内某一行的幂等编号：会话 + 目标 ⇒ 恒定（重跑同一会话不会重复装）。 */
+export declare function batchRequestId(sessionId: string, key: string): string;
+/** 开一轮会话：给定目标键与「自己」的键，按自更新安全排好序，每行落一个幂等编号。 */
+export declare function createBatchSession(args: {
+    id: string;
+    keys: readonly string[];
+    selfKey?: string | null;
+    stopOnFailure?: boolean;
+    now: number;
+}): BatchSession;
+/** 空会话（文件缺失或损坏时的回退：坏账本不能挡更新，与队列同一纪律）。 */
+export declare function emptyBatchSession(): BatchSession;
+/** 把外面读到的值验成可用的会话：错了不抛错，回空会话。 */
+export declare function normalizeBatchSession(raw: unknown): BatchSession;
+/** 按会话顺序取某一行。 */
+export declare function batchEntryOf(session: BatchSession, key: string): BatchEntry | null;
+/**
+ * 下一个该处理的目标键：
+ * - 按会话顺序找第一个非终态行；
+ * - `stopOnFailure` 为真且已有失败行时返回 null（停下，等人处理）；
+ * - 全部收尾返回 null。
+ */
+export declare function nextBatchKey(session: BatchSession): string | null;
+/** 改一行：返回新会话（不可变），键不存在时原样返回且 changed=false。 */
+export declare function markBatchEntry(session: BatchSession, key: string, patch: Partial<Omit<BatchEntry, 'key' | 'requestId'>>, now: number): {
+    session: BatchSession;
+    changed: boolean;
+};
+/** 进度读数（面板与门禁共用同一份口径）。 */
+export declare function batchProgress(session: BatchSession): BatchProgress;
+/** 一轮结束：每一行都进了终态（失败也算收尾——失败不该让整轮永远挂着）。 */
+export declare function isBatchFinished(session: BatchSession): boolean;
+/** 要重启才生效的那几家（批量装完给一条总账，别让用户逐家点）。 */
+export declare function needsRestartKeys(session: BatchSession): string[];
+/** 失败的那几家（给人话总账用）。 */
+export declare function failedKeys(session: BatchSession): string[];
+/**
+ * 断点续跑：把「进行中」的行退回 pending——重启/重载后不知道它们走到哪了，
+ * 由调用方重新查一次真实状态再决定装不装（幂等编号不变，重复提交不会重复装）。
+ * 终态行（done/current/failed/skipped）一律保留：**已完成的不重装**。
+ */
+export declare function resumeBatchSession(session: BatchSession, now: number): BatchSession;

package/dist/batch.js

@@ -0,0 +1,183 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/batch.ts
+const BATCH_SESSION_VERSION = 1;
+function isTerminalPhase(phase) {
+  return phase === "done" || phase === "failed" || phase === "skipped" || phase === "current";
+}
+function asMillis(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+const PHASES = ["pending", "checking", "ready", "installing", "current", "done", "failed", "skipped"];
+function asPhase(value) {
+  return typeof value === "string" && PHASES.includes(value) ? value : "pending";
+}
+function orderTargets(keys, selfKey) {
+  const seen = /* @__PURE__ */ new Set();
+  const others = [];
+  let self = null;
+  for (const key of keys) {
+    if (!isNonEmptyString(key) || seen.has(key)) continue;
+    seen.add(key);
+    if (selfKey && key === selfKey) self = key;
+    else others.push(key);
+  }
+  return self ? [...others, self] : others;
+}
+function batchRequestId(sessionId, key) {
+  return "batch:" + sessionId + ":" + key;
+}
+function createBatchSession(args) {
+  const id = isNonEmptyString(args.id) ? args.id : "batch";
+  const selfKey = isNonEmptyString(args.selfKey) ? args.selfKey : null;
+  const order = orderTargets(args.keys, selfKey);
+  const now = asMillis(args.now, 0);
+  const entries = order.map((key) => ({
+    key,
+    phase: "pending",
+    requestId: batchRequestId(id, key),
+    targetVersion: null,
+    restartRequired: false,
+    error: null,
+    updatedAt: now
+  }));
+  return {
+    version: BATCH_SESSION_VERSION,
+    id,
+    selfKey,
+    stopOnFailure: args.stopOnFailure === true,
+    order,
+    entries,
+    createdAt: now,
+    updatedAt: now
+  };
+}
+function emptyBatchSession() {
+  return {
+    version: BATCH_SESSION_VERSION,
+    id: "",
+    selfKey: null,
+    stopOnFailure: false,
+    order: [],
+    entries: [],
+    createdAt: 0,
+    updatedAt: 0
+  };
+}
+function normalizeBatchSession(raw) {
+  try {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return emptyBatchSession();
+    const input = raw;
+    if (input["version"] !== BATCH_SESSION_VERSION) return emptyBatchSession();
+    const id = isNonEmptyString(input["id"]) ? input["id"] : "";
+    const selfKey = isNonEmptyString(input["selfKey"]) ? input["selfKey"] : null;
+    const entries = [];
+    const seen = /* @__PURE__ */ new Set();
+    const rawEntries = input["entries"];
+    if (Array.isArray(rawEntries)) {
+      for (const item of rawEntries) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+        const e = item;
+        const key = e["key"];
+        if (!isNonEmptyString(key) || seen.has(key)) continue;
+        seen.add(key);
+        const requestId = isNonEmptyString(e["requestId"]) ? e["requestId"] : batchRequestId(id, key);
+        entries.push({
+          key,
+          phase: asPhase(e["phase"]),
+          requestId,
+          targetVersion: isNonEmptyString(e["targetVersion"]) ? e["targetVersion"] : null,
+          restartRequired: e["restartRequired"] === true,
+          error: isNonEmptyString(e["error"]) ? e["error"] : null,
+          updatedAt: asMillis(e["updatedAt"], 0)
+        });
+      }
+    }
+    const order = entries.map((e) => e.key);
+    return {
+      version: BATCH_SESSION_VERSION,
+      id,
+      selfKey: selfKey && seen.has(selfKey) ? selfKey : null,
+      stopOnFailure: input["stopOnFailure"] === true,
+      order,
+      entries,
+      createdAt: asMillis(input["createdAt"], 0),
+      updatedAt: asMillis(input["updatedAt"], 0)
+    };
+  } catch {
+    return emptyBatchSession();
+  }
+}
+function batchEntryOf(session, key) {
+  return session.entries.find((e) => e.key === key) ?? null;
+}
+function nextBatchKey(session) {
+  if (session.stopOnFailure && session.entries.some((e) => e.phase === "failed")) return null;
+  for (const key of session.order) {
+    const entry = session.entries.find((e) => e.key === key);
+    if (entry && !isTerminalPhase(entry.phase)) return key;
+  }
+  return null;
+}
+function markBatchEntry(session, key, patch, now) {
+  const at = session.entries.findIndex((e) => e.key === key);
+  if (at < 0) return { session, changed: false };
+  const next = { ...session.entries[at], ...patch, key: session.entries[at].key, requestId: session.entries[at].requestId, updatedAt: asMillis(now, session.entries[at].updatedAt) };
+  const entries = [...session.entries.slice(0, at), next, ...session.entries.slice(at + 1)];
+  return { session: { ...session, entries, updatedAt: next.updatedAt }, changed: true };
+}
+function batchProgress(session) {
+  const total = session.entries.length;
+  let done = 0;
+  let failed = 0;
+  let skipped = 0;
+  let current = 0;
+  let pending = 0;
+  for (const entry of session.entries) {
+    if (entry.phase === "done" || entry.phase === "current") done += 1;
+    else if (entry.phase === "failed") failed += 1;
+    else if (entry.phase === "skipped") skipped += 1;
+    else if (entry.phase === "installing" || entry.phase === "checking" || entry.phase === "ready") current += 1;
+    else pending += 1;
+  }
+  return { total, done, failed, skipped, current, pending, finished: isBatchFinished(session) };
+}
+function isBatchFinished(session) {
+  return session.entries.length > 0 && session.entries.every((e) => isTerminalPhase(e.phase));
+}
+function needsRestartKeys(session) {
+  return session.entries.filter((e) => e.restartRequired).map((e) => e.key);
+}
+function failedKeys(session) {
+  return session.entries.filter((e) => e.phase === "failed").map((e) => e.key);
+}
+function resumeBatchSession(session, now) {
+  const at = asMillis(now, session.updatedAt);
+  let changed = false;
+  const entries = session.entries.map((entry) => {
+    if (entry.phase === "checking" || entry.phase === "installing") {
+      changed = true;
+      return { ...entry, phase: "pending", error: null, updatedAt: at };
+    }
+    return entry;
+  });
+  return changed ? { ...session, entries, updatedAt: at } : session;
+}
+export {
+  BATCH_SESSION_VERSION,
+  batchEntryOf,
+  batchProgress,
+  batchRequestId,
+  createBatchSession,
+  emptyBatchSession,
+  failedKeys,
+  isBatchFinished,
+  isTerminalPhase,
+  markBatchEntry,
+  needsRestartKeys,
+  nextBatchKey,
+  normalizeBatchSession,
+  orderTargets,
+  resumeBatchSession
+};

package/dist/changelog-io.d.ts

@@ -0,0 +1,56 @@
+/**
+ * src/changelog-io.ts —— 更新日志的 Node 侧读写（#23）。
+ *
+ * 纯解析在 `src/changelog.ts`（零导入，两边可进）；
+ * 本文件只做跑腿（读盘、联网、解包、验 integrity），仅 Node 侧导入，
+ * 面板（浏览器闭包）永不导入本文件。
+ *
+ * 两种读取时机（#11 §4 第 5 条）：
+ * - 已装版离线读：`node_modules/<目标包>/CHANGELOG.md`（与版本 pin 绑定，零新增联网）；
+ * - 新版按需取：新版 tarball 内同名文件，复用官方源 + integrity 校验；
+ * 取不到一律回 null（调用方渲染中性提示，不挡安装、不写 blockedReason）。
+ */
+/** tarball 下载上限（字节，压缩态）：超限直接回落中性提示，不解包、不OOM。 */
+export declare const CHANGELOG_TARBALL_MAX_BYTES: number;
+/**
+ * tar 解压后上限（字节）：gzip 炸弹墙（#23 对抗复查补记——此前只卡压缩态，
+ * 恶意小包可炸出 GB 级 tar 直接 OOM 宿主）。超限回 null，调用方渲染中性提示。
+ */
+export declare const CHANGELOG_TAR_MAX_BYTES: number;
+/** 日志文本上限（字节）：超限截断后返回，不断面板。 */
+export declare const CHANGELOG_FETCH_MAX_BYTES: number;
+/** 默认官方源（与 service.NPM_REGISTRY 同值，显式传参优先）。 */
+export declare const CHANGELOG_DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+/**
+ * 已装版离线读（best-effort，失败回 null）：
+ *读 `<目标包目录>/CHANGELOG.md`，空文件回 null（调用方给中性提示）。
+ */
+export declare function readInstalledChangelogText(targetPackageDir: unknown, opts?: {
+    maxBytes?: number;
+}): Promise<string | null>;
+export interface ReleaseChangelogRef {
+    /** tarball 地址（service.fetchNpmRelease 回的 tarball 原样）。 */
+    tarball: unknown;
+    /** integrity 串（`sha512-…`，复用官方源校验）。 */
+    integrity: unknown;
+    /** 该发行版本号（用于严格路径校验，可选）。 */
+    version?: unknown;
+}
+/**
+ * 从已解压的 tar 包里取同名文件（best-effort，找不到回 null）。
+ * 只收普通文件（typeflag `0`/`\0`），目录与特殊文件一律跳过。
+ */
+export declare function extractChangelogFromTar(tarBytes: Uint8Array, maxBytes?: number): string | null;
+/**
+ * 新版按需取（best-effort，任何一步失败回 null，调用方渲染中性提示）：
+ * 取 tarball → 验 integrity（官方源同一信任根）→ gunzip → 取包内同名文件。
+ * 同源校验：tarball 与 registryUrl 同 origin、无用户信息、无 search/hash；
+ * 有目标包名 + 版本时再要求精确路径（与 service.fetchNpmRelease 同形）。
+ */
+export declare function fetchReleaseChangelogText(fetchImpl: unknown, release: ReleaseChangelogRef | null | undefined, opts?: {
+    targetPackageName?: string;
+    registryUrl?: string;
+    timeoutMs?: number;
+    maxTarballBytes?: number;
+    maxChangelogBytes?: number;
+}): Promise<string | null>;