docs: document status channel helpers

steipete · steipete · commit 2939ac6b72db · 2026-06-04T13:02:30.000-04:00
diff --git a/src/commands/status-all/channel-issues.ts b/src/commands/status-all/channel-issues.ts
@@ -1,3 +1,7 @@
+// Groups channel-scoped status issues for status report table rendering.
+// Kept tiny so both text and report builders share identical issue ordering.
+
+/** Groups issue-like rows by channel id while preserving the original issue order per channel. */
 export function groupChannelIssuesByChannel<T extends { channel: string }>(
   issues: readonly T[],
 ): Map<string, T[]> {
diff --git a/src/commands/status-all/channels-table.ts b/src/commands/status-all/channels-table.ts
@@ -1,3 +1,6 @@
+// Builds the user-facing `openclaw status --all` channel summary table rows.
+// Gateway issues are folded in here so every text/report surface shows the same warning state.
+
 import { groupChannelIssuesByChannel } from "./channel-issues.js";
 
 type ChannelTableRowInput = {
@@ -20,6 +23,7 @@ export const statusChannelsTableColumns = [
   { key: "Detail", header: "Detail", flex: true, minWidth: 24 },
 ] as const;
 
+/** Formats channel rows and overlays live gateway issues onto their display state. */
 export function buildStatusChannelsTableRows(params: {
   rows: readonly ChannelTableRowInput[];
   channelIssues: readonly ChannelIssueLike[];
@@ -33,6 +37,7 @@ export function buildStatusChannelsTableRows(params: {
   const formatIssueMessage = params.formatIssueMessage ?? ((message: string) => message);
   return params.rows.map((row) => {
     const issues = channelIssuesByChannel.get(row.id) ?? [];
+    // A disabled channel stays disabled even if the gateway still reports stale issues for it.
     const effectiveState = row.state === "off" ? "off" : issues.length > 0 ? "warn" : row.state;
     const issueSuffix =
       issues.length > 0
diff --git a/src/commands/status-all/channels-token-summary.ts b/src/commands/status-all/channels-token-summary.ts
@@ -1,3 +1,6 @@
+// Summarizes channel token/account credential fields for `openclaw status --all`.
+// The display path is intentionally secret-safe unless the caller explicitly requests disclosure.
+
 import { asRecord } from "@openclaw/normalization-core/record-coerce";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { hasConfiguredUnavailableCredentialStatus } from "../../channels/account-snapshot-fields.js";
@@ -10,6 +13,7 @@ export type ChannelAccountTokenSummaryRow = {
   snapshot: ChannelAccountSnapshot;
 };
 
+/** Collapses credential sources into a stable count label such as `env×2+file`. */
 function summarizeSources(sources: Array<string | undefined>): {
   label: string;
   parts: string[];
@@ -32,6 +36,7 @@ function formatTokenHint(token: string, opts: { showSecrets: boolean }): string
     return "empty";
   }
   if (!opts.showSecrets) {
+    // Show a stable fingerprint and length so operators can compare tokens without leaking them.
     return `sha256:${sha256HexPrefix(t, 8)} · len ${t.length}`;
   }
   const head = t.slice(0, 4);
@@ -42,6 +47,7 @@ function formatTokenHint(token: string, opts: { showSecrets: boolean }): string
   return `${head}…${tail} · len ${t.length}`;
 }
 
+/** Returns the credential status sentence for enabled channel accounts, if the plugin exposes token fields. */
 export function summarizeTokenConfig(params: {
   accounts: ChannelAccountTokenSummaryRow[];
   showSecrets: boolean;
@@ -52,6 +58,7 @@ export function summarizeTokenConfig(params: {
   }
 
   const accountRecs = enabled.map((a) => asRecord(a.account));
+  // Token field names are plugin-owned; infer the credential mode from the fields the plugin exposes.
   const hasBotTokenField = accountRecs.some((r) => "botToken" in r);
   const hasAppTokenField = accountRecs.some((r) => "appToken" in r);
   const hasSigningSecretField = accountRecs.some(
@@ -82,6 +89,7 @@ export function summarizeTokenConfig(params: {
     hasSigningSecretField &&
     enabled.every((a) => accountIsHttpMode(asRecord(a.account)))
   ) {
+    // Slack/Mattermost-style HTTP mode needs both bot token and signing secret to receive events.
     const unavailable = enabled.filter((a) => hasConfiguredUnavailableCredentialStatus(a.account));
     const ready = enabled.filter((a) => {
       const rec = asRecord(a.account);
@@ -137,6 +145,7 @@ export function summarizeTokenConfig(params: {
   }
 
   if (hasBotTokenField && hasAppTokenField) {
+    // Socket-mode style plugins require both halves; a single present token is still unusable.
     const unavailable = enabled.filter((a) => hasConfiguredUnavailableCredentialStatus(a.account));
     const ready = enabled.filter((a) => {
       const rec = asRecord(a.account);
diff --git a/src/commands/status-all/channels.ts b/src/commands/status-all/channels.ts
@@ -1,3 +1,6 @@
+// Builds channel status rows and account details for `openclaw status --all`.
+// This layer stays plugin-generic: channel-specific auth rules live in plugin config/status hooks.
+
 import fs from "node:fs";
 import { asRecord } from "@openclaw/normalization-core/record-coerce";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
@@ -62,6 +65,7 @@ function existsSyncMaybe(p: string | undefined): boolean | null {
   }
 }
 
+/** Resolves one configured/default account into the normalized row shape used by status rendering. */
 async function resolveChannelAccountRow(
   params: ResolvedChannelAccountRowParams,
 ): Promise<ChannelAccountRow> {
@@ -148,6 +152,7 @@ const buildAccountNotes = (params: {
   const allowFrom =
     plugin.config.resolveAllowFrom?.({ cfg, accountId: snapshot.accountId }) ?? snapshot.allowFrom;
   if (allowFrom?.length) {
+    // Cap allow-list output so large channel policies do not dominate the status table.
     const formatted = formatChannelAllowFrom({
       plugin,
       cfg,
@@ -168,6 +173,7 @@ function resolveLinkFields(summary: unknown): {
   authAgeMs: number | null;
   selfE164: string | null;
 } {
+  // Plugin summaries are optional extension data; normalize only the fields the core table understands.
   const rec = asRecord(summary);
   const statusState = typeof rec.statusState === "string" ? rec.statusState : null;
   const linked = typeof rec.linked === "boolean" ? rec.linked : null;
@@ -190,6 +196,7 @@ function collectMissingPaths(accounts: ChannelAccountRow[]): string[] {
       "dbPath",
       "authDir",
     ]) {
+      // Account config and snapshots can each expose file-backed credential paths.
       const raw =
         (accountRec[key] as string | undefined) ?? (snapshotRec[key] as string | undefined);
       const ok = existsSyncMaybe(raw);
@@ -214,8 +221,7 @@ function formatLoadFailureDetail(message: string): string {
   return `plugin load failed: ${reason}; run openclaw doctor --fix`;
 }
 
-// `status --all` channels table.
-// Keep this generic: channel-specific rules belong in the channel plugin.
+/** Builds the `status --all` channel summary and per-account detail tables. */
 export async function buildChannelsTable(
   cfg: OpenClawConfig,
   opts?: {
@@ -249,6 +255,7 @@ export async function buildChannelsTable(
     includeSetupFallbackPlugins,
   });
   for (const plugin of readOnlyPlugins.plugins) {
+    // Use the plugin's default account even when no accounts are configured so setup guidance is concrete.
     const accountIds = plugin.config.listAccountIds(cfg);
     const defaultAccountId = resolveChannelDefaultAccountId({
       plugin,
@@ -288,6 +295,7 @@ export async function buildChannelsTable(
         hasRuntimeCredentialAvailable({ liveAccounts, accountId: entry.accountId }))
         ? {
             ...entry,
+            // Fast-mode scans may not resolve local secrets; runtime evidence can still prove availability.
             account: markConfiguredUnavailableCredentialStatusesAvailable(entry.account),
           }
         : entry,
@@ -318,6 +326,7 @@ export async function buildChannelsTable(
     const label = plugin.meta.label ?? plugin.id;
 
     const state = (() => {
+      // Precedence matches operator actionability: disabled, local file breakage, plugin issues, auth, link.
       if (!anyEnabled) {
         return "off";
       }
@@ -512,6 +521,7 @@ export async function buildChannelsTable(
     });
     if (!hint || hint.channelId !== channelId) {
       if (!includeSetupFallbackPlugins && explicitConfiguredChannelIds.has(channelId)) {
+        // Fast mode intentionally skips setup fallback plugins, but configured ids still deserve visibility.
         rows.push({
           id: channelId,
           label: sanitizeForLog(channelId).trim() || "configured-channel",
