@lark-apaas/openclaw-scripts-diagnose-cli 0.1.1-alpha.27 → 0.1.1-alpha.29

package/dist/index.cjs

@@ -32,6 +32,8 @@ node_path = __toESM(node_path);
 let node_child_process = require("node:child_process");
 let node_crypto = require("node:crypto");
 node_crypto = __toESM(node_crypto);
+let node_os = require("node:os");
+node_os = __toESM(node_os);
 let node_stream = require("node:stream");
 let node_stream_promises = require("node:stream/promises");
 let node_assert = require("node:assert");
@@ -684,18 +686,10 @@ FeishuChannelRule = _FeishuChannelRule = __decorate([Rule({
 //#endregion
 //#region src/rules/feishu-default-account.ts
 let FeishuDefaultAccountRule = class FeishuDefaultAccountRule extends DiagnoseRule {
-	validate(ctx) {
-		const feishu = getNestedMap(ctx.config, "channels", "feishu");
-		if (feishu && "defaultAccount" in feishu) return {
-			pass: false,
-			message: "channels.feishu.defaultAccount should be removed"
-		};
+	validate(_ctx) {
 		return { pass: true };
 	}
-	repair(ctx) {
-		const feishu = getNestedMap(ctx.config, "channels", "feishu");
-		if (feishu && "defaultAccount" in feishu) delete feishu.defaultAccount;
-	}
+	repair(_ctx) {}
 };
 FeishuDefaultAccountRule = __decorate([Rule({
 	key: "feishu_default_account",
@@ -1582,32 +1576,51 @@ async function installOpenclaw(openclawTag, ossFileMap, opts = {}) {
 	if (!pkg) throw new Error("install-openclaw: role=cli,name=openclaw not found in manifest");
 	const targetDir = opts.targetDir ?? node_path.default.join(homeBase, pkg.installPath);
 	const bakDir = targetDir + ".bak";
+	const newDir = targetDir + ".new";
 	const tarball = await downloadWithCache(pkg, ossFileMap, opts);
 	console.error(`[install-openclaw] tag=${openclawTag} shasum=${pkg.shasum.slice(0, 12)}...`);
+	if (node_fs.default.existsSync(newDir)) node_fs.default.rmSync(newDir, {
+		recursive: true,
+		force: true
+	});
 	if (node_fs.default.existsSync(bakDir)) node_fs.default.rmSync(bakDir, {
 		recursive: true,
 		force: true
 	});
-	const hadExisting = node_fs.default.existsSync(targetDir);
-	if (hadExisting) moveSafe(targetDir, bakDir);
+	node_fs.default.mkdirSync(node_path.default.dirname(targetDir), { recursive: true });
+	const tmpStage = node_fs.default.mkdtempSync(node_path.default.join(opts.tmpRoot ?? node_os.default.tmpdir(), "openclaw-install-"));
 	try {
-		node_fs.default.mkdirSync(targetDir, { recursive: true });
-		execCaptureErr(`tar -xzf '${tarball}' -C '${targetDir}' --strip-components=1`);
-		if (!node_fs.default.existsSync(node_path.default.join(targetDir, "package.json"))) throw new Error("extracted tarball missing package.json");
-	} catch (e) {
+		execCaptureErr(`tar -xzf '${tarball}' -C '${tmpStage}' --strip-components=1`);
+		if (!node_fs.default.existsSync(node_path.default.join(tmpStage, "package.json"))) throw new Error("extracted tarball missing package.json");
+		moveSafe(tmpStage, newDir);
+		const hadExisting = node_fs.default.existsSync(targetDir);
 		try {
-			node_fs.default.rmSync(targetDir, {
+			if (hadExisting) moveSafe(targetDir, bakDir);
+			moveSafe(newDir, targetDir);
+		} catch (e) {
+			if (hadExisting && !node_fs.default.existsSync(targetDir) && node_fs.default.existsSync(bakDir)) try {
+				moveSafe(bakDir, targetDir);
+			} catch {}
+			try {
+				node_fs.default.rmSync(newDir, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+			throw e;
+		}
+		if (hadExisting && node_fs.default.existsSync(bakDir)) node_fs.default.rmSync(bakDir, {
+			recursive: true,
+			force: true
+		});
+	} finally {
+		if (node_fs.default.existsSync(tmpStage)) try {
+			node_fs.default.rmSync(tmpStage, {
 				recursive: true,
 				force: true
 			});
 		} catch {}
-		if (hadExisting && node_fs.default.existsSync(bakDir)) moveSafe(bakDir, targetDir);
-		throw e;
 	}
-	if (node_fs.default.existsSync(bakDir)) node_fs.default.rmSync(bakDir, {
-		recursive: true,
-		force: true
-	});
 	console.error(`[install-openclaw] done in ${Date.now() - t0}ms`);
 }
 async function installExtension(tag, ossFileMap, opts = {}) {
@@ -2504,9 +2517,248 @@ async function runDoctor(rawCtx, opts) {
 	};
 }
 //#endregion
+//#region src/help.ts
+const BIN = "mclaw-diagnose";
+function versionBanner() {
+	return `v0.1.1-alpha.29`;
+}
+const COMMANDS = [
+	{
+		name: "doctor",
+		hidden: false,
+		summary: "Diagnose openclaw config; apply repairs with --fix",
+		help: `USAGE
+  ${BIN} doctor [--fix] [--rule=<key>]...
+
+DESCRIPTION
+  Fetches DoctorCtx via innerapi, then runs one of three modes depending
+  on the flags. Output is a single JSON object on stdout.
+
+MODES
+  (no flags)              Check-only. Runs the rule engine against the
+                          sandbox's current openclaw config and returns
+                            { failedRules: { standard, ai, reset } }
+                          No files are mutated. Use this when you just
+                          want to know what's wrong.
+
+  --fix                   Check + repair-all. First runs the rule engine,
+                          then repairs every failing standard-mode rule.
+                          Returns
+                            { check: {...}, repair: {...} }
+                          Use this as the default "fix everything" action.
+
+  --fix --rule=<key>...   Targeted repair. Skips the check pass entirely
+                          and runs repair against the listed rule keys
+                          only. Unknown keys are silently ignored.
+                          Returns { repair: {...} } with only those
+                          rules' outcomes. Use this when you already
+                          know which rules need fixing.
+
+OPTIONS
+  --fix                   Enable repair. See MODES above.
+  --rule=<key>            Repair only this rule key. Repeatable. Only
+                          meaningful together with --fix.
+
+EXAMPLES
+  ${BIN} doctor                                            # check only
+  ${BIN} doctor --fix                                      # check then repair all
+  ${BIN} doctor --fix --rule=gateway                       # repair 'gateway' only
+  ${BIN} doctor --fix --rule=gateway --rule=jwt_token      # repair multiple
+
+EXIT CODES
+  0    success
+  1    generic error
+  77   innerapi authentication failed (sandbox JWT expired/invalid)
+`
+	},
+	{
+		name: "check",
+		hidden: true,
+		summary: "Run rule-engine check only",
+		help: `USAGE
+  ${BIN} check [--ctx=<base64>]
+
+DESCRIPTION
+  Runs the rule engine against the sandbox's current openclaw config and
+  returns { failedRules }. Used by sandbox_console's push-style callers
+  that already own the ctx — end-users should prefer \`doctor\`.
+
+OPTIONS
+  --ctx=<base64>   Opaque ctx JSON (base64). When absent, fetched from
+                   innerapi (same path as doctor).
+`
+	},
+	{
+		name: "repair",
+		hidden: true,
+		summary: "Apply standard-mode repairs",
+		help: `USAGE
+  ${BIN} repair [--ctx=<base64>]
+
+DESCRIPTION
+  Runs repair for the failing rules listed inside the ctx's repairData.
+  Intended for sandbox_console's push path — end-users should use
+  \`doctor --fix\` instead.
+
+OPTIONS
+  --ctx=<base64>   Opaque ctx JSON (base64). When absent, fetched from
+                   innerapi.
+`
+	},
+	{
+		name: "reset",
+		hidden: true,
+		summary: "Re-initialize sandbox via the 9-step reset pipeline",
+		help: `USAGE
+  ${BIN} reset --async  [--ctx=<base64>]
+  ${BIN} reset --worker --task-id=<id> [--ctx=<base64>]
+
+DESCRIPTION
+  Two-phase pipeline driven asynchronously: the --async invocation spawns
+  a detached worker and returns { taskId } immediately; the --worker
+  invocation (spawned by --async) runs the actual 9 steps and writes
+  progress to /tmp/openclaw-diagnose/reset-<taskId>.json.
+
+  Poll progress with \`${BIN} get_reset_task --task-id=<id>\`.
+
+OPTIONS
+  --async           Start a detached worker and return taskId on stdout.
+  --worker          Internal — run the 9-step pipeline (launched by --async).
+  --task-id=<id>    Required with --worker; identifies the progress file.
+  --ctx=<base64>    Opaque ctx JSON; fetched from innerapi when absent.
+`
+	},
+	{
+		name: "get_reset_task",
+		hidden: true,
+		summary: "Poll progress of an async reset task",
+		help: `USAGE
+  ${BIN} get_reset_task --task-id=<id>
+
+DESCRIPTION
+  Reads /tmp/openclaw-diagnose/reset-<taskId>.json and prints its content
+  as JSON on stdout. Safe to call repeatedly while reset is in progress.
+
+OPTIONS
+  --task-id=<id>    Required. Matches the id returned by \`reset --async\`.
+`
+	},
+	{
+		name: "install-openclaw",
+		hidden: true,
+		summary: "Download + install the openclaw tarball",
+		help: `USAGE
+  ${BIN} install-openclaw <tag> [--ctx=<base64> | --oss_file_map=<base64>]
+
+DESCRIPTION
+  Downloads the openclaw@<tag> tgz via the signed OSS URL found in the
+  ctx's install.ossFileMap, extracts it into a tmpfs staging dir, and
+  atomically swaps it into /home/gem/.npm-global/lib/node_modules/openclaw.
+  Used by step 5 of reset.
+
+ARGUMENTS
+  <tag>                Openclaw version tag, e.g. 2026.4.11.
+
+OPTIONS
+  --ctx=<base64>       Opaque ctx; ossFileMap is extracted from it.
+  --oss_file_map=...   Pre-built OSS URL map (base64 JSON); skips innerapi
+                       entirely. Wins over --ctx when both provided.
+`
+	},
+	{
+		name: "install-extension",
+		hidden: true,
+		summary: "Install openclaw extension package(s)",
+		help: `USAGE
+  ${BIN} install-extension <tag> (--all | --extension=<name>...) [options]
+
+DESCRIPTION
+  Downloads + installs one or more openclaw extension tarballs
+  (feishu, miaoda, etc.) into <home_base>/workspace/agent/extensions/,
+  then splices installMetadata into openclaw.json's plugins.installs
+  unless --skip-config-update is passed.
+
+ARGUMENTS
+  <tag>                Openclaw version tag; extension versions resolved
+                       against the matching manifest.
+
+OPTIONS
+  --all                Install every extension in the manifest.
+  --extension=<name>   Install a specific extension (repeatable).
+  --home_base=<dir>    Override the /home/gem base (tests).
+  --config_path=<p>    Override the openclaw.json path (tests).
+  --skip-config-update Leave plugins.installs in openclaw.json untouched.
+  --ctx=<base64>       Opaque ctx; see install-openclaw for semantics.
+  --oss_file_map=...   Pre-built OSS URL map (base64 JSON).
+`
+	},
+	{
+		name: "download-resource",
+		hidden: true,
+		summary: "Download + extract a single OSS resource",
+		help: `USAGE
+  ${BIN} download-resource <tag> --role=<role> --name=<name> [--dir=<dir>] [options]
+
+DESCRIPTION
+  Downloads one resource (template, config asset, etc.) identified by
+  (role, name) from the manifest and extracts/copies it to <dir>.
+
+ARGUMENTS
+  <tag>                Openclaw version tag.
+
+OPTIONS
+  --role=<role>        Package role (e.g. template, config).
+  --name=<name>        Package name within the role.
+  --dir=<dir>          Target dir (defaults to dirname(pkg.installPath)).
+  --ctx=<base64>       Opaque ctx; ossFileMap is extracted from it.
+  --oss_file_map=...   Pre-built OSS URL map (base64 JSON).
+`
+	}
+];
+function parseHelpFlags(args) {
+	return {
+		help: args.includes("--help") || args.includes("-h"),
+		expert: args.includes("-x") || args.includes("--expert")
+	};
+}
+/**
+* Render the top-level help to the given stream. When `expert` is true,
+* hidden commands are listed alongside the user-facing ones.
+*/
+function formatTopLevelHelp(expert) {
+	const visible = COMMANDS.filter((c) => !c.hidden);
+	const hidden = COMMANDS.filter((c) => c.hidden);
+	const pad = (s, w) => s + " ".repeat(Math.max(0, w - s.length));
+	const w = Math.max(...COMMANDS.map((c) => c.name.length)) + 2;
+	const lines = [];
+	lines.push(`${BIN} — OpenClaw config diagnose / repair CLI`);
+	lines.push(versionBanner());
+	lines.push("");
+	lines.push("USAGE");
+	lines.push(`  ${BIN} <command> [options]`);
+	lines.push(`  ${BIN} <command> --help       per-command help`);
+	lines.push(`  ${BIN} --help                 this message`);
+	lines.push("");
+	lines.push("COMMANDS");
+	for (const c of visible) lines.push(`  ${pad(c.name, w)}${c.summary}`);
+	if (expert && hidden.length > 0) {
+		lines.push("");
+		lines.push("INTERNAL COMMANDS (revealed by -x)");
+		for (const c of hidden) lines.push(`  ${pad(c.name, w)}${c.summary}`);
+	}
+	lines.push("");
+	return lines.join("\n");
+}
+/** Render per-command help. Returns undefined when the name is unknown. */
+function formatCommandHelp(name) {
+	const cmd = COMMANDS.find((c) => c.name === name);
+	if (!cmd) return void 0;
+	return cmd.help;
+}
+//#endregion
 //#region src/index.ts
 const args = node_process.default.argv.slice(2);
-const mode = args.find((a) => !a.startsWith("--"));
+const mode = args.find((a) => !a.startsWith("-"));
 /**
 * Decode `--ctx=<base64>` into an opaque JSON object. Returns undefined when
 * the flag isn't present — the caller decides whether to fall back to the
@@ -2539,6 +2791,25 @@ function getMultiFlag(args, name) {
 }
 async function main() {
 	installStderrMirror();
+	const helpFlags = parseHelpFlags(args);
+	if (mode && helpFlags.help) {
+		const body = formatCommandHelp(mode);
+		if (body) {
+			node_process.default.stdout.write(body);
+			return;
+		}
+		node_process.default.stderr.write(`Unknown command: ${mode}\n\n`);
+		node_process.default.stderr.write(formatTopLevelHelp(helpFlags.expert));
+		node_process.default.exit(1);
+	}
+	if (!mode) {
+		if (helpFlags.help) {
+			node_process.default.stdout.write(formatTopLevelHelp(helpFlags.expert));
+			return;
+		}
+		node_process.default.stderr.write(formatTopLevelHelp(helpFlags.expert));
+		node_process.default.exit(1);
+	}
 	switch (mode) {
 		case "check":
 		case "repair": {
@@ -2660,7 +2931,8 @@ async function main() {
 			break;
 		}
 		default:
-			console.error("Usage: mclaw-diagnose <check|repair|doctor|reset|get_reset_task|install-openclaw|install-extension|download-resource> [options]");
+			node_process.default.stderr.write(`Unknown command: ${mode}\n\n`);
+			node_process.default.stderr.write(formatTopLevelHelp(helpFlags.expert));
 			node_process.default.exit(1);
 	}
 }

package/package.json

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