docs: document infra process helpers

steipete · steipete · commit dc3f2bd1d927 · 2026-06-04T03:03:13.000-04:00
diff --git a/src/infra/approval-native-target-key.test.ts b/src/infra/approval-native-target-key.test.ts
@@ -1,3 +1,4 @@
+// Tests native approval target key generation.
 import { describe, expect, it } from "vitest";
 import { buildChannelApprovalNativeTargetKey } from "./approval-native-target-key.js";
 
diff --git a/src/infra/binaries.test.ts b/src/infra/binaries.test.ts
@@ -1,3 +1,4 @@
+// Tests bundled binary discovery and version command helpers.
 import { describe, expect, it, vi } from "vitest";
 import type { runExec } from "../process/exec.js";
 import type { RuntimeEnv } from "../runtime.js";
diff --git a/src/infra/boundary-path.test.ts b/src/infra/boundary-path.test.ts
@@ -1,3 +1,4 @@
+// Tests path boundary enforcement for safe file access.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/infra/build-stamp.test.ts b/src/infra/build-stamp.test.ts
@@ -1,3 +1,4 @@
+// Tests build stamp file parsing and fallback behavior.
 import fs from "node:fs/promises";
 import { describe, expect, it } from "vitest";
 import { writeBuildStamp } from "../../scripts/build-stamp.mjs";
diff --git a/src/infra/clipboard.ts b/src/infra/clipboard.ts
@@ -1,3 +1,4 @@
+// Reads and writes clipboard text through platform command helpers.
 import { runCommandWithTimeout } from "../process/exec.js";
 import { isWSL2Sync } from "./wsl.js";
 
diff --git a/src/infra/exec-approval-reply.test.ts b/src/infra/exec-approval-reply.test.ts
@@ -1,3 +1,4 @@
+// Tests execution approval reply text and decision formatting.
 import { describe, expect, it, vi } from "vitest";
 import type { ReplyPayload } from "../auto-reply/types.js";
 
diff --git a/src/infra/executable-path.ts b/src/infra/executable-path.ts
@@ -1,3 +1,4 @@
+// Resolves executable paths from PATH and platform-specific install locations.
 import fs from "node:fs";
 import path from "node:path";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
diff --git a/src/infra/heartbeat-events.test.ts b/src/infra/heartbeat-events.test.ts
@@ -1,3 +1,4 @@
+// Tests heartbeat event emission and listener cleanup.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   emitHeartbeatEvent,
diff --git a/src/infra/heartbeat-reason.test.ts b/src/infra/heartbeat-reason.test.ts
@@ -1,3 +1,4 @@
+// Tests heartbeat reason formatting and normalization.
 import { describe, expect, it } from "vitest";
 import { normalizeHeartbeatWakeReason } from "./heartbeat-reason.js";
 
