@marktrue/dsh-mobile-remote 3.2.1-alpha.3 → 3.2.1-rc.1

package/lib/index.js

@@ -39,6 +39,7 @@ import {
 } from "./app-alignment.js";
 export { APP_VERSION_HEADER } from "./app-alignment.js";
 import { clientReleaseView, createPluginUpdateController, publicTransaction } from "./plugin-update-controller.js";
+import { readOperationLog } from "./plugin-update-log.js";
 import { pluginContentDigest } from "./plugin-content-digest.js";
 import {
 	BRIDGE_PORT_CANDIDATES,
@@ -54,11 +55,10 @@ import {
 	TRANSACTION_PHASE,
 	checkForUpdate,
 	detectRestartForm,
-	fetchReleaseManifest,
 	isTerminalPhase,
 	planForShape,
 	reportPendingUpdate,
-	resolveManifestSource,
+	resolvePluginUpdateSource,
 	resolvePluginUrl,
 	restartPlan,
 	runRestart,
@@ -78,6 +78,7 @@ import {
 	releaseLock,
 	transactionFile,
 	updateLockFile,
+	validOperationId,
 } from "./plugin-update-transaction.js";
 import {
 	CARRIER_STATUS,
@@ -196,18 +197,11 @@ export const Config = z.object({
 	/** App 自动更新主机源目录；空值表示未配置。 */
 	updateDir: z.string().default(""),
 	/**
-	 * **插件自更新**的发布清单来源（ADR 0019）：
-	 * - `"upstream"`（默认）：上游仓库的 Release；优先取清单资产，缺失时按 release 资产合成；
-	 * - `"off"`：完全不检查（离线/隐私要求）；
-	 * - 其他必须是 `https://` 开头的清单地址（自建发布源）。
-	 * 检查**只读**，不改动本机任何东西；真正更新只在用户从手机明确触发时发生。
+	 * 插件自动更新来源固定为宿主 npm 配置；`off` 是管理员关闭开关。旧配置中的 upstream/自建源值会迁移到 npm，不再作为更新来源。
+	 * 检查只读；安装仍需用户明确确认，并由宿主事务重启/健康核验。
 	 */
 	updateProfileDir: z.string().default("").description("显式指定插件依赖所在 profile；为空时验证式定位。"),
-	// 允许集合与 resolveManifestSource 一致：upstream | off | https://… | 精确回环 http（外部 http 仍拒绝）。
-	pluginUpdateManifest: z
-		.string()
-		.pattern(/^(upstream|off|https:\/\/\S+|http:\/\/(127\.0\.0\.1|localhost)(:\d+)?\/\S*)$/)
-		.default("upstream"),
+	pluginUpdateManifest: z.string().default("npm").description("固定使用宿主 npm registry；只有设置为 off 时停用自动更新。"),
 	/** SSE 连接数上限。 */
 	maxConnections: z.number().default(16),
 	/**
@@ -2242,13 +2236,20 @@ export function apply(ctx, config, runtime = {}) {
 	// 检查是**非破坏性**的：只读清单、只改内存状态。真正改动 profile、安装依赖、重启宿主
 	// 只在用户从手机明确触发时发生（见 POST /plugin-update），且由**外部监督器**收尾。
 	const pluginRootDir = resolve(fileURLToPath(new URL("..", import.meta.url)));
+	const pluginPackageName = (() => {
+		try { return JSON.parse(readFileSync(join(pluginRootDir, "package.json"), "utf8")).name ?? ""; }
+		catch { return ""; }
+	})();
 	// profile 目录：靠**验证式查找**（向上找声明了本插件依赖的 package.json），
 	// 不靠模块层级推断——pnpm virtual store 下"往上两层"必错（评审 R3）。
 	// 允许显式配置覆盖；两者都拿不到就只给降级指引，绝不动文件。
 	const pluginDependencyKeys = dependencyKeysFor(pluginRootDir);
-	const pluginProfileDir = (typeof config.updateProfileDir === "string" && config.updateProfileDir.trim() !== "")
-		? config.updateProfileDir.trim()
-		: findProfileDir(pluginRootDir);
+	const runtimeProfileDir = typeof runtime.pluginUpdates?.profileDir === "string" ? runtime.pluginUpdates.profileDir.trim() : undefined;
+	const pluginProfileDir = runtimeProfileDir !== undefined
+		? runtimeProfileDir
+		: (typeof config.updateProfileDir === "string" && config.updateProfileDir.trim() !== "")
+			? config.updateProfileDir.trim()
+			: findProfileDir(pluginRootDir);
 	const selfContentSha256 = pluginContentDigest(pluginRootDir);
 	const pluginUpdateStateFile = transactionFile(homedir());
 	const pluginUpdateLockFile = updateLockFile(homedir());
@@ -2290,7 +2291,7 @@ export function apply(ctx, config, runtime = {}) {
 	const ensureUpdateCheck = () => {
 		if (pluginUpdateChecked) return;
 		pluginUpdateChecked = true;
-		if (resolveManifestSource(config.pluginUpdateManifest).kind === UPDATE_SOURCE_KIND.OFF) return;
+		if (resolvePluginUpdateSource(config.pluginUpdateManifest).kind === UPDATE_SOURCE_KIND.OFF) return;
 		updates.check()
 			.then((r) => Object.assign(pluginUpdateStatus, r))
 			.catch((e) => Object.assign(pluginUpdateStatus, { state: "unavailable", reason: String(e?.message ?? e) }));
@@ -2316,7 +2317,7 @@ export function apply(ctx, config, runtime = {}) {
 		return {
 			clientOrigin: publicReleaseOrigin(_req),
 			basePath,
-			loopback: resolveManifestSource(config.pluginUpdateManifest).loopback === true,
+			loopback: resolvePluginUpdateSource(config.pluginUpdateManifest).loopback === true,
 		};
 	}
 	/** 事务摘要：手机据此判断"结果待确认/已完成/已回滚"，而不是只比版本号（评审 R7）。 */
@@ -2335,7 +2336,7 @@ export function apply(ctx, config, runtime = {}) {
 		};
 	}
 	const updates = createPluginUpdateController({
-		home: homedir(), configValue: config.pluginUpdateManifest, profileDir: pluginProfileDir,
+		home: homedir(), configValue: config.pluginUpdateManifest, profileDir: pluginProfileDir, packageName: pluginPackageName,
 		capabilities: pluginUpdateCapabilities, localVersion: () => pluginVersion(), localContentSha256: selfContentSha256,
 		status: pluginUpdateStatus, log: m => ctx.logger.warn(m),
 		// basePath 必须一起传：helper 按精确挂载路径集合决定是否附口令，缺了它非默认挂载会 401（E3）
@@ -3931,10 +3932,21 @@ export function apply(ctx, config, runtime = {}) {
 		const tx = readTransaction(pluginUpdateStateFile);
 		const transaction = tx ? { opId: String(tx.opId ?? ""), generation: tx.lease?.generation ?? null } : null;
 		const base = { runningContentSha256: selfContentSha256, instanceId: pluginInstanceId, transaction };
-		if (tx && (tx.rolledBack === true || ["rolling-back", "rolled-back", "failed"].includes(String(tx.phase ?? "")))) {
-			return { ...base, state: "failed" };
+		if (tx) {
+			const phase = String(tx.phase ?? "");
+			const failedLike = tx.rolledBack === true || ["rolling-back", "rolled-back", "failed"].includes(phase);
+			// 终态失败只在“那次更新尝试的目标内容仍等于当前运行内容”时才继续描述现状。
+			// 回滚成功或用户之后手工升级/重启后，运行内容已不是该失败目标，历史失败不能永久
+			// 污染 currentReleaseHealth（否则手机端的“插件先行”门禁会一直被挡住）。
+			const targetContent = String(tx.targetContentSha256 ?? "").toLowerCase();
+			const runningContent = String(selfContentSha256 ?? "").toLowerCase();
+			const describesRunning = targetContent === "" || targetContent === runningContent;
+			if (failedLike) {
+				if (describesRunning) return { ...base, state: "failed" };
+			} else if (!isTerminalPhase(phase)) {
+				return { ...base, state: "waiting" };
+			}
 		}
-		if (tx && !isTerminalPhase(tx.phase)) return { ...base, state: "waiting" };
 		const current = resolveCurrentReleaseMeta();
 		return { ...base, state: current.ok ? "confirmed" : "waiting" };
 	}
@@ -5560,8 +5572,42 @@ export function apply(ctx, config, runtime = {}) {
 		}
 
 
+		// 只读 NPM 检查：桌面设置页/手机端可按需刷新；不下载产物、不改 profile、不重启。
+		if (rest === "/plugin-update/check") {
+			if (method !== "GET") return error(res, 405, "method-not-allowed");
+			try {
+				Object.assign(pluginUpdateStatus, await updates.check());
+			} catch {
+				Object.assign(pluginUpdateStatus, { state: "unavailable", reason: "update-check-failed", source: "npm", checkedAt: new Date().toISOString() });
+			}
+			return sendJson(res, 200, { ok: true, pluginUpdate: publicUpdateStatus(req) });
+		}
+
+		// 旧 carrier 缺少 App build metadata 时，用户明确触发的预检只下载/校验 NPM 产物，不改 profile。
+		if (rest === "/plugin-update/prepare") {
+			if (method !== "POST") return error(res, 405, "method-not-allowed");
+			let body;
+			try { const text = await readBody(req); body = text ? JSON.parse(text) : {}; }
+			catch { return error(res, 400, "invalid-operation-id"); }
+			const result = await updates.prepare(body);
+			return sendJson(res, result.status, result.body);
+		}
+
+		// Read-only, authenticated, cursor-based log replay after the host restarts.
+		if (rest === "/plugin-update/log") {
+			if (method !== "GET") return error(res, 405, "method-not-allowed");
+			const opId = url.searchParams.get("opId") ?? "";
+			if (!validOperationId(opId)) return error(res, 400, "invalid-operation-id");
+			const rawCursor = url.searchParams.get("afterSeq") ?? "0";
+			if (!/^(0|[1-9]\d*)$/.test(rawCursor) || !Number.isSafeInteger(Number(rawCursor))) return error(res, 400, "invalid-log-cursor");
+			const tx = readTransaction(pluginUpdateStateFile);
+			if (!tx || tx.opId !== opId || !tx.lease?.generation) return error(res, 404, "update-log-not-found");
+			const page = readOperationLog({ home: homedir(), generation: tx.lease.generation, afterSeq: Number(rawCursor) });
+			return sendJson(res, 200, { ok: true, opId, phase: tx.phase, ...page });
+		}
+
 		// 插件自更新：**手机可独立触发**（ADR 0019 的产品取舍——不加 PC 二次确认）。
-		// 这是唯一会改动本机 profile 并重启宿主的端点，因此 fail-closed 且**异步**：
+		// 这是唯一会改动本机 profile 并重启宿主的端点，因此 fail-closed 且**异步**:
 		//   - 先判方法/来源/能力/有无新版，任何一项不成立就拒绝，绝不开始；
 		//   - 立即返回可查询、幂等的 operation id；下载/安装/重启在后台推进
 		//     （评审 R6：原来同步阻塞到 pnpm 结束，会冻住全部 HTTP/SSE/agent，且响应丢失后
@@ -5569,7 +5615,7 @@ export function apply(ctx, config, runtime = {}) {
 		//   - 回滚与健康确认交给**外部监督器**，不依赖新版插件能否加载（评审 R1）。
 		if (rest === "/plugin-update") {
 			if (method !== "POST") return error(res, 405, "method-not-allowed");
-			const source = resolveManifestSource(config.pluginUpdateManifest);
+			const source = resolvePluginUpdateSource(config.pluginUpdateManifest);
 			if (source.kind === UPDATE_SOURCE_KIND.OFF) return error(res, 503, "update-source-off");
 			if (source.kind === UPDATE_SOURCE_KIND.INVALID) return error(res, 400, "update-source-invalid");
 			if (!pluginProfileDir) return error(res, 409, "profile-not-found");

package/lib/npm-update-source.js

@@ -0,0 +1,226 @@
+import { execFile } from "node:child_process";
+import { appCarrierAlias, appCarrierVersion } from "./app-carrier.js";
+import { parseVersion } from "./plugin-update.js";
+import { shellOptions } from "./tool-process.js";
+
+const SRI_PATTERN = /^sha(?:256|384|512)-[A-Za-z0-9+/]+={0,2}$/;
+
+/**
+ * Stable package follows latest; 预发布跟随其自身的通道（alpha / rc）。
+ * 例：3.2.2-alpha.15 查 alpha，3.2.2-rc.1 查 rc；绝不把预发布塞给 latest。
+ */
+export function npmUpdateChannel(localVersion) {
+	const parsed = parseVersion(localVersion);
+	if (!parsed) return { ok: false, reason: "npm-local-version-invalid" };
+	if (parsed.prerelease.length === 0) return { ok: true, channel: "latest" };
+	const channel = parsed.prerelease[0];
+	if (channel === "alpha" || channel === "rc") return { ok: true, channel };
+	return { ok: false, reason: "npm-prerelease-channel-unsupported" };
+}
+
+function packageIntegrity(pkg) {
+	const value = pkg?.dist?.integrity;
+	return typeof value === "string" && SRI_PATTERN.test(value) ? value : "";
+}
+
+/**
+ * `npm view <pkg> dist-tags --json` prints the tag map itself
+ * (`{"latest":"...","alpha":"..."}`), while some adapters/tests hand back the
+ * whole packument field (`{"dist-tags":{...}}`). Accept both so the check never
+ * fails merely because of the projection shape.
+ */
+function distTagMap(tags) {
+	if (!tags || typeof tags !== "object" || Array.isArray(tags)) return null;
+	const nested = tags["dist-tags"];
+	if (nested && typeof nested === "object" && !Array.isArray(nested)) return nested;
+	return tags;
+}
+
+/** 检查日志只放包名/版本/稳定原因码；绝不写 registry URL、凭据或 npm stderr。 */
+export const NPM_CHECK_LOG_LIMIT = 40;
+const CHECK_LOG_LINE_LIMIT = 240;
+
+function checkRecorder(log) {
+	if (!Array.isArray(log)) return () => {};
+	return (line) => {
+		const text = String(line ?? "").trim();
+		if (text === "") return;
+		log.push(text.length > CHECK_LOG_LINE_LIMIT ? `${text.slice(0, CHECK_LOG_LINE_LIMIT)}…` : text);
+		if (log.length > NPM_CHECK_LOG_LIMIT) log.splice(0, log.length - NPM_CHECK_LOG_LIMIT);
+	};
+}
+
+/**
+ * Resolve an immutable plugin/carrier pair from NPM metadata only.
+ * `packageView(spec)` is the host NPM adapter; tests inject a deterministic registry.
+ * This function never downloads a tarball and never returns registry URLs or raw metadata.
+ * `log` (optional array) receives sanitized, bounded diagnostic lines for the settings UI.
+ */
+export async function resolveNpmUpdateCandidate({ packageName, localVersion, packageView, log } = {}) {
+	const record = checkRecorder(log);
+	if (typeof packageName !== "string" || packageName.trim() === "") {
+		record(`包名无效：${String(packageName ?? "")}`);
+		return { ok: false, reason: "npm-package-name-invalid" };
+	}
+	if (typeof packageView !== "function") {
+		record(`找不到 npm 元数据适配器（${packageName}）`);
+		return { ok: false, reason: "npm-client-unavailable" };
+	}
+	const channel = npmUpdateChannel(localVersion);
+	if (!channel.ok) {
+		record(`# 本机版本 ${String(localVersion || "未知")} 无法确定 NPM 通道：${channel.reason}`);
+		return channel;
+	}
+	record(`# 本机版本 ${String(localVersion || "未知")} · NPM 通道 ${channel.channel}`);
+
+	let tags;
+	record(`$ npm view ${packageName} dist-tags --json`);
+	try {
+		tags = await packageView(packageName);
+	} catch (error) {
+		const reason = viewFailureReason(error);
+		record(`→ 失败：${reason}`);
+		return { ok: false, reason };
+	}
+	const candidateVersion = distTagMap(tags)?.[channel.channel];
+	if (typeof candidateVersion !== "string" || !parseVersion(candidateVersion)) {
+		record(`→ 缺少 ${channel.channel} 标签`);
+		return { ok: false, reason: "npm-channel-version-missing", channel: channel.channel };
+	}
+	record(`→ ${channel.channel}=${candidateVersion}`);
+
+	let plugin;
+	record(`$ npm view ${packageName}@${candidateVersion} --json`);
+	try {
+		plugin = await packageView(`${packageName}@${candidateVersion}`);
+	} catch (error) {
+		record(`→ 失败：${viewFailureReason(error)}`);
+		return { ok: false, reason: "npm-plugin-metadata-unavailable" };
+	}
+	if (!plugin || plugin.version !== candidateVersion) {
+		record(`→ 版本不符：${String(plugin?.version ?? "缺失")} ≠ ${candidateVersion}`);
+		return { ok: false, reason: "npm-plugin-version-mismatch" };
+	}
+	const pluginIntegrity = packageIntegrity(plugin);
+	if (!pluginIntegrity) {
+		record(`→ 元数据缺少 dist.integrity`);
+		return { ok: false, reason: "npm-plugin-integrity-missing" };
+	}
+	record(`→ 插件 v${candidateVersion}`);
+
+	const carrierVersion = appCarrierVersion(candidateVersion);
+	const alias = appCarrierAlias(packageName);
+	const expectedAliasSpec = `npm:${packageName}@${carrierVersion}`;
+	if (plugin.optionalDependencies?.[alias] !== expectedAliasSpec) {
+		record(`→ 载体别名不匹配：${String(plugin.optionalDependencies?.[alias] ?? "缺失")}（期望 ${expectedAliasSpec}）`);
+		return { ok: false, reason: "npm-carrier-alias-mismatch" };
+	}
+
+	let carrier;
+	record(`$ npm view ${packageName}@${carrierVersion} --json`);
+	try {
+		carrier = await packageView(`${packageName}@${carrierVersion}`);
+	} catch (error) {
+		record(`→ 失败：${viewFailureReason(error)}`);
+		return { ok: false, reason: "npm-carrier-metadata-unavailable" };
+	}
+	if (!carrier || carrier.version !== carrierVersion) {
+		record(`→ 版本不符：${String(carrier?.version ?? "缺失")} ≠ ${carrierVersion}`);
+		return { ok: false, reason: "npm-carrier-version-mismatch" };
+	}
+	const carrierIntegrity = packageIntegrity(carrier);
+	if (!carrierIntegrity) {
+		record(`→ 元数据缺少 dist.integrity`);
+		return { ok: false, reason: "npm-carrier-integrity-missing" };
+	}
+
+	const appVersion = typeof carrier.appVersion === "string" ? carrier.appVersion : null;
+	if (appVersion !== null) {
+		const parsedApp = parseVersion(appVersion);
+		const parsedPlugin = parseVersion(candidateVersion);
+		if (!parsedApp || parsedApp.build === null) {
+			record(`→ App 版本格式无效：${appVersion}`);
+			return { ok: false, reason: "npm-app-version-invalid" };
+		}
+		if (parsedApp.version !== parsedPlugin.version) {
+			record(`→ App 版本配对不符：${appVersion} ↔ 插件 ${candidateVersion}`);
+			return { ok: false, reason: "npm-app-version-pairing-mismatch" };
+		}
+	}
+	const contentSha256 = typeof carrier.pluginContentSha256 === "string" ? carrier.pluginContentSha256.toLowerCase() : "";
+	if (contentSha256 !== "" && !/^[0-9a-f]{64}$/.test(contentSha256)) {
+		record(`→ 插件内容标识格式无效（${carrierVersion}）`);
+		return { ok: false, reason: "npm-plugin-content-sha256-invalid" };
+	}
+
+	record(`→ 载体 v${carrierVersion} · App build ${appVersion ?? "缺失（需预检）"}`);
+
+	return {
+		ok: true,
+		channel: channel.channel,
+		plugin: {
+			name: packageName,
+			version: candidateVersion,
+			integrity: pluginIntegrity,
+			contentSha256,
+		},
+		carrier: {
+			name: packageName,
+			version: carrierVersion,
+			integrity: carrierIntegrity,
+			appVersion,
+			pluginContentSha256: contentSha256,
+			legacyMetadataMissing: appVersion === null,
+		},
+	};
+}
+
+export function runNpmView(args, { cwd = process.cwd(), timeoutMs = 20_000, execFileImpl = execFile, platform = process.platform } = {}) {
+	return new Promise((resolve) => {
+		execFileImpl("npm", args, {
+			cwd,
+			env: process.env,
+			timeout: timeoutMs,
+			maxBuffer: 1024 * 1024,
+			windowsHide: true,
+			// Windows 上 npm 是 npm.cmd，必须经 shell 解析；POSIX 直接 spawn。
+			...shellOptions(platform),
+		}, (error, stdout, stderr) => {
+			if (error) {
+				// npm stderr may contain private registry URLs; expose only a stable source error.
+				// 区分「找不到 npm 客户端」与「registry 不可用」，便于界面给出可执行提示：
+				// Windows shell 找不到 .cmd 时 cmd 会报「不是内部或外部命令」而不是 ENOENT。
+				const stderrText = String(stderr ?? "");
+				const clientMissing = error?.code === "ENOENT" || /not recognized|不是内部或外部命令|command not found/i.test(stderrText);
+				resolve({ ok: false, error: clientMissing ? "npm-client-unavailable" : "npm-view-failed" });
+				return;
+			}
+			resolve({ ok: true, stdout: String(stdout ?? "") });
+		});
+	});
+}
+
+/** 检查失败原因：npm 客户端缺失是环境问题，不应伪装成 registry 故障。 */
+function viewFailureReason(error) {
+	return error?.message === "npm-client-unavailable" ? "npm-client-unavailable" : "npm-registry-unavailable";
+}
+
+/**
+ * Host-side npm view adapter. It deliberately supplies no --registry argument so npm
+ * applies the DSH process's project/user config, including scoped registry and credentials.
+ */
+export function createNpmPackageView({ packageName, cwd, run = runNpmView, platform = process.platform } = {}) {
+	return async (spec) => {
+		if (typeof spec !== "string" || spec === "") throw new Error("npm-package-spec-invalid");
+		const args = spec === packageName
+			? ["view", packageName, "dist-tags", "--json"]
+			: ["view", spec, "--json"];
+		const result = await run(args, { cwd, platform });
+		if (!result?.ok) throw new Error(result?.error ?? "npm-view-failed");
+		try {
+			return JSON.parse(result.stdout);
+		} catch {
+			throw new Error("npm-view-json-invalid");
+		}
+	};
+}