dsh-plugin-update 0.2.0 → 0.3.0

package/dist/ports.d.ts

@@ -0,0 +1,208 @@
+/**
+ * src/ports.ts —— 更新模块的插口定义（规格 #591 的字面落实）。
+ *
+ * 由 update-core/src/ports.ts 原样拎入：六边形架构不变，核心只管做决定，插口由核心定，
+ * 跑腿的活全在外面。检验标准仍是核心不碰硬盘、网络、子进程也能被测透，所以本文件只放类型，
+ * 不放任何运行时逻辑；转译出的 JS 是空壳，第二家直接吃 TS 源码。
+ *
+ * 相对原样的增量（规格 #591 要求的新增注入点位，不动冻结的入参回参形状）：
+ * 插件标识、目标包名、官方源、安装时限经 UpdatePorts 的可选字段注入，默认值等于现状。
+ * 三个对外方法、快照六字段、任务公开形状、检查凭证形状、配方五键形状全部冻结不变。
+ */
+/**
+ * 宿主种类：核心按它选安装路由。
+ * - `desktop`：第三方 Desktop 宿主（发布 `desktopProfiles`／`desktopPnpm` 的那一支）；
+ * - `desktop-manager`：官方桌面版（宿主进程内 `pluginManager.installBundle` 那一支）；
+ * - `cli`：普通 DSH 宿主（本包自己起命令行）。
+ *
+ * 取值可增：新增取值属向后兼容，调用方不认就当普通宿主处理（诚实失败转手工命令）；
+ * 值按时间可调，键与形状仍冻结（见 README 第 5 节）。
+ */
+export type EnvironmentKind = 'desktop' | 'desktop-manager' | 'cli';
+/** 版本通道（#16）：默认只推 stable；prerelease 须调用方显式 opt-in。 */
+export type ReleaseChannel = 'stable' | 'prerelease';
+/** 装不了的原因（装前不满足条件只给原因不给装，见通用方案复用清单）。 */
+export type BlockedReason = 'unknown-profile' | 'source-install' | 'invalid-installation' | 'installation-changed' | 'pending-restart' | 'registry-conflict' | 'incompatible-node' | 'recovery-required';
+/** 核心定错误码，适配器只负责把外面世界的脏错误翻译进来。 */
+export type UpdateErrorCode = 'check-failed' | 'invalid-release' | 'check-expired' | 'installation-changed' | 'update-busy' | 'install-failed' | 'unsupported' | 'pending-restart' | 'source-install' | 'unknown-profile' | 'invalid-installation' | 'incompatible-node' | 'registry-conflict' | 'recovery-required';
+/** 快照：恰好六个字段，永远不带钥匙（检查编号与环境指纹另交）。 */
+export interface UpdateSnapshot {
+    /** 运行版本：宿主自带清单里的版本号。 */
+    runningVersion: string;
+    /** 磁盘已装版本：已安装包里的清单版本号（读不到为 null）。 */
+    installedVersion: string | null;
+    /** 远端最新版本：最近一次查新版带回的版本（没查过为 null）。 */
+    latestVersion: string | null;
+    /** 能不能装：环境允许、无阻拦原因、有没过期的检查且指纹一致、远端确实更新。 */
+    canInstall: boolean;
+    /** 装不了的原因（能装为 null）。 */
+    blockedReason: BlockedReason | null;
+    /** 当前任务：只读半程恒为 null，安装票再接真实任务。 */
+    job: UpdateJob | null;
+}
+/** 任务的公开形状（长任务状态随时可问，见通用方案第 5 步）。 */
+export interface UpdateJob {
+    id: string;
+    state: 'installing' | 'verifying' | 'restart-required' | 'completed' | 'failed' | 'interrupted';
+    targetVersion: string | null;
+    /**
+     * 任务说明：失败时是「失败码」或「失败码: 详情」（详情来自宿主原话，已截断、已去掉绝对路径）。
+     * 取值可变，字段与形状不变；要匹配请匹配前缀失败码，不要整串相等（README 第 12 节）。
+     */
+    message: string | null;
+    /** 提交时的请求编号：同一个编号重复提交直接返回旧结果，不重装。 */
+    requestId: string | null;
+}
+/**
+ * 检查凭证：查新版把快照和凭证分开交。
+ * 凭证是“用户当时点头的那一次检查”的绑定（编号加当时看到的环境指纹），
+ * 装更新时调用方把凭证递回来，快照里永远不带钥匙。
+ */
+export interface CheckReceipt {
+    checkId: string;
+    checkedAt: number;
+    expiresAt: number;
+}
+/** 查新版一次返回：快照与凭证分家。 */
+export interface CheckResult {
+    snapshot: UpdateSnapshot;
+    receipt: CheckReceipt | null;
+}
+/** 远端发行信息：只接受名字对得上、版本合法、包地址与完整性校验全合规的返回。 */
+export interface ReleaseInfo {
+    version: string;
+    nodeRange: string;
+    integrity: string;
+    tarball: string;
+}
+/**
+ * 安装执行路由：三条，由核心按宿主种类选（见 installRecipe），适配器只负责把它跑起来。
+ * - `desktop-service`：第三方 Desktop 宿主公开的 `desktopPnpm.runPlugin`；
+ * - `desktop-manager`：官方桌面版进程内的 `pluginManager.installBundle`；
+ * - `cli-process`：普通 DSH 宿主自己起命令行。
+ */
+export type InstallRoute = 'desktop-service' | 'desktop-manager' | 'cli-process';
+/**
+ * 安装执行配方：核心给适配器的完整政策产物（冻结五键：改键改模板即破冰，值按时间可调）。
+ * 一律「程序 + 参数数组」——pluginArgs 是**这条路自己的**参数数组，按路由解释：
+ *   - `desktop-service`／`cli-process`：pnpm 形状（`add --save-exact <包名>@<版本> --registry=<源>`）；
+ *   - `desktop-manager`：宿主管理器形状（`add <包名>@<精确版本>`，一个 spec 字符串、不带任何开关）。
+ * 使用范围名不做引号包裹也不按空格拆分（引号只出现在给用户看的手工命令里）。
+ * 源按路由落地：前两条进参数数组，`desktop-manager` 走管理器自己的 `registry` 选项（取同一个注入值）。
+ */
+export interface InstallRecipe {
+    route: InstallRoute;
+    /** 安装目标使用范围名，原样保留（含空格与非 ASCII 字符）。 */
+    profileName: string;
+    /** 精确版本（不带 ^ ~ 等前缀）。 */
+    version: string;
+    /** 这条路自己的参数数组；含义随路由而定（见本接口说明）。 */
+    pluginArgs: string[];
+    /** 执行时限（毫秒）：超时终止（命令行终止整棵进程树，管理器请求取消）并按安装失败处理。 */
+    timeoutMs: number;
+}
+/**
+ * 适配器看到的环境（小零件：读版本、看环境、上报宿主种类）。
+ * 拼安装命令和选执行器路由收归核心（精确版本、强制官方源是政策，不是跑腿）。
+ * environmentKind 由适配器探测，顺序固定：有 `desktopProfiles` 即 desktop；
+ * 否则有 `pluginManager.installBundle` 且使用范围名恰是命令行明确封禁的 `desktop` 即 desktop-manager；
+ * 其余为 cli。探测不出就按 cli 走，跑不通按诚实失败转手工命令。
+ */
+export interface EnvironmentView {
+    profileName: string | null;
+    environmentKind: EnvironmentKind;
+    homeDir: string | null;
+    profileDir: string | null;
+    installedVersion: string | null;
+    packageValid: boolean;
+    sourceInstall: boolean;
+    blockedReason: BlockedReason | null;
+    installationKey: string | null;
+    eligible: boolean;
+}
+/** 核心要的最小网络形状（结构化定义，不依赖任何运行时的网络类型）。 */
+export interface MinimalHeaders {
+    get(name: string): string | null;
+}
+export interface MinimalResponse {
+    ok: boolean;
+    /** HTTP 状态码（仅联网取数有；假件不给即省略，调用方不得猜）。 */
+    status?: number;
+    headers: MinimalHeaders;
+    text(): Promise<string>;
+}
+export type FetchImpl = (url: string, init?: {
+    headers?: Record<string, string>;
+    redirect?: string;
+    signal?: unknown;
+}) => Promise<MinimalResponse>;
+/**
+ * 插口：时钟和编号从外面灌进来（默认真的、测试用假的）。
+ * 核心不直接读硬盘、不直接联网，联网经外面递进来的 fetchImpl 发生一次。
+ * 安装用的存取与执行也全是外面给的小零件：任务记哪里、锁怎么加、
+ * 备份怎么做、安装命令怎么跑，核心只指挥顺序，不碰硬盘与子进程。
+ *
+ * 新增注入点位（规格 #591 第 2、4、5 条，全部可选，默认值等于现状）：
+ * 插件标识、目标包名、官方源、安装时限。不传即走现状，老调用补一个标识即可。
+ */
+export interface UpdatePorts {
+    readRunningVersion(): string;
+    readInstalled(): EnvironmentView | Promise<EnvironmentView>;
+    fetchImpl: FetchImpl;
+    now(): number;
+    randomId(): string;
+    nodeVersion: string;
+    checkTimeoutMs?: number;
+    confirmationTtlMs?: number;
+    /** 插件标识：单例键与日志标识用（规格 #591 第 2、6、8 条）。 */
+    pluginId?: string;
+    /** 目标包名：要检查更新的那个包是谁（规格 #591 第 4 条，默认等于现状）。 */
+    targetPackageName?: string;
+    /** 官方源：默认等于现状地址（规格 #591 第 4 条）。 */
+    registryUrl?: string;
+    /** 版本通道：默认 stable（与旧行为一字不差），显式传 prerelease 才收预发布（#16）。 */
+    releaseChannel?: ReleaseChannel;
+    /** 安装时限毫秒：默认 15 分钟（规格 #591 第 5 条）。 */
+    installTimeoutMs?: number;
+    /** 读已落盘的任务（没有为 null；读坏由外面抛错，核心收敛为状态不可用）。 */
+    readJob?: () => UpdateJob | null | Promise<UpdateJob | null>;
+    /** 写任务（传 null 为清空；写坏由外面抛错）。 */
+    writeJob?: (job: UpdateJob | null) => void | Promise<void>;
+    /** 抢锁：抢到为 true，被别人占着为 false（同一个使用范围同时只装一个）。 */
+    tryAcquireLock?: (lockId: string) => boolean | Promise<boolean>;
+    /** 放锁（只放自己抢到的那把）。 */
+    releaseLock?: (lockId: string) => void | Promise<void>;
+    /** 装前备份使用范围的清单（小清单，不含凭据与整个家目录）。 */
+    backupJob?: (job: UpdateJob) => void | Promise<void>;
+    /**
+     * 真正跑安装（按钮强制官方源、精确版本与 --save-exact）。
+     * 核心只把政策要的三件事交给适配器：版本、使用范围名、宿主种类；
+     * 适配器必须调 installRecipe 拿配方再执行，不得自己按系统或宿主分支选路由。
+     * 测试一律给假的，不真跑。
+     */
+    runInstall?: (args: {
+        version: string;
+        profileName: string | null;
+        environmentKind: EnvironmentKind;
+    }) => void | Promise<void>;
+}
+/** 对外三个方法（进度不单独给方法，调用方轮询查状态）。 */
+export interface UpdateCore {
+    /** 查状态：只读本地，不联网。 */
+    status(): Promise<UpdateSnapshot>;
+    /** 查新版：联网问一次，成功带回快照加检查凭证（分开交）。 */
+    check(): Promise<CheckResult>;
+    /**
+     * 装更新：拿检查编号加请求编号提交。
+     * 只读半程诚实失败（unsupported），安装票再实现。
+     */
+    install(args: {
+        checkId: string;
+        requestId: string;
+    }): Promise<UpdateSnapshot>;
+}
+/**
+ * 模块标识（运行时唯一内容）：类型在转译时已擦除，
+ * 转译出的 JS 只剩这一行；第二家直接吃 TS 源码。
+ */
+export declare const PORTS_SOURCE = "src/ports.ts";

