CLI: add root --help fast path and lazy channel option resolution (#30975)

* CLI argv: add strict root help invocation guard * Entry: add root help fast-path bootstrap bypass * CLI context: lazily resolve channel options * CLI context tests: cover lazy channel option resolution * CLI argv tests: cover root help invocation detection * Changelog: note additional startup path optimizations * Changelog: split startup follow-up into #30975 entry * CLI channel options: load precomputed startup metadata * CLI channel options tests: cover precomputed metadata path * Build: generate CLI startup metadata during build * Build script: invoke CLI startup metadata generator * CLI routes: preload plugins for routed health * CLI routes tests: assert health plugin preload * CLI: add experimental bundled entry and snapshot helper * Tools: compare CLI startup entries in benchmark script * Docs: add startup tuning notes for Pi and VM hosts * CLI: drop bundled entry runtime toggle * Build: remove bundled and snapshot scripts * Tools: remove bundled-entry benchmark shortcut * Docs: remove bundled startup bench examples * Docs: remove Pi bundled entry mention * Docs: remove VM bundled entry mention * Changelog: remove bundled startup follow-up claims * Build: remove snapshot helper script * Build: remove CLI bundle tsdown config * Doctor: add low-power startup optimization hints * Doctor: run startup optimization hint checks * Doctor tests: cover startup optimization host targeting * Doctor tests: mock startup optimization note export * CLI argv: require strict root-only help fast path * CLI argv tests: cover mixed root-help invocations * CLI channel options: merge metadata with runtime catalog * CLI channel options tests: assert dynamic catalog merge * Changelog: align #30975 startup follow-up scope * Docs tests: remove secondary-entry startup bench note * Docs Pi: add systemd recovery reference link * Docs VPS: add systemd recovery reference link
2026-05-11 15:23:43 +00:00 · 2026-03-01 14:23:46 -08:00
parent dcd19da425
commit 38da2d076c
19 changed files with 667 additions and 31 deletions
--- a/src/commands/doctor-platform-notes.ts
+++ b/src/commands/doctor-platform-notes.ts
@@ -140,3 +140,81 @@ export function noteDeprecatedLegacyEnvVars(
  ];
  (deps?.noteFn ?? note)(lines.join("\n"), "Environment");
 }
+
+function isTruthyEnvValue(value: string | undefined): boolean {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isTmpCompileCachePath(cachePath: string): boolean {
+  const normalized = cachePath.trim().replace(/\/+$/, "");
+  return (
+    normalized === "/tmp" ||
+    normalized.startsWith("/tmp/") ||
+    normalized === "/private/tmp" ||
+    normalized.startsWith("/private/tmp/")
+  );
+}
+
+export function noteStartupOptimizationHints(
+  env: NodeJS.ProcessEnv = process.env,
+  deps?: {
+    platform?: NodeJS.Platform;
+    arch?: string;
+    totalMemBytes?: number;
+    noteFn?: typeof note;
+  },
+) {
+  const platform = deps?.platform ?? process.platform;
+  if (platform === "win32") {
+    return;
+  }
+  const arch = deps?.arch ?? os.arch();
+  const totalMemBytes = deps?.totalMemBytes ?? os.totalmem();
+  const isArmHost = arch === "arm" || arch === "arm64";
+  const isLowMemoryLinux =
+    platform === "linux" && totalMemBytes > 0 && totalMemBytes <= 8 * 1024 ** 3;
+  const isStartupTuneTarget = platform === "linux" && (isArmHost || isLowMemoryLinux);
+  if (!isStartupTuneTarget) {
+    return;
+  }
+
+  const noteFn = deps?.noteFn ?? note;
+  const compileCache = env.NODE_COMPILE_CACHE?.trim() ?? "";
+  const disableCompileCache = env.NODE_DISABLE_COMPILE_CACHE?.trim() ?? "";
+  const noRespawn = env.OPENCLAW_NO_RESPAWN?.trim() ?? "";
+  const lines: string[] = [];
+
+  if (!compileCache) {
+    lines.push(
+      "- NODE_COMPILE_CACHE is not set; repeated CLI runs can be slower on small hosts (Pi/VM).",
+    );
+  } else if (isTmpCompileCachePath(compileCache)) {
+    lines.push(
+      "- NODE_COMPILE_CACHE points to /tmp; use /var/tmp so cache survives reboots and warms startup reliably.",
+    );
+  }
+
+  if (isTruthyEnvValue(disableCompileCache)) {
+    lines.push("- NODE_DISABLE_COMPILE_CACHE is set; startup compile cache is disabled.");
+  }
+
+  if (noRespawn !== "1") {
+    lines.push(
+      "- OPENCLAW_NO_RESPAWN is not set to 1; set it to avoid extra startup overhead from self-respawn.",
+    );
+  }
+
+  if (lines.length === 0) {
+    return;
+  }
+
+  const suggestions = [
+    "- Suggested env for low-power hosts:",
+    "  export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache",
+    "  mkdir -p /var/tmp/openclaw-compile-cache",
+    "  export OPENCLAW_NO_RESPAWN=1",
+    isTruthyEnvValue(disableCompileCache) ? "  unset NODE_DISABLE_COMPILE_CACHE" : undefined,
+  ].filter((line): line is string => Boolean(line));
+
+  noteFn([...lines, ...suggestions].join("\n"), "Startup optimization");
+}