dsh-plugin-update 0.2.0 → 0.3.0

package/dist/client.js

@@ -2,6 +2,46 @@
 import { buildPhoneNames, DEFAULT_PANEL_POLL_MS, MIN_PANEL_POLL_MS } from "./config.js";
 import { buildPhoneName, buildPhoneNames as buildPhoneNames2 } from "./config.js";
 import { manualCommand as manualCommand2 } from "./commands.js";
+import {
+  QUEUE_INTENT_TTL_MS,
+  cancelEnqueuedInQueue,
+  emptyQueueState,
+  enqueueInQueue,
+  isHeadOfQueue,
+  isQueueBusy,
+  normalizeQueueState,
+  pruneExpiredIntents,
+  queuePositionOf,
+  releaseOwnerInQueue,
+  setOwnerIfFree,
+  visibleQueueFor
+} from "./queue.js";
+import {
+  BATCH_SESSION_VERSION,
+  batchEntryOf,
+  batchProgress,
+  batchRequestId,
+  createBatchSession,
+  emptyBatchSession,
+  failedKeys,
+  isBatchFinished,
+  isTerminalPhase,
+  markBatchEntry,
+  needsRestartKeys,
+  nextBatchKey,
+  normalizeBatchSession,
+  orderTargets,
+  resumeBatchSession
+} from "./batch.js";
+import {
+  CHANGELOG_FILENAME,
+  CHANGELOG_NEUTRAL_HINT,
+  CHANGELOG_NEUTRAL_LINE,
+  changelogForUpdate,
+  parseChangelog,
+  renderChangelogHTML,
+  selectChangelogEntries
+} from "./changelog.js";
 const CLIENT_POLL = {
   defaultMs: DEFAULT_PANEL_POLL_MS,
   minMs: MIN_PANEL_POLL_MS
@@ -16,10 +56,44 @@ function assertPollInterval(ms) {
   return ms;
 }
 export {
+  BATCH_SESSION_VERSION,
+  CHANGELOG_FILENAME,
+  CHANGELOG_NEUTRAL_HINT,
+  CHANGELOG_NEUTRAL_LINE,
   CLIENT_POLL,
+  QUEUE_INTENT_TTL_MS,
   assertPollInterval,
+  batchEntryOf,
+  batchProgress,
+  batchRequestId,
   buildClientPhoneNames,
   buildPhoneName,
   buildPhoneNames2 as buildPhoneNames,
-  manualCommand2 as manualCommand
+  cancelEnqueuedInQueue,
+  changelogForUpdate,
+  createBatchSession,
+  emptyBatchSession,
+  emptyQueueState,
+  enqueueInQueue,
+  failedKeys,
+  isBatchFinished,
+  isHeadOfQueue,
+  isQueueBusy,
+  isTerminalPhase,
+  manualCommand2 as manualCommand,
+  markBatchEntry,
+  needsRestartKeys,
+  nextBatchKey,
+  normalizeBatchSession,
+  normalizeQueueState,
+  orderTargets,
+  parseChangelog,
+  pruneExpiredIntents,
+  queuePositionOf,
+  releaseOwnerInQueue,
+  renderChangelogHTML,
+  resumeBatchSession,
+  selectChangelogEntries,
+  setOwnerIfFree,
+  visibleQueueFor
 };

package/dist/commands.d.ts

@@ -0,0 +1,59 @@
+/**
+ * src/commands.ts — 安装命令的纯拼接（政策收归核心）。
+ *
+ * 由 update-core/src/commands.ts 原样拎入，两条产物形状冻结（改键改模板即破冰）：
+ *   1. 执行配方（installRecipe）——真正安装时用：按宿主种类选路由，程序与参数数组分开，
+ *      使用范围名原样进数组；一律精确版本与官方源——第三方 Desktop 与普通宿主那两条把源写进
+ *      参数数组（带 --save-exact），官方桌面版那条只交一个精确版本规格，源走宿主管理器的选项。
+ *   2. 手工兜底文案（manualCommand）——给人复制到终端执行：沿用命令串形状，
+ *      使用范围名含特殊字符时加引号（只影响展示，不影响配方）。
+ * 自包含：不引用同层其它文件，版本号小工具按需内联。
+ * 类型引用只用 import type，转译后无运行时导入。
+ *
+ * 相对原样的增量（规格 #591 第 4、5 条）：目标包名、官方源、安装时限经可选字段注入，
+ * 默认值等于现状常量。不传即走现状，老调用零变化。
+ */
+import type { BlockedReason, EnvironmentKind, InstallRecipe, ReleaseChannel } from './ports.js';
+/** 安装时限：15 分钟（起进程到退出，超时终止整棵进程树并按失败处理）。 */
+export declare const INSTALL_TIMEOUT_MS: number;
+/**
+ * 安装执行配方：宿主种类决定路由，使用范围决定目标。
+ *
+ * - 第三方 Desktop（desktop）→ desktop-service：由桌面端公开的 desktopPnpm 服务用参数数组
+ *   拉起打包好的 CLI，插件不碰 .cmd 垫片、不经 shell。
+ * - 官方桌面版（desktop-manager）→ desktop-manager：交给宿主进程内的插件管理器，参数只有
+ *   「add + 精确版本规格」——它只收一个 spec 字符串、不接受任何开关，源走它的 registry 选项。
+ * - 普通 DSH 宿主（cli）→ cli-process：用「当前运行时的可执行文件 + CLI 的 JS 入口
+ *   + 参数数组」自己起进程；三系统同一套形态，差异只在可执行文件与入口由适配器提供。
+ *
+ * 前两条一律带官方源与 --save-exact；官方源不可达时由适配器诚实失败，不换源。
+ * 宿主种类不是已知三种取值、或目标包名不合管理器规格时不给配方（诚实失败转手工命令），不猜。
+ */
+export declare function installRecipe(input: {
+    profileName: string | null;
+    version: string;
+    environmentKind: EnvironmentKind;
+    targetPackageName?: string;
+    registryUrl?: string;
+    timeoutMs?: number;
+    /** 版本通道（#16）：默认 stable；显式传 prerelease 才可装预发布精确版。 */
+    releaseChannel?: ReleaseChannel;
+}): InstallRecipe | null;
+/**
+ * 手工兜底命令：给人复制到终端执行，形状沿用 `dsh plugin --profile <名> add <包>@<版本>`。
+ * 与配方同一套政策（精确版本、官方源、--save-exact），只是使用范围名含特殊字符时加引号，
+ * 因为这一串要经用户自己的 shell 解释。网络受限时用户可自行去掉 --registry=。
+ * 源码安装等不安全情形不给命令。
+ */
+export declare function manualCommand(input: {
+    profileName: string | null;
+    latestVersion: string | null;
+    installedVersion: string | null;
+    runningVersion: string;
+    jobTargetVersion: string | null;
+    blockedReason: BlockedReason | null;
+    sourceInstall: boolean;
+    targetPackageName?: string;
+    registryUrl?: string;
+    releaseChannel?: ReleaseChannel;
+}): string | null;

package/dist/commands.js

@@ -6,6 +6,27 @@ const INSTALL_TIMEOUT_MS = 15 * 6e4;
 function validVersion(v) {
   return typeof v === "string" && /^\d+\.\d+\.\d+$/.test(v);
 }
+function validPrereleaseIds(ids) {
+  if (typeof ids !== "string" || !ids) return false;
+  const parts = ids.split(".");
+  if (parts.length === 0) return false;
+  for (const p of parts) {
+    if (!p || !/^[0-9A-Za-z-]+$/.test(p)) return false;
+    if (/^\d+$/.test(p) && p.length > 1 && p.startsWith("0")) return false;
+  }
+  return true;
+}
+function validReleaseVersion(v) {
+  if (typeof v !== "string" || !v) return false;
+  const dash = v.indexOf("-");
+  if (dash < 0) return validVersion(v);
+  if (v.slice(dash + 1).includes("+")) return false;
+  return validVersion(v.slice(0, dash)) && validPrereleaseIds(v.slice(dash + 1));
+}
+function versionAllowed(version, channel) {
+  if (channel === "prerelease") return validReleaseVersion(version);
+  return validVersion(version);
+}
 function parseTriple(v) {
   const parts = String(v).split(".");
   if (parts.length > 3) return null;
@@ -29,6 +50,39 @@ function compareVersions(a, b) {
   }
   return 0;
 }
+function compareReleaseVersions(a, b) {
+  if (!validReleaseVersion(a) || !validReleaseVersion(b)) throw new Error("invalid-release");
+  const dashA = a.indexOf("-");
+  const dashB = b.indexOf("-");
+  const coreA = dashA < 0 ? a : a.slice(0, dashA);
+  const coreB = dashB < 0 ? b : b.slice(0, dashB);
+  const order = compareVersions(coreA, coreB);
+  if (order !== 0) return order;
+  const preA = dashA < 0 ? null : a.slice(dashA + 1).split(".");
+  const preB = dashB < 0 ? null : b.slice(dashB + 1).split(".");
+  if (preA === null && preB === null) return 0;
+  if (preA === null) return 1;
+  if (preB === null) return -1;
+  const width = Math.max(preA.length, preB.length);
+  for (let i = 0; i < width; i++) {
+    const x = preA[i];
+    const y = preB[i];
+    if (x === void 0) return -1;
+    if (y === void 0) return 1;
+    const xn = /^\d+$/.test(x) ? Number(x) : null;
+    const yn = /^\d+$/.test(y) ? Number(y) : null;
+    if (xn !== null && yn !== null) {
+      if (xn < yn) return -1;
+      if (xn > yn) return 1;
+      continue;
+    }
+    if (xn !== null) return -1;
+    if (yn !== null) return 1;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
 function usableProfileName(raw) {
   const name = typeof raw === "string" ? raw.trim() : "";
   if (!name || name.length > 255 || name.startsWith("-")) return null;
@@ -38,7 +92,8 @@ function usableProfileName(raw) {
 function installRecipe(input) {
   const name = usableProfileName(input?.profileName);
   const version = input?.version;
-  if (!name || !validVersion(version)) return null;
+  const channel = input?.releaseChannel === "prerelease" ? "prerelease" : "stable";
+  if (!name || !versionAllowed(version, channel)) return null;
   const kind = input?.environmentKind;
   if (kind !== "desktop" && kind !== "desktop-manager" && kind !== "cli") return null;
   const targetName = input?.targetPackageName ?? PACKAGE_NAME;
@@ -71,14 +126,15 @@ function manualCommand(input) {
   const targetName = input.targetPackageName ?? PACKAGE_NAME;
   const registry = input.registryUrl ?? NPM_REGISTRY;
   if (!targetName || !registry) return null;
+  const channel = input.releaseChannel === "prerelease" ? "prerelease" : "stable";
   const arg = /^[A-Za-z0-9_.-]+$/.test(name) ? name : JSON.stringify(name);
-  const picks = [input.latestVersion, input.jobTargetVersion, input.installedVersion].filter(validVersion);
+  const picks = [input.latestVersion, input.jobTargetVersion, input.installedVersion].filter((v) => versionAllowed(v, channel));
   let version = picks.length > 0 ? picks[0] : "latest";
   try {
-    const ranked = picks.filter((v) => compareVersions(v, input.runningVersion) >= 0);
+    const ranked = picks.filter((v) => compareReleaseVersions(v, input.runningVersion) >= 0);
     if (ranked.length > 0) {
       version = ranked[0];
-      for (const v of ranked) if (compareVersions(v, version) === 1) version = v;
+      for (const v of ranked) if (compareReleaseVersions(v, version) === 1) version = v;
     }
   } catch {
   }

package/dist/config.d.ts

@@ -0,0 +1,48 @@
+export declare const DEFAULT_PREFIX = "wf";
+export declare const PHONE_ACTIONS: readonly ["updateStatus", "updateCheck", "updateInstall"];
+export type PhoneAction = (typeof PHONE_ACTIONS)[number];
+export declare const DEFAULT_TARGET_PACKAGE = "dsh-mattpocock-skills-deck";
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
+export declare const LEGACY_PLUGIN_ID = "dsh-mattpocock-skills-deck";
+export declare const LEGACY_DIR_SEGMENT = "updates";
+export declare const STATE_FILE = "state.json";
+export declare const LOCK_FILE = "install.lock";
+export declare const BACKUP_FILE = "before.json";
+export declare const SKIPPED_FILE = "skipped.json";
+export declare const RELEASE_CHANNELS: readonly ["stable", "prerelease"];
+export type ReleaseChannelOption = (typeof RELEASE_CHANNELS)[number];
+export declare const DEFAULT_CHECK_TIMEOUT_MS = 10000;
+export declare const DEFAULT_CONFIRMATION_TTL_MS: number;
+export declare const DEFAULT_INSTALL_TIMEOUT_MS: number;
+export declare const DEFAULT_PANEL_POLL_MS = 1000;
+export declare const RECHECK_WINDOW_MS = 2000;
+export declare const MIN_PANEL_POLL_MS = 250;
+export interface UpdateConfigInput {
+    pluginId: string;
+    prefix?: string;
+    targetPackageName?: string;
+    registryUrl?: string;
+    homeDir?: string;
+    checkTimeoutMs?: number;
+    confirmationTtlMs?: number;
+    installTimeoutMs?: number;
+    panelPollMs?: number;
+    releaseChannel?: ReleaseChannelOption;
+}
+export interface ResolvedUpdateConfig {
+    pluginId: string;
+    prefix: string;
+    targetPackageName: string;
+    registryUrl: string;
+    homeDir: string | null;
+    checkTimeoutMs: number;
+    confirmationTtlMs: number;
+    installTimeoutMs: number;
+    panelPollMs: number;
+    releaseChannel: ReleaseChannelOption;
+}
+export declare function assertPluginId(value: unknown): string;
+export declare function assertPrefix(value: unknown, role: string): string;
+export declare function resolveUpdateConfig(input: UpdateConfigInput): ResolvedUpdateConfig;
+export declare function buildPhoneNames(prefix: string): Record<PhoneAction, string>;
+export declare function buildPhoneName(prefix: string, action: PhoneAction): string;

package/dist/config.js

@@ -8,6 +8,8 @@ const LEGACY_DIR_SEGMENT = "updates";
 const STATE_FILE = "state.json";
 const LOCK_FILE = "install.lock";
 const BACKUP_FILE = "before.json";
+const SKIPPED_FILE = "skipped.json";
+const RELEASE_CHANNELS = ["stable", "prerelease"];
 const DEFAULT_CHECK_TIMEOUT_MS = 1e4;
 const DEFAULT_CONFIRMATION_TTL_MS = 10 * 6e4;
 const DEFAULT_INSTALL_TIMEOUT_MS = 15 * 6e4;
@@ -60,7 +62,11 @@ function resolveUpdateConfig(input) {
   if (panelPollMs < MIN_PANEL_POLL_MS) {
     throw new Error("[dsh-plugin-update] \u9762\u677F\u8F6E\u8BE2 panelPollMs \u975E\u6CD5\uFF1A\u4E0D\u5F97\u5C0F\u4E8E 250 \u6BEB\u79D2\uFF08\u6536\u5230 " + JSON.stringify(input.panelPollMs) + "\uFF09");
   }
-  return { pluginId, prefix, targetPackageName, registryUrl, homeDir, checkTimeoutMs, confirmationTtlMs, installTimeoutMs, panelPollMs };
+  const releaseChannel = input.releaseChannel === void 0 ? "stable" : input.releaseChannel;
+  if (releaseChannel !== "stable" && releaseChannel !== "prerelease") {
+    throw new Error("[dsh-plugin-update] \u7248\u672C\u901A\u9053 releaseChannel \u975E\u6CD5\uFF1A\u53EA\u6536 stable \u6216 prerelease\uFF08\u6536\u5230 " + JSON.stringify(input.releaseChannel) + "\uFF09");
+  }
+  return { pluginId, prefix, targetPackageName, registryUrl, homeDir, checkTimeoutMs, confirmationTtlMs, installTimeoutMs, panelPollMs, releaseChannel };
 }
 function buildPhoneNames(prefix) {
   const checked = assertPrefix(prefix, "\u7535\u8BDD\u540D\u524D\u7F00 prefix");
@@ -88,6 +94,8 @@ export {
   MIN_PANEL_POLL_MS,
   PHONE_ACTIONS,
   RECHECK_WINDOW_MS,
+  RELEASE_CHANNELS,
+  SKIPPED_FILE,
   STATE_FILE,
   assertPluginId,
   assertPrefix,

package/dist/diag.d.ts

@@ -0,0 +1,125 @@
+/**
+ * src/diag.ts —— 电话侧失败证据 diag 落地（#21，承接 #18 契约）。
+ *
+ * 失败回包加可选内联小证据对象 `diag`：平时面板仍只按稳定码分支与文案映射，
+ * 复制诊断按钮用 `diag` 组出一段自包含、可粘贴、已脱敏的文本；日志通道保留用于深挖。
+ * `diag` 只增不改、旧面板宽容读（未知键与错类型一律忽略），缺省即省略；
+ * 脱敏是构造属性，无安全详情时宁可省略也不给原文。所有失败经一次回包即证据闭包，
+ * 不做二次往返；深证据超限再另议，不在本模块内。
+ *
+ * 16 键目录（第一版，线键永不改名）：
+ *   v / stage / route / method / httpStatus / exitCode / latencyMs / detail /
+ *   targetPackageName / runningVersion / latestVersion / environmentKind /
+ *   requestId / checkId / registryHost / action
+ * 其余一律易变（面板必须忽略），queuePos 等上游语义落定后再转正——本模块永不产出
+ * queuePos（保留未来键，见 STAGE_EXPECT 之外的显式断言）。
+ *
+ * 阶段枚举冻结并与真实接缝对齐（6 值）：
+ *   read-installed（读已装）/ fetch-release（取远端）/ validate-release（校验发行物）/
+ *   preflight（装前复核）/ exec（执行）/ verify（装后校验）
+ * 路由与方法正交，不拼串。动作提示由包内政策按（阶段×信号）推导
+ * （retry / manual / contact / restart），面板只渲染不推导。
+ *
+ * 缺省即省略（无此格即本阶段不适用或未知），按（阶段×键）期望表断言；
+ * 对象版本只管大门（v=1），新增可选键不 bump 版本，面板永不分支于版本。
+ * 宽容读契约：未知键忽略、错类型忽略、缺省当正常；面板分支只允许用稳定码。
+ *
+ * 序列化墙：整个 diag JSON ≤ DIAG_INLINE_BUDGET_BYTES（1024，单源见 redaction.ts）。
+ * 按 #24  enforcement 按序丢弃（registryHost → action → 版本 → 其余可选，detail 只截断；
+ * action 可省，v/码/阶段/路由/请求编号永不丢）。verify 阶段暂无电话来源（装后校验走后台异步，
+ * 不经电话失败回包），枚举保留、电话侧不产出；running/latest 仅已知时带，未知即省略。
+ * 构造全程 best-effort：任何一步异常即回 undefined（调用方按无 diag 的旧形状返回，
+ * 新面板×旧载荷仍为正常缺省，不抛）。
+ */
+/** diag 对象版本：只管大门，新增可选键不 bump，面板永不分支于版本。 */
+export declare const DIAG_VERSION = 1;
+/** 阶段枚举（冻结 6 值，与真实接缝对齐）。 */
+export declare const DIAG_STAGES: readonly ["read-installed", "fetch-release", "validate-release", "preflight", "exec", "verify"];
+export type DiagStage = (typeof DIAG_STAGES)[number];
+/** 动作提示（冻结 4 值，包内按阶段×信号推导，面板只渲染）。 */
+export declare const DIAG_ACTIONS: readonly ["retry", "manual", "contact", "restart"];
+export type DiagAction = (typeof DIAG_ACTIONS)[number];
+/** 16 键目录与线类型（面板宽容读的唯一依据）。 */
+export declare const DIAG_KNOWN_TYPES: Record<string, 'number' | 'string'>;
+export declare const DIAG_KEYS: string[];
+/** （阶段×键）期望表：期望有 / 期望没有（缺省即省略，异常仅提示不改分支）。 */
+export declare const DIAG_STAGE_EXPECT: Record<DiagStage, {
+    want: string[];
+    forbid: string[];
+}>;
+export interface DiagInput {
+    /** 稳定码（已收敛后的 error 格，如 check-failed / invalid-release / install-failed …）。 */
+    errorCode: string;
+    /** 电话种类：update-status / update-check / update-install（loggedPhone 的 kind）。 */
+    phoneKind: string;
+    /** 原始错误对象（读 httpStatus / exitCode / detail，不读栈）。 */
+    error?: unknown;
+    /** 调用入参（读 requestId / checkId，脏类型一律忽略）。 */
+    args?: Record<string, unknown>;
+    /** 包配置：目标包名与官方源（源主机名只给认可源）。 */
+    targetPackageName?: unknown;
+    registryUrl?: unknown;
+    /** 已知运行版本（显式覆盖或清单解析值，非版本形状一律省略）。 */
+    runningVersion?: unknown;
+    /** 已知远端版本（失败路径多半未知，未知即省略）。 */
+    latestVersion?: unknown;
+    /** 宿主种类（显式覆盖值，三取值之外一律省略）。 */
+    environmentKind?: unknown;
+    /** 本次电话耗时毫秒（只收有限非负数）。 */
+    latencyMs?: unknown;
+}
+export interface DiagObject {
+    v: number;
+    stage: DiagStage;
+    /** 路由与方法正交；exec 在宿主种类未知时省略（不猜，缺省即省略）。 */
+    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?: DiagAction;
+    /** 显式截断位（#24）：仅超墙动过手时为 true，否则省略以保持 16 键纯净。 */
+    truncated?: boolean;
+}
+/**
+ * 阶段推导（第一性原理：阶段 = 哪道接缝挂了，由电话 × 码共同定位，不单看码）。
+ * - update-status 只读本地：一切失败归 read-installed（从不执行安装，install-failed 在此亦为读失败）。
+ * - update-check 两段：取数失败归 fetch-release，校验失败归 validate-release，其余环境失败归 read-installed。
+ * - update-install 三段：安装执行失败归 exec，取数重验失败归 fetch/validate，其余（含凭证/队列/环境）归 preflight。
+ * verify 暂无电话来源（装后校验走后台异步，不经电话失败回包），此处永不返回 verify。
+ */
+export declare function deriveStage(errorCode: string, phoneKind: string): DiagStage;
+/**
+ * 路由与方法正交（不拼串，各自独立断言）。
+ * - 取数/校验：registry/https；读已装/装后校验：disk/fs。
+ * - preflight：仅 update-busy 走 queue/fs（队列即公平门），其余（凭证/环境）走 disk/fs。
+ * - exec：路由即真实安装路由（由宿主种类定），方法为传输形态；宿主种类未知时省略（不猜）。
+ */
+export declare function deriveRouteMethod(stage: DiagStage, environmentKind: unknown, errorCode?: string): {
+    route?: string;
+    method?: string;
+};
+/** 动作提示包内推导（面板只渲染，不自写状态码分支）。 */
+export declare function deriveAction(stage: DiagStage, errorCode: string): DiagAction;
+/**
+ * 组装 diag（best-effort：任何异常回 undefined，调用方按无 diag 的旧形状返回）。
+ * 永不产出 queuePos；类型恒对；缺省即省略。
+ */
+export declare function buildDiag(input: DiagInput): DiagObject | undefined;
+/**
+ * 序列化 ≤1024 字节墙（#24 单源）：经 redaction.enforceDiagBudget 按序丢弃。
+ * truncated 位显式返回：false 即 16 键原样（删掉该位，保持 #18 目录纯净）；
+ * true 即超墙动过手（保留该位，面板宽容读忽略它，旧面板剥掉 diag 仍逐字不变）。
+ * 仍超（理论上不可能，永不丢键兜底）则回 undefined 按无 diag 处理。
+ */
+export declare function enforceBudget(diag: DiagObject): (DiagObject & {
+    truncated?: boolean;
+}) | undefined;