package/dist/queue.d.ts

@@ -0,0 +1,109 @@
+/** 队列意向默认有效期：10 分钟（与凭证有效期同口径，调用方可覆盖）。 */
+export declare const QUEUE_INTENT_TTL_MS: number;
+/** 正在安装的拥有者（一次只能有一个，与全局锁持有者一一对应）。 */
+export interface QueueOwner {
+    pluginId: string;
+    jobId: string;
+    requestId: string | null;
+    targetVersion: string | null;
+    startedAt: number;
+}
+/** 排队中的安装意向（尚未开始装，只占位）。 */
+export interface QueuedEntry {
+    pluginId: string;
+    requestId: string | null;
+    targetVersion: string | null;
+    enqueuedAt: number;
+}
+/** 队列落盘形状（版本号锁死为 1，收到别的数字按空队列处理，不抛错）。 */
+export interface UpdateQueueState {
+    version: 1;
+    owner: QueueOwner | null;
+    waiting: QueuedEntry[];
+}
+/** 空队列（调用方拿它当起点，落盘文件缺失或损坏时同样回退到它）。 */
+export declare function emptyQueueState(): UpdateQueueState;
+/** 把外面读到的值验成可用的队列：错了不抛错，直接回空队列（队列坏了不能挡安装）。 */
+export declare function normalizeQueueState(raw: unknown): UpdateQueueState;
+/** 丢弃过期的 waiting 意向（owner 不过期——它由全局锁与安装时限看守，不由这里清）。 */
+export declare function pruneExpiredIntents(state: UpdateQueueState, nowMs: number, ttlMs?: number): UpdateQueueState;
+/**
+ * 占位：同一 (pluginId, requestId) 幂等占一位，已在即返回旧位置不挪位。
+ * 位置口径：0 = 已是拥有者，1..n = waiting 中的顺位（队首为 1），与 visibleQueueFor 的
+ * position 同口径。targetVersion 仅作展示用，不参与身份判定；已在时不覆盖旧条目。
+ */
+export declare function enqueueInQueue(state: UpdateQueueState, entry: {
+    pluginId: string;
+    requestId?: string | null;
+    targetVersion?: string | null;
+    enqueuedAt: number;
+}): {
+    state: UpdateQueueState;
+    position: number | null;
+};
+/**
+ * 取消排队意向：只能取消自己的 waiting 条目（pluginId 必须对上），owner 不经这里取消。
+ * 对不上（他人的条目、owner、查无此人）返回 removed: false 且状态原样。
+ */
+export declare function cancelEnqueuedInQueue(state: UpdateQueueState, pluginId: string, requestId: string | null): {
+    state: UpdateQueueState;
+    removed: boolean;
+};
+/** 拥有者收尾：只有 (pluginId, jobId) 双对上才清掉，对不上原样（不替别人摘牌）。 */
+export declare function releaseOwnerInQueue(state: UpdateQueueState, pluginId: string, jobId: string): {
+    state: UpdateQueueState;
+    released: boolean;
+};
+/** 把队首意向提为拥有者（调用方抢到全局锁后记账用；队空或信息不全返回 promoted: false）。 */
+export declare function promoteHeadToOwner(state: UpdateQueueState, args: {
+    jobId: string;
+    startedAt: number;
+}): {
+    state: UpdateQueueState;
+    promoted: boolean;
+};
+/** 直接记拥有者（抢到全局锁但 waiting 里没有自己意向时的兜底记账；已有 owner 不覆盖）。 */
+export declare function setOwnerIfFree(state: UpdateQueueState, owner: {
+    pluginId: string;
+    jobId: string;
+    requestId?: string | null;
+    targetVersion?: string | null;
+    startedAt: number;
+}): {
+    state: UpdateQueueState;
+    set: boolean;
+};
+/**
+ * 查位置：0 = 正拥有全局锁在装，1..n = waiting 顺位（队首为 1），null = 不在队列里。
+ * 面板拿它展示“前方还有 N 个”，不展开他人明细也能排得明白。
+ */
+export declare function queuePositionOf(state: UpdateQueueState, pluginId: string, requestId: string | null): number | null;
+/** 队首是不是我（公平门：非队首不许抢锁；队空时人人都是队首）。 */
+export declare function isHeadOfQueue(state: UpdateQueueState, pluginId: string, requestId: string | null): boolean;
+/** 全局是否正忙（有人拥有锁在装）。 */
+export declare function isQueueBusy(state: UpdateQueueState): boolean;
+export interface VisibleQueueOwner {
+    /** 他人拥有时仅露 busy 占位（pluginId 为 null），不露标识；自己拥有时给全量。 */
+    pluginId: string | null;
+    jobId?: string;
+    requestId?: string | null;
+    targetVersion?: string | null;
+    startedAt?: number;
+    busy: true;
+}
+export interface VisibleQueue {
+    busy: boolean;
+    /** 未隐藏时为全量 owner；隐藏他人时他人 owner 折成 {pluginId: null, busy: true}；空闲为 null。 */
+    owner: QueueOwner | VisibleQueueOwner | null;
+    /** 未隐藏时为全 waiting；隐藏时仅留查看者自己的。 */
+    waiting: QueuedEntry[];
+    /** 查看者在全队列中的位置（0 = 在装，1..n = 顺位，null = 不在队列），隐藏时同样给（只给数不给明细）。 */
+    position: number | null;
+}
+/**
+ * 面板可见性开关：包提供全面功能，消费者传参决定是否看他人项。
+ * - showOthers=true：owner + waiting 全量。
+ * - showOthers=false（默认）：waiting 仅留自己的；owner 是自己的给全量，是他人的折成
+ *   busy 占位（能显示“前方有其他插件在安装”，但看不到是哪一家）。
+ */
+export declare function visibleQueueFor(state: UpdateQueueState, viewerPluginId: string, showOthers?: boolean, requestId?: string | null): VisibleQueue;

