dsh-version-check 0.0.0-stage → 0.3.0

package/lib/install.d.ts

@@ -0,0 +1,29 @@
+import { ChildProcess } from "node:child_process";
+/** npm 安装结束时的结果。 */
+export interface InstallResult {
+  code: number | null;
+  signal: string | null;
+  outputTail: string;
+  timedOut: boolean;
+  error?: Error;
+}
+/** npm 安装的参数与结束回调。 */
+export interface InstallOptions {
+  npmExecutable: string;
+  npmPrefix: string;
+  version: string;
+  timeoutMs: number;
+  onExit: (result: InstallResult) => void;
+}
+/**
+ * 用 npm 全局安装指定版本的 `@deepseek-ai/dsh`。
+ * 输出收集末尾 4000 字符，超时后终止子进程。
+ */
+export declare function runNpmInstall({ npmExecutable, npmPrefix, version, timeoutMs, onExit }: InstallOptions): ChildProcess;
+/**
+ * 请求 systemd 重启 DSH 服务，使用 --no-block 立即返回。
+ * 监听 systemctl 的非零退出码，重启请求未被 systemd 接受时通过 onError 上报。
+ * @param unitName systemd 服务单元名。
+ * @param onError 失败时的回调；未提供时写入 stderr。
+ */
+export declare function scheduleServiceRestart(unitName: string, onError?: ((error: Error) => void) | null): ChildProcess;

package/lib/install.js

