docs: document cli gateway plugin helpers

src/cli/gateway-cli.ts

@@ -1 +1,3 @@
+// Public CLI barrel for gateway subcommand registration.
+/** Register all gateway CLI subcommands on the root program. */
 export { registerGatewayCli } from "./gateway-cli/register.js";

src/cli/gateway-rpc.types.ts

@@ -1,3 +1,5 @@
+// Shared RPC option shape for gateway CLI commands.
+/** Common gateway RPC flags accepted by direct gateway command helpers. */
 export type GatewayRpcOpts = {
   url?: string;
   token?: string;

src/cli/native-hook-relay-cli.ts

@@ -1,3 +1,4 @@
+// CLI adapter for invoking native provider hooks through direct relay or gateway fallback.
 import { Readable, Writable } from "node:stream";
 import {
   invokeNativeHookRelayBridge,
@@ -11,6 +12,7 @@ import { parseTimeoutMsWithFallback } from "./parse-timeout.js";
 
 const MAX_NATIVE_HOOK_STDIN_BYTES = 1024 * 1024;
 
+/** User-facing flags for the native hook relay command. */
 export type NativeHookRelayCliOptions = {
   provider?: string;
   relayId?: string;
@@ -28,6 +30,7 @@ type NativeHookRelayCliDeps = {
   callGateway?: typeof callGateway;
 };
 
+/** Run one native hook relay invocation from stdin JSON to stdout/stderr response streams. */
 export async function runNativeHookRelayCli(
   opts: NativeHookRelayCliOptions,
   deps: NativeHookRelayCliDeps = {},
@@ -144,10 +147,12 @@ function formatRelayCliError(prefix: string, error: unknown): string {
   return `${prefix}: ${message}\n`;
 }
 
+/** Create a readable text stream for relay CLI tests. */
 export function createReadableTextStream(text: string): NodeJS.ReadableStream {
   return Readable.from([text]);
 }
 
+/** Create a writable stream that exposes captured text for relay CLI tests. */
 export function createWritableTextBuffer(): NodeJS.WritableStream & { text: () => string } {
   const chunks: Buffer[] = [];
   const stream = new Writable({

src/cli/plugins-install-record-commit.ts

@@ -1,3 +1,4 @@
+// Commit helpers that move transient plugin install records into the persisted install index.
 import { isDeepStrictEqual } from "node:util";
 import {
   replaceConfigFile,
@@ -28,10 +29,12 @@ function mergeUnsetPaths(
   return merged.length > 0 ? merged : undefined;
 }
 
+/** Return whether config still contains legacy/transient plugin install records. */
 export function hasPendingPluginInstallRecords(config: OpenClawConfig): boolean {
   return Object.keys(config.plugins?.installs ?? {}).length > 0;
 }
 
+/** Find pending install records that match the base config and can be stripped as unchanged. */
 export function unchangedPendingPluginInstallRecordIds(
   config: OpenClawConfig,
   baseConfig: OpenClawConfig,
@@ -42,6 +45,7 @@ export function unchangedPendingPluginInstallRecordIds(
     .map(([pluginId]) => pluginId);
 }
 
+/** Remove pending plugin install records from config, optionally only for selected ids. */
 export function stripPendingPluginInstallRecords(
   config: OpenClawConfig,
   pluginIds?: Iterable<string>,
@@ -113,6 +117,7 @@ async function commitPluginInstallRecordsWithWriter(params: {
     });
   } catch (error) {
     try {
+      // Keep config and install index atomic from the caller's perspective.
       await writePersistedInstalledPluginIndexInstallRecords(previousInstallRecords);
     } catch (rollbackError) {
       throw new Error(
@@ -124,6 +129,7 @@ async function commitPluginInstallRecordsWithWriter(params: {
   }
 }
 
+/** Persist plugin install records and commit the matching config update to disk. */
 export async function commitPluginInstallRecordsWithConfig(params: {
   previousInstallRecords?: Record<string, PluginInstallRecord>;
   nextInstallRecords: Record<string, PluginInstallRecord>;
@@ -143,6 +149,7 @@ export async function commitPluginInstallRecordsWithConfig(params: {
   });
 }
 
+/** Commit config while migrating any pending install records into the install index. */
 export async function commitConfigWriteWithPendingPluginInstalls(params: {
   nextConfig: OpenClawConfig;
   writeOptions?: ConfigWriteOptions;
@@ -187,6 +194,7 @@ export async function commitConfigWriteWithPendingPluginInstalls(params: {
   };
 }
 
+/** Replace the config file after moving pending plugin install records into the install index. */
 export async function commitConfigWithPendingPluginInstalls(params: {
   nextConfig: OpenClawConfig;
   baseHash?: string;
@@ -210,6 +218,7 @@ export async function commitConfigWithPendingPluginInstalls(params: {
   });
 }
 
+/** Transform config with retry support while preserving plugin install index consistency. */
 export async function transformConfigWithPendingPluginInstalls<T = void>(
   params: Omit<TransformConfigFileWithRetryParams<T>, "commit">,
 ): Promise<ConfigMutationResult<T>> {
@@ -246,6 +255,7 @@ export async function transformConfigWithPendingPluginInstalls<T = void>(
   });
 }
 
+/** Mutating-draft adapter for config transforms that may contain pending plugin installs. */
 export async function mutateConfigWithPendingPluginInstalls<T = void>(
   params: Omit<TransformConfigFileWithRetryParams<T>, "commit" | "transform"> & {
     mutate: (draft: OpenClawConfig, context: ConfigMutationContext) => Promise<T | void> | T | void;

src/cli/plugins-location-bridges.ts

@@ -1,3 +1,4 @@
+// Bridge builder for users upgrading from bundled plugins to external plugin packages.
 import type { ExternalizedBundledPluginBridge } from "../plugins/externalized-bundled-plugins.js";
 import { readPersistedInstalledPluginIndex } from "../plugins/installed-plugin-index-store.js";
 import type { InstalledPluginIndexRecord } from "../plugins/installed-plugin-index.js";
@@ -48,6 +49,7 @@ function buildBridgeFromPersistedBundledRecord(
   };
 }
 
+/** List install bridges inferred from the persisted plugin index before current discovery runs. */
 export async function listPersistedBundledPluginLocationBridges(options: {
   workspaceDir?: string;
   env?: NodeJS.ProcessEnv;