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

scripts/bench-cli-startup.ts

@@ -11,6 +11,8 @@ type Sample = {
   signal: NodeJS.Signals | null;
 };
 
+type CaseSummary = ReturnType<typeof summarize>;
+
 const DEFAULT_RUNS = 8;
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_ENTRY = "dist/entry.js";
@@ -124,30 +126,75 @@ function collectExitSummary(samples: Sample[]): string {
   return [...buckets.entries()].map(([key, count]) => `${key}x${count}`).join(", ");
 }
 
-async function main(): Promise<void> {
-  const entry = parseFlagValue("--entry") ?? DEFAULT_ENTRY;
-  const runs = parsePositiveInt(parseFlagValue("--runs"), DEFAULT_RUNS);
-  const timeoutMs = parsePositiveInt(parseFlagValue("--timeout-ms"), DEFAULT_TIMEOUT_MS);
-
-  console.log(`Node: ${process.version}`);
-  console.log(`Entry: ${entry}`);
-  console.log(`Runs per command: ${runs}`);
-  console.log(`Timeout: ${timeoutMs}ms`);
-  console.log("");
-
+function printSuite(params: {
+  title: string;
+  entry: string;
+  runs: number;
+  timeoutMs: number;
+}): Map<string, CaseSummary> {
+  console.log(params.title);
+  console.log(`Entry: ${params.entry}`);
+  const suite = new Map<string, CaseSummary>();
   for (const commandCase of DEFAULT_CASES) {
     const samples = runCase({
-      entry,
+      entry: params.entry,
       runCase: commandCase,
-      runs,
-      timeoutMs,
+      runs: params.runs,
+      timeoutMs: params.timeoutMs,
     });
     const stats = summarize(samples);
     const exitSummary = collectExitSummary(samples);
+    suite.set(commandCase.name, stats);
     console.log(
       `${commandCase.name.padEnd(13)} avg=${formatMs(stats.avg)} p50=${formatMs(stats.p50)} p95=${formatMs(stats.p95)} min=${formatMs(stats.min)} max=${formatMs(stats.max)} exits=[${exitSummary}]`,
     );
   }
+  console.log("");
+  return suite;
+}
+
+async function main(): Promise<void> {
+  const entryPrimary =
+    parseFlagValue("--entry-primary") ?? parseFlagValue("--entry") ?? DEFAULT_ENTRY;
+  const entrySecondary = parseFlagValue("--entry-secondary");
+  const runs = parsePositiveInt(parseFlagValue("--runs"), DEFAULT_RUNS);
+  const timeoutMs = parsePositiveInt(parseFlagValue("--timeout-ms"), DEFAULT_TIMEOUT_MS);
+
+  console.log(`Node: ${process.version}`);
+  console.log(`Runs per command: ${runs}`);
+  console.log(`Timeout: ${timeoutMs}ms`);
+  console.log("");
+
+  const primaryResults = printSuite({
+    title: "Primary entry",
+    entry: entryPrimary,
+    runs,
+    timeoutMs,
+  });
+
+  if (entrySecondary) {
+    const secondaryResults = printSuite({
+      title: "Secondary entry",
+      entry: entrySecondary,
+      runs,
+      timeoutMs,
+    });
+
+    console.log("Delta (secondary - primary, avg)");
+    for (const commandCase of DEFAULT_CASES) {
+      const primary = primaryResults.get(commandCase.name);
+      const secondary = secondaryResults.get(commandCase.name);
+      if (!primary || !secondary) {
+        continue;
+      }
+      const delta = secondary.avg - primary.avg;
+      const pct = primary.avg > 0 ? (delta / primary.avg) * 100 : 0;
+      const sign = delta > 0 ? "+" : "";
+      console.log(
+        `${commandCase.name.padEnd(13)} ${sign}${formatMs(delta)} (${sign}${pct.toFixed(1)}%)`,
+      );
+    }
+  }
 }
 
 await main();

scripts/write-cli-startup-metadata.ts

@@ -0,0 +1,93 @@
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function dedupe(values: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const value of values) {
+    if (!value || seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    out.push(value);
+  }
+  return out;
+}
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(scriptDir, "..");
+const distDir = path.join(rootDir, "dist");
+const outputPath = path.join(distDir, "cli-startup-metadata.json");
+const extensionsDir = path.join(rootDir, "extensions");
+const CORE_CHANNEL_ORDER = [
+  "telegram",
+  "whatsapp",
+  "discord",
+  "irc",
+  "googlechat",
+  "slack",
+  "signal",
+  "imessage",
+] as const;
+
+type ExtensionChannelEntry = {
+  id: string;
+  order: number;
+  label: string;
+};
+
+function readBundledChannelCatalogIds(): string[] {
+  const entries: ExtensionChannelEntry[] = [];
+  for (const dirEntry of readdirSync(extensionsDir, { withFileTypes: true })) {
+    if (!dirEntry.isDirectory()) {
+      continue;
+    }
+    const packageJsonPath = path.join(extensionsDir, dirEntry.name, "package.json");
+    try {
+      const raw = readFileSync(packageJsonPath, "utf8");
+      const parsed = JSON.parse(raw) as {
+        openclaw?: {
+          channel?: {
+            id?: unknown;
+            order?: unknown;
+            label?: unknown;
+          };
+        };
+      };
+      const id = parsed.openclaw?.channel?.id;
+      if (typeof id !== "string" || !id.trim()) {
+        continue;
+      }
+      const orderRaw = parsed.openclaw?.channel?.order;
+      const labelRaw = parsed.openclaw?.channel?.label;
+      entries.push({
+        id: id.trim(),
+        order: typeof orderRaw === "number" ? orderRaw : 999,
+        label: typeof labelRaw === "string" ? labelRaw : id.trim(),
+      });
+    } catch {
+      // Ignore malformed or missing extension package manifests.
+    }
+  }
+  return entries
+    .toSorted((a, b) => (a.order === b.order ? a.label.localeCompare(b.label) : a.order - b.order))
+    .map((entry) => entry.id);
+}
+
+const catalog = readBundledChannelCatalogIds();
+const channelOptions = dedupe([...CORE_CHANNEL_ORDER, ...catalog]);
+
+mkdirSync(distDir, { recursive: true });
+writeFileSync(
+  outputPath,
+  `${JSON.stringify(
+    {
+      generatedBy: "scripts/write-cli-startup-metadata.ts",
+      channelOptions,
+    },
+    null,
+    2,
+  )}\n`,
+  "utf8",
+);