@@ -0,0 +1,109 @@
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+// src/install.ts
+/**
+* npm 全局安装与 systemd 服务重启的子进程封装。
+*/
+/**
+* 用 npm 全局安装指定版本的 `@deepseek-ai/dsh`。
+* 输出收集末尾 4000 字符，超时后终止子进程。
+*/
+function runNpmInstall({ npmExecutable, npmPrefix, version, timeoutMs, onExit }) {
+	const child = spawn(npmExecutable, [
+		"install",
+		"-g",
+		`@deepseek-ai/dsh@${version}`,
+		"--prefix",
+		npmPrefix,
+		"--no-audit",
+		"--no-fund",
+		"--loglevel=error"
+	], {
+		cwd: homedir(),
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	let outputTail = "";
+	const append = (chunk) => {
+		outputTail = (outputTail + chunk).slice(-4e3);
+	};
+	child.stdout.setEncoding("utf8");
+	child.stderr.setEncoding("utf8");
+	child.stdout.on("data", append);
+	child.stderr.on("data", append);
+	let timedOut = false;
+	let settled = false;
+	let timer = null;
+	const finish = (result) => {
+		if (settled) return;
+		settled = true;
+		if (timer !== null) clearTimeout(timer);
+		onExit({
+			...result,
+			outputTail
+		});
+	};
+	timer = setTimeout(() => {
+		timedOut = true;
+		child.kill("SIGKILL");
+	}, timeoutMs);
+	child.on("error", (error) => finish({
+		code: null,
+		signal: null,
+		timedOut: false,
+		error
+	}));
+	child.on("close", (code, signal) => finish({
+		code,
+		signal,
+		timedOut
+	}));
+	return child;
+}
+/**
+* 请求 systemd 重启 DSH 服务，使用 --no-block 立即返回。
+* 监听 systemctl 的非零退出码，重启请求未被 systemd 接受时通过 onError 上报。
+* @param unitName systemd 服务单元名。
+* @param onError 失败时的回调；未提供时写入 stderr。
+*/
+function scheduleServiceRestart(unitName, onError = null) {
+	const child = spawn("systemctl", [
+		"--user",
+		"restart",
+		"--no-block",
+		unitName
+	], {
+		detached: true,
+		stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		]
+	});
+	let stderrTail = "";
+	child.stderr.setEncoding("utf8");
+	child.stderr.on("data", (chunk) => {
+		stderrTail = (stderrTail + chunk).slice(-400);
+	});
+	let reported = false;
+	const report = (error) => {
+		if (reported) return;
+		reported = true;
+		if (typeof onError === "function") onError(error);
+		else console.error(`无法重启 DSH 服务: ${error.message}`);
+	};
+	child.on("error", (error) => report(error));
+	child.on("exit", (code, signal) => {
+		if (code === 0) return;
+		const detail = stderrTail.trim();
+		const suffix = detail.length > 0 ? `: ${detail}` : "";
+		const reason = signal === null ? `退出码 ${code}` : `信号 ${signal}`;
+		report(/* @__PURE__ */ new Error(`systemctl 重启请求失败（${reason}）${suffix}`));
+	});
+	child.unref();
+	return child;
+}
+export { runNpmInstall, scheduleServiceRestart };

package/lib/preferences.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 用户设置：更新检查开关、自动检查间隔与发布渠道的校验、合并与持久化。
+ * 设置保存在 $DSH_HOME/dsh-version-check/preferences.json；
+ * profile patch 里的同名字段作为默认值，用户设置覆盖它们。
+ */
+/** 生效的设置。 */
+export interface Preferences {
+  checkEnabled: boolean;
+  checkIntervalMinutes: number;
+  channel: string;
+}
+/** 只包含用户提交字段的设置补丁。 */
+export type PreferencesPatch = Partial<Preferences>;
+/**
+ * 设置文件的绝对路径。
+ * @param env 环境变量，默认使用 process.env。
+ */
+export declare function preferencesFilePath(env?: NodeJS.ProcessEnv): string;
+/**
+ * 校验并归一化设置补丁，只保留提供的字段。
+ * @param raw 请求体。
+ */
+export declare function normalizePreferencesPatch(raw: unknown): PreferencesPatch;
+/**
+ * 合并默认设置与用户设置，返回实际生效的设置。
+ * @param defaults patch 层默认值。
+ * @param stored 已保存的用户设置。
+ */
+export declare function resolvePreferences(defaults: Preferences, stored: unknown): Preferences;
+/**
+ * 读取设置文件；文件不存在时返回空对象。
+ * 文件内容无法解析时抛错，由调用方按显式错误处理。
+ * @param path 设置文件路径。
+ */
+export declare function readPreferencesFile(path: string): Record<string, unknown>;
+/**
+ * 原子写入设置文件：先写临时文件再改名，权限为 0600。
+ * @param path 设置文件路径。
+ * @param preferences 生效设置。
+ */
+export declare function writePreferencesFile(path: string, preferences: Preferences): void;

package/lib/preferences.js

@@ -0,0 +1,132 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+// src/preferences.ts
+/**
+* 用户设置：更新检查开关、自动检查间隔与发布渠道的校验、合并与持久化。
+* 设置保存在 $DSH_HOME/dsh-version-check/preferences.json；
+* profile patch 里的同名字段作为默认值，用户设置覆盖它们。
+*/
+const PREFERENCES_VERSION = 1;
+const INTERVAL_MINUTES_MIN = 1;
+const INTERVAL_MINUTES_MAX = 10080;
+const CHANNEL_PATTERN = /^[A-Za-z][A-Za-z0-9._-]*$/;
+const PREFERENCES_DIRECTORY = "dsh-version-check";
+const PREFERENCES_FILENAME = "preferences.json";
+const SETTING_FIELDS = [
+	"checkEnabled",
+	"checkIntervalMinutes",
+	"channel"
+];
+/**
+* 设置文件的绝对路径。
+* @param env 环境变量，默认使用 process.env。
+*/
+function preferencesFilePath(env = process.env) {
+	const home = typeof env.DSH_HOME === "string" && env.DSH_HOME.length > 0 ? env.DSH_HOME : join(homedir(), ".dsh");
+	return join(home, PREFERENCES_DIRECTORY, PREFERENCES_FILENAME);
+}
+function normalizeField(field, value) {
+	if (field === "checkEnabled") {
+		if (typeof value !== "boolean") throw new TypeError("checkEnabled 必须是布尔值");
+		return value;
+	}
+	if (field === "checkIntervalMinutes") {
+		if (typeof value !== "number" || !Number.isInteger(value) || value < INTERVAL_MINUTES_MIN || value > INTERVAL_MINUTES_MAX) throw new TypeError(`checkIntervalMinutes 必须是 ${INTERVAL_MINUTES_MIN} 到 ${INTERVAL_MINUTES_MAX} 之间的整数`);
+		return value;
+	}
+	if (field === "channel") {
+		if (typeof value !== "string") throw new TypeError("channel 必须是字符串");
+		const text = value.trim();
+		if (text !== "auto" && !CHANNEL_PATTERN.test(text)) throw new TypeError("channel 必须是 auto 或一个 npm dist-tag 名称");
+		return text;
+	}
+	throw new TypeError(`未知的设置字段: ${field}`);
+}
+/**
+* 校验并归一化设置补丁，只保留提供的字段。
+* @param raw 请求体。
+*/
+function normalizePreferencesPatch(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new TypeError("设置必须是 JSON 对象");
+	const patch = {};
+	for (const [field, value] of Object.entries(raw)) {
+		if (!isSettingField(field)) throw new TypeError(`未知的设置字段: ${field}`);
+		switch (field) {
+			case "checkEnabled":
+				patch.checkEnabled = normalizeField("checkEnabled", value);
+				break;
+			case "checkIntervalMinutes":
+				patch.checkIntervalMinutes = normalizeField("checkIntervalMinutes", value);
+				break;
+			case "channel": patch.channel = normalizeField("channel", value);
+		}
+	}
+	if (Object.keys(patch).length === 0) throw new TypeError("设置补丁不能为空");
+	return patch;
+}
+/**
+* 合并默认设置与用户设置，返回实际生效的设置。
+* @param defaults patch 层默认值。
+* @param stored 已保存的用户设置。
+*/
+function resolvePreferences(defaults, stored) {
+	const resolved = {
+		checkEnabled: normalizeField("checkEnabled", defaults.checkEnabled),
+		checkIntervalMinutes: normalizeField("checkIntervalMinutes", defaults.checkIntervalMinutes),
+		channel: normalizeField("channel", defaults.channel)
+	};
+	if (stored === null || typeof stored !== "object" || Array.isArray(stored)) throw new TypeError("已保存的设置必须是对象");
+	const storedFields = stored;
+	for (const field of SETTING_FIELDS) {
+		if (!Object.hasOwn(stored, field)) continue;
+		switch (field) {
+			case "checkEnabled":
+				resolved.checkEnabled = normalizeField("checkEnabled", storedFields[field]);
+				break;
+			case "checkIntervalMinutes":
+				resolved.checkIntervalMinutes = normalizeField("checkIntervalMinutes", storedFields[field]);
+				break;
+			case "channel": resolved.channel = normalizeField("channel", storedFields[field]);
+		}
+	}
+	return resolved;
+}
+/**
+* 读取设置文件；文件不存在时返回空对象。
+* 文件内容无法解析时抛错，由调用方按显式错误处理。
+* @param path 设置文件路径。
+*/
+function readPreferencesFile(path) {
+	if (!existsSync(path)) return {};
+	const text = readFileSync(path, "utf8");
+	const parsed = JSON.parse(text);
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`设置文件不是对象: ${path}`);
+	return parsed;
+}
+/**
+* 原子写入设置文件：先写临时文件再改名，权限为 0600。
+* @param path 设置文件路径。
+* @param preferences 生效设置。
+*/
+function writePreferencesFile(path, preferences) {
+	const directory = dirname(path);
+	mkdirSync(directory, { recursive: true });
+	const temporary = `${path}.${process.pid}.tmp`;
+	const payload = JSON.stringify({
+		version: PREFERENCES_VERSION,
+		...preferences
+	}, null, 2) + "\n";
+	try {
+		writeFileSync(temporary, payload, { mode: 384 });
+		renameSync(temporary, path);
+	} finally {
+		rmSync(temporary, { force: true });
+	}
+	chmodSync(path, 384);
+}
+/** 判断字符串是否是设置字段名。 */
+function isSettingField(field) {
+	return SETTING_FIELDS.includes(field);
+}
+export { normalizePreferencesPatch, preferencesFilePath, readPreferencesFile, resolvePreferences, writePreferencesFile };