package/dist/queue.js

@@ -0,0 +1,182 @@
+// AUTO-GENERATED by node build.mjs — DO NOT EDIT. Source: src/queue.ts
+const QUEUE_INTENT_TTL_MS = 10 * 6e4;
+function emptyQueueState() {
+  return { version: 1, owner: null, waiting: [] };
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function asMillis(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+function normalizeQueueState(raw) {
+  try {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return emptyQueueState();
+    const input = raw;
+    if (input["version"] !== 1) return emptyQueueState();
+    let owner = null;
+    const rawOwner = input["owner"];
+    if (rawOwner && typeof rawOwner === "object" && !Array.isArray(rawOwner)) {
+      const o = rawOwner;
+      if (isNonEmptyString(o["pluginId"]) && isNonEmptyString(o["jobId"])) {
+        owner = {
+          pluginId: o["pluginId"],
+          jobId: o["jobId"],
+          requestId: typeof o["requestId"] === "string" ? o["requestId"] : null,
+          targetVersion: typeof o["targetVersion"] === "string" ? o["targetVersion"] : null,
+          startedAt: asMillis(o["startedAt"], 0)
+        };
+      }
+    }
+    const waiting = [];
+    const rawWaiting = input["waiting"];
+    if (Array.isArray(rawWaiting)) {
+      for (const item of rawWaiting) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+        const e = item;
+        if (!isNonEmptyString(e["pluginId"])) continue;
+        waiting.push({
+          pluginId: e["pluginId"],
+          requestId: typeof e["requestId"] === "string" ? e["requestId"] : null,
+          targetVersion: typeof e["targetVersion"] === "string" ? e["targetVersion"] : null,
+          enqueuedAt: asMillis(e["enqueuedAt"], 0)
+        });
+      }
+    }
+    return { version: 1, owner, waiting };
+  } catch {
+    return emptyQueueState();
+  }
+}
+function sameIntent(a, b) {
+  return a.pluginId === b.pluginId && (a.requestId ?? null) === (b.requestId ?? null);
+}
+function pruneExpiredIntents(state, nowMs, ttlMs = QUEUE_INTENT_TTL_MS) {
+  const now = asMillis(nowMs, 0);
+  const ttl = typeof ttlMs === "number" && Number.isFinite(ttlMs) && ttlMs > 0 ? ttlMs : QUEUE_INTENT_TTL_MS;
+  const waiting = state.waiting.filter((e) => now - asMillis(e.enqueuedAt, now) < ttl);
+  if (waiting.length === state.waiting.length) return state;
+  return { version: 1, owner: state.owner, waiting };
+}
+function enqueueInQueue(state, entry) {
+  const base = normalizeQueueState(state);
+  if (!isNonEmptyString(entry.pluginId)) return { state: base, position: null };
+  const key = { pluginId: entry.pluginId, requestId: entry.requestId ?? null };
+  if (base.owner && sameIntent(base.owner, key)) return { state: base, position: 0 };
+  const at = base.waiting.findIndex((e) => sameIntent(e, key));
+  if (at >= 0) return { state: base, position: at + 1 };
+  const next = {
+    pluginId: entry.pluginId,
+    requestId: entry.requestId ?? null,
+    targetVersion: typeof entry.targetVersion === "string" ? entry.targetVersion : null,
+    enqueuedAt: asMillis(entry.enqueuedAt, 0)
+  };
+  const waiting = [...base.waiting, next];
+  return { state: { version: 1, owner: base.owner, waiting }, position: waiting.length };
+}
+function cancelEnqueuedInQueue(state, pluginId, requestId) {
+  const base = normalizeQueueState(state);
+  if (!isNonEmptyString(pluginId)) return { state: base, removed: false };
+  const key = { pluginId, requestId: requestId ?? null };
+  if (base.owner && sameIntent(base.owner, key)) return { state: base, removed: false };
+  const at = base.waiting.findIndex((e) => sameIntent(e, key));
+  if (at < 0) return { state: base, removed: false };
+  const waiting = [...base.waiting.slice(0, at), ...base.waiting.slice(at + 1)];
+  return { state: { version: 1, owner: base.owner, waiting }, removed: true };
+}
+function releaseOwnerInQueue(state, pluginId, jobId) {
+  const base = normalizeQueueState(state);
+  if (!isNonEmptyString(pluginId) || !isNonEmptyString(jobId)) return { state: base, released: false };
+  if (!base.owner || base.owner.pluginId !== pluginId || base.owner.jobId !== jobId) {
+    return { state: base, released: false };
+  }
+  return { state: { version: 1, owner: null, waiting: base.waiting }, released: true };
+}
+function promoteHeadToOwner(state, args) {
+  const base = normalizeQueueState(state);
+  if (base.owner || base.waiting.length === 0) return { state: base, promoted: false };
+  if (!isNonEmptyString(args.jobId)) return { state: base, promoted: false };
+  const [head, ...rest] = base.waiting;
+  const owner = {
+    pluginId: head.pluginId,
+    jobId: args.jobId,
+    requestId: head.requestId,
+    targetVersion: head.targetVersion,
+    startedAt: asMillis(args.startedAt, 0)
+  };
+  return { state: { version: 1, owner, waiting: rest }, promoted: true };
+}
+function setOwnerIfFree(state, owner) {
+  const base = normalizeQueueState(state);
+  if (base.owner) return { state: base, set: false };
+  if (!isNonEmptyString(owner.pluginId) || !isNonEmptyString(owner.jobId)) return { state: base, set: false };
+  return {
+    state: {
+      version: 1,
+      owner: {
+        pluginId: owner.pluginId,
+        jobId: owner.jobId,
+        requestId: owner.requestId ?? null,
+        targetVersion: typeof owner.targetVersion === "string" ? owner.targetVersion : null,
+        startedAt: asMillis(owner.startedAt, 0)
+      },
+      // 抢到锁即消费自己的队首意向（若有），不留僵尸占位。
+      waiting: base.waiting.filter((e) => !sameIntent(e, { pluginId: owner.pluginId, requestId: owner.requestId ?? null }))
+    },
+    set: true
+  };
+}
+function queuePositionOf(state, pluginId, requestId) {
+  const base = normalizeQueueState(state);
+  if (!isNonEmptyString(pluginId)) return null;
+  const key = { pluginId, requestId: requestId ?? null };
+  if (base.owner && sameIntent(base.owner, key)) return 0;
+  const at = base.waiting.findIndex((e) => sameIntent(e, key));
+  return at >= 0 ? at + 1 : null;
+}
+function isHeadOfQueue(state, pluginId, requestId) {
+  const base = normalizeQueueState(state);
+  if (!isNonEmptyString(pluginId)) return false;
+  if (base.waiting.length === 0) return true;
+  const head = base.waiting[0];
+  return head.pluginId === pluginId && (head.requestId ?? null) === (requestId ?? null);
+}
+function isQueueBusy(state) {
+  return normalizeQueueState(state).owner !== null;
+}
+function visibleQueueFor(state, viewerPluginId, showOthers = false, requestId) {
+  const base = normalizeQueueState(state);
+  const rid = requestId === void 0 ? derivedRequestId(base, viewerPluginId) : requestId ?? null;
+  const position = isNonEmptyString(viewerPluginId) ? queuePositionOf(base, viewerPluginId, rid) : null;
+  if (showOthers === true) {
+    return { busy: base.owner !== null, owner: base.owner, waiting: [...base.waiting], position };
+  }
+  const mine = isNonEmptyString(viewerPluginId) ? base.waiting.filter((e) => e.pluginId === viewerPluginId) : [];
+  let owner = null;
+  if (base.owner) {
+    if (base.owner.pluginId === viewerPluginId) owner = base.owner;
+    else owner = { pluginId: null, busy: true };
+  }
+  return { busy: base.owner !== null, owner, waiting: mine, position };
+}
+function derivedRequestId(state, viewerPluginId) {
+  const mine = state.waiting.filter((e) => e.pluginId === viewerPluginId);
+  if (state.owner && state.owner.pluginId === viewerPluginId) return state.owner.requestId;
+  if (mine.length === 0) return null;
+  return mine[0].requestId;
+}
+export {
+  QUEUE_INTENT_TTL_MS,
+  cancelEnqueuedInQueue,
+  emptyQueueState,
+  enqueueInQueue,
+  isHeadOfQueue,
+  isQueueBusy,
+  normalizeQueueState,
+  promoteHeadToOwner,
+  pruneExpiredIntents,
+  queuePositionOf,
+  releaseOwnerInQueue,
+  setOwnerIfFree,
+  visibleQueueFor
+};

package/dist/reader.d.ts

@@ -0,0 +1,84 @@
+/**
+ * src/reader.ts —— 把本机真实情况翻译成更新核心要的零件（读取器）。
+ *
+ * 由 src/host/updateReader.js 改写拎入：只翻译不决定。相对旧实现的增量（规格 #591）：
+ * 1. 插件标识必填（第 2 条）：非空且不含路径分隔符；环境指纹强制含插件标识（第 6 条单例隔离）。
+ * 2. 三处注入默认现状（第 4 条）：目标包名、官方源、目录根经配置注入，默认值等于现状。
+ * 3. 时间可调（第 5 条）：联网超时、凭证有效期、安装时限经配置注入，默认值等于现状。
+ * 4. 包完好判定看目标包名（默认旧包名，默认行为零变化）。
+ */
+import type { EnvironmentKind, EnvironmentView, FetchImpl, ReleaseChannel, UpdateCore, UpdateJob } from './ports.js';
+/** 从起点文件向上找到名字对得上的包（装的是源码还是装好的包都认）。 */
+export declare function containingPackage(filename: string, name: string): Promise<{
+    directory: string;
+    manifest: Record<string, unknown>;
+    contents: string;
+} | null>;
+export interface ResolveTargetPackageOptions {
+    /** 显式目标包目录：给了就不走任何自动解析（hoisted、多副本、开发态链接等场景的逃生口）。 */
+    targetPackageDir?: string;
+}
+/**
+ * 按包名解析目标包（issue #3 治本：不再拿“本包自己住在哪”回答“要更新的包在哪”）。
+ *
+ * 顺序固定：
+ *   1. 显式目录优先（给了就不走自动解析）；
+ *   2. `createRequire(base).resolve(name + '/package.json')` 直解清单；
+ *   3. `createRequire(base).resolve(name)` 取入口，再用 `containingPackage(入口)` 向上找清单；
+ *   4. 手工 sibling 步行（绕过 `exports` 映射：逐级找 `node_modules/<name>/package.json`；
+ *      第 2、3 步受 `exports` 约束，对“契约完整但未导出 `.` 与 `./package.json`”的包会失败，
+ *      这一步按文件系统直读，保证普通依赖形态一定命中）；
+ *   5. 退回自锚定 `containingPackage(自身文件)`（vendor 在目标包内部的老形态）。
+ *
+ * 全失败返回 null，调用方诚实失败，不猜。
+ */
+export declare function resolveTargetPackage(targetName: string, opts?: ResolveTargetPackageOptions): Promise<{
+    directory: string;
+    manifest: Record<string, unknown>;
+    contents: string;
+} | null>;
+/** 使用范围名的唯一取法：调用方给了就用它，否则取使用范围目录的最后一段（宿主探测与读环境共用）。 */
+export declare function resolveProfileName(profileName: string | null | undefined, profileDir: string): string;
+/** 使用范围名是否合法（纯谓词，导出供验证与面板复用）。 */
+export declare function profileNameValid(name: unknown): boolean;
+/** 依赖写法是否像从源装的（纯谓词，导出供验证与面板复用）。 */
+export declare function registrySpec(spec: unknown): boolean;
+/** 家目录默认值：环境变量优先，支持 ~ 写法（导出给调用方取默认值用）。 */
+export declare function defaultHomeDir(env: Record<string, string | undefined>, osHome: string): string;
+export interface UpdateReaderOptions {
+    runningVersion: string;
+    profileDir: string;
+    pluginId: string;
+    profileName?: string;
+    homeDir?: string;
+    /** 显式目标包目录：优先于按包名自动解析（hoisted、多副本、开发态链接等场景的逃生口）。 */
+    targetPackageDir?: string;
+    env?: Record<string, string | undefined>;
+    osHome?: string;
+    fetchImpl?: FetchImpl;
+    now?: () => number;
+    randomId?: () => string;
+    nodeVersion?: string;
+    environmentKind?: EnvironmentKind;
+    targetPackageName?: string;
+    registryUrl?: string;
+    checkTimeoutMs?: number;
+    confirmationTtlMs?: number;
+    /** 版本通道：默认 stable，显式传 prerelease 才收预发布（#16，加法扩展）。 */
+    releaseChannel?: ReleaseChannel;
+    readInstalled?: () => EnvironmentView | Promise<EnvironmentView>;
+    readJob?: () => UpdateJob | null | Promise<UpdateJob | null>;
+    writeJob?: (job: UpdateJob | null) => void | Promise<void>;
+    tryAcquireLock?: (lockId: string) => boolean | Promise<boolean>;
+    releaseLock?: (lockId: string) => void | Promise<void>;
+    backupJob?: (job: UpdateJob) => void | Promise<void>;
+    runInstall?: (args: {
+        version: string;
+        profileName: string | null;
+        environmentKind: EnvironmentKind;
+    }) => void | Promise<void>;
+}
+/** 建更新读取器：运行版本、使用范围目录、插件标识三者必填，其余不给用本机默认。 */
+export declare function createUpdateReader(options: UpdateReaderOptions): UpdateCore & {
+    readEnv: () => Promise<EnvironmentView>;
+};

package/dist/reader.js

@@ -6,7 +6,7 @@ import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { assertPluginId } from "./config.js";
-import { createUpdateCore, validVersion } from "./service.js";
+import { createUpdateCore, isVersionAllowedInChannel, validVersion } from "./service.js";
 const LOCK_FILES = ["pnpm-lock.yaml", "pnpm-workspace.yaml", "package-lock.json"];
 function inside(directory, filename) {
   const suffix = relative(directory, filename);
@@ -97,8 +97,8 @@ function profileNameValid(name) {
 function registrySpec(spec) {
   return typeof spec === "string" && spec.trim().length > 0 && (validVersion(spec.trim()) || /^[~^>=< ]*[0-9x*][0-9x*./\-_ |~^>=<]*$/u.test(spec.trim()) || /^[A-Za-z][A-Za-z0-9._-]*$/u.test(spec.trim()));
 }
-async function validPackage(pkg, targetName) {
-  if (!pkg || pkg.manifest?.name !== targetName || !validVersion(pkg.manifest.version)) return false;
+async function validPackage(pkg, targetName, channel = "stable") {
+  if (!pkg || pkg.manifest?.name !== targetName || !isVersionAllowedInChannel(pkg.manifest.version, channel)) return false;
   const main = pkg.manifest.main;
   const exportsField = pkg.manifest.exports;
   const dshField = pkg.manifest.dsh;
@@ -153,6 +153,7 @@ function createUpdateReader(options) {
   const environmentKind = options.environmentKind ?? "cli";
   const targetPackageName = options.targetPackageName ?? "dsh-mattpocock-skills-deck";
   const registryUrl = options.registryUrl ?? "https://registry.npmjs.org/";
+  const releaseChannel = options.releaseChannel === "prerelease" ? "prerelease" : "stable";
   const loadedPackage = resolveTargetPackage(
     targetPackageName,
     options.targetPackageDir ? { targetPackageDir: options.targetPackageDir } : {}
@@ -200,7 +201,7 @@ function createUpdateReader(options) {
     const deps = profile.manifest.dependencies ?? {};
     result.sourceInstall = !registrySpec(deps[targetPackageName]) || !inside(join(profileDir, "node_modules"), installed.directory);
     result.installedVersion = typeof installed.manifest.version === "string" ? installed.manifest.version : null;
-    result.packageValid = await validPackage(installed, targetPackageName);
+    result.packageValid = await validPackage(installed, targetPackageName, releaseChannel);
     const loaded = await loadedPackage;
     const loadedUnresolvable = loaded === null;
     const identity = `${homeDir}\0${profileDir}\0${profileName}\0${pluginId}`;
@@ -234,6 +235,7 @@ function createUpdateReader(options) {
     confirmationTtlMs: options.confirmationTtlMs,
     targetPackageName,
     registryUrl,
+    releaseChannel,
     readJob: options.readJob,
     writeJob: options.writeJob,
     tryAcquireLock: options.tryAcquireLock,