@lark-apaas/openclaw-scripts-diagnose-cli 0.1.18-alpha.0 → 0.1.18-alpha.2

package/dist/index.cjs

@@ -52,7 +52,7 @@ node_assert = __toESM(node_assert);
 * it terse and parseable.
 */
 function getVersion() {
-	return "0.1.18-alpha.0";
+	return "0.1.18-alpha.2";
 }
 //#endregion
 //#region src/rule-engine/base.ts
@@ -3791,6 +3791,16 @@ function effectiveCompatible(pluginVersion, openclawVersion) {
 	const max = coerceCalVer(maxInfo.max);
 	return maxInfo.exclusive ? semver.default.lt(oc, max) : !semver.default.gt(oc, max);
 }
+const FORK_LARK_PLUGIN_PINNED_VERSION = "2026.4.1";
+/**
+* Resolve the version to evaluate against VERSION_COMPAT_MAP for a given plugin.
+* The fork is pinned to FORK_LARK_PLUGIN_PINNED_VERSION regardless of its own
+* version; everything else uses its real version.
+*/
+function resolveCompatVersion(packageName, version) {
+	if (packageName === "@lark-apaas/openclaw-lark") return FORK_LARK_PLUGIN_PINNED_VERSION;
+	return version;
+}
 /**
 * Floor match: find the entry with the largest openclawLarkVersion that is
 * ≤ pluginVersion ("closest lower-or-equal version").
@@ -3807,19 +3817,12 @@ function findClosestEntry(pluginVersion) {
 const PLUGIN_NAME$1 = "openclaw-lark";
 const LEGACY_SHORT_NAMES = ["feishu-openclaw-plugin"];
 const FORK_SCOPES = ["@lark-apaas"];
-/** 特化 fork 版全名：复用官方 effectiveCompatible，按对标版本取完整兼容区间 */
-const FORK_LARK_PLUGIN_FULL_NAME = "@lark-apaas/openclaw-lark";
-/**
-* fork 版对标的官方 openclaw-lark 版本。fork 自身版本不在 VERSION_COMPAT_MAP 内，
-* 兼容性按此对标版本经 effectiveCompatible 取完整区间（含推断上界）判定。
-*/
-const FORK_LARK_PLUGIN_PINNED_VERSION = "2026.4.1";
 /**
 * fork 版兼容区间的下界，取自 VERSION_COMPAT_MAP 中 openclawLarkVersion=2026.4.1
 * 的 minOpenclawVersion，避免与映射表脱钩写死。仅用于区分升级方向
 * （oc 低于下界 → 升 openclaw；高于上界 → 升 lark）；该条目被移除时回退到已知值。
 */