diff --git a/src/infra/heartbeat-runner.test-utils.ts b/src/infra/heartbeat-runner.test-utils.ts
@@ -1,3 +1,4 @@
+// Shared heartbeat runner fixtures for infra tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/infra/host-env-security.ts b/src/infra/host-env-security.ts
@@ -1,3 +1,4 @@
+// Filters host environment variables before passing them to runtimes.
 import { sortUniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import { HOST_ENV_SECURITY_POLICY } from "./host-env-security-policy.js";
 import { markOpenClawExecEnv } from "./openclaw-exec-env.js";
diff --git a/src/infra/install-mode-options.test.ts b/src/infra/install-mode-options.test.ts
@@ -1,3 +1,4 @@
+// Tests install mode option parsing for setup commands.
 import { describe, expect, it } from "vitest";
 import {
   resolveInstallModeOptions,
diff --git a/src/infra/is-main.test.ts b/src/infra/is-main.test.ts
@@ -1,3 +1,4 @@
+// Tests module main-entry detection helpers.
 import { describe, expect, it, vi } from "vitest";
 import { isMainModule } from "./is-main.js";
 
diff --git a/src/infra/npm-registry-spec.test.ts b/src/infra/npm-registry-spec.test.ts
@@ -1,3 +1,4 @@
+// Tests npm registry spec parsing for packages, tags, and versions.
 import { describe, expect, it } from "vitest";
 import {
   compareOpenClawReleaseVersions,
diff --git a/src/infra/package-tag.test.ts b/src/infra/package-tag.test.ts
@@ -1,3 +1,4 @@
+// Tests package tag parsing and stable release tag behavior.
 import { describe, expect, it } from "vitest";
 import { normalizePackageTagInput } from "./package-tag.js";
 
diff --git a/src/infra/provider-usage.fetch.gemini.test.ts b/src/infra/provider-usage.fetch.gemini.test.ts
@@ -1,3 +1,4 @@
+// Tests Gemini provider usage fetch normalization.
 import { describe, expect, it } from "vitest";
 import { createProviderUsageFetch, makeResponse } from "../test-utils/provider-usage-fetch.js";
 import { fetchGeminiUsage } from "./provider-usage.fetch.gemini.js";
diff --git a/src/infra/provider-usage.test.ts b/src/infra/provider-usage.test.ts
@@ -1,3 +1,4 @@
+// Tests provider usage aggregation and formatting.
 import { beforeEach, describe, expect, it } from "vitest";
 import { createProviderUsageFetch } from "../test-utils/provider-usage-fetch.js";
 import {
diff --git a/src/infra/push-web.ts b/src/infra/push-web.ts
@@ -1,3 +1,4 @@
+// Stores and verifies web push subscriptions and delivery payloads.
 import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { resolveStateDir } from "../config/paths.js";
diff --git a/src/infra/restart-coordinator.ts b/src/infra/restart-coordinator.ts
@@ -1,3 +1,4 @@
+// Coordinates restart requests around active embedded agent runs.
 import { getActiveEmbeddedRunCount } from "../agents/embedded-agent-runner/run-state.js";
 import { getTotalPendingReplies } from "../auto-reply/reply/dispatcher-registry.js";
 import { getTotalQueueSize } from "../process/command-queue.js";
diff --git a/src/infra/sqlite-pragma.test-support.ts b/src/infra/sqlite-pragma.test-support.ts
@@ -1,3 +1,4 @@
+// Test helper for reading SQLite pragma state.
 import type { DatabaseSync } from "node:sqlite";
 
 // SQLite pragma test helpers normalize node:sqlite bigint/number outputs.
diff --git a/src/infra/ssh-config.test.ts b/src/infra/ssh-config.test.ts
@@ -1,3 +1,4 @@
+// Tests SSH config parsing and spawned command options.
 import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { beforeAll, describe, expect, it, vi } from "vitest";
diff --git a/src/infra/system-run-approval-context.test.ts b/src/infra/system-run-approval-context.test.ts
@@ -1,3 +1,4 @@
+// Tests system-run approval context construction.
 import { describe, expect, test } from "vitest";
 import {
   parsePreparedSystemRunPayload,
diff --git a/src/infra/unhandled-rejections.fatal-detection.test.ts b/src/infra/unhandled-rejections.fatal-detection.test.ts
@@ -1,3 +1,4 @@
+// Tests fatal unhandled rejection detection in process bootstrap.
 import process from "node:process";
 import { describe, it, expect, vi, beforeAll, afterAll, beforeEach, afterEach } from "vitest";
 
diff --git a/src/infra/watch-node.test.ts b/src/infra/watch-node.test.ts
@@ -1,3 +1,4 @@
+// Tests watched node process restart and hashing behavior.
 import { createHash } from "node:crypto";
 import { EventEmitter } from "node:events";
 import fs from "node:fs";

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests native approval target key generation.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { buildChannelApprovalNativeTargetKey } from "./approval-native-target-key.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests bundled binary discovery and version command helpers.`
`1`	`2`	`import { describe, expect, it, vi } from "vitest";`
`2`	`3`	`import type { runExec } from "../process/exec.js";`
`3`	`4`	`import type { RuntimeEnv } from "../runtime.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests path boundary enforcement for safe file access.`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import { describe, expect, it } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests build stamp file parsing and fallback behavior.`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import { describe, expect, it } from "vitest";`
`3`	`4`	`import { writeBuildStamp } from "../../scripts/build-stamp.mjs";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Reads and writes clipboard text through platform command helpers.`
`1`	`2`	`import { runCommandWithTimeout } from "../process/exec.js";`
`2`	`3`	`import { isWSL2Sync } from "./wsl.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests execution approval reply text and decision formatting.`
`1`	`2`	`import { describe, expect, it, vi } from "vitest";`
`2`	`3`	`import type { ReplyPayload } from "../auto-reply/types.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Resolves executable paths from PATH and platform-specific install locations.`
`1`	`2`	`import fs from "node:fs";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests heartbeat event emission and listener cleanup.`
`1`	`2`	`import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import {`
`3`	`4`	`emitHeartbeatEvent,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests heartbeat reason formatting and normalization.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { normalizeHeartbeatWakeReason } from "./heartbeat-reason.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Shared heartbeat runner fixtures for infra tests.`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import os from "node:os";`
`3`	`4`	`import path from "node:path";`