docs: document config io helpers

steipete · steipete · commit 6989d6283a5b · 2026-06-04T03:49:54.000-04:00
diff --git a/src/config/config-paths.ts b/src/config/config-paths.ts
@@ -1,3 +1,4 @@
+// Resolves and classifies config paths for reads, writes, and metadata.
 import { isPlainObject } from "../utils.js";
 import { isBlockedObjectKey } from "./prototype-keys.js";
 
diff --git a/src/config/config.identity-avatar.test.ts b/src/config/config.identity-avatar.test.ts
@@ -1,3 +1,4 @@
+// Covers identity avatar config normalization and file-path handling.
 import path from "node:path";
 import { describe, expect, it } from "vitest";
 import { withTempHome } from "./test-helpers.js";
diff --git a/src/config/config.legacy-config-detection.rejects-routing-allowfrom.test.ts b/src/config/config.legacy-config-detection.rejects-routing-allowfrom.test.ts
@@ -1,3 +1,4 @@
+// Regresses rejection of legacy routing allowFrom config.
 import { describe, expect, it } from "vitest";
 import { validateConfigObject } from "./validation.js";
 
diff --git a/src/config/config.meta-timestamp-coercion.test.ts b/src/config/config.meta-timestamp-coercion.test.ts
@@ -1,3 +1,4 @@
+// Verifies config metadata timestamp coercion behavior.
 import { describe, expect, it } from "vitest";
 import { validateConfigObject } from "./validation.js";
 