package/lib/registry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * npm registry 的 dist-tags 查询、已发布版本列表与回滚候选筛选。
+ */
+/** fetch 返回值的结构，只用到状态码与 JSON 解析。 */
+export interface FetchResponseLike {
+  status: number;
+  json(): Promise<unknown>;
+}
+/** 测试可注入的 fetch 实现。 */
+export type FetchLike = (url: string, init: {
+  headers: Record<string, string>;
+  signal: AbortSignal;
+}) => Promise<FetchResponseLike>;
+/** dist-tag 到版本号的映射。 */
+export type DistTags = Record<string, string>;
+/**
+ * 拉取 `@deepseek-ai/dsh` 的 dist-tags。
+ * @param registryUrl registry 地址，末尾斜杠可有可无。
+ * @param fetchImpl fetch 实现，测试时注入。
+ * @returns 只保留版本号合法的条目。
+ */
+export declare function fetchDistTags(registryUrl: unknown, fetchImpl?: FetchLike): Promise<DistTags>;
+/**
+ * 选择要跟踪的 dist-tag。
+ * 优先使用显式 channel；auto 时按当前版本的 prerelease 渠道选 tag，
+ * 渠道不存在则 latest，仍不存在则取第一个合法 tag。
+ * @param distTags dist-tags 表。
+ * @param currentVersion 当前安装的版本。
+ * @param channelOverride 显式渠道，默认为 auto。
+ * @returns 没有合法 tag 时返回 null。
+ */
+export declare function pickTarget(distTags: DistTags | null | undefined, currentVersion: string, channelOverride?: string): {
+  tag: string;
+  version: string;
+} | null;
+/** registry 里的一个已发布版本。 */
+export interface PublishedVersion {
+  version: string;
+  publishedAt: string | null;
+}
+/**
+ * 拉取 `@deepseek-ai/dsh` 的包元数据，取出全部已发布版本与发布时间。
+ * @param registryUrl registry 地址，末尾斜杠可有可无。
+ * @param fetchImpl fetch 实现，测试时注入。
+ * @returns 只保留版本号合法的条目，顺序与 registry 返回一致。
+ */
+export declare function fetchPublishedVersions(registryUrl: unknown, fetchImpl?: FetchLike): Promise<PublishedVersion[]>;
+/**
+ * 从已发布版本中筛出比当前安装版本更旧的版本，按版本号从新到旧排序。
+ * @param versions 已发布版本列表。
+ * @param installedVersion 当前安装的版本。
+ */
+export declare function selectRollbackCandidates(versions: PublishedVersion[] | null | undefined, installedVersion: string): PublishedVersion[];