-const FORK_LARK_PLUGIN_MIN_OC_VERSION = findEntry(FORK_LARK_PLUGIN_PINNED_VERSION)?.minOpenclawVersion ?? "2026.3.28";
+const FORK_LARK_PLUGIN_MIN_OC_VERSION = findEntry("2026.4.1")?.minOpenclawVersion ?? "2026.3.28";
 let _ocVersion = void 0;
 function getOcVersion() {
 	if (_ocVersion === void 0) _ocVersion = readOpenclawRuntimeVersion();
@@ -3896,7 +3899,7 @@ let FeishuPluginLarkUpgradeRule = class FeishuPluginLarkUpgradeRule extends Diag
 		if (!cc) return { pass: true };
 		const { ocCur, recommendedOc, installed, isLegacy } = cc;
 		if (isForkPlugin(installed)) {
-			if (installed.fullName !== FORK_LARK_PLUGIN_FULL_NAME) return { pass: true };
+			if (installed.fullName !== "@lark-apaas/openclaw-lark") return { pass: true };
 			if (resolveForkUpgradeDirection(ocCur) !== "lark") return { pass: true };
 			return {
 				pass: false,
@@ -3983,7 +3986,7 @@ function describeCompatConstraint(entry, pluginVersion) {
 *   'lark'     → oc 高于区间上界（插件相对当前 openclaw 过旧），需升级飞书插件
 */
 function resolveForkUpgradeDirection(ocCur) {
-	if (effectiveCompatible(FORK_LARK_PLUGIN_PINNED_VERSION, ocCur)) return null;
+	if (effectiveCompatible("2026.4.1", ocCur)) return null;
 	return compareCalVer(ocCur, FORK_LARK_PLUGIN_MIN_OC_VERSION) < 0 ? "openclaw" : "lark";
 }
 /**
@@ -3993,7 +3996,7 @@ function resolveForkUpgradeDirection(ocCur) {
 * recommendedOc 可为 undefined（doctor 模式），此时不指定目标升级版本。
 */
 function validateForkPlugin(installed, ocCur, recommendedOc) {
-	if (installed.fullName !== FORK_LARK_PLUGIN_FULL_NAME) return { pass: true };
+	if (installed.fullName !== "@lark-apaas/openclaw-lark") return { pass: true };
 	if (resolveForkUpgradeDirection(ocCur) !== "openclaw") return { pass: true };
 	const recommendation = recommendedOc ? `；将 openclaw 升级到 ${recommendedOc} 即可满足` : `；请升级 openclaw 至 ${FORK_LARK_PLUGIN_MIN_OC_VERSION} 或更高版本`;
 	return {
@@ -4061,7 +4064,7 @@ function needsLarkUpgrade(ctx) {
 	if (!cc) return false;
 	const { ocCur, installed } = cc;
 	if (isForkPlugin(installed)) {
-		if (installed.fullName === FORK_LARK_PLUGIN_FULL_NAME) return !effectiveCompatible(FORK_LARK_PLUGIN_PINNED_VERSION, ocCur);
+		if (installed.fullName === "@lark-apaas/openclaw-lark") return !effectiveCompatible(FORK_LARK_PLUGIN_PINNED_VERSION, ocCur);
 		return false;
 	}
 	return isLarkUpgradeNeededFromCC(cc);
@@ -5206,6 +5209,139 @@ async function installOpenclaw(openclawTag, ossFileMap, opts = {}) {
 	}
 	console.error(`[install-openclaw] done in ${Date.now() - t0}ms`);
 }
+//#endregion
+//#region src/lark-tools-update.ts
+/**
+* 共享的飞书插件备份 / 恢复 / `openclaw-lark-tools update` 调用。
+*
+* upgrade-lark（场景修复流）与 install-extension（升级触发的兼容性预判路径）都需要
+* 「备份 → npx 适配升级 → 失败回滚」的同一套处理，此处统一封装，避免两份实现漂移。
+*
+* 日志通过可选 `log` 注入：upgrade-lark 传写日志文件的 Logger，install-extension 传
+* `console.error`，独立调用方不传则静默。
+*/
+const NOOP_LOG = () => {};
+/** 升级前需备份的 extensions/ 下的插件目录（含 legacy） */
+const FEISHU_PLUGIN_DIRS = ["openclaw-lark", "feishu-openclaw-plugin"];
+/** 读取 package.json 的 version 字段，失败返回 null（仅用于日志） */
+function readPkgVersion(pkgPath) {
+	try {
+		const pkg = JSON.parse(node_fs.default.readFileSync(pkgPath, "utf-8"));
+		return typeof pkg.version === "string" ? pkg.version : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* 备份 openclaw.json + FEISHU_PLUGIN_DIRS 下存在的插件目录到 backupDir。
+* 只备份当前存在的文件；不存在的记日志后跳过（恢复时据此判断「升级前是否存在」）。
+*/
+function backupFeishuPlugins(opts) {
+	const { workspaceDir, configPath, backupDir } = opts;
+	const log = opts.log ?? NOOP_LOG;
+	try {
+		node_fs.default.mkdirSync(backupDir, { recursive: true });
+		log(`backup dir: ${backupDir}`);
+		if (node_fs.default.existsSync(configPath)) {
+			const stat = node_fs.default.statSync(configPath);
+			node_fs.default.copyFileSync(configPath, node_path.default.join(backupDir, "openclaw.json"));
+			log(`  backed up: openclaw.json (${stat.size} bytes)`);
+		} else log(`  skipped: openclaw.json (not found)`);
+		node_fs.default.mkdirSync(node_path.default.join(backupDir, "extensions"), { recursive: true });
+		const extSrc = node_path.default.join(workspaceDir, "extensions");
+		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
+			const src = node_path.default.join(extSrc, pluginDir);
+			if (node_fs.default.existsSync(src)) {
+				const dst = node_path.default.join(backupDir, "extensions", pluginDir);
+				node_fs.default.cpSync(src, dst, { recursive: true });
+				const version = readPkgVersion(node_path.default.join(src, "package.json"));
+				log(`  backed up: extensions/${pluginDir}${version ? ` (version: ${version})` : ""}`);
+			} else log(`  skipped: extensions/${pluginDir} (not found)`);
+		}
+		return { ok: true };
+	} catch (e) {
+		const msg = `backup failed: ${e.message}`;
+		log(`ERROR: ${msg}`);
+		return {
+			ok: false,
+			error: msg
+		};
+	}
+}
+/**
+* 回滚到备份快照：先删除当前 openclaw.json + 插件目录，再从备份恢复（仅恢复备份中存在的，
+* 即升级前确实存在的文件）。这样升级过程中新建的文件会被清理，真正回到 pre-state。
+*/
+function restoreFeishuPlugins(opts) {
+	const { workspaceDir, configPath, backupDir } = opts;
+	const log = opts.log ?? NOOP_LOG;
+	try {
+		if (node_fs.default.existsSync(configPath)) {
+			node_fs.default.rmSync(configPath, { force: true });
+			log(`  deleted: openclaw.json`);
+		}
+		const extDst = node_path.default.join(workspaceDir, "extensions");
+		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
+			const dst = node_path.default.join(extDst, pluginDir);
+			if (node_fs.default.existsSync(dst)) {
+				node_fs.default.rmSync(dst, {
+					recursive: true,
+					force: true
+				});
+				log(`  deleted: extensions/${pluginDir}`);
+			}
+		}
+		const configBackup = node_path.default.join(backupDir, "openclaw.json");
+		if (node_fs.default.existsSync(configBackup)) {
+			node_fs.default.copyFileSync(configBackup, configPath);
+			log(`  restored: openclaw.json`);
+		} else log(`  skipped restore: openclaw.json (not in backup — was not present before upgrade)`);
+		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
+			const backupSrc = node_path.default.join(backupDir, "extensions", pluginDir);
+			if (node_fs.default.existsSync(backupSrc)) {
+				node_fs.default.cpSync(backupSrc, node_path.default.join(extDst, pluginDir), { recursive: true });
+				log(`  restored: extensions/${pluginDir}`);
+			} else log(`  skipped restore: extensions/${pluginDir} (not in backup — was not present before upgrade)`);
+		}
+		return true;
+	} catch (e) {
+		log(`  restore error: ${e.message}`);
+		return false;
+	}
+}
+/**
+* 执行 `npx -y @larksuite/openclaw-lark-tools update`，自动按当前 openclaw 内核选择
+* 适配的 openclaw-lark 版本。stdout/stderr 已 trim；exitCode 缺失时归一为 1。
+*/
+function runLarkToolsUpdate(opts) {
+	const log = opts.log ?? NOOP_LOG;
+	const r = (0, node_child_process.spawnSync)("npx", [
+		"-y",
+		"@larksuite/openclaw-lark-tools",
+		"update"
+	], {
+		cwd: opts.cwd,
+		encoding: "utf-8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		timeout: opts.timeoutMs ?? 6e5
+	});
+	const stdout = r.stdout?.trim() ?? "";
+	const stderr = r.stderr?.trim() ?? "";
+	const exitCode = r.status ?? 1;
+	if (stdout) log(`npx stdout:\n${stdout}`);
+	if (stderr) log(`npx stderr:\n${stderr}`);
+	log(`npx exit: ${exitCode}${r.error ? ` error: ${r.error.message}` : ""}`);
+	return {
+		exitCode,
+		stdout,
+		stderr,
+		spawnError: r.error?.message
+	};
+}
 async function installExtension(tag, ossFileMap, opts = {}) {
 	const homeBase = resolveHomeBase(opts.homeBase);
 	const hasAll = !!opts.all;
@@ -5370,44 +5506,34 @@ async function installLarkPluginWithCompatCheck(opts) {
 		console.error("[install-extension] WARN: cannot read openclaw version — falling back to direct tarball install for openclaw-lark");
 		return false;
 	}
-	const compatible = pkg.version ? effectiveCompatible(pkg.version, ocCur) : true;
-	console.error(`[install-extension] openclaw-lark@${pkg.version ?? "unknown"} compat with openclaw@${ocCur}: ${compatible}`);
+	const compatVersion = resolveCompatVersion(pkg.packageName, pkg.version);
+	const compatible = compatVersion ? effectiveCompatible(compatVersion, ocCur) : true;
+	console.error(`[install-extension] ${pkg.packageName ?? pkg.name}@${pkg.version ?? "unknown"} (compat-as ${compatVersion ?? "unknown"}) vs openclaw@${ocCur}: ${compatible}`);
 	if (compatible) return false;
 	console.error(`[install-extension] openclaw-lark@${pkg.version} incompatible with openclaw@${ocCur} — using openclaw-lark-tools update`);
+	const log = (msg) => console.error(`[install-extension] ${msg}`);
 	const backupDir = node_path.default.join(homeBase, `.openclaw-lark-backup-${tag}`);
-	const backupOk = backupLarkPlugin({
+	const backupOk = backupFeishuPlugins({
 		workspaceDir,
 		configPath,
-		backupDir
-	});
+		backupDir,
+		log
+	}).ok;
 	if (!backupOk) console.error("[install-extension] WARN: backup failed — proceeding without backup for openclaw-lark-tools path");
 	try {
-		const npxResult = (0, node_child_process.spawnSync)("npx", [
-			"-y",
-			"@larksuite/openclaw-lark-tools",
-			"update"
-		], {
+		const { exitCode } = runLarkToolsUpdate({
 			cwd: workspaceDir,
-			encoding: "utf-8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			],
-			timeout: 6e5
+			log
 		});
-		const npxExit = npxResult.status ?? 1;
-		if (npxResult.stdout?.trim()) console.error(`[install-extension] openclaw-lark-tools stdout:\n${npxResult.stdout.trim()}`);
-		if (npxResult.stderr?.trim()) console.error(`[install-extension] openclaw-lark-tools stderr:\n${npxResult.stderr.trim()}`);
-		console.error(`[install-extension] openclaw-lark-tools exit: ${npxExit}`);
-		if (npxExit !== 0) {
+		if (exitCode !== 0) {
 			console.error("[install-extension] openclaw-lark-tools failed — attempting rollback");
-			if (backupOk) restoreLarkPlugin({
+			if (backupOk) restoreFeishuPlugins({
 				workspaceDir,
 				configPath,
-				backupDir
+				backupDir,
+				log
 			});
-			throw new Error(`openclaw-lark-tools update exited with code ${npxExit}`);
+			throw new Error(`openclaw-lark-tools update exited with code ${exitCode}`);
 		}
 		const validation = validateLarkPluginInstall({
 			homeBase,
@@ -5415,10 +5541,11 @@ async function installLarkPluginWithCompatCheck(opts) {
 		});
 		if (!validation.ok) {
 			console.error(`[install-extension] post-install validation failed: ${validation.error} — rolling back`);
-			if (backupOk) restoreLarkPlugin({
+			if (backupOk) restoreFeishuPlugins({
 				workspaceDir,
 				configPath,
-				backupDir
+				backupDir,
+				log
 			});
 			throw new Error(`openclaw-lark post-install validation failed: ${validation.error}`);
 		}
@@ -5433,38 +5560,6 @@ async function installLarkPluginWithCompatCheck(opts) {
 		} catch {}
 	}
 }
-function backupLarkPlugin(opts) {
-	const { workspaceDir, configPath, backupDir } = opts;
-	try {
-		node_fs.default.mkdirSync(backupDir, { recursive: true });
-		if (node_fs.default.existsSync(configPath)) node_fs.default.copyFileSync(configPath, node_path.default.join(backupDir, "openclaw.json"));
-		const pluginSrc = node_path.default.join(workspaceDir, "extensions", LARK_PLUGIN_NAME$1);
-		if (node_fs.default.existsSync(pluginSrc)) node_fs.default.cpSync(pluginSrc, node_path.default.join(backupDir, LARK_PLUGIN_NAME$1), { recursive: true });
-		return true;
-	} catch (e) {
-		console.error(`[install-extension] backup error: ${e.message}`);
-		return false;
-	}
-}
-function restoreLarkPlugin(opts) {
-	const { workspaceDir, configPath, backupDir } = opts;
-	try {
-		const configBak = node_path.default.join(backupDir, "openclaw.json");
-		if (node_fs.default.existsSync(configBak)) node_fs.default.copyFileSync(configBak, configPath);
-		const pluginBak = node_path.default.join(backupDir, LARK_PLUGIN_NAME$1);
-		const pluginDst = node_path.default.join(workspaceDir, "extensions", LARK_PLUGIN_NAME$1);
-		if (node_fs.default.existsSync(pluginBak)) {
-			if (node_fs.default.existsSync(pluginDst)) node_fs.default.rmSync(pluginDst, {
-				recursive: true,
-				force: true
-			});
-			node_fs.default.cpSync(pluginBak, pluginDst, { recursive: true });
-		}
-		console.error("[install-extension] rollback complete");
-	} catch (e) {
-		console.error(`[install-extension] rollback error: ${e.message}`);
-	}
-}
 /**
 * Post-install validation for the tools-based upgrade path.
 * Checks: plugin directory exists + plugin is enabled in openclaw.json.
@@ -11011,7 +11106,7 @@ async function reportCliRun(opts) {
 //#region src/help.ts
 const BIN = "mclaw-diagnose";
 function versionBanner() {
-	return `v0.1.18-alpha.0`;
+	return `v0.1.18-alpha.2`;
 }
 const COMMANDS = [
 	{
@@ -11697,83 +11792,6 @@ function buildUpgradeLarkResultSummary(result, checkOnly) {
 }
 //#endregion
 //#region src/upgrade-lark.ts
-/** 升级前需备份的 extensions/ 下的插件目录 */
-const FEISHU_PLUGIN_DIRS = ["openclaw-lark", "feishu-openclaw-plugin"];
-function backupFiles(opts) {
-	const { workspaceDir, configPath, backupDir, log } = opts;
-	try {
-		node_fs.default.mkdirSync(backupDir, { recursive: true });
-		log(`backup dir: ${backupDir}`);
-		if (node_fs.default.existsSync(configPath)) {
-			const stat = node_fs.default.statSync(configPath);
-			node_fs.default.copyFileSync(configPath, node_path.default.join(backupDir, "openclaw.json"));
-			log(`  backed up: openclaw.json (${stat.size} bytes)`);
-		} else log(`  skipped: openclaw.json (not found)`);
-		node_fs.default.mkdirSync(node_path.default.join(backupDir, "extensions"), { recursive: true });
-		const extSrc = node_path.default.join(workspaceDir, "extensions");
-		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
-			const src = node_path.default.join(extSrc, pluginDir);
-			if (node_fs.default.existsSync(src)) {
-				const dst = node_path.default.join(backupDir, "extensions", pluginDir);
-				node_fs.default.cpSync(src, dst, { recursive: true });
-				const version = readPkgVersion(node_path.default.join(src, "package.json"));
-				log(`  backed up: extensions/${pluginDir}${version ? ` (version: ${version})` : ""}`);
-			} else log(`  skipped: extensions/${pluginDir} (not found)`);
-		}
-		return { ok: true };
-	} catch (e) {
-		const msg = `backup failed: ${e.message}`;
-		log(`ERROR: ${msg}`);
-		return {
-			ok: false,
-			error: msg
-		};
-	}
-}
-function restoreFiles(opts) {
-	const { workspaceDir, configPath, backupDir, log } = opts;
-	try {
-		if (node_fs.default.existsSync(configPath)) {
-			node_fs.default.rmSync(configPath, { force: true });
-			log(`  deleted: openclaw.json`);
-		}
-		const extDst = node_path.default.join(workspaceDir, "extensions");
-		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
-			const dst = node_path.default.join(extDst, pluginDir);
-			if (node_fs.default.existsSync(dst)) {
-				node_fs.default.rmSync(dst, {
-					recursive: true,
-					force: true
-				});
-				log(`  deleted: extensions/${pluginDir}`);
-			}
-		}
-		const configBackup = node_path.default.join(backupDir, "openclaw.json");
-		if (node_fs.default.existsSync(configBackup)) {
-			node_fs.default.copyFileSync(configBackup, configPath);
-			log(`  restored: openclaw.json`);
-		} else log(`  skipped restore: openclaw.json (not in backup — was not present before upgrade)`);
-		for (const pluginDir of FEISHU_PLUGIN_DIRS) {
-			const backupSrc = node_path.default.join(backupDir, "extensions", pluginDir);
-			if (node_fs.default.existsSync(backupSrc)) {
-				node_fs.default.cpSync(backupSrc, node_path.default.join(extDst, pluginDir), { recursive: true });
-				log(`  restored: extensions/${pluginDir}`);
-			} else log(`  skipped restore: extensions/${pluginDir} (not in backup — was not present before upgrade)`);
-		}
-		return true;
-	} catch (e) {
-		log(`  restore error: ${e.message}`);
-		return false;
-	}
-}
-function readPkgVersion(pkgPath) {
-	try {
-		const pkg = JSON.parse(node_fs.default.readFileSync(pkgPath, "utf-8"));
-		return typeof pkg.version === "string" ? pkg.version : null;
-	} catch {
-		return null;
-	}
-}
 function snapshotVersions(cwd, log) {
 	const ocResult = (0, node_child_process.spawnSync)("openclaw", ["--version"], {
 		cwd,
@@ -12029,7 +12047,7 @@ function runUpgradeLark(opts) {
 	log("── [1/6] 文件备份 ────────────────────────────────────────");
 	log(`before-state: botCount=${countFeishuBots(configPath)}`);
 	const t_backupStart = Date.now();
-	const backup = backupFiles(fsOpts);
+	const backup = backupFeishuPlugins(fsOpts);
 	timing.backupMs = Date.now() - t_backupStart;
 	if (!backup.ok) {
 		log(`ERROR: ${backup.error}`);
@@ -12056,27 +12074,11 @@ function runUpgradeLark(opts) {
 	log("");
 	log("── [3/6] npx install (@larksuite/openclaw-lark-tools update) ──");
 	const t_npxStart = Date.now();
-	const npxResult = (0, node_child_process.spawnSync)("npx", [
-		"-y",
-		"@larksuite/openclaw-lark-tools",
-		"update"
-	], {
+	const { exitCode: npxExitCode, stdout: npxStdout, stderr: npxStderr } = runLarkToolsUpdate({
 		cwd,
-		encoding: "utf-8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		],
-		timeout: 6e5
+		log
 	});
 	timing.npxInstallMs = Date.now() - t_npxStart;
-	const npxStdout = npxResult.stdout?.trim() ?? "";
-	const npxStderr = npxResult.stderr?.trim() ?? "";
-	const npxExitCode = npxResult.status ?? 1;
-	if (npxStdout) log(`npx stdout:\n${npxStdout}`);
-	if (npxStderr) log(`npx stderr:\n${npxStderr}`);
-	log(`npx exit: ${npxExitCode}${npxResult.error ? ` error: ${npxResult.error.message}` : ""}`);
 	if (statusCheckDelayMs > 0) {
 		log("");
 		log(`── 等待 ${statusCheckDelayMs / 1e3}s（让 openclaw 服务完成重启） ─────────────`);
@@ -12085,7 +12087,7 @@ function runUpgradeLark(opts) {
 	}
 	const doRollback = (reason) => {
 		log(`ERROR: ${reason}`);
-		const rollbackOk = restoreFiles(fsOpts);
+		const rollbackOk = restoreFeishuPlugins(fsOpts);
 		log(`rollback: ${rollbackOk ? "ok" : "FAILED"}`);
 		return finalReturn({
 			status: "failed",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/openclaw-scripts-diagnose-cli",
-  "version": "0.1.18-alpha.0",
+  "version": "0.1.18-alpha.2",
   "description": "CLI for OpenClaw config diagnose and repair with JSON5 support",
   "main": "dist/index.cjs",
   "bin": {