diff --git a/src/config/io.clobber-snapshot.test.ts b/src/config/io.clobber-snapshot.test.ts
@@ -1,3 +1,4 @@
+// Covers config IO clobber snapshot handling during writes.
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import os from "node:os";
diff --git a/src/config/io.compat.test.ts b/src/config/io.compat.test.ts
@@ -1,3 +1,4 @@
+// Verifies config IO compatibility loading and migration behavior.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/config/io.observe-recovery.test.ts b/src/config/io.observe-recovery.test.ts
@@ -1,3 +1,4 @@
+// Covers config IO recovery observation after corrupt or missing files.
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import os from "node:os";
diff --git a/src/config/io.owner-display-secret.test.ts b/src/config/io.owner-display-secret.test.ts
@@ -1,3 +1,4 @@
+// Verifies owner display secrets stay redacted in config IO paths.
 import { describe, expect, it } from "vitest";
 import {
   type OwnerDisplaySecretRuntimeState,
diff --git a/src/config/io.write-prepare.ts b/src/config/io.write-prepare.ts
@@ -1,3 +1,4 @@
+// Prepares config writes by diffing current state and preserving metadata.
 import { isDeepStrictEqual } from "node:util";
 import { normalizeConfiguredProviderCatalogModelId } from "@openclaw/model-catalog-core/provider-model-id-normalization";
 import { parseConfigPathArrayIndex } from "../shared/path-array-index.js";
diff --git a/src/config/legacy.shared.ts b/src/config/legacy.shared.ts
@@ -1,3 +1,4 @@
+// Defines shared legacy config rule contracts for detection and migration.
 export type LegacyConfigRule = {
   path: string[];
   message: string;
diff --git a/src/config/plugin-auto-enable.prefer-over.test.ts b/src/config/plugin-auto-enable.prefer-over.test.ts
@@ -1,3 +1,4 @@
+// Verifies plugin auto-enable prefer-over precedence rules.
 import fs from "node:fs";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/config/schema-base.ts b/src/config/schema-base.ts
@@ -1,3 +1,4 @@
+// Builds base config schema metadata shared across generated config surfaces.
 import { isSensitiveUrlConfigPath } from "@openclaw/net-policy/redact-sensitive-url";
 import { VERSION } from "../version.js";
 import { FIELD_HELP } from "./schema.help.js";
diff --git a/src/config/schema.base.generated.test.ts b/src/config/schema.base.generated.test.ts
@@ -1,3 +1,4 @@
+// Verifies generated base config schema snapshots and sensitive redaction.
 import { SENSITIVE_URL_HINT_TAG } from "@openclaw/net-policy/redact-sensitive-url";
 import { describe, expect, it } from "vitest";
 import { computeBaseConfigSchemaResponse } from "./schema-base.js";
diff --git a/src/config/schema.labels.ts b/src/config/schema.labels.ts
@@ -1,3 +1,4 @@
+// Defines user-facing config field labels used by schema metadata.
 import { MEDIA_AUDIO_FIELD_LABELS } from "./media-audio-field-metadata.js";
 
 export const FIELD_LABELS: Record<string, string> = {
diff --git a/src/config/schema.shared.test.ts b/src/config/schema.shared.test.ts
@@ -1,3 +1,4 @@
+// Covers shared config schema fragments and defaults.
 import { describe, expect, it } from "vitest";
 import { findWildcardHintMatch, schemaHasChildren } from "./schema.shared.js";
 
diff --git a/src/config/state-dir-dotenv.test.ts b/src/config/state-dir-dotenv.test.ts
@@ -1,3 +1,4 @@
+// Covers state-directory dotenv discovery, parsing, and merge behavior.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/config/state-dir-dotenv.ts b/src/config/state-dir-dotenv.ts
@@ -1,3 +1,4 @@
+// Loads state-directory dotenv entries used by config and runtime startup.
 import fs from "node:fs";
 import path from "node:path";
 import dotenv from "dotenv";
diff --git a/src/config/types.channel-messaging-common.ts b/src/config/types.channel-messaging-common.ts
@@ -1,3 +1,4 @@
+// Defines common channel messaging configuration types.
 import type {
   BlockStreamingCoalesceConfig,
   ContextVisibilityMode,
diff --git a/src/config/types.messages.ts b/src/config/types.messages.ts
@@ -1,3 +1,4 @@
+// Defines message queue and delivery configuration types.
 import type { QueueDropPolicy, QueueMode, QueueModeByProvider } from "./types.queue.js";
 import type { TtsConfig } from "./types.tts.js";
 
diff --git a/src/config/types.msteams.ts b/src/config/types.msteams.ts
@@ -1,3 +1,4 @@
+// Defines Microsoft Teams channel configuration types.
 import type {
   BlockStreamingCoalesceConfig,
   ChannelPreviewStreamingConfig,
diff --git a/src/config/types.slack.ts b/src/config/types.slack.ts
@@ -1,3 +1,4 @@
+// Defines Slack channel configuration types.
 import type {
   ChannelStreamingBlockConfig,
   ChannelStreamingProgressConfig,
diff --git a/src/config/validation.allowed-values.test.ts b/src/config/validation.allowed-values.test.ts
@@ -1,3 +1,4 @@
+// Verifies config validation rejects unsupported enumerated values.
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
 import { testing, validateConfigObjectRaw } from "./validation.js";
diff --git a/src/config/validation.legacy-rules-fast-path.test.ts b/src/config/validation.legacy-rules-fast-path.test.ts
@@ -1,3 +1,4 @@
+// Verifies legacy-rule validation uses the fast path for known config shapes.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { LegacyConfigRule } from "./legacy.shared.js";
 
diff --git a/src/config/zod-schema.post-compaction-guard.test.ts b/src/config/zod-schema.post-compaction-guard.test.ts
@@ -1,3 +1,4 @@
+// Guards post-compaction config schema behavior against regressions.
 import { describe, expect, it } from "vitest";
 import { ToolsSchema } from "./zod-schema.agent-runtime.js";
 import { OpenClawSchema } from "./zod-schema.js";

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Resolves and classifies config paths for reads, writes, and metadata.`
`1`	`2`	`import { isPlainObject } from "../utils.js";`
`2`	`3`	`import { isBlockedObjectKey } from "./prototype-keys.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers identity avatar config normalization and file-path handling.`
`1`	`2`	`import path from "node:path";`
`2`	`3`	`import { describe, expect, it } from "vitest";`
`3`	`4`	`import { withTempHome } from "./test-helpers.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Regresses rejection of legacy routing allowFrom config.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { validateConfigObject } from "./validation.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Verifies config metadata timestamp coercion behavior.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { validateConfigObject } from "./validation.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers config IO clobber snapshot handling during writes.`
`1`	`2`	`import fs from "node:fs";`
`2`	`3`	`import fsp from "node:fs/promises";`
`3`	`4`	`import os from "node:os";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Verifies config IO compatibility loading and migration behavior.`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import os from "node:os";`
`3`	`4`	`import path from "node:path";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers config IO recovery observation after corrupt or missing files.`
`1`	`2`	`import fs from "node:fs";`
`2`	`3`	`import fsp from "node:fs/promises";`
`3`	`4`	`import os from "node:os";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Verifies owner display secrets stay redacted in config IO paths.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import {`
`3`	`4`	`type OwnerDisplaySecretRuntimeState,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Prepares config writes by diffing current state and preserving metadata.`
`1`	`2`	`import { isDeepStrictEqual } from "node:util";`
`2`	`3`	`import { normalizeConfiguredProviderCatalogModelId } from "@openclaw/model-catalog-core/provider-model-id-normalization";`
`3`	`4`	`import { parseConfigPathArrayIndex } from "../shared/path-array-index.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Defines shared legacy config rule contracts for detection and migration.`
`1`	`2`	`export type LegacyConfigRule = {`
`2`	`3`	`path: string[];`
`3`	`4`	`message: string;`