From 95045b1d5bb2c40a9b18f9db7b01092ae3d1b13d Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 3 Jun 2026 18:25:21 -0400 Subject: [PATCH] docs: document cli gateway plugin helpers --- src/cli/gateway-cli.ts | 2 ++ src/cli/gateway-rpc.types.ts | 2 ++ src/cli/native-hook-relay-cli.ts | 5 +++++ src/cli/plugins-install-record-commit.ts | 10 ++++++++++ src/cli/plugins-location-bridges.ts | 2 ++ 5 files changed, 21 insertions(+) diff --git a/src/cli/gateway-cli.ts b/src/cli/gateway-cli.ts index 76169304f91..2d72e1bcb2d 100644 --- a/src/cli/gateway-cli.ts +++ b/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"; diff --git a/src/cli/gateway-rpc.types.ts b/src/cli/gateway-rpc.types.ts index 5ad47b5f328..3cc2c36dd78 100644 --- a/src/cli/gateway-rpc.types.ts +++ b/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; diff --git a/src/cli/native-hook-relay-cli.ts b/src/cli/native-hook-relay-cli.ts index d920d9c99b4..c85cb49697a 100644 --- a/src/cli/native-hook-relay-cli.ts +++ b/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({ diff --git a/src/cli/plugins-install-record-commit.ts b/src/cli/plugins-install-record-commit.ts index 70c0ebd3f4e..c4eab178fb4 100644 --- a/src/cli/plugins-install-record-commit.ts +++ b/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, @@ -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; nextInstallRecords: Record; @@ -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( params: Omit, "commit">, ): Promise> { @@ -246,6 +255,7 @@ export async function transformConfigWithPendingPluginInstalls( }); } +/** Mutating-draft adapter for config transforms that may contain pending plugin installs. */ export async function mutateConfigWithPendingPluginInstalls( params: Omit, "commit" | "transform"> & { mutate: (draft: OpenClawConfig, context: ConfigMutationContext) => Promise | T | void; diff --git a/src/cli/plugins-location-bridges.ts b/src/cli/plugins-location-bridges.ts index 51fd5f66f1f..4b089c90f2f 100644 --- a/src/cli/plugins-location-bridges.ts +++ b/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;