@marktrue/dsh-mobile-remote 3.2.2-alpha.1-app → 3.2.2-alpha.1

package/lib/plugin-update-transaction.js

@@ -0,0 +1,322 @@
+// 插件自更新的**事务**（ADR 0019「插件自更新」）。
+//
+// 评审（GitLab #32 note 1286）指出的根因是：原来的实现把"回滚"放在**新版插件自己的
+// apply() 里**，而新版插件一旦起不来就永远走不到那里；落位目录又只按版本号命名，
+// 同版本不同内容的更新会先删掉自己的回滚目标；profile 目录还是从模块路径"往上数两层"
+// 猜出来的，在 pnpm 的 virtual store 布局下必错。
+//
+// 本模块把这些前提一次性做对：
+//   1. **不可变产物目录**：按内容标识命名，绝不覆盖既有目录（回滚目标因此永远还在）；
+//   2. **单事务 + 锁**：同一 profile 同时只允许一个更新事务，重复请求幂等返回同一 opId；
+//   3. **profile 目录靠"验证"而不是靠层级推断**：向上找第一个声明了本插件依赖的
+//      package.json；找不到就返回空，调用方转降级指引，绝不动文件。
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { freezePackage, frozenPackageReady } from "./runtime-dependency-snapshot.js";
+import { randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/** 事务阶段。`RESTART_PENDING` 是唯一需要外部监督器介入的阶段。 */
+export const TRANSACTION_PHASE = {
+	/** 正在下载/解包/落位：还没动 profile，失败可安全放弃。 */
+	STAGING: "staging",
+	/** 依赖已切换、正在安装。 */
+	INSTALLING: "installing",
+	/** 已提交，等待宿主重启生效——**监督器接管**。 */
+	RESTART_PENDING: "restart-pending",
+	/** 正在回滚（**中间态**：App 不得据此判成功，F7）。 */
+	ROLLING_BACK: "rolling-back",
+	/** 新版本已确认健康并生效。 */
+	SETTLED: "settled",
+	/** 已回滚到上一版并确认可用。 */
+	ROLLED_BACK: "rolled-back",
+	/** 失败（含回滚失败）。 */
+	FAILED: "failed",
+};
+
+/** 锁的默认失效时间：超过它视为持有者已死（宿主崩溃/被杀）。 */
+export const DEFAULT_LOCK_STALE_MS = 10 * 60 * 1000;
+
+export function newOperationId() {
+	return randomUUID();
+}
+
+/** 事务状态文件（放在插件数据目录，与通知/队列同源）。 */
+export function transactionFile(home) {
+	return join(home, ".dsh", "mobile-remote", "plugin-update-transaction.json");
+}
+
+/** 更新锁**目录**（mkdir 原子独占；见 acquireLock）。 */
+export function updateLockPath(home) {
+	return join(home, ".dsh", "mobile-remote", "plugin-update.lock.d");
+}
+
+/** 兼容旧名（它指向的是一个目录，不再是文件）。 */
+export const updateLockFile = updateLockPath;
+
+/** 下载/解包的工作目录（事务独占）。 */
+export function workRoot(home) {
+	return join(home, ".dsh", "mobile-remote", "update-work");
+}
+
+/** 不可变产物目录根。 */
+export function artifactRoot(home) {
+	return join(home, ".dsh", "mobile-remote", "plugin-artifacts");
+}
+
+/** 不可变快照根（回滚目标）。 */
+export function snapshotRoot(home) {
+	return join(home, ".dsh", "mobile-remote", "plugin-snapshots");
+}
+
+/** 按**内容标识**命名的不可变产物目录；同版本不同内容因此天然分属不同目录。 */
+export function artifactDir(root, contentSha256) {
+	return join(root, String(contentSha256 || "unknown").toLowerCase());
+}
+
+/** 按**内容标识**命名的不可变快照目录（更新前的旧内容）。 */
+export function snapshotDir(root, contentSha256) {
+	return join(root, String(contentSha256 || "unknown").toLowerCase());
+}
+
+export function readTransaction(file) {
+	try {
+		const doc = JSON.parse(readFileSync(file, "utf8"));
+		return doc && typeof doc === "object" ? doc : null;
+	} catch {
+		return null;
+	}
+}
+
+export function writeTransaction(file, tx) {
+	mkdirSync(dirname(file), { recursive: true });
+	const next = { ...tx, updatedAt: new Date().toISOString() };
+	writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+	return next;
+}
+
+export function clearTransaction(file) {
+	try {
+		rmSync(file, { force: true });
+	} catch {
+		// 清不掉不影响正确性：下次事务会覆盖它
+	}
+}
+
+/** Converge only under the same OS arbitration as acquire/release/state writes. */
+export function convergeStaleTransaction({ stateFile, lockPath, expectedLease, now = () => Date.now(), staleMs = 600_000 } = {}) {
+  const result = arbitrate(lockPath, { operation: "converge", stateFile, expectedLease, now: now(), staleMs });
+  if (!result.ok) return { action: "blocked", error: result.error, transaction: readTransaction(stateFile) };
+  return result;
+}
+
+/**
+ * 定位 profile 目录：从插件真实路径向上找**第一个声明了本插件依赖**的 package.json。
+ *
+ * 为什么不"往上数两层"：Node 解析包链接时会走 realpath，pnpm 标准布局下插件位于
+ * `profile/node_modules/.pnpm/<entry>/node_modules/dsh-mobile-remote`，往上两层得到的是
+ * `.pnpm/<entry>` 而不是 profile。这里改成**验证式查找**：找到的目录必须真的把
+ * `dsh-mobile-remote` 写在 dependencies 里，否则继续往上，全都不匹配就返回空串。
+ */
+/** 旧键：早期安装用的包名（保持向后兼容）。 */
+export const LEGACY_DEPENDENCY_KEY = "dsh-mobile-remote";
+
+/**
+ * 本插件在 profile 里可能出现的依赖键。
+ * 包名一旦带 scope（npm 正式渠道），profile 的依赖键就变成 `@scope/name`——
+ * 若还硬编码旧键，自更新会找不到 profile。因此键从**插件自己的 package.json** 推导。
+ */
+export function dependencyKeysFor(pluginRoot, { readJson = readJsonFile } = {}) {
+	const keys = [];
+	try {
+		const name = readJson(join(pluginRoot, "package.json"))?.name;
+		if (typeof name === "string" && name.trim() !== "") keys.push(name.trim());
+	} catch {
+		// 读不到自己的包名时只留旧键
+	}
+	if (!keys.includes(LEGACY_DEPENDENCY_KEY)) keys.push(LEGACY_DEPENDENCY_KEY);
+	return keys;
+}
+
+/** 在 profile 的 dependencies 里找出实际使用的那个依赖键（找不到返回空串）。 */
+export function dependencyKeyIn(doc, keys = [LEGACY_DEPENDENCY_KEY]) {
+	for (const key of keys) {
+		if (typeof doc?.dependencies?.[key] === "string") return key;
+	}
+	return "";
+}
+
+export function findProfileDir(startDir, { readJson = readJsonFile, maxDepth = 8, keys } = {}) {
+	const dependencyKeys = keys ?? dependencyKeysFor(startDir, { readJson });
+	let dir = resolve(startDir);
+	for (let i = 0; i < maxDepth; i++) {
+		try {
+			const doc = readJson(join(dir, "package.json"));
+			if (dependencyKeyIn(doc, dependencyKeys) !== "") return dir;
+		} catch {
+			// 该层没有 package.json 或不可读：继续向上
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return "";
+}
+
+function readJsonFile(file) {
+	return JSON.parse(readFileSync(file, "utf8"));
+}
+
+/** 读 profile 里本插件的依赖声明；找不到返回空串（调用方据此转降级指引）。 */
+export function profileSpecifierOf(profileDir, { readJson = readJsonFile, keys = [LEGACY_DEPENDENCY_KEY] } = {}) {
+	if (!profileDir) return "";
+	try {
+		const doc = readJson(join(profileDir, "package.json"));
+		const key = dependencyKeyIn(doc, keys);
+		return key === "" ? "" : doc.dependencies[key];
+	} catch {
+		return "";
+	}
+}
+
+// C3: stable arbitration inode, kernel flock, and an unguessable generation fence.
+// Metadata is never interpreted/removed by read->rename/rm outside this arbitration.
+const arbiter = fileURLToPath(new URL("./update-lock-arbiter.js", import.meta.url));
+function arbitrate(lockPath, request) {
+  mkdirSync(dirname(lockPath), { recursive: true });
+  const r = spawnSync("flock", ["--exclusive", "--wait", "5", `${lockPath}.arbitration`, process.execPath, arbiter], {
+    input: JSON.stringify({ ...request, lockPath }), encoding: "utf8", timeout: 7000,
+  });
+  if (r.error || r.status !== 0) return { ok: false, error: "lock-arbitration-unavailable" };
+  try { return JSON.parse(r.stdout); } catch { return { ok: false, error: "lock-arbitration-invalid" }; }
+}
+export function readLock(dir) {
+  try { return JSON.parse(readFileSync(join(dir, "holder.json"), "utf8")); } catch { return null; }
+}
+export function defaultIsPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch(e) { return e.code === "EPERM"; }
+}
+export function lockHeld(dir) { return readLock(dir) !== null; }
+export function acquireLock(dir, { opId, pid = process.pid, now = Date.now(), lease, stateFile } = {}) {
+  if (!validOperationId(opId)) return { ok: false, error: "invalid-operation-id" };
+  return arbitrate(dir, { operation: "acquire", opId, pid, now, lease, stateFile });
+}
+export function releaseLock(dir, lease, { stateFile } = {}) {
+  // An opId alone is not ownership. Old workers need the exact generation too.
+  if (!lease?.generation) return false;
+  return arbitrate(dir, { operation: "release", lease, stateFile }).ok;
+}
+export function handOverLock(dir, { lease, toPid } = {}) {
+  if (!lease?.generation) return false;
+  return arbitrate(dir, { operation: "handover", lease, toPid }).ok;
+}
+export function assertUpdateLease(lockPath, lease) {
+  const r = arbitrate(lockPath, { operation: "assert", lease });
+  if (!r.ok) throw new Error(r.error);
+  return r.holder;
+}
+export function writeOwnedTransaction(stateFile, tx, { lockPath, lease, currentFile, expectedPhases } = {}) {
+  const r = arbitrate(lockPath, { operation: "state-write", lease, stateFile, tx, currentFile, expectedPhases });
+  if (!r.ok) throw new Error(r.error);
+  return r.transaction;
+}
+export function switchOwnedDependency({ profileDir, nextSpecifier, key, lockPath, lease } = {}) {
+  return arbitrate(lockPath, { operation: "switch-profile", lease, profileDir, specifier: nextSpecifier, key });
+}
+export function claimOwnedRecovery(stateFile, { owner }, { lockPath, lease, currentFile } = {}) {
+  return arbitrate(lockPath, { operation: 'claim-recovery', lease, stateFile, owner, currentFile });
+}
+export function finishOwnedTerminal(stateFile, { phase, result, expectedPhases }, { lockPath, lease, currentFile } = {}) {
+  const r = arbitrate(lockPath, { operation: 'finish-terminal', lease, stateFile, phase, result, expectedPhases, currentFile });
+  if (!r.ok) throw new Error(r.error);
+  return r.transaction;
+}
+export function restoreOwnedProfile({ profileDir, snapshotDir, snapshot, key, preserveSpecifier = false, lockPath, lease } = {}) {
+  return arbitrate(lockPath, { operation: 'restore-profile', profileDir, snapshotDir, snapshot, key, preserveSpecifier, lease });
+}
+export function publishOwnedSnapshotLink({ profileDir, snapshotDir, key, lockPath, lease } = {}) {
+  return arbitrate(lockPath, { operation: 'publish-snapshot-link', profileDir, snapshotDir, key, lease });
+}
+export function validOperationId(opId) {
+  return typeof opId === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,95}$/.test(opId);
+}
+export function serverOperationPath(home, id) {
+  if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id)) throw new Error("invalid-filesystem-id");
+  return join(home, ".dsh", "mobile-remote", "transactions", `${id}.json`);
+}
+
+/**
+ * 把当前已安装的插件内容快照成**自包含、可加载**的不可变副本（F4）：
+ *   - **解引用 symlink**：pnpm 布局下副本里的依赖是符号链接，若原样复制会指向树外的
+ *     store；解引用后快照自己就是完整的依赖树；
+ *   - **原子发布**：全部复制完成后才写 `.complete` 标记；中途失败留下的半成品不会被
+ *     当成可用快照（`snapshotReady` 会拒绝）。
+ */
+export function snapshotInstalled({ installedRoot, destDir, copyFile } = {}) {
+  if (!existsSync(installedRoot)) return { ok: false, error: "installed-root-missing" };
+  return freezePackage({ sourceRoot: installedRoot, destination: destDir, copyFile });
+}
+
+/** 默认复制实现：**解引用符号链接**，得到自包含树。 */
+export function defaultCopyDir(src, dest) {
+	try {
+		mkdirSync(dest, { recursive: true });
+		copyRecursive(src, dest, new Set());
+		return { ok: true };
+	} catch (e) {
+		return { ok: false, error: String(e?.message ?? e) };
+	}
+}
+
+function copyRecursive(src, dest, seen) {
+	// 防环：symlink 解引用后可能回到祖先
+	const key = `${src}->${dest}`;
+	if (seen.has(key)) return;
+	seen.add(key);
+	for (const entry of readdirSync(src, { withFileTypes: true })) {
+		const from = join(src, entry.name);
+		const to = join(dest, entry.name);
+		if (entry.isSymbolicLink()) {
+			// 解引用：把链接目标的内容复制过来（目标缺失则跳过，不制造悬空链接）
+			let real;
+			try {
+				real = realpathSync(from);
+			} catch {
+				throw new Error("required-link-broken");
+			}
+			const st = statSync(real);
+			if (st.isDirectory()) {
+				mkdirSync(to, { recursive: true });
+				copyRecursive(real, to, seen);
+			} else if (st.isFile()) {
+				writeFileSync(to, readFileSync(real));
+			}
+			continue;
+		}
+		if (entry.isDirectory()) {
+			mkdirSync(to, { recursive: true });
+			copyRecursive(from, to, seen);
+		} else if (entry.isFile()) {
+			writeFileSync(to, readFileSync(from));
+		}
+	}
+}
+
+/** 快照完成标记（原子发布的凭据）。 */
+export const COMPLETE_MARKER = ".complete";
+
+/** 目录是否存在且非空（用于判断产物是否可用）。 */
+export function dirReady(dir) {
+	try {
+		return statSync(dir).isDirectory() && readdirSync(dir).length > 0;
+	} catch {
+		return false;
+	}
+}
+
+/** 快照是否**完整可用**：非空且带完成标记（半复制不会被当成回滚目标）。 */
+export function snapshotReady(dir) {
+	return frozenPackageReady(dir);
+}

