docs: document gateway cli helpers

steipete · steipete · commit 69c27677f663 · 2026-06-04T10:56:59.000-04:00
diff --git a/src/cli/gateway-cli/discover.ts b/src/cli/gateway-cli/discover.ts
@@ -1,3 +1,4 @@
+// Gateway discovery rendering helpers for Bonjour and wide-area DNS beacon output.
 import { colorize, theme } from "../../../packages/terminal-core/src/theme.js";
 import type { GatewayBonjourBeacon } from "../../infra/bonjour-discovery.js";
 import { buildGatewayDiscoveryTarget } from "../../infra/gateway-discovery-targets.js";
@@ -21,6 +22,7 @@ export function pickGatewayPort(beacon: GatewayBonjourBeacon): number | null {
 }
 
 export function dedupeBeacons(beacons: GatewayBonjourBeacon[]): GatewayBonjourBeacon[] {
+  // Use display and endpoint fields; Bonjour can surface the same gateway on multiple interfaces.
   const out: GatewayBonjourBeacon[] = [];
   const seen = new Set<string>();
   for (const b of beacons) {
diff --git a/src/cli/gateway-cli/lifecycle.runtime.ts b/src/cli/gateway-cli/lifecycle.runtime.ts
@@ -1,3 +1,4 @@
+// Lazy lifecycle runtime export hub used by gateway run-loop restart paths.
 export {
   abortEmbeddedAgentRun,
   getActiveEmbeddedRunCount,
diff --git a/src/cli/gateway-cli/qa-parent-watchdog.ts b/src/cli/gateway-cli/qa-parent-watchdog.ts
@@ -1,3 +1,4 @@
+// QA watchdog for shutting down orphaned gateway children and cleaning staged temp roots.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
@@ -48,6 +49,7 @@ function resolveQaParentPid(env: NodeJS.ProcessEnv, ownPid: number): number | nu
 }
 
 function resolveQaCleanupRoot(rawValue: string | undefined): string | null {
+  // Only cleanup roots with the QA prefix; env values are external to the child process.
   const raw = rawValue?.trim();
   if (!raw) {
     return null;
diff --git a/src/cli/gateway-cli/register.ts b/src/cli/gateway-cli/register.ts
@@ -1,3 +1,4 @@
+// Commander registration for gateway status, health, diagnostics, discovery, and run commands.
 import type { Command } from "commander";
 import { formatDocsLink } from "../../../packages/terminal-core/src/links.js";
 import { colorize, isRich, theme } from "../../../packages/terminal-core/src/theme.js";
@@ -107,6 +108,7 @@ async function runGatewayCommand(
   label?: string,
   opts?: { json?: boolean },
 ) {
+  // JSON mode preserves structured gateway transport errors for automation callers.
   try {
     await action();
   } catch (err) {
diff --git a/src/cli/gateway-cli/run-command.ts b/src/cli/gateway-cli/run-command.ts
@@ -1,3 +1,4 @@
+// Gateway run command option registration and lazy handoff to runtime startup.
 import type { Command } from "commander";
 
 const GATEWAY_AUTH_MODES = ["none", "token", "password", "trusted-proxy"] as const;
diff --git a/src/cli/gateway-cli/run-loop.ts b/src/cli/gateway-cli/run-loop.ts
@@ -1,3 +1,4 @@
+// In-process gateway run loop, restart signaling, drain, and update respawn handling.
 import { randomUUID } from "node:crypto";
 import net from "node:net";
 import { clearRuntimeConfigSnapshot } from "../../config/runtime-snapshot.js";
@@ -45,6 +46,7 @@ const gatewayLifecycleRuntimeLoader = createLazyImportLoader<GatewayLifecycleRun
 const loadGatewayLifecycleRuntimeModule = () => gatewayLifecycleRuntimeLoader.load();
 
 function createRestartIterationHook(onRestart: () => Promise<void> | void): () => Promise<boolean> {
+  // The first loop starts fresh; subsequent iterations are in-process restarts.
   let isFirstIteration = true;
   return async () => {
     if (isFirstIteration) {
diff --git a/src/cli/gateway-cli/run.ts b/src/cli/gateway-cli/run.ts
@@ -1,3 +1,4 @@
+// Gateway run option resolution and local server startup command implementation.
 import fs from "node:fs";
 import { request } from "node:http";
 import path from "node:path";
@@ -133,6 +134,7 @@ function extractGatewayMiskeys(parsed: unknown): {
   hasGatewayToken: boolean;
   hasRemoteToken: boolean;
 } {
+  // Detect common token misplacements before startup falls back to unauthenticated mode.
   if (!parsed || typeof parsed !== "object") {
     return { hasGatewayToken: false, hasRemoteToken: false };
   }
diff --git a/src/cli/gateway-cli/shared.ts b/src/cli/gateway-cli/shared.ts
@@ -1,3 +1,4 @@
+// Shared gateway CLI helpers for supervised-service stop guidance.
 import {
   resolveGatewayLaunchAgentLabel,
   resolveGatewaySystemdServiceName,
@@ -31,6 +32,7 @@ function renderGatewayServiceStopHints(env: NodeJS.ProcessEnv = process.env): st
 }
 
 export async function maybeExplainGatewayServiceStop() {
+  // Direct `gateway run` should not race a managed service on the same port.
   const service = resolveGatewayService();
   let loaded: boolean | null;
   try {
diff --git a/src/cli/gateway-rpc.runtime.ts b/src/cli/gateway-rpc.runtime.ts
@@ -1,3 +1,4 @@
+// Runtime gateway RPC helper shared by CLI commands that call the Gateway.
 import {
   GATEWAY_CLIENT_MODES,
   GATEWAY_CLIENT_NAMES,
@@ -24,6 +25,7 @@ export async function callGatewayFromCliRuntime(
   params?: unknown,
   extra?: CallGatewayFromCliRuntimeExtra,
 ) {
+  // Progress is disabled for JSON output so stdout stays parseable.
   const showProgress = extra?.progress ?? opts.json !== true;
   return await withProgress(
     {
diff --git a/src/cli/gateway-rpc.ts b/src/cli/gateway-rpc.ts
@@ -1,3 +1,4 @@
+// Lazy gateway RPC facade and shared Commander options for CLI subcommands.
 import type { Command } from "commander";
 import type {
   GatewayClientMode,
@@ -16,6 +17,7 @@ const gatewayRpcRuntimeLoader = createLazyImportLoader<GatewayRpcRuntimeModule>(
 );
 
 async function loadGatewayRpcRuntime(): Promise<GatewayRpcRuntimeModule> {
+  // Keep gateway transport/runtime imports out of help and shell completion startup.
   return gatewayRpcRuntimeLoader.load();
 }
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Lazy lifecycle runtime export hub used by gateway run-loop restart paths.`
`1`	`2`	`export {`
`2`	`3`	`abortEmbeddedAgentRun,`
`3`	`4`	`getActiveEmbeddedRunCount,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Gateway run command option registration and lazy handoff to runtime startup.`
`1`	`2`	`import type { Command } from "commander";`
`2`	`3`
`3`	`4`	`const GATEWAY_AUTH_MODES = ["none", "token", "password", "trusted-proxy"] as const;`