docs: document infra runtime helpers

steipete · steipete · commit 0d109750aec7 · 2026-06-04T02:55:39.000-04:00
diff --git a/src/infra/approval-native-delivery.ts b/src/infra/approval-native-delivery.ts
@@ -1,3 +1,4 @@
+// Native delivery contract for approval prompts and responses.
 import type {
   ChannelApprovalNativeAdapter,
   ChannelApprovalNativeSurface,
diff --git a/src/infra/archive-helpers.test.ts b/src/infra/archive-helpers.test.ts
@@ -1,3 +1,4 @@
+// Tests archive helper behavior for filesystem packaging.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/infra/backup-volatile-filter.test.ts b/src/infra/backup-volatile-filter.test.ts
@@ -1,3 +1,4 @@
+// Tests volatile path filtering for backup operations.
 import { describe, expect, it } from "vitest";
 import { isVolatileBackupPath } from "./backup-volatile-filter.js";
 
diff --git a/src/infra/boundary-file-read.test.ts b/src/infra/boundary-file-read.test.ts
@@ -1,3 +1,4 @@
+// Tests safe boundary file reads against upstream fs-safe behavior.
 import * as upstream from "@openclaw/fs-safe/advanced";
 import { describe, expect, it } from "vitest";
 import * as shim from "./boundary-file-read.js";
diff --git a/src/infra/brew.ts b/src/infra/brew.ts
@@ -1,3 +1,4 @@
+// Discovers Homebrew paths and package metadata for diagnostics.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/infra/device-auth-store.ts b/src/infra/device-auth-store.ts
@@ -1,3 +1,4 @@
+// Persists device authorization records for paired nodes.
 import fs from "node:fs";
 import path from "node:path";
 import { resolveStateDir } from "../config/paths.js";
diff --git a/src/infra/gateway-lock.test.ts b/src/infra/gateway-lock.test.ts
@@ -1,3 +1,4 @@
+// Tests gateway lock file ownership and stale-lock behavior.
 import { createHash } from "node:crypto";
 import { EventEmitter } from "node:events";
 import fsSync from "node:fs";
diff --git a/src/infra/gateway-processes.ts b/src/infra/gateway-processes.ts
@@ -1,3 +1,4 @@
+// Inspects local gateway processes for status and diagnostics.
 import { spawnSync } from "node:child_process";
 import fsSync from "node:fs";
 import { uniqueValues } from "@openclaw/normalization-core/string-normalization";
diff --git a/src/infra/google-api-base-url.test.ts b/src/infra/google-api-base-url.test.ts
@@ -1,3 +1,4 @@
+// Tests Google API base URL normalization for provider requests.
 import { describe, expect, it } from "vitest";
 import { DEFAULT_GOOGLE_API_BASE_URL, normalizeGoogleApiBaseUrl } from "./google-api-base-url.js";
 
diff --git a/src/infra/hardlink-guards.test.ts b/src/infra/hardlink-guards.test.ts
@@ -1,3 +1,4 @@
+// Tests hardlink guard detection for unsafe filesystem paths.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/infra/heartbeat-runner.response-prefix-template.test.ts b/src/infra/heartbeat-runner.response-prefix-template.test.ts
@@ -1,3 +1,4 @@
+// Tests heartbeat runner response prefix template handling.
 import { describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { runHeartbeatOnce, type HeartbeatDeps } from "./heartbeat-runner.js";
diff --git a/src/infra/heartbeat-runner.typing.test.ts b/src/infra/heartbeat-runner.typing.test.ts
@@ -1,3 +1,4 @@
+// Tests heartbeat runner typing indicator behavior.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.public.js";
 import type { OpenClawConfig } from "../config/config.js";
diff --git a/src/infra/infra-runtime.test.ts b/src/infra/infra-runtime.test.ts
@@ -1,3 +1,4 @@
+// Tests infra runtime loading and platform-dependent helpers.
 import os from "node:os";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
diff --git a/src/infra/install-package-dir.test.ts b/src/infra/install-package-dir.test.ts
@@ -1,3 +1,4 @@
+// Tests package install directory detection and validation.
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
diff --git a/src/infra/kysely-sync.ts b/src/infra/kysely-sync.ts
@@ -1,3 +1,4 @@
+// Adapts node:sqlite sync database calls for Kysely-style query execution.
 import type { DatabaseSync, SQLInputValue } from "node:sqlite";
 import type { CompiledQuery, Kysely, QueryResult } from "kysely";
 import { InsertQueryNode, Kysely as KyselyInstance } from "kysely";
diff --git a/src/infra/node-pairing.ts b/src/infra/node-pairing.ts
@@ -1,3 +1,4 @@
+// Manages node pairing identities for gateway and remote device trust.
 import { randomUUID } from "node:crypto";
 import { normalizeArrayBackedTrimmedStringList } from "@openclaw/normalization-core/string-normalization";
 import { resolveMissingRequestedScope } from "../shared/operator-scope-compat.js";
diff --git a/src/infra/openclaw-exec-env.test.ts b/src/infra/openclaw-exec-env.test.ts
@@ -1,3 +1,4 @@
+// Tests OpenClaw execution environment construction.
 import { describe, expect, it } from "vitest";
 import {
   ensureOpenClawExecMarkerOnProcess,
diff --git a/src/infra/ports-lsof.ts b/src/infra/ports-lsof.ts
@@ -1,3 +1,4 @@
+// Uses lsof output to map listening ports to local processes.
 import fs from "node:fs";
 import fsPromises from "node:fs/promises";
 
diff --git a/src/infra/ports-probe.test.ts b/src/infra/ports-probe.test.ts
@@ -1,3 +1,4 @@
+// Tests local port probing and availability detection.
 import net from "node:net";
 import { describe, expect, it } from "vitest";
 import { tryListenOnPort } from "./ports-probe.js";
diff --git a/src/infra/provider-usage.load.plugin.test.ts b/src/infra/provider-usage.load.plugin.test.ts
@@ -1,3 +1,4 @@
+// Tests provider usage loading from plugin-provided sources.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { createProviderUsageFetch } from "../test-utils/provider-usage-fetch.js";
 
diff --git a/src/infra/push-web.test.ts b/src/infra/push-web.test.ts
@@ -1,3 +1,4 @@
+// Tests web push subscription storage and delivery helpers.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/infra/session-cost-usage.types.ts b/src/infra/session-cost-usage.types.ts
@@ -1,3 +1,4 @@
+// Shared session cost and usage accounting type contracts.
 import type { NormalizedUsage } from "../agents/usage.js";
 import type {
   SessionUsageTimePoint as SharedSessionUsageTimePoint,
diff --git a/src/infra/supervisor-markers.ts b/src/infra/supervisor-markers.ts
@@ -1,3 +1,4 @@
+// Defines process supervisor marker labels for gateway diagnostics.
 import { GATEWAY_LAUNCH_AGENT_LABEL, resolveGatewayLaunchAgentLabel } from "../daemon/constants.js";
 
 const SUPERVISOR_HINTS = {
diff --git a/src/infra/system-run-approval-binding.ts b/src/infra/system-run-approval-binding.ts
@@ -1,3 +1,4 @@
+// Binds system-run approval requests to stable command identities.
 import crypto from "node:crypto";
 import type {
   SystemRunApprovalBinding,

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Native delivery contract for approval prompts and responses.`
`1`	`2`	`import type {`
`2`	`3`	`ChannelApprovalNativeAdapter,`
`3`	`4`	`ChannelApprovalNativeSurface,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests archive helper behavior for filesystem packaging.`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import { afterEach, describe, expect, it, vi } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests volatile path filtering for backup operations.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { isVolatileBackupPath } from "./backup-volatile-filter.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests safe boundary file reads against upstream fs-safe behavior.`
`1`	`2`	`import * as upstream from "@openclaw/fs-safe/advanced";`
`2`	`3`	`import { describe, expect, it } from "vitest";`
`3`	`4`	`import * as shim from "./boundary-file-read.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Discovers Homebrew paths and package metadata for diagnostics.`
`1`	`2`	`import fs from "node:fs";`
`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`	`+// Persists device authorization records for paired nodes.`
`1`	`2`	`import fs from "node:fs";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import { resolveStateDir } from "../config/paths.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests gateway lock file ownership and stale-lock behavior.`
`1`	`2`	`import { createHash } from "node:crypto";`
`2`	`3`	`import { EventEmitter } from "node:events";`
`3`	`4`	`import fsSync from "node:fs";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Inspects local gateway processes for status and diagnostics.`
`1`	`2`	`import { spawnSync } from "node:child_process";`
`2`	`3`	`import fsSync from "node:fs";`
`3`	`4`	`import { uniqueValues } from "@openclaw/normalization-core/string-normalization";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests Google API base URL normalization for provider requests.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import { DEFAULT_GOOGLE_API_BASE_URL, normalizeGoogleApiBaseUrl } from "./google-api-base-url.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tests hardlink guard detection for unsafe filesystem paths.`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import os from "node:os";`
`3`	`4`	`import path from "node:path";`