package/lib/registry.js

@@ -0,0 +1,124 @@
+import { compareVersions, isValidVersion, parseVersion, prereleaseChannel } from "./versions.js";
+// src/registry.ts
+/**
+* npm registry 的 dist-tags 查询、已发布版本列表与回滚候选筛选。
+*/
+const DIST_TAGS_PATH = "/-/package/@deepseek-ai%2Fdsh/dist-tags";
+const PACKUMENT_PATH = "/@deepseek-ai%2Fdsh";
+const FETCH_TIMEOUT_MS = 15e3;
+/** 错误消息里去掉 URL 内嵌的凭据，避免把凭据带进界面状态。 */
+function displayUrl(url) {
+	const parsed = new URL(url);
+	parsed.username = "";
+	parsed.password = "";
+	return parsed.href;
+}
+/**
+* 拉取 `@deepseek-ai/dsh` 的 dist-tags。
+* @param registryUrl registry 地址，末尾斜杠可有可无。
+* @param fetchImpl fetch 实现，测试时注入。
+* @returns 只保留版本号合法的条目。
+*/
+async function fetchDistTags(registryUrl, fetchImpl = fetch) {
+	if (typeof registryUrl !== "string" || registryUrl.length === 0) throw new TypeError("registryUrl 必须是非空字符串");
+	const url = `${registryUrl.replace(/\/+$/, "")}${DIST_TAGS_PATH}`;
+	const response = await fetchImpl(url, {
+		headers: { accept: "application/json" },
+		signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+	});
+	if (response.status !== 200) throw new Error(`registry 返回 HTTP ${response.status}: ${displayUrl(url)}`);
+	const payload = await response.json();
+	if (payload === null || typeof payload !== "object" || Array.isArray(payload)) throw new Error(`registry 的 dist-tags 响应不是对象: ${displayUrl(url)}`);
+	const distTags = {};
+	for (const [tag, version] of Object.entries(payload)) if (typeof version === "string" && isValidVersion(version)) distTags[tag] = version;
+	return distTags;
+}
+/**
+* 选择要跟踪的 dist-tag。
+* 优先使用显式 channel；auto 时按当前版本的 prerelease 渠道选 tag，
+* 渠道不存在则 latest，仍不存在则取第一个合法 tag。
+* @param distTags dist-tags 表。
+* @param currentVersion 当前安装的版本。
+* @param channelOverride 显式渠道，默认为 auto。
+* @returns 没有合法 tag 时返回 null。
+*/
+function pickTarget(distTags, currentVersion, channelOverride = "auto") {
+	const entries = Object.entries(distTags === null || distTags === void 0 ? {} : distTags).filter(([, version]) => typeof version === "string" && isValidVersion(version));
+	if (entries.length === 0) return null;
+	const lookup = new Map(entries);
+	const override = typeof channelOverride === "string" ? channelOverride : "auto";
+	if (override !== "auto" && lookup.has(override)) return {
+		tag: override,
+		version: lookup.get(override)
+	};
+	const channel = prereleaseChannel(currentVersion);
+	if (channel !== null && lookup.has(channel)) return {
+		tag: channel,
+		version: lookup.get(channel)
+	};
+	if (lookup.has("latest")) return {
+		tag: "latest",
+		version: lookup.get("latest")
+	};
+	const [tag, version] = entries[0];
+	return {
+		tag,
+		version
+	};
+}
+/**
+* 拉取 `@deepseek-ai/dsh` 的包元数据，取出全部已发布版本与发布时间。
+* @param registryUrl registry 地址，末尾斜杠可有可无。
+* @param fetchImpl fetch 实现，测试时注入。
+* @returns 只保留版本号合法的条目，顺序与 registry 返回一致。
+*/
+async function fetchPublishedVersions(registryUrl, fetchImpl = fetch) {
+	if (typeof registryUrl !== "string" || registryUrl.length === 0) throw new TypeError("registryUrl 必须是非空字符串");
+	const url = `${registryUrl.replace(/\/+$/, "")}${PACKUMENT_PATH}`;
+	const response = await fetchImpl(url, {
+		headers: { accept: "application/json" },
+		signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+	});
+	if (response.status !== 200) throw new Error(`registry 返回 HTTP ${response.status}: ${displayUrl(url)}`);
+	const payload = await response.json();
+	if (payload === null || typeof payload !== "object" || Array.isArray(payload)) throw new Error(`registry 的版本列表响应不是对象: ${displayUrl(url)}`);
+	const record = payload;
+	const versions = record.versions;
+	if (versions === null || typeof versions !== "object" || Array.isArray(versions)) throw new Error(`registry 的版本列表响应缺少 versions 字段: ${displayUrl(url)}`);
+	const time = record.time;
+	const times = time !== null && typeof time === "object" && !Array.isArray(time) ? time : {};
+	const published = [];
+	for (const version of Object.keys(versions)) {
+		if (!isValidVersion(version)) continue;
+		const publishedAt = times[version];
+		published.push({
+			version,
+			publishedAt: typeof publishedAt === "string" ? publishedAt : null
+		});
+	}
+	return published;
+}
+/**
+* 从已发布版本中筛出比当前安装版本更旧的版本，按版本号从新到旧排序。
+* @param versions 已发布版本列表。
+* @param installedVersion 当前安装的版本。
+*/
+function selectRollbackCandidates(versions, installedVersion) {
+	if (parseVersion(installedVersion) === null) throw new TypeError(`installedVersion 不是合法的版本号: ${String(installedVersion)}`);
+	const seen = /* @__PURE__ */ new Set();
+	const candidates = [];
+	for (const entry of Array.isArray(versions) ? versions : []) {
+		if (entry === null || typeof entry !== "object") continue;
+		const version = entry.version;
+		if (typeof version !== "string" || !isValidVersion(version) || seen.has(version)) continue;
+		if (compareVersions(version, installedVersion) >= 0) continue;
+		seen.add(version);
+		candidates.push({
+			version,
+			publishedAt: typeof entry.publishedAt === "string" ? entry.publishedAt : null
+		});
+	}
+	candidates.sort((left, right) => compareVersions(right.version, left.version));
+	return candidates;
+}
+export { fetchDistTags, fetchPublishedVersions, pickTarget, selectRollbackCandidates };

