From cb5d43ba95ca76c3d7437dd07fca04de70211eab Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 10:55:01 -0400 Subject: [PATCH] docs: document cli utility helpers --- src/cli/deps.ts | 2 ++ src/cli/devices-cli.runtime.ts | 2 ++ src/cli/devices-cli.ts | 2 ++ src/cli/dns-cli.ts | 2 ++ src/cli/docs-cli.ts | 1 + src/cli/exec-approvals-cli.ts | 2 ++ src/cli/exec-policy-cli.ts | 2 ++ src/cli/failure-output.ts | 2 ++ src/cli/gateway-cli/call.ts | 1 + src/cli/gateway-cli/dev.ts | 2 ++ 10 files changed, 18 insertions(+) diff --git a/src/cli/deps.ts b/src/cli/deps.ts index 8bd3117c26d..e64a9c60c2d 100644 --- a/src/cli/deps.ts +++ b/src/cli/deps.ts @@ -1,3 +1,4 @@ +// Default CLI dependency surface with lazy outbound channel send adapters. import { normalizeChannelId } from "../channels/registry.js"; import type { OutboundSendDeps } from "../infra/outbound/send-deps.js"; import { createLazyRuntimeSurface } from "../shared/lazy-runtime.js"; @@ -76,6 +77,7 @@ function createLazySender( } export function createDefaultDeps(): CliDeps { + // Proxy lookup preserves the historic deps.channelName shape without eagerly importing plugins. const deps: CliDeps = {}; const resolveSender = (channelId: string) => createLazySender(channelId, async () => { diff --git a/src/cli/devices-cli.runtime.ts b/src/cli/devices-cli.runtime.ts index 9a2354d4b32..57d86610d0c 100644 --- a/src/cli/devices-cli.runtime.ts +++ b/src/cli/devices-cli.runtime.ts @@ -1,3 +1,4 @@ +// Device pairing runtime commands for gateway and loopback-local fallback operations. import { normalizeLowercaseStringOrEmpty, normalizeOptionalString, @@ -155,6 +156,7 @@ function resolveLocalPairingFallback( opts: DevicesRpcOpts, error: unknown, ): { details: ConnectPairingRequiredDetails } | null { + // Local fallback is only safe for implicit loopback gateway URLs. const message = normalizeLowercaseStringOrEmpty(normalizeErrorMessage(error)); const details = readConnectPairingRequiredMessage(message); if (!details) { diff --git a/src/cli/devices-cli.ts b/src/cli/devices-cli.ts index d0b8aecd865..cbed91bfc81 100644 --- a/src/cli/devices-cli.ts +++ b/src/cli/devices-cli.ts @@ -1,3 +1,4 @@ +// Commander registration for device pairing and auth-token commands. import type { Command } from "commander"; import { applyParentDefaultHelpAction } from "./program/parent-default-help.js"; @@ -22,6 +23,7 @@ type DevicesRuntimeModule = typeof import("./devices-cli.runtime.js"); let devicesRuntimePromise: Promise | undefined; function loadDevicesRuntime(): Promise { + // Keep device-pairing crypto/table dependencies out of root help startup. return (devicesRuntimePromise ??= import("./devices-cli.runtime.js")); } diff --git a/src/cli/dns-cli.ts b/src/cli/dns-cli.ts index 511b8189de8..c351d6f759d 100644 --- a/src/cli/dns-cli.ts +++ b/src/cli/dns-cli.ts @@ -1,3 +1,4 @@ +// DNS setup helper for wide-area discovery using Tailscale addresses and CoreDNS. import { spawnSync } from "node:child_process"; import fs from "node:fs"; import path from "node:path"; @@ -35,6 +36,7 @@ function run(cmd: string, args: string[], opts?: RunOpts): string { } function writeFileSudoIfNeeded(filePath: string, content: string): void { + // Zone/CoreDNS paths may be root-owned; fall back to sudo tee only after normal write fails. try { fs.writeFileSync(filePath, content, "utf-8"); return; diff --git a/src/cli/docs-cli.ts b/src/cli/docs-cli.ts index 612ee1bbc15..e4f4671ed7a 100644 --- a/src/cli/docs-cli.ts +++ b/src/cli/docs-cli.ts @@ -1,3 +1,4 @@ +// Commander registration for live OpenClaw docs search. import type { Command } from "commander"; import { formatDocsLink } from "../../packages/terminal-core/src/links.js"; import { theme } from "../../packages/terminal-core/src/theme.js"; diff --git a/src/cli/exec-approvals-cli.ts b/src/cli/exec-approvals-cli.ts index 4df3a607ddb..6212e7303f7 100644 --- a/src/cli/exec-approvals-cli.ts +++ b/src/cli/exec-approvals-cli.ts @@ -1,3 +1,4 @@ +// CLI for reading and mutating exec approval allowlists locally, via gateway, or via node. import fs from "node:fs/promises"; import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce"; import type { Command } from "commander"; @@ -132,6 +133,7 @@ async function loadWritableSnapshotTarget(opts: ExecApprovalsCliOpts): Promise<{ targetLabel: string; baseHash: string; }> { + // Writes carry the base hash so gateway/node updates can reject stale snapshots. const { snapshot, nodeId, source } = await loadSnapshotTarget(opts); if (source === "local") { defaultRuntime.log(theme.muted("Writing local approvals.")); diff --git a/src/cli/exec-policy-cli.ts b/src/cli/exec-policy-cli.ts index 02646cf0a0c..4518c2e75c8 100644 --- a/src/cli/exec-policy-cli.ts +++ b/src/cli/exec-policy-cli.ts @@ -1,3 +1,4 @@ +// CLI for showing and applying exec policy presets across config and approvals. import crypto from "node:crypto"; import type { Command } from "commander"; import { formatDocsLink } from "../../packages/terminal-core/src/links.js"; @@ -128,6 +129,7 @@ function sanitizeExecPolicyMessage(value: unknown): string { } function hashExecApprovalsFile(file: ExecApprovalsFile): string { + // Match the persisted formatting hash so restore/set operations can detect drift. const raw = `${JSON.stringify(file, null, 2)}\n`; return crypto.createHash("sha256").update(raw).digest("hex"); } diff --git a/src/cli/failure-output.ts b/src/cli/failure-output.ts index 328f356e933..01eac1fa519 100644 --- a/src/cli/failure-output.ts +++ b/src/cli/failure-output.ts @@ -1,3 +1,4 @@ +// Shared root CLI failure formatting with debug stack gating and recovery hints. import { isTruthyEnvValue } from "../infra/env.js"; import { formatErrorMessage, formatUncaughtError } from "../infra/errors.js"; import { formatCliCommand } from "./command-format.js"; @@ -27,6 +28,7 @@ function pushPrefixed(out: string[], value: string): void { } export function formatCliFailureLines(options: FormatCliFailureOptions): string[] { + // Default output stays terse; stack traces require explicit debug intent. const env = options.env ?? process.env; const lines = [ `[openclaw] ${options.title}`, diff --git a/src/cli/gateway-cli/call.ts b/src/cli/gateway-cli/call.ts index 2083f09df1c..74b3b2627e7 100644 --- a/src/cli/gateway-cli/call.ts +++ b/src/cli/gateway-cli/call.ts @@ -1,3 +1,4 @@ +// Shared gateway RPC command options and progress-wrapped CLI call helper. import type { Command } from "commander"; import { GATEWAY_CLIENT_MODES, diff --git a/src/cli/gateway-cli/dev.ts b/src/cli/gateway-cli/dev.ts index b7273fc14bb..3b352e35b65 100644 --- a/src/cli/gateway-cli/dev.ts +++ b/src/cli/gateway-cli/dev.ts @@ -1,3 +1,4 @@ +// Dev gateway bootstrap for a local loopback config and seeded dev workspace. import fs from "node:fs"; import os from "node:os"; import path from "node:path"; @@ -15,6 +16,7 @@ const DEV_IDENTITY_EMOJI = "🤖"; const DEV_AGENT_WORKSPACE_SUFFIX = "dev"; async function loadDevTemplate(name: string, fallback: string): Promise { + // Template frontmatter is metadata only; workspace files receive the body content. try { const templateDirs = await resolveWorkspaceTemplateSearchDirs(); for (const templateDir of templateDirs) {