package/lib/plugin-update.js

@@ -0,0 +1,309 @@
+// 插件侧的**更新判定**（CONTEXT「内容标识」「对齐提示」「降级指引」）。
+//
+// 这里只放纯逻辑，不做任何 I/O 决策之外的事：
+//   - 规范化发布清单；
+//   - 解析 tgz 的下载地址（清单里给 `url`，否则相对清单自身地址解析）；
+//   - 比较「本地内容标识 vs 清单内容标识」决定要不要下载（版本号只做提示与排序）；
+//   - 识别本机的**安装形态**，据此给出可执行动作或降级指引。
+// 下载、校验、落位、pnpm、重启属于执行面，不在这里（见后续阶段的执行模块）。
+//
+// 三条判据互不代替：能力能不能用看能力声明；要不要下载看**内容标识**；要不要提示看版本号。
+import { createHash } from "node:crypto";
+
+/** 本模块能处理的清单 schema。 */
+export const SUPPORTED_MANIFEST_SCHEMA = 1;
+
+/** 更新判定结果。 */
+export const UPDATE_ACTION = {
+	/** 本地内容与清单一致：已是最新。 */
+	UP_TO_DATE: "up-to-date",
+	/** 清单内容与本地不同、且不早于本地：应更新。 */
+	UPDATE_AVAILABLE: "update-available",
+	/** 本地比清单新（例如本地装了更新的自建构建）：不降级。 */
+	LOCAL_AHEAD: "local-ahead",
+	/** 清单不可用或字段缺失：无法判断，如实报出。 */
+	UNKNOWN: "unknown",
+};
+
+/** 安装形态（决定升级动作，见 docs/06-install-run.md 的三种方式）。 */
+export const INSTALL_SHAPE = {
+	/** 从 npm/registry 解析（`^3.2.0` 之类）。 */
+	REGISTRY: "registry",
+	/** `github:owner/repo#tag` 这类 git 依赖。 */
+	GITHUB_TAG: "github-tag",
+	/** `file:` 指向一个本地 clone（含 .git）。 */
+	FILE_CLONE: "file-clone",
+	/** `file:` 指向一个已解开的目录（非 git 仓库）。 */
+	FILE_DIR: "file-dir",
+	/** `file:` 指向一个 .tgz 包。 */
+	TGZ_FILE: "tgz-file",
+	/** 无法识别。 */
+	UNKNOWN: "unknown",
+};
+
+/** 更新执行方式：能自动完成，还是只能给出可复制的指引。 */
+export const UPDATE_MODE = {
+	AUTO: "auto",
+	GUIDANCE: "guidance",
+};
+
+/**
+ * 解析 `X.Y.Z`、可选 SemVer prerelease（如 `3.2.1-alpha.1`）与数字 `+N` build 号；不合法返回 null。
+ * `version` 是**只含 core** 的 `X.Y.Z` 字串：两端配对（App 的 `X.Y.Z+N` 与插件）只比它，
+ * prerelease 只影响插件自身的排序（见 compareVersion）。
+ */
+export function parseVersion(value) {
+	const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+(\d+))?$/
+		.exec(typeof value === "string" ? value.trim() : "");
+	if (!m) return null;
+	const prerelease = m[4] === undefined ? [] : m[4].split(".");
+	// SemVer §9：纯数字的 prerelease 标识符不得有前导零（`alpha.01` 非法，`alpha.1` 合法）。
+	for (const identifier of prerelease) {
+		if (/^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith("0")) return null;
+	}
+	return {
+		major: +m[1],
+		minor: +m[2],
+		patch: +m[3],
+		version: `${+m[1]}.${+m[2]}.${+m[3]}`,
+		prerelease,
+		build: m[5] === undefined ? null : +m[5],
+	};
+}
+
+/** 比较两个 prerelease 标识符（SemVer §11.4：数字按数值比、数字 < 字母数字、字母数字按 ASCII）。 */
+function comparePrereleaseIdentifier(a, b) {
+	const numericA = /^\d+$/.test(a);
+	const numericB = /^\d+$/.test(b);
+	if (numericA && numericB) {
+		// 无前导零的数字串：先比长度再比字典序即等价于按数值比较（超长数字也不丢精度）。
+		if (a.length !== b.length) return a.length < b.length ? -1 : 1;
+		if (a === b) return 0;
+		return a < b ? -1 : 1;
+	}
+	if (numericA) return -1;
+	if (numericB) return 1;
+	if (a === b) return 0;
+	return a < b ? -1 : 1;
+}
+
+/** 比较 prerelease 段：无 prerelease 的版本优先级更高（3.2.1 > 3.2.1-alpha.1）。 */
+function comparePrerelease(a, b) {
+	const left = a.prerelease;
+	const right = b.prerelease;
+	if (left.length === 0 && right.length === 0) return 0;
+	if (left.length === 0) return 1;
+	if (right.length === 0) return -1;
+	const length = Math.min(left.length, right.length);
+	for (let index = 0; index < length; index++) {
+		const comparison = comparePrereleaseIdentifier(left[index], right[index]);
+		if (comparison !== 0) return comparison;
+	}
+	if (left.length === right.length) return 0;
+	return left.length < right.length ? -1 : 1;
+}
+
+/**
+ * 比较两个版本号，返回 -1 / 0 / 1；任一不可解析时返回 null。
+ * 主序按 SemVer：core → prerelease（`3.2.1-alpha.1 < 3.2.1`、`alpha.2 > alpha.1`）。
+ * `+build` 是本仓既有扩展：只在 core 与 prerelease 都相同时参与比较
+ * （App 侧用它判断"有没有更新"；两端配对看的是 core，见 compareSemanticVersion）。
+ */
+export function compareVersion(a, b) {
+	const pa = parseVersion(a);
+	const pb = parseVersion(b);
+	if (!pa || !pb) return null;
+	for (const k of ["major", "minor", "patch"]) {
+		if (pa[k] !== pb[k]) return pa[k] < pb[k] ? -1 : 1;
+	}
+	const prerelease = comparePrerelease(pa, pb);
+	if (prerelease !== 0) return prerelease;
+	if (pa.build !== null && pb.build !== null && pa.build !== pb.build) return pa.build < pb.build ? -1 : 1;
+	return 0;
+}
+
+/**
+ * 规范化发布清单。只接受 schema 1；`plugin` 段是插件自更新所必需的部分。
+ * 缺失字段不猜测：把可选的留空、必需的报错。
+ */
+export function normalizeReleaseManifest(raw) {
+	if (!raw || typeof raw !== "object") return { ok: false, error: "manifest-not-object" };
+	if (raw.schema !== SUPPORTED_MANIFEST_SCHEMA) {
+		return { ok: false, error: "manifest-schema-unsupported", schema: raw.schema };
+	}
+	const p = raw.plugin;
+	if (!p || typeof p !== "object") return { ok: false, error: "manifest-plugin-missing" };
+	if (typeof p.version !== "string" || !parseVersion(p.version)) return { ok: false, error: "manifest-plugin-version-invalid" };
+	if (typeof p.file !== "string" || p.file === "") return { ok: false, error: "manifest-plugin-file-missing" };
+	const sha256 = typeof p.sha256 === "string" ? p.sha256.toLowerCase() : "";
+	if (!/^[0-9a-f]{64}$/.test(sha256)) return { ok: false, error: "manifest-plugin-sha256-invalid" };
+	const contentSha256 = typeof p.contentSha256 === "string" ? p.contentSha256.toLowerCase() : "";
+	if (contentSha256 !== "" && !/^[0-9a-f]{64}$/.test(contentSha256)) {
+		return { ok: false, error: "manifest-plugin-content-sha256-invalid" };
+	}
+	return {
+		ok: true,
+		schema: raw.schema,
+		plugin: {
+			version: p.version,
+			file: p.file,
+			url: typeof p.url === "string" && p.url !== "" ? p.url : "",
+			size: Number.isFinite(p.size) ? p.size : null,
+			sha256,
+			contentSha256,
+		},
+		app: raw.app && typeof raw.app === "object" ? raw.app : null,
+	};
+}
+
+/**
+ * 解析插件包的下载地址：清单给了 `url` 就用它，否则相对**清单自身地址**解析。
+ * 两者都没有则返回空串（调用方按"来源不可用"处理）。
+ */
+export function resolvePluginUrl(manifestUrl, plugin) {
+	if (plugin?.url) return plugin.url;
+	if (!manifestUrl || !plugin?.file) return "";
+	try {
+		return new URL(plugin.file, manifestUrl).toString();
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * 决定要不要下载新版本。
+ *
+ * 判据是**内容标识**：版本号相同而内容不同（真实存在的形态）必须被识别为"应更新"。
+ * 缺少内容标识时退化为版本比较，并把这一盲区写进 `reason`，不假装判断是完整的。
+ */
+export function decidePluginUpdate({ localVersion, localContentSha256, remote }) {
+	if (!remote || typeof remote !== "object" || !parseVersion(remote.version)) {
+		return { action: UPDATE_ACTION.UNKNOWN, reason: "remote-version-missing" };
+	}
+	const comparison = compareVersion(remote.version, localVersion ?? "");
+	const localDigest = (localContentSha256 ?? "").toLowerCase();
+	const remoteDigest = (remote.contentSha256 ?? "").toLowerCase();
+
+	if (localDigest && remoteDigest) {
+		if (localDigest === remoteDigest) {
+			return { action: UPDATE_ACTION.UP_TO_DATE, reason: "content-identical", comparison };
+		}
+		if (comparison !== null && comparison < 0) {
+			return { action: UPDATE_ACTION.LOCAL_AHEAD, reason: "content-differs-local-newer", comparison };
+		}
+		return {
+			action: UPDATE_ACTION.UPDATE_AVAILABLE,
+			reason: comparison === 0 ? "content-differs-same-version" : "content-differs-remote-newer",
+			comparison,
+		};
+	}
+
+	if (comparison === null) return { action: UPDATE_ACTION.UNKNOWN, reason: "local-version-unparseable" };
+	if (comparison > 0) return { action: UPDATE_ACTION.UPDATE_AVAILABLE, reason: "version-newer-no-content-digest", comparison };
+	if (comparison < 0) return { action: UPDATE_ACTION.LOCAL_AHEAD, reason: "version-older-no-content-digest", comparison };
+	// 版本相同又无内容标识：这是"看不见版本号相同内容不同"的盲区，如实标注
+	return { action: UPDATE_ACTION.UP_TO_DATE, reason: "version-equal-no-content-digest", comparison };
+}
+
+/** 从依赖声明推断安装形态；纯字符串判断，不碰文件系统。 */
+export function classifySpecifier(specifier) {
+	const s = typeof specifier === "string" ? specifier.trim() : "";
+	if (s === "") return INSTALL_SHAPE.UNKNOWN;
+	if (/^github:/i.test(s)) return INSTALL_SHAPE.GITHUB_TAG;
+	if (/^link:/i.test(s)) return INSTALL_SHAPE.UNKNOWN;
+	if (/^file:/i.test(s)) {
+		const target = s.slice("file:".length).toLowerCase();
+		if (target.endsWith(".tgz") || target.endsWith(".tar.gz")) return INSTALL_SHAPE.TGZ_FILE;
+		return INSTALL_SHAPE.FILE_DIR; // 目录形态；是否 git clone 需要文件系统确认
+	}
+	if (/^[\^~]?\d+\.\d+\.\d+/.test(s) || /^(>|>=|<|<=|=|\*|latest)/.test(s)) return INSTALL_SHAPE.REGISTRY;
+	return INSTALL_SHAPE.UNKNOWN;
+}
+
+/**
+ * 探测安装形态。`specifier` 来自 profile 的 `package.json`；目录形态再用注入的谓词确认
+ * 是否 git 仓库。`deps` 可注入，便于在不碰真实文件系统的测试里驱动。
+ */
+export function detectInstallShape({ specifier, dirPath = "", isGitRepo = () => false } = {}) {
+	const base = classifySpecifier(specifier);
+	if (base === INSTALL_SHAPE.FILE_DIR && dirPath && isGitRepo(dirPath)) return INSTALL_SHAPE.FILE_CLONE;
+	return base;
+}
+
+/**
+ * 该形态下如何更新。`auto` 表示本机可以自行完成（改依赖声明 + 安装 + 重启）；
+ * `guidance` 表示只能给出**与实际安装方式对应的那一条**指引，不并列三条让用户猜。
+ */
+export function planForShape(shape, { specifier = "", dirPath = "" } = {}) {
+	const installCmd = "pnpm install";
+	switch (shape) {
+	case INSTALL_SHAPE.REGISTRY:
+		return {
+			mode: UPDATE_MODE.AUTO,
+			shape,
+			summary: "从 npm 源升级：改写 profile 依赖版本后重新安装",
+			steps: [`把 profile 的依赖版本改为新版（当前 ${specifier || "未知"}）`, "重新安装依赖", "重启 DSH 让插件生效"],
+			commands: [installCmd],
+		};
+	case INSTALL_SHAPE.GITHUB_TAG:
+		return {
+			mode: UPDATE_MODE.AUTO,
+			shape,
+			summary: "git 依赖升级：把 tag 改到新版本后重新安装",
+			steps: [`把 profile 依赖的 tag 改为 v<新版>（当前 ${specifier || "未知"}）`, "重新安装依赖", "重启 DSH 让插件生效"],
+			commands: [installCmd],
+		};
+	case INSTALL_SHAPE.FILE_CLONE:
+		return {
+			mode: UPDATE_MODE.AUTO,
+			shape,
+			summary: "本地 clone 升级：拉取新代码后重新安装",
+			steps: [`在 clone 目录拉取新版本${dirPath ? `（${dirPath}）` : ""}`, "重新安装依赖", "重启 DSH 让插件生效"],
+			commands: [dirPath ? `git -C ${dirPath} pull` : "git pull", installCmd],
+		};
+	case INSTALL_SHAPE.FILE_DIR:
+		return {
+			mode: UPDATE_MODE.AUTO,
+			shape,
+			summary: "本地目录升级：用新版内容替换该目录后重新安装",
+			steps: [`用新版插件内容替换该目录${dirPath ? `（${dirPath}）` : ""}`, "重新安装依赖", "重启 DSH 让插件生效"],
+			commands: [installCmd],
+		};
+	case INSTALL_SHAPE.TGZ_FILE:
+		return {
+			mode: UPDATE_MODE.AUTO,
+			shape,
+			summary: "tgz 安装升级：换上新版 tgz 后重新安装",
+			steps: [`下载新版 tgz 并替换${dirPath ? `（${dirPath}）` : "原包"}`, "重新安装依赖", "重启 DSH 让插件生效"],
+			commands: [installCmd],
+		};
+	default:
+		return {
+			mode: UPDATE_MODE.GUIDANCE,
+			shape: INSTALL_SHAPE.UNKNOWN,
+			summary: "无法识别本机插件安装方式，按 docs/06-install-run.md 的三种方式之一处理",
+			steps: ["确认插件是通过 clone、git tag 还是 tgz 安装的", "按对应方式更新到新版", "重启 DSH 让插件生效"],
+			commands: [],
+		};
+	}
+}
+
+/**
+ * 对齐提示用的比较：只比 core `X.Y.Z`，`prerelease` 与 `+build` 都不参与。
+ * 契约：插件 `3.2.1-alpha.1` 与 App `3.2.1+24` 按 core `3.2.1` 视为对齐；
+ * 同一发布周期内每次构建/预发布都不应把提示刷成噪声。
+ */
+export function compareSemanticVersion(a, b) {
+	const pa = parseVersion(a);
+	const pb = parseVersion(b);
+	if (!pa || !pb) return null;
+	for (const k of ["major", "minor", "patch"]) {
+		if (pa[k] !== pb[k]) return pa[k] < pb[k] ? -1 : 1;
+	}
+	return 0;
+}
+
+/** 计算某个文件的 sha256（发布侧与运行侧共用同一写法，避免大小写/编码差异）。 */
+export function sha256Hex(buf) {
+	return createHash("sha256").update(buf).digest("hex");
+}