package/lib/styles/client.css

@@ -0,0 +1,80 @@
+/* dsh-version-check 侧边栏徽标、版本面板与设置页的样式。只使用主题 token 与布局常量。 */
+.dvc-layer{position:relative;display:flex;align-items:center;flex:none;width:100%;height:42px;margin:8px 0 0}
+.dvc-badge{display:inline-flex;align-items:center;gap:8px;width:calc(100% + 4px);height:42px;margin:0 -2px;padding:0 10px 0 8px;border:none;border-radius:12px;background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:14px;cursor:pointer;overflow:hidden;text-align:start}
+.dvc-badge:hover,.dvc-badge[data-active]{background:var(--dsw-alias-interactive-bg-hover)}
+.dvc-icon{flex:none;display:block}
+.dvc-label{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dvc-value{flex:none;margin-left:auto;display:inline-flex;align-items:center;gap:6px;color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:16px;font-variant-numeric:tabular-nums}
+.dvc-value[data-tone="update"]{color:var(--dsw-alias-state-business-primary)}
+.dvc-value[data-tone="error"]{color:var(--dsw-alias-state-error-primary)}
+.dvc-dot{flex:none;display:inline-block;width:6px;height:6px;border-radius:50%;background:var(--dsw-alias-state-business-primary)}
+.dvc-layer.dvc-rail{width:36px;height:36px;margin:0}
+.dvc-rail .dvc-badge{position:relative;justify-content:center;gap:0;width:36px;height:36px;margin:0;padding:0;border-radius:50%}
+.dvc-rail-dot{position:absolute;top:3px;right:3px;display:block;width:6px;height:6px;border-radius:50%;background:var(--dsw-alias-state-business-primary)}
+.dvc-panel{position:fixed;z-index:30;isolation:isolate;display:flex;flex-direction:column;width:360px;max-width:calc(100vw - 24px);max-height:60vh;border:0;border-radius:12px;box-shadow:var(--dsw-elevation-prominent);overflow:hidden}
+.dvc-panel::before{content:"";position:absolute;inset:0;z-index:-1;border-radius:inherit;background:var(--dsw-specific-menu);backdrop-filter:var(--dsw-menu-backdrop-filter);pointer-events:none}
+.dvc-header{box-sizing:border-box;flex:none;display:flex;align-items:center;justify-content:space-between;min-height:44px;padding:10px 12px}
+.dvc-title{color:var(--dsw-alias-label-primary);font-size:14px;font-weight:500;line-height:20px}
+.dvc-body{flex:1;min-height:0;padding:0 12px 12px;overflow-y:auto;font-size:13px;color:var(--dsw-alias-label-primary)}
+.dvc-version-row{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:0 0 10px}
+.dvc-version-block{display:flex;flex-direction:column;gap:2px;min-width:0}
+.dvc-version-label{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px}
+.dvc-version{color:var(--dsw-alias-label-primary);font-family:var(--ds-font-family-code,monospace);font-size:18px;font-weight:510;line-height:24px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dvc-pill{flex:none;border-radius:999px;padding:2px 8px;background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-secondary);font-size:11px;line-height:16px}
+.dvc-pill[data-tone="update"]{color:var(--dsw-alias-state-business-primary)}
+.dvc-pill[data-tone="error"]{color:var(--dsw-alias-state-error-primary)}
+.dvc-row{display:flex;justify-content:space-between;gap:16px;padding:6px 0}
+.dvc-row-label{color:var(--dsw-alias-label-tertiary)}
+.dvc-row-value{min-width:0;color:var(--dsw-alias-label-primary);text-align:end;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dvc-divider{border-top:.5px solid var(--dsw-alias-border-l2)}
+.dvc-error{margin:6px 0 0;color:var(--dsw-alias-state-error-primary);font-size:12px;line-height:18px}
+.dvc-progress{margin:6px 0 0;color:var(--dsw-alias-label-secondary);font-size:12px;line-height:18px}
+.dvc-output{margin:2px 0 0;color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px;display:-webkit-box;-webkit-box-orient:vertical;-webkit-line-clamp:2;overflow:hidden;word-break:break-all;white-space:pre-wrap}
+.dvc-actions{display:flex;justify-content:flex-end;gap:10px;padding-top:8px}
+.dvc-button{height:36px;padding:0 14px;border:.5px solid var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-md);background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:14px;cursor:pointer}
+.dvc-button:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover)}
+.dvc-button[data-primary]{border-color:transparent;background:var(--dsw-alias-button-primary-fill);color:var(--dsw-alias-label-primary-foreground);font-weight:500}
+.dvc-button[data-primary]:hover:not(:disabled){background:var(--dsw-alias-button-primary-hover)}
+.dvc-button:disabled{opacity:.5;cursor:default}
+.dvc-note{margin:8px 0 0;color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px}
+.dvc-settings{display:flex;flex-direction:column;padding-bottom:8px;color:var(--dsw-alias-label-primary);font-size:14px;line-height:20px}
+.dvc-settings-blurb{margin:0;padding:4px 0 12px;color:var(--dsw-alias-label-secondary);font-size:12px;line-height:18px}
+.dvc-settings-row{display:flex;align-items:center;justify-content:space-between;gap:24px;padding:16px 0;border-bottom:.5px solid var(--dsw-alias-border-l2)}
+.dvc-settings-rowText{display:flex;flex-direction:column;gap:4px;min-width:0}
+.dvc-settings-rowTitle{font-size:14px;line-height:20px}
+.dvc-settings-rowDesc{color:var(--dsw-alias-label-secondary);font-size:12px;line-height:18px}
+.dvc-settings-control{display:flex;flex:none;align-items:center;gap:8px}
+.dvc-switch{box-sizing:border-box;position:relative;flex:none;width:36px;height:20px;padding:2px;border:0;border-radius:999px;corner-shape:round;background:var(--dsw-alias-border-l3);cursor:pointer;appearance:none;-webkit-appearance:none}
+.dvc-switch[aria-checked="true"]{background:var(--dsw-alias-brand-primary)}
+.dvc-switch:disabled{cursor:default;opacity:.5}
+.dvc-switch:focus-visible{outline:var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));outline-offset:2px}
+.dvc-switchThumb{position:absolute;top:50%;left:2px;display:block;width:16px;height:16px;margin:0;border-radius:50%;corner-shape:round;background:var(--dsw-alias-label-primary-foreground);transform:translateY(-50%);transition:transform .12s ease}
+.dvc-switch[aria-checked="false"] .dvc-switchThumb{background:var(--dsw-alias-switch-thumb)}
+.dvc-switch[aria-checked="true"] .dvc-switchThumb{transform:translate(16px,-50%)}
+.dvc-settings-input{box-sizing:border-box;width:96px;height:32px;padding:0 8px;border:.5px solid var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-md);background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:13px}
+.dvc-settings-input:focus-visible{outline:var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));outline-offset:2px}
+.dvc-settings-input[aria-invalid="true"]{border-color:var(--dsw-alias-state-error-primary)}
+.dvc-settings-select{box-sizing:border-box;height:32px;padding:0 8px;border:.5px solid var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-md);background:transparent;color:var(--dsw-alias-label-primary);font:inherit;font-size:13px}
+.dvc-settings-select:focus-visible{outline:var(--dsw-focus-ring-width) solid var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));outline-offset:2px}
+.dvc-settings-unit{color:var(--dsw-alias-label-tertiary);font-size:12px}
+.dvc-settings-feedback{min-height:18px;margin:8px 0 0;color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:18px}
+.dvc-settings-feedback[data-tone="error"]{color:var(--dsw-alias-state-error-primary)}
+.dvc-settings-section{display:flex;flex-direction:column;gap:8px;padding-top:16px}
+.dvc-settings-section .dvc-settings-rowDesc{margin:0}
+.dvc-rollback-header{display:flex;align-items:center;justify-content:space-between;gap:16px}
+.dvc-rollback-picker{display:flex}
+.dvc-rollback-pick{height:32px;padding:0 12px;font-size:13px}
+.dvc-rollback-list{display:flex;flex-direction:column;gap:4px}
+.dvc-rollback-row{display:flex;align-items:center;gap:12px;padding:8px 0;border-bottom:.5px solid var(--dsw-alias-border-l2)}
+.dvc-rollback-version{flex:none;color:var(--dsw-alias-label-primary);font-family:var(--ds-font-family-code,monospace);font-size:13px}
+.dvc-rollback-date{flex:1;min-width:0;color:var(--dsw-alias-label-tertiary);font-size:12px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dvc-rollback-row .dvc-button{height:28px;padding:0 10px;font-size:12px}
+.dvc-rollback-toggle{align-self:flex-start;height:28px;padding:0 10px;font-size:12px}
+.dvc-rollback-confirmText{margin:0 0 4px;color:var(--dsw-alias-label-secondary);font-size:12px;line-height:18px}
+.dvc-rollback-confirmActions{display:flex;justify-content:flex-end;gap:8px;padding-top:4px}
+.dvc-rollback-popover{position:fixed;z-index:30;isolation:isolate;display:flex;flex-direction:column;width:320px;max-width:calc(100vw - 24px);max-height:360px;border-radius:12px;box-shadow:var(--dsw-elevation-prominent);overflow:hidden}
+.dvc-rollback-popover::before{content:"";position:absolute;inset:0;z-index:-1;border-radius:inherit;background:var(--dsw-specific-menu);backdrop-filter:var(--dsw-menu-backdrop-filter);pointer-events:none}
+.dvc-rollback-popoverHeader{box-sizing:border-box;flex:none;display:flex;align-items:center;min-height:44px;padding:10px 12px}
+.dvc-rollback-popoverTitle{color:var(--dsw-alias-label-primary);font-size:14px;font-weight:500;line-height:20px}
+.dvc-rollback-popoverBody{flex:1;min-height:0;padding:0 12px 8px;overflow-y:auto}
+.dvc-rollback-popoverFooter{flex:none;padding:8px 12px;border-top:.5px solid var(--dsw-alias-border-l2)}

package/lib/versions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 版本号解析与比较，按 semver 的优先级规则处理 prerelease。
+ * build metadata（`+` 之后的部分）解析时忽略。
+ */
+export interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: string[];
+}
+/**
+ * 解析一个版本字符串。
+ * @param text 版本字符串，允许 v 前缀与 build metadata。
+ * @returns 非法输入返回 null。
+ */
+export declare function parseVersion(text: unknown): ParsedVersion | null;
+/**
+ * 按 semver 优先级比较两个版本号。
+ * 有 prerelease 的版本小于同号正式版；prerelease 标识符逐个比较，
+ * 前缀相同时更长的标识符列表更大。
+ */
+export declare function compareVersions(a: unknown, b: unknown): -1 | 0 | 1;
+/**
+ * 取版本号 prerelease 渠道，即第一个 prerelease 标识符。
+ * @param version 版本字符串。
+ * @returns 无 prerelease 或版本非法时返回 null。
+ */
+export declare function prereleaseChannel(version: unknown): string | null;
+/**
+ * 判断字符串是否是一个合法版本号。
+ */
+export declare function isValidVersion(text: unknown): boolean;