From 976ea3ff509191109f09caafcb2d2cd8dfa99006 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 13:10:25 -0400 Subject: [PATCH] docs: document status command wiring --- src/commands/status.command.text-runtime.ts | 3 +++ src/commands/status.command.ts | 9 +++++++++ src/commands/status.daemon.ts | 5 +++++ src/commands/status.format.ts | 9 +++++++++ src/commands/status.gateway-connection.ts | 6 ++++++ 5 files changed, 32 insertions(+) diff --git a/src/commands/status.command.text-runtime.ts b/src/commands/status.command.text-runtime.ts index d3e621a7396..0790327da55 100644 --- a/src/commands/status.command.text-runtime.ts +++ b/src/commands/status.command.text-runtime.ts @@ -1,3 +1,6 @@ +// Text-mode status runtime barrel. +// Kept separate from command orchestration so JSON/fast status does not import table/theme helpers. + export { formatCliCommand } from "../cli/command-format.js"; export { info } from "../globals.js"; export { formatTimeAgo } from "../infra/format-time/format-relative.ts"; diff --git a/src/commands/status.command.ts b/src/commands/status.command.ts index e1816695e70..73f2236aa27 100644 --- a/src/commands/status.command.ts +++ b/src/commands/status.command.ts @@ -1,3 +1,6 @@ +// Main `openclaw status` command orchestrator. +// It routes all/json/deep modes, collects scan/runtime state, and delegates formatting to report builders. + import { normalizePairingConnectRequestId, readConnectPairingRequiredMessage, @@ -53,6 +56,7 @@ function loadStatusNodeModeModule() { return statusNodeModeModuleLoader.load(); } +/** Extracts device-pairing recovery context from structured gateway errors or legacy message text. */ export function resolvePairingRecoveryContext(params: { error?: string | null; closeReason?: string | null; @@ -72,6 +76,7 @@ export function resolvePairingRecoveryContext(params: { : null, }; } + // Older gateways only exposed pairing details in close/error text; keep status recovery helpful there. const source = [params.error, params.closeReason] .filter((part) => typeof part === "string" && part.trim().length > 0) .join(" "); @@ -86,6 +91,7 @@ export function resolvePairingRecoveryContext(params: { }; } +/** Runs `openclaw status`, including JSON/all routing and optional deep probes. */ export async function statusCommand( opts: { json?: boolean; @@ -98,6 +104,7 @@ export async function statusCommand( runtime: RuntimeEnv, ) { if (opts.all && !opts.json) { + // Human `--all` has a dedicated report path; JSON `--all` stays on the JSON schema. await loadStatusAllModule().then(({ statusAllCommand }) => statusAllCommand(runtime, { timeoutMs: opts.timeoutMs }), ); @@ -221,6 +228,7 @@ export async function statusCommand( }); if (opts.verbose) { + // Verbose status prints the raw gateway target resolution before the report tables. const { buildGatewayConnectionDetails } = await import("../gateway/call.js"); const details = buildGatewayConnectionDetails({ config: scan.cfg }); logGatewayConnectionDetails({ @@ -234,6 +242,7 @@ export async function statusCommand( const tableWidth = getTerminalTableWidth(); if (secretDiagnostics.length > 0) { + // Secret diagnostics are already redacted by the scanner; show them before the main report. runtime.log(theme.warn("Secret diagnostics:")); for (const entry of secretDiagnostics) { runtime.log(`- ${entry}`); diff --git a/src/commands/status.daemon.ts b/src/commands/status.daemon.ts index 7a55cb12158..0f55575ace6 100644 --- a/src/commands/status.daemon.ts +++ b/src/commands/status.daemon.ts @@ -1,3 +1,6 @@ +// Daemon service summary helpers for status output. +// Gateway and node service state share the same normalized shape. + import { resolveNodeService } from "../daemon/node-service.js"; import { resolveGatewayService } from "../daemon/service.js"; import { formatDaemonRuntimeShort } from "./status.format.js"; @@ -34,10 +37,12 @@ async function buildDaemonStatusSummary( }; } +/** Returns the gateway daemon status summary. */ export async function getDaemonStatusSummary(): Promise { return await buildDaemonStatusSummary("gateway"); } +/** Returns the node service status summary. */ export async function getNodeDaemonStatusSummary(): Promise { return await buildDaemonStatusSummary("node"); } diff --git a/src/commands/status.format.ts b/src/commands/status.format.ts index 9945e7ddcb2..7c28b8dec0b 100644 --- a/src/commands/status.format.ts +++ b/src/commands/status.format.ts @@ -1,3 +1,6 @@ +// Formatting helpers for status tokens, durations, prompt-cache stats, and daemon runtime snippets. +// These helpers are shared by report rows and command output surfaces. + import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce"; import { getSystemdCgroupHygieneSummary } from "../daemon/service-runtime.js"; import { formatDurationPrecise } from "../infra/format-time/format-duration.ts"; @@ -5,9 +8,11 @@ import { formatRuntimeStatusWithDetails } from "../infra/runtime-status.ts"; import type { SessionStatus } from "./status.types.js"; export { shortenText } from "./text-format.js"; +/** Formats a token count in thousands for compact status rows. */ export const formatKTokens = (value: number) => `${(value / 1000).toFixed(value >= 10_000 ? 0 : 1)}k`; +/** Formats a duration or returns `unknown` for missing/non-finite values. */ export const formatDuration = (ms: number | null | undefined) => { if (ms == null || !Number.isFinite(ms)) { return "unknown"; @@ -15,6 +20,7 @@ export const formatDuration = (ms: number | null | undefined) => { return formatDurationPrecise(ms, { decimals: 1 }); }; +/** Formats session token usage and prompt-cache hit rate for the sessions table. */ export const formatTokensCompact = ( sess: Pick< SessionStatus, @@ -42,6 +48,7 @@ export const formatTokensCompact = ( return result; }; +/** Formats prompt-cache details for verbose sessions table output. */ export const formatPromptCacheCompact = ( sess: Pick, ) => { @@ -98,6 +105,7 @@ function resolvePromptCacheStats( }; } +/** Formats daemon runtime status plus launchd/systemd details into one compact string. */ export const formatDaemonRuntimeShort = (runtime?: { status?: string; pid?: number; @@ -114,6 +122,7 @@ export const formatDaemonRuntimeShort = (runtime?: { const noisyLaunchctlDetail = runtime.missingUnit === true && normalizeLowercaseStringOrEmpty(detail).includes("could not find service"); + // launchctl reports missing units noisily; installed=false already carries that signal. if (detail && !noisyLaunchctlDetail) { details.push(detail); } diff --git a/src/commands/status.gateway-connection.ts b/src/commands/status.gateway-connection.ts index 7192e5a4b8f..bc9fcee4dbc 100644 --- a/src/commands/status.gateway-connection.ts +++ b/src/commands/status.gateway-connection.ts @@ -1,7 +1,11 @@ +// Gateway connection detail formatting for status reports. +// Keeps verbose human text and status-all connection sections consistent. + import type { RuntimeEnv } from "../runtime.js"; import type { NodeOnlyGatewayInfo } from "./status.node-mode.js"; import type { StatusScanOverviewResult } from "./status.scan-overview.ts"; +/** Logs multi-line gateway connection details with the standard heading. */ export function logGatewayConnectionDetails(params: { runtime: Pick; info: (value: string) => string; @@ -17,6 +21,7 @@ export function logGatewayConnectionDetails(params: { } } +/** Builds status-all gateway connection details, including remote-url fallback diagnostics. */ export function resolveStatusAllConnectionDetails(params: { nodeOnlyGateway: NodeOnlyGatewayInfo | null; remoteUrlMissing: boolean; @@ -30,6 +35,7 @@ export function resolveStatusAllConnectionDetails(params: { if (!params.remoteUrlMissing) { return params.gatewayConnection.message; } + // Remote mode without a URL probes local fallback only so the report can still diagnose config. return [ "Gateway mode: remote", "Gateway target: (missing gateway.remote.url)",